@homericintelligence/athena-opencode 0.5.0 → 0.5.2

package/skills/pr-review/scripts/pr_identity.py

@@ -1,4 +1,4 @@
-"""Validate pull-request identifiers shared by PR review helpers."""
+"""Validate pull-request identifiers shared by pull-request review helpers."""
 
 from __future__ import annotations
 
@@ -12,45 +12,51 @@ GITHUB_HOST = "github.com"
 
 
 def validate_pr_identifier(value: str) -> None:
-    """Require a positive PR number or canonical GitHub pull-request URL."""
+    """Require a positive pull-request number or a canonical GitHub pull-request URL."""
     if (value.isascii() and value.isdigit() and int(value) > 0) or PR_URL.fullmatch(
         value
     ):
         return
-    raise RuntimeError(f"invalid pull-request identifier: {value!r}")
+    raise RuntimeError(f"The pull-request identifier is not valid: {value!r}.")
 
 
 def require_commit_oid(value: object, label: str) -> str:
-    """Return one canonical immutable commit OID or fail closed."""
+    """Return one canonical immutable commit object identifier or fail closed."""
     if not isinstance(value, str) or COMMIT_OID.fullmatch(value) is None:
-        raise RuntimeError(f"{label} must be a lowercase 40-hex Git commit OID")
+        raise RuntimeError(
+            f"The value for {label} must be a Git commit object identifier that "
+            "contains 40 lowercase hexadecimal characters."
+        )
     return value
 
 
 def require_github_repository(value: object, label: str) -> str:
-    """Return a canonical owner/repository target or reject unsafe input."""
+    """Return a canonical GitHub repository or reject unsafe input."""
     if not isinstance(value, str) or GITHUB_REPOSITORY.fullmatch(value) is None:
-        raise RuntimeError(f"{label} must be a canonical GitHub owner/repository")
+        raise RuntimeError(
+            "The value for "
+            f"{label} must use the canonical GitHub OWNER/REPOSITORY format."
+        )
     return value
 
 
 def require_github_host(value: object, label: str) -> str:
     """Return the supported canonical GitHub hostname or fail closed."""
     if value != GITHUB_HOST:
-        raise RuntimeError(f"{label} must be {GITHUB_HOST}")
+        raise RuntimeError(f"The value for {label} must be '{GITHUB_HOST}'.")
     return GITHUB_HOST
 
 
 def canonical_pull_request_url(repository: object, number: object) -> str:
-    """Return one exact public-GitHub pull-request URL from trusted identity."""
+    """Return one exact public GitHub pull-request URL from a trusted identity."""
     canonical_repository = require_github_repository(repository, "repository")
     if isinstance(number, bool) or not isinstance(number, int) or number < 1:
-        raise RuntimeError("pull-request number must be a positive integer")
+        raise RuntimeError("The pull-request number must be a positive integer.")
     return f"https://{GITHUB_HOST}/{canonical_repository}/pull/{number}"
 
 
 def pull_request_number(value: str) -> int:
-    """Return the positive number encoded by a validated PR identifier."""
+    """Return the positive number in a validated pull-request identifier."""
     validate_pr_identifier(value)
     if value.isdigit():
         return int(value)
