alissa-tools-github-devloop 0.7.0__tar.gz → 0.8.0__tar.gz

{alissa_tools_github_devloop-0.7.0/src/main/alissa_tools_github_devloop.egg-info → alissa_tools_github_devloop-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-devloop
-Version: 0.7.0
+Version: 0.8.0
 Summary: ALISSA-TOOLS-GITHUB-DEVLOOP
 Home-page: https://alissa.app
 Author: Fahera

{alissa_tools_github_devloop-0.7.0 → alissa_tools_github_devloop-0.8.0}/src/main/alissa/tools/github/devloop/__main__.py

@@ -191,6 +191,32 @@ def build_parser() -> argparse.ArgumentParser:
         "wedge self-heal fires; 0 = use stale_minutes (the default)",
     )
 
+    orphan = over.add_mutually_exclusive_group()
+    orphan.add_argument(
+        "--orphan-sweep",
+        dest="orphan_sweep_enabled",
+        action="store_true",
+        default=None,
+        help="complete the handoff of a DRAFT PR whose session died before "
+        "readying it: once no worker session for it is listed and its head "
+        "has been public past the grace window, mark it ready and request the "
+        "configured reviewer(s), once per PR/head (the default)",
+    )
+    orphan.add_argument(
+        "--no-orphan-sweep",
+        dest="orphan_sweep_enabled",
+        action="store_false",
+        help="never complete a draft's handoff mechanically — an unhanded-off "
+        "draft waits for an operator (also narrows the PR search to non-drafts)",
+    )
+    over.add_argument(
+        "--orphan-grace-minutes",
+        type=int,
+        metavar="MINUTES",
+        help="how long the draft's head must have been public before the "
+        "orphan sweep fires; 0 = use stale_minutes (the default)",
+    )
+
     claims = over.add_mutually_exclusive_group()
     claims.add_argument(
         "--activity-claims",
@@ -249,6 +275,8 @@ def overrides_from(args: argparse.Namespace) -> dict:
         "resume_enabled": args.resume_enabled,
         "rerequest_enabled": args.rerequest_enabled,
         "rerequest_grace_minutes": args.rerequest_grace_minutes,
+        "orphan_sweep_enabled": args.orphan_sweep_enabled,
+        "orphan_grace_minutes": args.orphan_grace_minutes,
         "activity_claims_enabled": args.activity_claims_enabled,
         "dry_run": args.dry_run,
     }
@@ -282,7 +310,8 @@ def log_effective_config(config: Config, login: str) -> None:
     log.info(
         "poll every %ss; dry_run=%s; attempt_cap=%s; stale after %s min; "
         "max_sessions=%s; fix_rounds=%s; maintain=%s (label %r); resume=%s; "
-        "rerequest=%s (grace %s min); activity_claims=%s",
+        "rerequest=%s (grace %s min); orphan_sweep=%s (grace %s min); "
+        "activity_claims=%s",
         config.poll_interval, config.dry_run, config.attempt_cap,
         config.stale_minutes,
         config.max_sessions or "unlimited",
@@ -291,6 +320,8 @@ def log_effective_config(config: Config, login: str) -> None:
         config.resume_enabled,
         config.rerequest_enabled,
         config.rerequest_grace_seconds // 60,
+        config.orphan_sweep_enabled,
+        config.orphan_grace_seconds // 60,
         config.activity_claims_enabled,
     )
     log.debug("hub_template: %s", config.hub_template)

{alissa_tools_github_devloop-0.7.0 → alissa_tools_github_devloop-0.8.0}/src/main/alissa/tools/github/devloop/config.py

@@ -65,6 +65,8 @@ CONFIG_KEYS = (
     "resume_enabled",
     "rerequest_enabled",
     "rerequest_grace_minutes",
+    "orphan_sweep_enabled",
+    "orphan_grace_minutes",
     "activity_claims_enabled",
     "dry_run",
 )
@@ -207,6 +209,30 @@ class Config:
     # positive value to widen or narrow it independently.
     rerequest_grace_minutes: int = 0
 
