yaga-cli 0.1.0__py3-none-any.whl

yaga/__init__.py

@@ -0,0 +1 @@
+"""Extensible developer workflow automation for local and CI use."""

yaga/__main__.py

@@ -0,0 +1,27 @@
+"""Select the installed CLI or dependency-free composite Action boundary."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+if (
+    os.environ.get("YAGA_ACTION_RUNTIME") == "1"
+    and os.environ.get("YAGA_COMMIT_ACTION_RUNTIME") == "1"
+):
+    print("YAGA failed: multiple Action runtimes were selected", file=sys.stderr)
+    raise SystemExit(2)
+
+if os.environ.get("YAGA_ACTION_RUNTIME") == "1":
+    from yaga.action_cli import main
+
+    raise SystemExit(main())
+
+if os.environ.get("YAGA_COMMIT_ACTION_RUNTIME") == "1":
+    from yaga.commit_action_cli import main
+
+    raise SystemExit(main())
+
+from yaga.cli import main
+
+main()

yaga/_update_worker.py

@@ -0,0 +1,65 @@
+"""Standalone Windows update worker, copied outside the environment before replacement."""
+
+from __future__ import annotations
+
+import ctypes
+import subprocess
+import sys
+from ctypes import wintypes
+from pathlib import Path
+
+
+def main() -> int:
+    if sys.platform != "win32":
+        return 2
+    kernel = ctypes.WinDLL("kernel32", use_last_error=True)
+    kernel.OpenProcess.argtypes = [wintypes.DWORD, wintypes.BOOL, wintypes.DWORD]
+    kernel.OpenProcess.restype = wintypes.HANDLE
+    kernel.WaitForSingleObject.argtypes = [wintypes.HANDLE, wintypes.DWORD]
+    kernel.WaitForSingleObject.restype = wintypes.DWORD
+    kernel.CloseHandle.argtypes = [wintypes.HANDLE]
+    kernel.QueryFullProcessImageNameW.argtypes = [
+        wintypes.HANDLE,
+        wintypes.DWORD,
+        wintypes.LPWSTR,
+        ctypes.POINTER(wintypes.DWORD),
+    ]
+    handles = []
+    try:
+        for index, raw_pid in enumerate(sys.argv[2:4]):
+            handle = kernel.OpenProcess(0x00100000 | 0x1000, False, int(raw_pid))
+            if not handle:
+                if ctypes.get_last_error() == 87:  # The process already exited.
+                    continue
+                raise OSError("cannot wait for the YAGA process to exit")
+            handles.append(handle)
+            if index == 1:
+                name = ctypes.create_unicode_buffer(32768)
+                size = wintypes.DWORD(len(name))
+                if not kernel.QueryFullProcessImageNameW(handle, 0, name, ctypes.byref(size)):
+                    raise OSError("cannot identify the YAGA launcher")
+                if Path(name.value).name.casefold() != "yaga.exe":
+                    continue  # python -m yaga has no launcher; never wait for the user's shell.
+            if kernel.WaitForSingleObject(handle, 60000) != 0:
+                raise OSError("YAGA did not exit within the update handoff timeout")
+        result = subprocess.run(
+            [sys.argv[1], "--no-config", "tool", "upgrade", "yaga-cli"],
+            timeout=600,
+            check=False,
+        )
+        print(f"YAGA_UPDATE_EXIT_CODE={result.returncode}", flush=True)
+        return result.returncode
+    except (OSError, subprocess.SubprocessError) as error:
+        print(
+            f"YAGA update failed: {type(error).__name__}; run uv tool upgrade yaga-cli", flush=True
+        )
+        print("YAGA_UPDATE_EXIT_CODE=2", flush=True)
+        return 2
+    finally:
+        for handle in handles:
+            kernel.CloseHandle(handle)
+        Path(__file__).unlink(missing_ok=True)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

yaga/action.py

@@ -0,0 +1,24 @@
+"""Strict public inputs for the YAGA composite action."""
+
+from __future__ import annotations
+
+from yaga.agent_review.runtime import operation_name, run_action
+from yaga.errors import GateError
+
+SUPPORTED_GATES = frozenset({"agent-review"})
+
+
+def gate_name(value: object) -> str:
+    """Accept only a deliberately implemented gate."""
+    if not isinstance(value, str) or value not in SUPPORTED_GATES:
+        raise GateError("gate is invalid")
+    return value
+
+
+def run_gate(gate: object, operation: object) -> int:
+    """Run one closed gate operation through the shared dispatcher."""
+    selected_gate = gate_name(gate)
+    selected_operation = operation_name(operation)
+    if selected_gate == "agent-review":
+        return run_action(selected_operation)
+    raise GateError("gate is invalid")  # pragma: no cover - gate_name is closed above

yaga/action_cli.py

@@ -0,0 +1,25 @@
+"""Dependency-free command boundary used by the composite Action."""
+
+from __future__ import annotations
+
+import sys
+
+from yaga.action import run_gate
+from yaga.errors import GateError, safe_error_text
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Accept exactly one closed Action command and dispatch it fail-closed."""
+    arguments = list(sys.argv[1:] if argv is None else argv)
+    if len(arguments) != 3 or arguments[0] != "gate":
+        print("YAGA failed: action command is invalid", file=sys.stderr)
+        return 1
+    try:
+        return run_gate(arguments[1], arguments[2])
+    except GateError as error:
+        print(f"YAGA failed: {safe_error_text(error)}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

yaga/agent_review/__init__.py

@@ -0,0 +1,34 @@
+"""Provider-neutral Agent review policy models and validation."""
+
+from yaga.agent_review.evaluation import LensOutcome, ReviewAggregate, evaluate_policy
+from yaga.agent_review.plan import ReviewPlan, ReviewPlanItem, build_plan, render_plan
+from yaga.agent_review.policy import AgentReviewPolicy, ReviewLens, load_policy
+from yaga.agent_review.results import (
+    AgentReviewResults,
+    LensResult,
+    build_pending_results,
+    evaluate_results,
+    load_results,
+    render_evaluation,
+    render_results_template,
+)
+
+__all__ = [
+    "AgentReviewPolicy",
+    "AgentReviewResults",
+    "LensOutcome",
+    "ReviewAggregate",
+    "ReviewLens",
+    "ReviewPlan",
+    "ReviewPlanItem",
+    "LensResult",
+    "build_plan",
+    "build_pending_results",
+    "evaluate_policy",
+    "evaluate_results",
+    "load_policy",
+    "load_results",
+    "render_plan",
+    "render_evaluation",
+    "render_results_template",
+]

yaga/agent_review/evaluation.py

@@ -0,0 +1,93 @@
+"""Provider-neutral evaluation of named Agent review outcomes."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from enum import StrEnum
+
+from yaga.agent_review.policy import AgentReviewPolicy
+from yaga.errors import ConfigurationError
+
+
+class LensOutcome(StrEnum):
+    """Closed outcome states emitted by provider adapters."""
+
+    PASSED = "passed"
+    FAILED = "failed"
+    PENDING = "pending"
+
+
+@dataclass(frozen=True, slots=True)
+class ReviewAggregate:
+    """Deterministic policy result with separate blocking and advisory details."""
+
+    state: LensOutcome
+    blocking_failures: tuple[str, ...]
+    blocking_pending: tuple[str, ...]
+    advisory_failures: tuple[str, ...]
+    advisory_pending: tuple[str, ...]
+
+
+def evaluate_policy(
+    policy: AgentReviewPolicy,
+    outcomes: Mapping[str, LensOutcome | str],
+) -> ReviewAggregate:
+    """Aggregate exact named-lens outcomes without letting advisory lenses block."""
+    if not isinstance(policy, AgentReviewPolicy):
+        raise TypeError("policy must be an AgentReviewPolicy")
+    if not isinstance(outcomes, Mapping):
+        raise TypeError("outcomes must be a mapping")
+    if any(not isinstance(name, str) for name in outcomes):
+        raise ConfigurationError("Agent review outcome names must be strings")
+    known = {lens.name for lens in policy.lenses}
+    unknown = sorted(set(outcomes) - known)
+    if unknown:
+        raise ConfigurationError(f"Agent review outcome names unknown lens {unknown[0]}")
+    normalized: dict[str, LensOutcome] = {}
+    for name, value in outcomes.items():
+        try:
+            normalized[name] = LensOutcome(value)
+        except (TypeError, ValueError) as error:
+            raise ConfigurationError(f"Agent review outcome for {name} is invalid") from error
+
+    advisory_names = tuple(lens.name for lens in policy.lenses if lens.name not in policy.required)
+    blocking_failures = tuple(
+        name for name in policy.required if normalized.get(name) is LensOutcome.FAILED
+    )
+    blocking_pending = tuple(
+        name
+        for name in policy.required
+        if normalized.get(name, LensOutcome.PENDING) is LensOutcome.PENDING
+    )
+    advisory_failures = tuple(
+        name for name in advisory_names if normalized.get(name) is LensOutcome.FAILED
+    )
+    advisory_pending = tuple(
+        name
+        for name in advisory_names
+        if normalized.get(name, LensOutcome.PENDING) is LensOutcome.PENDING
+    )
+    if policy.aggregation == "all-required":
+        state = (
+            LensOutcome.FAILED
+            if blocking_failures
+            else LensOutcome.PENDING
+            if blocking_pending
+            else LensOutcome.PASSED
+        )
+    else:
+        state = (
+            LensOutcome.PASSED
+            if any(normalized.get(name) is LensOutcome.PASSED for name in policy.required)
+            else LensOutcome.FAILED
+            if not blocking_pending and len(blocking_failures) == len(policy.required)
+            else LensOutcome.PENDING
+        )
+    return ReviewAggregate(
+        state,
+        blocking_failures,
+        blocking_pending,
+        advisory_failures,
+        advisory_pending,
+    )

yaga/agent_review/github/__init__.py

@@ -0,0 +1 @@
+"""GitHub provider adapter for the provider-neutral Agent review gate."""

yaga/agent_review/github/boundary.py

@@ -0,0 +1,292 @@
+"""Authenticate the lifecycle boundary carried by YAGA commit statuses."""
+
+from __future__ import annotations
+
+import re
+import urllib.parse
+from dataclasses import dataclass
+from datetime import datetime
+
+from yaga.agent_review.github.constants import (
+    CODEX_STATUS_CONTEXT,
+    EVENT_ACTIONS,
+    GITHUB_ACTIONS_LOGIN,
+    GITHUB_ACTIONS_USER_ID,
+    MAX_WORKFLOW_RUN_RECORDS,
+)
+from yaga.errors import GateError
+from yaga.github import RestApi
+from yaga.models import (
+    commit_sha,
+    positive_int,
+    record,
+    repository_name,
+    timestamp,
+    workflow_path,
+)
+from yaga.status import CommitStatus
+
+_ACTION_CODES = {
+    "closed": "c",
+    "converted_to_draft": "d",
+    "edited": "e",
+    "opened": "o",
+    "ready_for_review": "y",
+    "reopened": "r",
+    "synchronize": "s",
+}
+_ACTIONS_BY_CODE = {code: action for action, code in _ACTION_CODES.items()}
+_PHASE_CODES = {
+    "CI pending": "CP",
+    "Codex pending": "RP",
+    "Codex passed": "RS",
+    "Codex failed": "RF",
+    "CI passed": "CS",
+    "CI failed": "CF",
+}
+_PHASES_BY_CODE = {code: phase for phase, code in _PHASE_CODES.items()}
+_DESCRIPTION_RE = re.compile(
+    r"\AYAGA boundary (?P<run>[1-9][0-9]{0,18})/(?P<attempt>[1-9][0-9]{0,3}) "
+    r"(?P<action>[cdeorys]) PR (?P<pr>[1-9][0-9]{0,18}) "
+    r"base (?P<base>[0-9a-f]{40}) at (?P<time>[^\r\n]{10,40}) "
+    r"(?P<phase>CP|RP|RS|RF|CS|CF)\Z"
+)
+_BOUNDARY_TITLE_RE = re.compile(
+    r"\AYAGA (?P<action>closed|converted_to_draft|edited|opened|ready_for_review|reopened|synchronize) "
+    r"boundary for #(?P<pr>[1-9][0-9]{0,18})\Z"
+)
+_METADATA_TITLE_RE = re.compile(r"\AYAGA metadata edit for #(?P<pr>[1-9][0-9]{0,18})\Z")
+
+
+@dataclass(frozen=True)
+class ReviewBoundary:
+    """Exact trusted lifecycle transition shared by all publisher stages."""
+
+    run_id: int
+    run_attempt: int
+    action: str
+    pull_request_number: int
+    head_sha: str
+    base_sha: str
+    occurred_at: datetime
+
+
+def boundary_description(boundary: ReviewBoundary, phase: str) -> str:
+    """Encode a human-readable, strictly parseable status description."""
+    if phase not in _PHASE_CODES or boundary.action not in _ACTION_CODES:
+        raise GateError("YAGA boundary phase is invalid")
+    attempt = positive_int(boundary.run_attempt, "boundary attempt")
+    if attempt > 9_999:
+        raise GateError("YAGA boundary attempt is too large")
+    occurred_at = boundary.occurred_at.isoformat(timespec="seconds").replace("+00:00", "Z")
+    description = (
+        f"YAGA boundary {positive_int(boundary.run_id, 'boundary run')}/{attempt} "
+        f"{_ACTION_CODES[boundary.action]} PR "
+        f"{positive_int(boundary.pull_request_number, 'boundary PR')} "
+        f"base {commit_sha(boundary.base_sha, 'boundary base')} at {occurred_at} "
+        f"{_PHASE_CODES[phase]}"
+    )
+    if len(description) > 140:
+        raise GateError("YAGA boundary description is too long")
+    return description
+
+
+def parse_boundary_description(
+    status: CommitStatus,
+    *,
+    head_sha: str,
+) -> tuple[ReviewBoundary, str] | None:
+    """Parse an untrusted boundary claim from one status description."""
+    if status.description is None:
+        return None
+    match = _DESCRIPTION_RE.fullmatch(status.description)
+    if match is None:
+        return None
+    try:
+        action = _ACTIONS_BY_CODE.get(match.group("action"))
+        if action not in EVENT_ACTIONS:
+            return None
+        boundary = ReviewBoundary(
+            run_id=positive_int(int(match.group("run")), "boundary run"),
+            run_attempt=positive_int(int(match.group("attempt")), "boundary attempt"),
+            action=action,
+            pull_request_number=positive_int(int(match.group("pr")), "boundary PR"),
+            head_sha=commit_sha(head_sha, "boundary head"),
+            base_sha=commit_sha(match.group("base"), "boundary base"),
+            occurred_at=timestamp(match.group("time"), "boundary occurrence"),
+        )
+    except (ValueError, GateError):
+        return None
+    phase = _PHASES_BY_CODE.get(match.group("phase"))
+    return (boundary, phase) if phase is not None else None
+
+
+def _attempt_url(
+    server_url: str,
+    repository: str,
+    run_id: int,
+    run_attempt: int,
+) -> str:
+    parsed = urllib.parse.urlsplit(server_url)
+    if (
+        parsed.scheme != "https"
+        or not parsed.netloc
+        or parsed.username is not None
+        or parsed.password is not None
+        or parsed.path not in {"", "/"}
+        or parsed.query
+        or parsed.fragment
+    ):
+        raise GateError("GitHub server URL is invalid")
+    return (
+        f"{parsed.scheme}://{parsed.netloc}/{repository}/actions/runs/"
+        f"{run_id}/attempts/{run_attempt}"
+    )
+
+
+def validate_boundary_source(
+    api: RestApi,
+    *,
+    repository: str,
+    lifecycle_workflow: str,
+    server_url: str,
+    boundary: ReviewBoundary,
+    provenance_status: CommitStatus,
+) -> datetime:
+    """Require the pending provenance and return its trusted run update time."""
+    repository = repository_name(repository)
+    lifecycle_workflow = workflow_path(lifecycle_workflow, "lifecycle workflow")
+    if (
+        provenance_status.context != CODEX_STATUS_CONTEXT
+        or provenance_status.state != "pending"
+        or provenance_status.creator_id != GITHUB_ACTIONS_USER_ID
+        or provenance_status.creator_login != GITHUB_ACTIONS_LOGIN
+        or provenance_status.target_url
+        != _attempt_url(
+            server_url,
+            repository,
+            boundary.run_id,
+            boundary.run_attempt,
+        )
+    ):
+        raise GateError("lifecycle boundary status provenance is invalid")
+    parsed = parse_boundary_description(provenance_status, head_sha=boundary.head_sha)
+    if parsed is None or parsed != (boundary, "CI pending"):
+        raise GateError("lifecycle boundary status does not carry the expected boundary")
+
+    payload = record(
+        api.get(f"/repos/{repository}/actions/runs/{boundary.run_id}"),
+        "lifecycle workflow run",
+    )
+    run_repository = record(payload.get("repository"), "lifecycle workflow repository")
+    if (
+        payload.get("id") != boundary.run_id
+        or payload.get("run_attempt") != boundary.run_attempt
+        or payload.get("path") != lifecycle_workflow
+        or payload.get("event") != "pull_request_target"
+        or payload.get("status") != "completed"
+        or payload.get("conclusion") != "success"
+        or payload.get("head_sha") != boundary.head_sha
+        or run_repository.get("full_name") != repository
+        or payload.get("display_title")
+        != f"YAGA {boundary.action} boundary for #{boundary.pull_request_number}"
+    ):
+        raise GateError("lifecycle boundary workflow run is not trusted")
+    created_at = timestamp(payload.get("created_at"), "lifecycle workflow creation")
+    updated_at = timestamp(payload.get("updated_at"), "lifecycle workflow update")
+    if (
+        updated_at < created_at
+        or boundary.occurred_at > created_at
+        or provenance_status.created_at < created_at
+    ):
+        raise GateError("lifecycle boundary timing is invalid")
+
+    run_number = positive_int(payload.get("run_number"), "lifecycle workflow number")
+    current_position = (run_number, boundary.run_attempt, boundary.run_id)
+    query = urllib.parse.urlencode(
+        {
+            "event": "pull_request_target",
+            "head_sha": boundary.head_sha,
+            "page": "1",
+            "per_page": str(MAX_WORKFLOW_RUN_RECORDS),
+        }
+    )
+    filename = lifecycle_workflow.rsplit("/", 1)[1]
+    listing = record(
+        api.get(f"/repos/{repository}/actions/workflows/{filename}/runs?{query}"),
+        "lifecycle workflow runs",
+    )
+    count = listing.get("total_count")
+    runs = listing.get("workflow_runs")
+    if (
+        isinstance(count, bool)
+        or not isinstance(count, int)
+        or count < 0
+        or not isinstance(runs, list)
+        or count != len(runs)
+        or count >= MAX_WORKFLOW_RUN_RECORDS
+    ):
+        raise GateError("lifecycle workflow run list is incomplete or invalid")
+    seen: set[int] = set()
+    current_seen = False
+    for index, value in enumerate(runs):
+        item = record(value, f"lifecycle workflow run {index}")
+        item_repository = record(
+            item.get("repository"),
+            f"lifecycle workflow run {index} repository",
+        )
+        run_id = positive_int(item.get("id"), f"lifecycle workflow run {index} ID")
+        if run_id in seen:
+            raise GateError("lifecycle workflow run ID is repeated")
+        seen.add(run_id)
+        if (
+            item.get("path") != lifecycle_workflow
+            or item.get("event") != "pull_request_target"
+            or item.get("head_sha") != boundary.head_sha
+            or item_repository.get("full_name") != repository
+        ):
+            raise GateError("lifecycle workflow run list contains an untrusted run")
+        position = (
+            positive_int(item.get("run_number"), f"lifecycle workflow run {index} number"),
+            positive_int(item.get("run_attempt"), f"lifecycle workflow run {index} attempt"),
+            run_id,
+        )
+        title = item.get("display_title")
+        boundary_title = _BOUNDARY_TITLE_RE.fullmatch(title) if isinstance(title, str) else None
+        metadata_title = _METADATA_TITLE_RE.fullmatch(title) if isinstance(title, str) else None
+        title_pr = (
+            boundary_title.group("pr")
+            if boundary_title is not None
+            else metadata_title.group("pr")
+            if metadata_title is not None
+            else None
+        )
+        if title_pr is None or positive_int(int(title_pr), "lifecycle title PR") != (
+            boundary.pull_request_number
+        ):
+            raise GateError("lifecycle workflow run title is invalid")
+        current_seen |= position == current_position
+        if position > current_position and metadata_title is None:
+            raise GateError("a newer lifecycle boundary exists for this head")
+    if not current_seen:
+        raise GateError("lifecycle boundary is outside the bounded run window")
+    return updated_at
+
+
+def same_boundary(left: ReviewBoundary, right: ReviewBoundary) -> bool:
+    """Compare stable identity while ignoring the provenance status timestamp."""
+    return (
+        left.run_id,
+        left.run_attempt,
+        left.action,
+        left.pull_request_number,
+        left.head_sha,
+        left.base_sha,
+    ) == (
+        right.run_id,
+        right.run_attempt,
+        right.action,
+        right.pull_request_number,
+        right.head_sha,
+        right.base_sha,
+    )