@@ -64,17 +70,23 @@ def require_canonical_pull_request_url(
     """Require the exact canonical URL for a retained pull-request identity."""
     canonical_url = canonical_pull_request_url(repository, number)
     if value != canonical_url:
-        raise RuntimeError(f"{label} must be the canonical GitHub pull-request URL")
+        raise RuntimeError(
+            f"The value for {label} must be the canonical GitHub pull-request URL."
+        )
     return canonical_url
 
 
 def repository_from_pr_url(url: str, number: int) -> str:
-    """Return owner/repository after validating a canonical PR URL and number."""
+    """Return the repository from a canonical pull-request URL and number."""
     parsed_url = urlparse(url)
     path_parts = parsed_url.path.strip("/").split("/")
     if len(path_parts) != 4 or path_parts[2] != "pull" or path_parts[3] != str(number):
-        raise RuntimeError(f"GitHub returned invalid pull-request URL: {url}")
+        raise RuntimeError(
+            f"GitHub returned a pull-request URL that is not valid: '{url}'."
+        )
     repository = "/".join(path_parts[:2])
     if url != canonical_pull_request_url(repository, number):
-        raise RuntimeError(f"GitHub returned invalid pull-request URL: {url}")
+        raise RuntimeError(
+            f"GitHub returned a pull-request URL that is not valid: '{url}'."
+        )
     return repository

package/skills/pr-review/scripts/resolve_pr.py

@@ -1,17 +1,15 @@
 #!/usr/bin/env python3
-"""Resolve an explicit PR or the sole open PR for the current branch."""
+"""Resolve an explicit pull request or the only open pull request for the current branch."""
 
 from __future__ import annotations
 
+import importlib.util
 import json
 import sys
 from collections.abc import Sequence
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any
-
-if __package__ in {None, ""}:
-    sys.path.insert(0, str(Path(__file__).resolve().parents[3]))
+from typing import TYPE_CHECKING, Any
 
 from pr_identity import (
     canonical_pull_request_url,
@@ -23,38 +21,59 @@ from pr_identity import (
     validate_pr_identifier,
 )
 
-from skills._cli import (
-    argument_parser,
-    git_read_arguments,
-    git_read_environment,
-    run_command,
-)
+if TYPE_CHECKING or __package__ not in {None, ""}:
+    from skills._cli import (
+        argument_parser,
+        git_read_arguments,
+        git_read_environment,
+        run_command,
+    )
+else:
+    _cli_path = Path(__file__).resolve().parents[2] / "_cli.py"
+    _cli_spec = importlib.util.spec_from_file_location(
+        "athena_installed_cli", _cli_path
+    )
+    if _cli_spec is None or _cli_spec.loader is None:
+        raise RuntimeError(
+            f"The installed Athena CLI helper is unavailable: '{_cli_path}'."
+        )
+    _cli = importlib.util.module_from_spec(_cli_spec)
+    _cli_spec.loader.exec_module(_cli)
+    argument_parser = _cli.argument_parser
+    git_read_arguments = _cli.git_read_arguments
+    git_read_environment = _cli.git_read_environment
+    run_command = _cli.run_command
 
 FIELDS = "number,url,state,headRefName,baseRefName,headRefOid,baseRefOid"
 
 
 @dataclass(frozen=True)
 class RepositoryTarget:
-    """A forge target supplied without ambient CLI or checkout inference."""
+    """The workflow gets this forge target from explicit input.
+
+    It does not infer the target from the checkout.
+    """
 
     host: str
     repository: str
 
     def repository_argument(self) -> str:
-        """Return the fully qualified repository target accepted by gh."""
+        """Return the fully qualified repository target for the GitHub CLI."""
         return f"{self.host}/{self.repository}"
 
 
 def command(*arguments: str) -> str:
     result = run_command(arguments, capture_output=True, text=True, check=False)
     if result.returncode != 0:
-        message = result.stderr.strip() or f"command failed: {' '.join(arguments)}"
+        message = result.stderr.strip() or (
+            f"The command failed. Command: {' '.join(arguments)}"
+        )
         raise RuntimeError(message)
     return result.stdout
 
 
 def current_branch() -> str:
-    """Return the current branch through the hermetic Git read boundary."""
+    """Return the current branch through the isolated Git read boundary."""
     result = run_command(
         ["git", *git_read_arguments(), "branch", "--show-current"],
         capture_output=True,
@@ -63,7 +82,9 @@ def current_branch() -> str:
         check=False,
     )
     if result.returncode != 0:
-        message = result.stderr.strip() or "git branch --show-current failed"
+        message = (
+            result.stderr.strip() or "The git branch --show-current command failed."
+        )
         raise RuntimeError(message)
     return result.stdout.strip()
 
@@ -71,7 +92,7 @@ def current_branch() -> str:
 def load_object(output: str) -> dict[str, Any]:
     value = json.loads(output)
     if not isinstance(value, dict):
-        raise TypeError("GitHub returned an invalid pull-request object")
+        raise TypeError("GitHub returned a pull-request object that is not valid.")
     return value
 
 
@@ -81,18 +102,18 @@ def target_from_arguments(
     host: str | None,
     repository: str | None,
 ) -> RepositoryTarget:
-    """Resolve a trusted target from explicit flags or one canonical PR URL."""
+    """Resolve a trusted target from explicit options or one canonical pull-request URL."""
 
     def identity_from_url(value: str) -> tuple[int, str]:
         try:
             number = pull_request_number(value)
             return number, repository_from_pr_url(value, number)
         except RuntimeError as error:
-            parser.error(f"invalid pull-request URL: {error}")
-        raise AssertionError("argument parser returned after a URL error")
+            parser.error(f"The pull-request URL is not valid: {error}")
+        raise AssertionError("The argument parser returned after a URL error.")
 
     if (host is None) != (repository is None):
-        parser.error("--target-host and --target-repository must be supplied together")
+        parser.error("Specify --target-host and --target-repository together.")
     if host is not None and repository is not None:
         try:
             target = RepositoryTarget(
@@ -104,7 +125,9 @@ def target_from_arguments(
         if identifier is not None and identifier.startswith("https://"):
             _, supplied_repository = identity_from_url(identifier)
             if supplied_repository.casefold() != target.repository.casefold():
-                parser.error("pull-request URL does not match --target-repository")
+                parser.error(
+                    "The pull-request URL does not match '--target-repository'."
+                )
         return target
     if identifier is not None and identifier.startswith("https://"):
         _, repository = identity_from_url(identifier)
@@ -113,20 +136,22 @@ def target_from_arguments(
             repository=repository,
         )
     parser.error(
-        "numeric pull requests and branch discovery require --target-host and "
-        "--target-repository"
+        "For a numeric pull-request identifier or branch discovery, specify "
+        "'--target-host' and '--target-repository'."
     )
-    raise AssertionError("argument parser returned after a target error")
+    raise AssertionError("The argument parser returned after a target error.")
 
 
 def _resolve_open_pr(identifier: str, target: RepositoryTarget) -> dict[str, Any]:
-    """Return the complete metadata for one explicitly identified open PR."""
+    """Return complete metadata for one explicitly identified pull request."""
     validate_pr_identifier(identifier)
     number = pull_request_number(identifier)
     if identifier.startswith("https://"):
         supplied_repository = repository_from_pr_url(identifier, number)
         if supplied_repository.casefold() != target.repository.casefold():
-            raise RuntimeError("pull-request URL does not match the retained target")
+            raise RuntimeError(
+                "The pull-request URL does not match the retained target."
+            )
     pull_request = load_object(
         command(
             "gh",
@@ -140,12 +165,14 @@ def _resolve_open_pr(identifier: str, target: RepositoryTarget) -> dict[str, Any
         )
     )
     if pull_request.get("state") != "OPEN":
-        raise RuntimeError(f"pull request {identifier} is not open")
+        raise RuntimeError(f"The pull request is not open: '{identifier}'.")
     if pull_request.get("number") != number:
-        raise RuntimeError("GitHub returned a pull request different from the request")
+        raise RuntimeError(
+            "GitHub returned a pull request that differs from the request."
+        )
     for field in ("baseRefOid", "headRefOid"):
         require_commit_oid(
-            pull_request.get(field), f"GitHub immutable PR revision {field}"
+            pull_request.get(field), f"GitHub immutable pull-request revision {field}"
         )
     return pull_request
 
@@ -153,18 +180,21 @@ def _resolve_open_pr(identifier: str, target: RepositoryTarget) -> dict[str, Any
 def _validate_repository_identity(
     pull_request: dict[str, Any], target: RepositoryTarget
 ) -> None:
-    """Reject a PR URL that differs from the retained explicit forge target."""
+    """Reject a pull-request URL that differs from the retained forge target."""
     number = pull_request.get("number")
     url = pull_request.get("url")
     if not isinstance(number, int) or not isinstance(url, str):
-        raise TypeError("GitHub returned incomplete pull-request identity")
+        raise TypeError("GitHub returned an incomplete pull-request identity.")
     pull_repository = repository_from_pr_url(url, number)
     if pull_repository.casefold() != target.repository.casefold():
         raise RuntimeError(
-            f"pull request {url} does not belong to target repository {target.repository}"
+            f"The pull request {url} is not in the target repository "
+            f"'{target.repository}'."
         )
     if url != canonical_pull_request_url(target.repository, number):
-        raise RuntimeError(f"GitHub returned invalid pull-request URL: {url}")
+        raise RuntimeError(
+            f"GitHub returned a pull-request URL that is not valid: '{url}'."
+        )
     pull_request["review_target"] = {
         "host": target.host,
         "kind": "github",
@@ -180,7 +210,9 @@ def resolve(explicit: str | None, target: RepositoryTarget) -> dict[str, Any]:
 
     branch = current_branch()
     if not branch:
-        raise RuntimeError("current checkout is detached; provide a PR number or URL")
+        raise RuntimeError(
+            "The current checkout is detached. Specify a pull-request number or URL."
+        )
     raw_candidates = json.loads(
         command(
             "gh",
@@ -199,20 +231,24 @@ def resolve(explicit: str | None, target: RepositoryTarget) -> dict[str, Any]:
         )
     )
     if not isinstance(raw_candidates, list):
-        raise TypeError("GitHub returned an invalid pull-request list")
+        raise TypeError("GitHub returned a pull-request list that is not valid.")
     candidates = [item for item in raw_candidates if isinstance(item, dict)]
     if len(candidates) == 1:
         number = candidates[0].get("number")
         if not isinstance(number, int) or number < 1:
-            raise RuntimeError("GitHub returned an invalid pull-request candidate")
+            raise RuntimeError(
+                "GitHub returned a pull-request candidate that is not valid."
+            )
         return _resolve_open_pr(str(number), target)
     if not candidates:
-        raise LookupError(f"no open pull request found for branch {branch!r}")
+        raise LookupError(f"GitHub found no open pull request for branch {branch!r}.")
     rendered = "\n".join(
         f"  #{candidate.get('number')}: {candidate.get('url')}"
         for candidate in candidates
     )
-    raise ValueError(f"multiple open pull requests found for {branch!r}:\n{rendered}")
+    raise ValueError(
+        f"GitHub found multiple open pull requests for {branch!r}.\n{rendered}"
+    )
 
 
 def main(argv: Sequence[str] | None = None) -> int:
@@ -220,12 +256,12 @@ def main(argv: Sequence[str] | None = None) -> int:
     parser.add_argument(
         "--target-host",
         metavar="HOST",
-        help="canonical GitHub host from the configured forge capability",
+        help="Use the canonical GitHub host from the configured forge capability.",
     )
     parser.add_argument(
         "--target-repository",
         metavar="OWNER/REPOSITORY",
-        help="canonical GitHub repository from the configured forge capability",
+        help="Use the canonical GitHub repository from the configured forge capability.",
     )
     parser.add_argument("pull_request", nargs="?", metavar="PR_NUMBER_OR_URL")
     arguments = parser.parse_args(argv)