agentic-project-kit 1.0.1__py3-none-any.whl

agentic_project_kit/cli_commands/release.py

@@ -0,0 +1,392 @@
+from __future__ import annotations
+
+from datetime import date as date_cls
+import json
+import re
+from typing import Annotated
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from agentic_project_kit.post_release import build_post_release_report, render_post_release_report
+from agentic_project_kit.release_prepare import prepare_release_state
+from agentic_project_kit.release_metadata_authority_gate import (
+    evaluate_release_metadata_authority_gate,
+    render_release_metadata_authority_gate_result,
+)
+from agentic_project_kit.post_release_closeout import post_release_doi_closeout, render_post_release_doi_closeout_result
+from agentic_project_kit.release import (
+    ReleaseCheckStatus,
+    build_release_plan,
+    build_release_preflight_report,
+    build_release_state_report,
+    render_release_plan,
+    render_release_preflight_report,
+    render_release_state_report,
+)
+from agentic_project_kit.release_state import build_release_lifecycle_status, render_release_lifecycle_status
+from agentic_project_kit.release_notes import (
+    build_release_notes_report,
+    check_release_notes_outputs,
+    render_release_notes_markdown,
+    write_release_notes_outputs,
+)
+
+console = Console()
+
+
+def _print_json(payload: dict[str, object]) -> None:
+    typer.echo(json.dumps(payload, indent=2, sort_keys=True))
+
+
+def register_release_commands(app: typer.Typer) -> None:
+    app.command("release-plan")(release_plan_command)
+    app.command("release-preflight")(release_preflight_command)
+    app.command("release-prep")(release_prep_command)
+    app.command("release-status")(release_status_command)
+    app.command("release-notes-generate")(release_notes_generate_command)
+    app.command("release-metadata-authority-gate")(release_metadata_authority_gate_command)
+    app.command("release-check")(release_check_command)
+    app.command("post-release-check")(post_release_check_command)
+    app.command(
+        "post-release-doi-closeout",
+        help="Record verified DOI metadata after GitHub release and Zenodo publication.",
+    )(post_release_doi_closeout_command)
+
+
+def release_plan_command(
+    project_root: Path = typer.Option(Path("."), "--root"),
+    version: str | None = typer.Option(None, "--version", help="Release version without leading v."),
+) -> None:
+    """Print a release preparation checklist for the current project."""
+    root = project_root.resolve()
+    if version is None:
+        current_version = build_release_plan(root).version
+        current_report = build_release_preflight_report(root, version=current_version)
+        already_released = any(
+            check.status == ReleaseCheckStatus.FAIL
+            for check in current_report.checks
+            if check.name in {"remote tag unused", "GitHub release unused"}
+        )
+        if already_released:
+            console.print(
+                "Current package version is already released. "
+                "Pass the next target explicitly, for example: "
+                "agentic-kit release-plan --version <next-version>",
+                markup=False,
+            )
+            raise typer.Exit(code=2)
+    plan = build_release_plan(root, version=version)
+    console.print(render_release_plan(plan), markup=False)
+
+
+def release_preflight_command(
+    version: str = typer.Option(..., "--version", help="Target release version without leading v."),
+) -> None:
+    """Validate before-metadata release readiness for a target version."""
+    raise typer.Exit(code=run_release_preflight(version))
+
+
+def run_release_preflight(version: str) -> int:
+    """Validate the before-metadata release phase for a target version.
+
+    This intentionally does not require project files to already contain the
+    target version. That is the job of release-check after metadata is patched.
+    """
+    report = build_release_preflight_report(Path(".").resolve(), version=version)
+    console.print(render_release_preflight_report(report), markup=False)
+    return 0 if report.ok else 1
+
+
+def release_prep_command(
+    project_root: Path = typer.Option(Path("."), "--root"),
+    version: str = typer.Option(..., "--version", help="Target release version without leading v."),
+    release_date: str | None = typer.Option(
+        None,
+        "--date",
+        help="Release metadata date in YYYY-MM-DD format. Defaults to today.",
+    ),
+    summary_lines: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--summary-line",
+            help="Release changelog summary line. Repeat for multiple lines; required to avoid stale template reuse.",
+        ),
+    ] = None,
+    summary_lines_from: Path | None = typer.Option(
+        None,
+        "--summary-lines-from",
+        help="Read explicit release changelog summary lines from a JSON artifact generated from release notes.",
+    ),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Report changed paths without writing files."),
+    json_output: bool = typer.Option(False, "--json", help="Print a machine-readable result."),
+) -> None:
+    """Prepare release metadata through the supported agentic-kit route.
+
+    This edits only local release metadata files. It does not tag, publish,
+    push, create GitHub releases, or write Zenodo DOI metadata.
+    """
+    plain_version = version.removeprefix("v")
+    date_value = release_date or date_cls.today().isoformat()
+    if not re.fullmatch(r"\d+\.\d+\.\d+", plain_version):
+        message = f"Invalid release version: {version!r}; expected MAJOR.MINOR.PATCH"
+        if json_output:
+            _print_json(
+                {
+                    "ok": False,
+                    "version": plain_version,
+                    "date": date_value,
+                    "dry_run": dry_run,
+                    "error": message,
+                }
+            )
+        else:
+            console.print(f"ERROR: {message}", markup=False)
+        raise typer.Exit(code=2)
+
+    try:
+        effective_summary_lines = _combine_release_prep_summary_lines(
+            explicit_lines=summary_lines or [],
+            summary_lines_from=summary_lines_from,
+        )
+        result = prepare_release_state(
+            project_root.resolve(),
+            version=plain_version,
+            date=date_value,
+            summary_lines=effective_summary_lines,
+            dry_run=dry_run,
+        )
+    except (FileNotFoundError, ValueError) as exc:
+        if json_output:
+            _print_json(
+                {
+                    "ok": False,
+                    "version": plain_version,
+                    "date": date_value,
+                    "dry_run": dry_run,
+                    "error": str(exc),
+                }
+            )
+        else:
+            console.print(f"ERROR: {exc}", markup=False)
+        raise typer.Exit(code=2) from exc
+
+    if json_output:
+        _print_json(result.as_dict())
+    else:
+        mode = "DRY-RUN" if dry_run else "WRITE"
+        if result.changed_paths:
+            console.print(
+                f"{mode}: prepared release metadata for v{result.version} on {result.date}",
+                markup=False,
+            )
+            for changed_path in result.changed_paths:
+                console.print(f"CHANGED: {changed_path}", markup=False)
+        else:
+            console.print(f"{mode}: release metadata already prepared for v{result.version}", markup=False)
+
+
+def release_status_command(
+    project_root: Path = typer.Option(Path("."), "--root"),
+    version: str | None = typer.Option(None, "--version", help="Release version without leading v."),
+    include_remote: bool = typer.Option(False, "--include-remote", help="Include remote tag, GitHub Release, and DOI/Zenodo checks."),
+    json_output: bool = typer.Option(False, "--json", help="Print a machine-readable result."),
+) -> None:
+    """Render the local release lifecycle state without mutating release files."""
+    result = build_release_lifecycle_status(project_root.resolve(), version=version, include_remote=include_remote)
+    if json_output:
+        _print_json(result.as_dict())
+    else:
+        console.print(render_release_lifecycle_status(result), markup=False)
+    if result.blockers:
+        raise typer.Exit(code=2)
+
+
+def release_notes_generate_command(
+    project_root: Path = typer.Option(Path("."), "--root"),
+    version: str = typer.Option(..., "--version", help="Target release version without leading v."),
+    from_tag: str = typer.Option(..., "--from-tag", help="Previous release tag used as the lower diff bound."),
+    to_ref: str = typer.Option("HEAD", "--to-ref", help="Upper git ref used for release-note evidence."),
+    json_out: Path | None = typer.Option(None, "--json-out", help="Write generated JSON release notes here."),
+    out: Path | None = typer.Option(None, "--out", help="Write generated Markdown release notes here."),
+    summary_lines_json: Path | None = typer.Option(
+        None,
+        "--summary-lines-json",
+        help="Write a compact JSON artifact containing explicit release-prep summary lines.",
+    ),
+    write: bool = typer.Option(False, "--write", help="Write --json-out and --out files."),
+    check: bool = typer.Option(False, "--check", help="Check existing --json-out and --out files for generated-output drift."),
+    include_github_metadata: bool = typer.Option(False, "--include-github-metadata", help="Augment PR evidence with optional gh pr view metadata."),
+    json_output: bool = typer.Option(False, "--json", help="Print a machine-readable result."),
+) -> None:
+    """Generate deterministic evidence-backed release notes from a local git tag diff."""
+    result = build_release_notes_report(
+        project_root.resolve(),
+        version=version,
+        from_tag=from_tag,
+        to_ref=to_ref,
+        include_github_metadata=include_github_metadata,
+    )
+    if summary_lines_json is not None:
+        _write_release_summary_lines_artifact(result, summary_lines_json=summary_lines_json)
+    if write:
+        if json_out is None or out is None:
+            message = "--write requires both --json-out and --out"
+            if json_output:
+                _print_json({"ok": False, "status": "BLOCK", "message": message})
+            else:
+                console.print(f"BLOCK: {message}", markup=False)
+            raise typer.Exit(code=2)
+        write_release_notes_outputs(result, json_out=json_out, markdown_out=out)
+    drift_check: dict[str, object] | None = None
+    if check:
+        if json_out is None or out is None:
+            message = "--check requires both --json-out and --out"
+            if json_output:
+                _print_json({"ok": False, "status": "BLOCK", "message": message})
+            else:
+                console.print(f"BLOCK: {message}", markup=False)
+            raise typer.Exit(code=2)
+        drift_check = check_release_notes_outputs(result, json_out=json_out, markdown_out=out)
+    if json_output:
+        payload = result.as_dict()
+        if drift_check is not None:
+            payload["drift_check"] = drift_check
+        _print_json(payload)
+    else:
+        console.print(render_release_notes_markdown(result), markup=False)
+        if drift_check is not None:
+            console.print(f"DRIFT_CHECK={drift_check['status']}", markup=False)
+    if result.validation.status != "PASS":
+        raise typer.Exit(code=2)
+    if drift_check is not None and drift_check["status"] != "PASS":
+        raise typer.Exit(code=2)
+
+
+def _combine_release_prep_summary_lines(*, explicit_lines: list[str], summary_lines_from: Path | None) -> list[str]:
+    lines = list(explicit_lines)
+    if summary_lines_from is not None:
+        lines.extend(_read_release_summary_lines_artifact(summary_lines_from))
+    return lines
+
+
+def _read_release_summary_lines_artifact(path: Path) -> list[str]:
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    if isinstance(payload, list):
+        raw_lines = payload
+    elif isinstance(payload, dict) and isinstance(payload.get("summary_lines"), list):
+        raw_lines = payload["summary_lines"]
+    elif isinstance(payload, dict) and isinstance(payload.get("items"), list):
+        raw_lines = [item.get("title") for item in payload["items"] if isinstance(item, dict)]
+    else:
+        raise ValueError("--summary-lines-from must point to a JSON list, a {summary_lines: [...]} artifact, or a release-notes JSON report")
+    lines = [str(line).strip() for line in raw_lines if str(line).strip()]
+    if not lines:
+        raise ValueError("--summary-lines-from did not contain any usable release changelog summary lines")
+    return lines
+
+
+def _release_summary_lines_from_report(report: object) -> list[str]:
+    items = getattr(report, "items")
+    return [str(item.title).strip() for item in items if str(item.title).strip()]
+
+
+def _write_release_summary_lines_artifact(report: object, *, summary_lines_json: Path) -> None:
+    lines = _release_summary_lines_from_report(report)
+    payload: dict[str, object] = {
+        "schema_version": 1,
+        "kind": "release_prep_summary_lines",
+        "version": getattr(report, "version"),
+        "from_tag": getattr(report, "from_tag"),
+        "to_ref": getattr(report, "to_ref"),
+        "source": "agentic-kit release-notes-generate",
+        "summary_lines": lines,
+    }
+    summary_lines_json.parent.mkdir(parents=True, exist_ok=True)
+    summary_lines_json.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+
+def release_metadata_authority_gate_command(
+    project_root: Path = typer.Option(Path("."), "--root"),
+    base_ref: str = typer.Option("origin/main", "--base-ref", help="Git ref used as the diff base."),
+    version: str | None = typer.Option(None, "--version", help="Expected release version without leading v."),
+    evidence: Annotated[
+        list[Path] | None,
+        typer.Option(
+            "--evidence",
+            help="Authoritative release-prep evidence file. May be passed more than once.",
+        ),
+    ] = None,
+    json_output: bool = typer.Option(False, "--json", help="Print a machine-readable result."),
+) -> None:
+    """Block manual release metadata anchor edits without release-prep evidence."""
+    try:
+        result = evaluate_release_metadata_authority_gate(
+            project_root.resolve(),
+            base_ref=base_ref,
+            version=version,
+            evidence_paths=evidence or [],
+        )
+    except (RuntimeError, ValueError) as exc:
+        result = None
+        if json_output:
+            _print_json(
+                {
+                    "ok": False,
+                    "status": "BLOCK",
+                    "version": version,
+                    "base_ref": base_ref,
+                    "changed_release_anchor_paths": [],
+                    "evidence_paths": [path.as_posix() for path in evidence or []],
+                    "message": str(exc),
+                }
+            )
+        else:
+            console.print(f"BLOCK: {exc}", markup=False)
+        raise typer.Exit(code=2) from exc
+
+    if json_output:
+        _print_json(result.as_dict())
+    else:
+        console.print(render_release_metadata_authority_gate_result(result), markup=False)
+
+    if not result.ok:
+        raise typer.Exit(code=1)
+
+
+def release_check_command(
+    project_root: Path = typer.Option(Path("."), "--root"),
+    version: str | None = typer.Option(None, "--version", help="Release version without leading v."),
+) -> None:
+    """Validate release state for a target version."""
+    report = build_release_state_report(project_root.resolve(), version=version)
+    console.print(render_release_state_report(report), markup=False)
+    if not report.ok:
+        raise typer.Exit(code=1)
+
+
+def post_release_check_command(
+    project_root: Path = typer.Option(Path("."), "--root"),
+    version: str | None = typer.Option(None, "--version", help="Release version without leading v."),
+) -> None:
+    """Validate post-release GitHub and Zenodo state without guessing DOI metadata."""
+    report = build_post_release_report(project_root.resolve(), version=version)
+    console.print(render_post_release_report(report), markup=False)
+    if not report.ok:
+        raise typer.Exit(code=1)
+
+
+def post_release_doi_closeout_command(
+    project_root: Path = typer.Option(Path("."), "--root"),
+    version: str = typer.Option(..., "--version", help="Release version without leading v."),
+    write: bool = typer.Option(False, "--write", help="Write verified DOI metadata updates."),
+    json_output: bool = typer.Option(False, "--json", help="Print a machine-readable result."),
+) -> None:
+    result = post_release_doi_closeout(project_root.resolve(), version=version, write=write)
+    if json_output:
+        _print_json(result.as_dict())
+    else:
+        console.print(render_post_release_doi_closeout_result(result), markup=False)
+    if not result.ok:
+        raise typer.Exit(code=result.returncode)