+    # The orphan-draft sweep (issue #68), the ready-flip sibling of the wedge
+    # self-heal above. That one completes a dead session's terminal act on a
+    # PR already in review; this one completes the act that PUTS a PR in
+    # review. A developer session's handoff is `gh pr ready` then a review
+    # request, and a session that died before both leaves a DRAFT nothing owns:
+    # the reviewer daemon sees only PRs with a request on them, the fix edge
+    # refuses drafts outright, and the issue-edge resume keys off an OPEN
+    # labeled issue -- which a replayed or post-merge draft does not have
+    # (observed on fahera-mx/studio.alissa.app#279: found by an operator, by
+    # accident). With this on, a draft that is provably ownerless is readied
+    # and review-requested mechanically, at most once per (PR, head). Default
+    # ON, on the same grounds as rerequest_enabled: it spawns nothing, every
+    # gate defers on absent evidence, and dry_run still suppresses every side
+    # effect. false skips the sweep AND narrows the PR search back to
+    # non-drafts, restoring the previous cost profile exactly.
+    orphan_sweep_enabled: bool = True
+
+    # How long the draft's head must have been public before the sweep fires --
+    # rerequest_grace_minutes' twin, and load-bearing for the same reason: a
+    # live session opens its draft and hands it off minutes later, so firing on
+    # sight would race the very session that is about to do the job. 0 means
+    # "use stale_minutes", the documented default.
+    orphan_grace_minutes: int = 0
+
     # Cross-instance spawn dedupe (issue #53): before spawning on any edge,
     # read the trigger artifact's mechanical activity comment and treat a
     # spawn line younger than stale_minutes as an in-flight claim EVEN when
@@ -254,6 +280,15 @@ class Config:
         the re-request instantly on a default config."""
         return (self.rerequest_grace_minutes or self.stale_minutes) * 60
 
+    @property
+    def orphan_grace_seconds(self) -> int:
+        """How long a draft's head must have been public before the orphan
+        sweep fires, in seconds. Read this, never the raw field --
+        `rerequest_grace_seconds`' contract verbatim: 0 is the sentinel for
+        "the stale window", and a caller reading the field directly would
+        ready-and-request a draft opened seconds ago on a default config."""
+        return (self.orphan_grace_minutes or self.stale_minutes) * 60
+
     @property
     def manifest_path(self) -> Path:
         return self.workspace_root / "alissa-workspace.yaml"
@@ -366,6 +401,18 @@ class Config:
                 f"got {grace}"
             )
 
+        # The orphan sweep's own grace, validated exactly like the one above --
+        # same 0 sentinel, same reason a negative value is the only invalid
+        # one (it would fire on a draft pushed in the future).
+        orphan_grace = int(
+            raw.get("orphan_grace_minutes", cls.orphan_grace_minutes)
+        )
+        if orphan_grace < 0:
+            raise ValueError(
+                f"orphan_grace_minutes must be >= 0 (0 = use stale_minutes), "
+                f"got {orphan_grace}"
+            )
+
         interval = int(raw.get("poll_interval", cls.poll_interval))
         if interval < MIN_POLL_INTERVAL:
             raise ValueError(
@@ -402,6 +449,10 @@ class Config:
                 raw.get("rerequest_enabled", cls.rerequest_enabled)
             ),
             rerequest_grace_minutes=grace,
+            orphan_sweep_enabled=bool(
+                raw.get("orphan_sweep_enabled", cls.orphan_sweep_enabled)
+            ),
+            orphan_grace_minutes=orphan_grace,
             activity_claims_enabled=bool(
                 raw.get("activity_claims_enabled", cls.activity_claims_enabled)
             ),

{alissa_tools_github_devloop-0.7.0 → alissa_tools_github_devloop-0.8.0}/src/main/alissa/tools/github/devloop/ghclient.py

@@ -119,6 +119,15 @@ class PullRequest:
     # review-response edge is closed. GitHub clears an entry when that
     # reviewer submits and re-adds it on re-request.
     requested_reviewers: tuple[str, ...]
+    # The GraphQL node id, carried ONLY for `mark_ready`: REST cannot take a
+    # pull request out of draft at all (there is no `draft` field on the PATCH
+    # endpoint), so the orphan sweep's ready flip has to go through GraphQL's
+    # `markPullRequestReadyForReview`, which addresses PRs by node id. It rides
+    # along on the `pull_request()` fetch every caller already pays rather than
+    # costing a lookup of its own. Defaulted so the many test fakes and the
+    # other three edges -- none of which flip drafts -- need not supply it;
+    # `mark_ready` refuses an empty one rather than POSTing a nonsense mutation.
+    node_id: str = ""
 
     @property
     def full_name(self) -> str:
@@ -205,6 +214,27 @@ class ReviewRequestRejected(RuntimeError):
     plain retry."""
 
 