agentic_project_kit/cli_commands/release_publish_orchestration.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+from agentic_project_kit import __version__ as PACKAGE_VERSION
+from agentic_project_kit.release_publish_orchestration import (
+    evaluate_release_publish_plan,
+    render_release_publish_plan,
+)
+
+
+def release_publish_command(
+    version: str = typer.Option(PACKAGE_VERSION, "--version"),
+    dry_run: bool = typer.Option(True, "--dry-run/--no-dry-run"),
+    execute: bool = typer.Option(False, "--execute"),
+    allow_execute: bool = typer.Option(False, "--allow-execute"),
+    root: Path = typer.Option(Path("."), "--root"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    """Plan release publishing without live tag/release side effects."""
+    plan = evaluate_release_publish_plan(
+        root.resolve(),
+        version=version,
+        dry_run=dry_run,
+        execute=execute,
+        allow_execute=allow_execute,
+    )
+    if json_output:
+        typer.echo(json.dumps(plan.as_dict(), indent=2, sort_keys=True))
+    else:
+        typer.echo(render_release_publish_plan(plan), nl=False)
+    if not plan.ok:
+        raise typer.Exit(code=plan.returncode)

agentic_project_kit/cli_commands/remote_branch_hygiene.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+from agentic_project_kit.remote_branch_hygiene import (
+    analyze_remote_branch_hygiene,
+    build_remote_branch_hygiene_evidence_report_payload,
+    collect_remote_branch_hygiene_inputs,
+    delete_remote_branch,
+    render_remote_branch_hygiene_report,
+    report_as_json_data,
+    write_remote_branch_hygiene_evidence_report,
+)
+
+
+def register_remote_branch_hygiene_command(app: typer.Typer) -> None:
+    app.command("remote-branch-hygiene")(remote_branch_hygiene_command)
+    app.command("remote-branch-hygiene-report")(remote_branch_hygiene_report_command)
+    app.command("remote-branch-hygiene-apply")(remote_branch_hygiene_apply_command)
+
+
+def remote_branch_hygiene_command(
+    project_root: Path = typer.Option(Path("."), "--root"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    """Dry-run remote branch hygiene classification for K3."""
+    remote_branches, open_pr_heads = collect_remote_branch_hygiene_inputs(project_root.resolve())
+    report = analyze_remote_branch_hygiene(remote_branches, open_pr_heads)
+    if json_output:
+        typer.echo(json.dumps(report_as_json_data(report), indent=2, sort_keys=True))
+    else:
+        typer.echo(render_remote_branch_hygiene_report(report), nl=False)
+
+def _assert_safe_output_path(project_root: Path, output_path: Path) -> Path:
+    resolved_root = project_root.resolve()
+    resolved = output_path.resolve()
+    safe_roots = (
+        resolved_root / "tmp",
+        resolved_root / "docs" / "reports",
+        resolved_root / ".agentic",
+    )
+    if not any(resolved == root or root in resolved.parents for root in safe_roots):
+        safe = ", ".join(str(root) for root in safe_roots)
+        raise typer.BadParameter(f"output path must be below one of: {safe}")
+    return resolved
+
+
+def remote_branch_hygiene_report_command(
+    project_root: Path = typer.Option(Path("."), "--root"),
+    output_path: Path = typer.Option(..., "--output"),
+    execute: bool = typer.Option(False, "--execute"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    """Write a K3 remote branch hygiene evidence report only with --execute."""
+    root = project_root.resolve()
+    remote_branches, open_pr_heads = collect_remote_branch_hygiene_inputs(root)
+    report = analyze_remote_branch_hygiene(remote_branches, open_pr_heads)
+    safe_output = _assert_safe_output_path(root, output_path)
+
+    if execute:
+        write_remote_branch_hygiene_evidence_report(safe_output, report)
+        mode = "execute"
+        mutation = "evidence-report-write"
+        written = True
+    else:
+        mode = "dry-run"
+        mutation = "none"
+        written = False
+
+    payload = {
+        "schema_version": 1,
+        "kind": "k3_remote_branch_hygiene_report_write_result",
+        "mode": mode,
+        "mutation": mutation,
+        "result_status": "PASS",
+        "written": written,
+        "output_path": str(safe_output),
+        "report": build_remote_branch_hygiene_evidence_report_payload(report),
+    }
+    if json_output:
+        typer.echo(json.dumps(payload, indent=2, sort_keys=True))
+    else:
+        typer.echo("K3_REMOTE_BRANCH_HYGIENE_REPORT")
+        typer.echo(f"MODE: {mode}")
+        typer.echo(f"MUTATION: {mutation}")
+        typer.echo(f"WRITTEN: {str(written).lower()}")
+        typer.echo(f"OUTPUT: {safe_output}")
+
+def _branch_name_is_single_remote_ref(branch: str) -> bool:
+    return branch.startswith("origin/") and branch not in {"origin", "origin/HEAD", "origin/main"} and "," not in branch
+
+
+def _find_safe_delete_candidate(report, branch: str):
+    if not _branch_name_is_single_remote_ref(branch):
+        raise typer.BadParameter("only must be one non-protected origin/<name> remote branch")
+    for finding in report.findings:
+        if finding.branch == branch:
+            if finding.proposed_action != "candidate-delete-merged-remote-branch":
+                raise typer.BadParameter(f"{branch} is not a safe delete candidate")
+            if finding.has_open_pr:
+                raise typer.BadParameter(f"{branch} is not a safe delete candidate")
+            if not finding.merged_to_origin_main:
+                raise typer.BadParameter(f"{branch} is not a safe delete candidate")
+            return finding
+    raise typer.BadParameter(f"branch not found in current hygiene report: {branch}")
+
+
+def remote_branch_hygiene_apply_command(
+    project_root: Path = typer.Option(Path("."), "--root"),
+    only: str = typer.Option(..., "--only"),
+    execute: bool = typer.Option(False, "--execute"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    """Safely apply exactly one remote branch deletion candidate."""
+    root = project_root.resolve()
+    remote_branches, open_pr_heads = collect_remote_branch_hygiene_inputs(root)
+    report = analyze_remote_branch_hygiene(remote_branches, open_pr_heads)
+    finding = _find_safe_delete_candidate(report, only)
+
+    if execute:
+        delete_remote_branch(root, finding.branch)
+        mode = "execute"
+        mutation = "delete-single-remote-branch"
+        deleted = True
+    else:
+        mode = "dry-run"
+        mutation = "none"
+        deleted = False
+
+    payload = {
+        "schema_version": 1,
+        "kind": "k3_remote_branch_hygiene_apply_result",
+        "mode": mode,
+        "mutation": mutation,
+        "result_status": "PASS",
+        "branch": finding.branch,
+        "short_name": finding.short_name,
+        "deleted": deleted,
+        "safety_class": finding.safety_class,
+        "reason": finding.reason,
+    }
+    if json_output:
+        typer.echo(json.dumps(payload, indent=2, sort_keys=True))
+    else:
+        typer.echo("K3_REMOTE_BRANCH_HYGIENE_APPLY")
+        typer.echo(f"MODE: {mode}")
+        typer.echo(f"MUTATION: {mutation}")
+        typer.echo(f"BRANCH: {finding.branch}")
+        typer.echo(f"DELETED: {str(deleted).lower()}")

agentic_project_kit/cli_commands/remote_next.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from agentic_project_kit.remote_next import (
+    remote_next_result_as_json_data,
+    render_remote_next_result,
+    run_remote_next,
+)
+from agentic_project_kit.remote_next_closeout import (
+    render_remote_next_closeout_result,
+    run_remote_next_closeout,
+)
+
+
+def register_remote_next_command(app: typer.Typer) -> None:
+    @app.command("remote-next")
+    def remote_next_command(
+        project_root: Annotated[Path, typer.Option("--root")] = Path("."),
+        json_output: Annotated[bool, typer.Option("--json", help="Print machine-readable JSON result.")] = False,
+    ) -> None:
+        result = run_remote_next(project_root)
+        if json_output:
+            typer.echo(json.dumps(remote_next_result_as_json_data(result), indent=2, sort_keys=True))
+        else:
+            typer.echo(render_remote_next_result(result))
+        if result.returncode != 0:
+            raise typer.Exit(code=result.returncode)
+
+    @app.command("rn")
+    def rn_command(
+        project_root: Annotated[Path, typer.Option("--root")] = Path("."),
+        json_output: Annotated[bool, typer.Option("--json", help="Print machine-readable JSON result.")] = False,
+    ) -> None:
+        result = run_remote_next(project_root)
+        if json_output:
+            typer.echo(json.dumps(remote_next_result_as_json_data(result), indent=2, sort_keys=True))
+        else:
+            typer.echo(render_remote_next_result(result))
+        if result.returncode != 0:
+            raise typer.Exit(code=result.returncode)
+
+    @app.command("rnc")
+    def rnc_command(
+        project_root: Annotated[Path, typer.Option("--root")] = Path("."),
+        no_push: Annotated[bool, typer.Option("--no-push", help="Commit locally without pushing.")] = False,
+    ) -> None:
+        result = run_remote_next_closeout(project_root, push=not no_push)
+        typer.echo(render_remote_next_closeout_result(result))
+        if result.status == "no_closeout":
+            raise typer.Exit(code=2)
+        if not result.success:
+            raise typer.Exit(code=1)