+class ReadyForReviewRejected(RuntimeError):
+    """`mark_ready` completed but the pull request is still a draft.
+
+    The draft→ready flip is the FIRST half of the orphan sweep's remedy and the
+    half the second depends on: a reviewer requested on a PR that is still a
+    draft is not in review, so a flip that silently did not happen would leave
+    the sweep recording a handoff that never occurred.
+
+    GraphQL's `markPullRequestReadyForReview` answers with the pull request
+    itself, so the flip is verified exactly as `assign_self` and
+    `request_review` verify theirs. It can decline for reasons no retry
+    changes -- a PR that is not a draft to begin with is fine (the mutation is
+    idempotent and reports `isDraft: false`), but a node id that resolves to
+    something else, or a token without write access on the repo, is not.
+
+    Caller contract: escalate-don't-retry, `ReviewRequestRejected`'s doctrine
+    verbatim, and for the same reason -- the daemon must not POST into a
+    permanent refusal every poll. The DONE marker is never recorded on this
+    path: the handoff did not happen."""
+
+
 class AssignmentRejected(RuntimeError):
     """`assign_self` returned 2xx but the login is not on the issue.
 
@@ -381,19 +411,27 @@ class GitHub:
             out.append((parts[-2], parts[-1], number, assignees))
         return out
 
-    def search_prs(self, repos: tuple[str, ...] = ()) -> list[tuple[str, str, int]]:
-        """Open non-draft PRs AUTHORED by the token identity across the
-        watched repos, as `(owner, repo, number)` hits -- the candidate set of
-        the review-response edge.
+    def search_prs(
+        self, repos: tuple[str, ...] = (), include_drafts: bool = False
+    ) -> list[tuple[str, str, int]]:
+        """Open PRs AUTHORED by the token identity across the watched repos, as
+        `(owner, repo, number)` hits -- the candidate set of the PR-side edges.
 
         `author:@me` resolves server-side from the gh token (the same token
         verify_identity() pins at startup), so the daemon only ever considers
         its own PRs -- the developer identity is the author of every PR its
-        spawned sessions push. `draft:false` keeps the daemon's own fresh
-        draft PRs (the pre-review norm) from costing a pull_request() re-fetch
-        every poll; evaluate_pr() re-checks `draft` anyway, since a PR can
-        flip back to draft between search and fetch (same belt-and-braces as
-        reviewloop's review_requests + CR1 re-check).
+        spawned sessions push.
+
+        `include_drafts` widens the query by dropping `draft:false`. Off (the
+        default) it keeps the daemon's own fresh draft PRs -- the pre-review
+        norm -- from costing a pull_request() re-fetch every poll, which is the
+        only reason that qualifier was ever there; the review-response edge
+        re-checks `draft` anyway, since a PR can flip back to draft between
+        search and fetch (same belt-and-braces as reviewloop's review_requests
+        + CR1 re-check). The orphan sweep turns it ON because a draft is
+        precisely its subject, and the re-fetch it costs is not avoidable
+        overhead there: draft-ness alone says nothing, and only the fetch can
+        show whether a reviewer is on the PR.
 
         Fails closed on an empty allowlist for the same reason search_issues
         does: an unscoped query would return every PR the token ever authored
@@ -410,7 +448,11 @@ class GitHub:
             )
             return []
 
-        query = "is:pr is:open draft:false author:@me"
+        # Assembled so the non-draft query is byte-identical to what this
+        # method has always sent -- the qualifier is dropped in place, not
+        # re-ordered around.
+        draft = "" if include_drafts else " draft:false"
+        query = f"is:pr is:open{draft} author:@me"
         for full_name in repos:
             query += f" repo:{full_name}"
 
@@ -605,6 +647,7 @@ class GitHub:
             # `or ""`: GitHub sends null for an empty description.
             body=data.get("body") or "",
             requested_reviewers=requested,
+            node_id=data.get("node_id") or "",
         )
 
     def reviews(self, owner: str, repo: str, number: int) -> list[Review]:
@@ -672,6 +715,126 @@ class GitHub:
         committer = data.get("committer") or {}
         return parse_github_timestamp(committer.get("date"))
 
+    _READY_MUTATION = (
+        "mutation($id:ID!){markPullRequestReadyForReview(input:{pullRequestId:"
+        "$id}){pullRequest{isDraft}}}"
+    )
+
+    def mark_ready(self, pr: PullRequest) -> None:
+        """Take a draft pull request out of draft -- `gh pr ready`'s API call,
+        performed by the daemon when the session that owed it died first.
+
+        GraphQL, not REST, and not by choice: the REST pulls endpoint has no
+        writable `draft` field, so `markPullRequestReadyForReview` is the only
+        way to flip it. That mutation addresses the PR by NODE ID, which is why
+        `PullRequest` carries one.
+
+        Takes the whole PullRequest rather than owner/repo/number because the
+        node id is the only address the mutation accepts and the record is
+        where it lives -- passing the parts would mean every caller re-deriving
+        an id it already holds.
+
+        The mutation is idempotent: run against a PR that is already ready it
+        succeeds and reports `isDraft: false`, which is exactly the state the
+        caller wants, so a retry after a lost response is safe.
+
+        The response carries `isDraft`, so the flip is VERIFIED rather than
+        assumed (see ReadyForReviewRejected) -- the sweep's second half
+        (requesting a reviewer) is meaningless on a PR that is still a draft,
+        and a handoff recorded on an unflipped PR would be a lie the ledger
+        then refuses to revisit. An empty node id is refused before the call:
+        it is unaddressable, and GraphQL would answer a confusing type error
+        rather than a useful one.
+
+        GraphQL errors make `gh` exit non-zero, so they arrive as CommandError
+        (transient to the caller) or RateLimited, exactly like every REST call
+        here."""
+        if not pr.node_id:
+            raise ReadyForReviewRejected(
+                f"{pr.pr_slug}: no GraphQL node id on the pull request record, "
+                f"so the draft→ready flip cannot be addressed -- refusing to "
+                f"call markPullRequestReadyForReview without one."
+            )
+        data = self._api(
+            "graphql",
+            "-f",
+            f"query={self._READY_MUTATION}",
+            "-f",
+            f"id={pr.node_id}",
+        )
+        payload = (
+            ((data or {}).get("data") or {}).get("markPullRequestReadyForReview")
+            or {}
+        )
+        still_draft = (payload.get("pullRequest") or {}).get("isDraft")
+        # `is not False`, not `if still_draft`: a missing or malformed payload
+        # yields None, and "the response did not say it worked" must read as a
+        # refusal, never as success.
+        if still_draft is not False:
+            raise ReadyForReviewRejected(
+                f"{pr.pr_slug}: markPullRequestReadyForReview returned "
+                f"isDraft={still_draft!r} -- the draft→ready flip did not land, "
+                f"so the pull request is still out of review."
+            )
+
+    def request_reviews(
+        self, owner: str, repo: str, number: int, reviewers: "tuple[str, ...]"
+    ) -> "tuple[str, ...]":
+        """Request review from SEVERAL logins at once; returns the ones that
+        landed. `request_review`'s shape for the orphan sweep, which has no
+        single review author to name and must request the CONFIGURED reviewer
+        set instead.
+
+        One POST for the whole set (the endpoint takes a list), so a three-name
+        roster costs one call rather than three.
+
+        The success rule is deliberately WEAKER than `request_review`'s: this
+        raises only when NOTHING landed. The remedy's purpose is to make the PR
+        visible to the reviewer daemon's `review-requested:@me` search, and one
+        honoured request achieves that completely -- failing the whole handoff
+        because a second, mistyped reviewer was dropped would re-orphan a PR
+        that is, in fact, now in review. Names GitHub silently dropped are
+        returned-by-omission so the caller can log them; only an empty landing
+        set is a rejection.
+
+        Casefolded like `request_review`'s check, because GitHub logins are
+        case-insensitive while the reviewer set is operator-typed."""
+        wanted = tuple(r for r in reviewers if r and r.strip())
+        if not wanted:
+            raise ReviewRequestRejected(
+                f"{owner}/{repo}#{number}: no reviewers to request -- the "
+                f"configured reviewer set is empty, so no review request can "
+                f"be made."
+            )
+        payload = json.dumps({"reviewers": list(wanted)})
+        fd, body_path = tempfile.mkstemp(prefix="devloop-orphan-", suffix=".json")
+        try:
+            with os.fdopen(fd, "w") as handle:
+                handle.write(payload)
+            data = self._api(
+                "-X",
+                "POST",
+                f"repos/{owner}/{repo}/pulls/{number}/requested_reviewers",
+                "--input",
+                body_path,
+            )
+        finally:
+            os.unlink(body_path)
+
+        on_pr = {
+            (r.get("login") or "").casefold()
+            for r in ((data or {}).get("requested_reviewers") or [])
+        }
+        landed = tuple(r for r in wanted if r.casefold() in on_pr)
+        if not landed:
+            raise ReviewRequestRejected(
+                f"{owner}/{repo}#{number}: GitHub accepted the request but none "
+                f"of {wanted!r} are among the requested reviewers -- the review "
+                f"request did not land, so the reviewer daemon still cannot see "
+                f"this PR."
+            )
+        return landed
+
     def request_review(self, owner: str, repo: str, number: int, reviewer: str) -> None:
         """Request review from ONE login on a pull request.