raidlock 0.1.0__py3-none-any.whl

raidlock/prsync.py

@@ -0,0 +1,318 @@
+"""Pull request awareness: link cards to PRs, poll state and checks through gh, close merged cards through the gates."""
+
+import json
+import re
+import time
+
+from . import pr as P
+from .core import clock, model
+from .core.errors import Precondition
+from .runners import policy
+
+FIELDS = "number,url,state,isDraft,mergedAt,headRefOid,headRefName,baseRefName,statusCheckRollup,reviewDecision"
+RATE = re.compile(r"rate limit|abuse detection|HTTP 429", re.IGNORECASE)
+PASS = {"SUCCESS"}
+FAIL = {"FAILURE", "ERROR", "TIMED_OUT", "CANCELLED", "ACTION_REQUIRED", "STARTUP_FAILURE", "STALE"}
+STATES = ("OPEN", "CLOSED", "MERGED")
+SHA = re.compile(r"^[0-9a-f]{40}([0-9a-f]{24})?$")
+MAX_BACKOFF = 900
+
+
+class RateLimited(Precondition):
+    kind = "rate_limited"
+
+
+def parse_ref(ref):
+    text = str(ref or "").strip().lstrip("#")
+    if text.isdigit() and 0 < int(text) < 10**9:
+        return {"number": int(text), "url": ""}
+    match = P.PR_URL.fullmatch(text)
+    if match and int(match.group(1)) > 0:
+        return {"number": int(match.group(1)), "url": text}
+    raise Precondition("a pull request is a number or a .../pull/<n> URL", ref=text[:200])
+
+
+def summarize(rollup):
+    """Collapse gh's statusCheckRollup into counts and one state: success, failure, pending or none."""
+    passed = failed = pending = 0
+    failing = []
+    for item in rollup if isinstance(rollup, list) else []:
+        if not isinstance(item, dict):
+            continue
+        name = str(item.get("name") or item.get("context") or "check")[:100]
+        if item.get("__typename") == "StatusContext" or ("state" in item and "conclusion" not in item):
+            state = str(item.get("state", "")).upper()
+            if state == "SUCCESS":
+                passed += 1
+            elif state in ("FAILURE", "ERROR"):
+                failed += 1
+                failing.append(name)
+            else:
+                pending += 1
+            continue
+        if str(item.get("status", "")).upper() != "COMPLETED":
+            pending += 1
+            continue
+        conclusion = str(item.get("conclusion", "")).upper()
+        if conclusion in PASS:
+            passed += 1
+        elif conclusion in FAIL:
+            failed += 1
+            failing.append(name)
+        else:
+            pending += 1
+    total = passed + failed + pending
+    state = "failure" if failed else "pending" if pending else "success" if total else "none"
+    return {"state": state, "passed": passed, "failed": failed, "pending": pending, "total": total, "failing": failing}
+
+
+def _repo_path(board, card):
+    try:
+        return policy.target(board.workspace, board.dir, card["locks"])["path"]
+    except Precondition:
+        return None
+
+
+@P.protected
+def fetch(board, card):
+    """Current PR state from gh, validated. Raises RateLimited when GitHub throttles."""
+    pr = card["pr"]
+    proc = P.gh(
+        ["pr", "view", pr.get("url") or str(pr["number"]), "--json", FIELDS], cwd=_repo_path(board, card), env=board.env
+    )
+    if proc is None:
+        raise Precondition("gh is not installed", hint="install the GitHub CLI and run gh auth login")
+    if proc.returncode != 0:
+        err = P.sanitize(proc.stderr or proc.stdout, board.env).strip()
+        if RATE.search(err):
+            raise RateLimited("GitHub rate limit reached; try again later", card=card["id"])
+        raise Precondition(f"gh pr view failed for {card['id']}: {err[:300]}", card=card["id"])
+    try:
+        data = json.loads(proc.stdout)
+    except ValueError:
+        raise Precondition(f"gh returned invalid JSON for {card['id']}", card=card["id"]) from None
+    if not isinstance(data, dict) or data.get("number") != pr["number"]:
+        raise Precondition(f"gh returned a different pull request for {card['id']}", card=card["id"])
+    state = str(data.get("state", "")).upper()
+    head = str(data.get("headRefOid") or "")
+    if state not in STATES or (head and not SHA.match(head)):
+        raise Precondition(f"gh returned an unexpected pull request state for {card['id']}", card=card["id"])
+    url = str(data.get("url") or pr.get("url") or "")
+    if pr.get("url") and url != pr["url"]:
+        raise Precondition(f"gh returned a different pull request for {card['id']}", card=card["id"])
+    return {
+        "state": state,
+        "draft": bool(data.get("isDraft")),
+        "merged_at": str(data.get("mergedAt") or ""),
+        "head": head,
+        "head_branch": str(data.get("headRefName") or "")[:200],
+        "base": str(data.get("baseRefName") or "")[:200],
+        "review_decision": str(data.get("reviewDecision") or ""),
+        "checks": summarize(data.get("statusCheckRollup")),
+        "url": url if P.PR_URL.fullmatch(url) else pr.get("url", ""),
+    }
+
+
+def link(board, caller, card_id, ref):
+    """Lead: link a card to an existing pull request."""
+    found = parse_ref(ref)
+    with board.lead_write(caller, "link a pull request"):
+        card = board.card(card_id)
+        previous = card.get("pr") or {}
+        card["pr"] = {
+            "number": found["number"],
+            "url": found["url"] or (previous.get("url") if previous.get("number") == found["number"] else ""),
+            "linked": clock.iso(),
+            "state": "",
+            "checks": summarize([]),
+        }
+        board._note(card, caller.name, f"linked pull request #{found['number']}")
+        board._save_card(card)
+        board._record(
+            "status",
+            caller.name,
+            f"{card_id} linked to pull request #{found['number']}",
+            task=card_id,
+            data={"event": "pr_linked", "pr": card["pr"]},
+        )
+    return {"card": card_id, "pr": card["pr"]}
+
+
+def _due(card, min_interval, force):
+    pr = card["pr"]
+    if force:
+        return True
+    if card["lane"] == "done" and pr.get("state") in ("MERGED", "CLOSED"):
+        return False
+    if pr.get("state") == "CLOSED":
+        return False
+    return not pr.get("synced") or clock.age_seconds(pr["synced"]) >= min_interval
+
+
+def hold_reason(board, card, info):
+    """Why a merged PR does not close its card yet, or "" when the gates may run."""
+    if card["lane"] not in ("review", "blocked"):
+        return f"card is in {card['lane']}"
+    last = model.last_verification(card) or {}
+    if not last.get("sha"):
+        return "no verify receipt"
+    if info["head"] != last["sha"]:
+        return f"merged head {info['head'][:12]} is not the verified commit {last['sha'][:12]}"
+    if info["checks"]["state"] == "failure":
+        return "checks failed: " + ", ".join(info["checks"]["failing"][:5])
+    if info["checks"]["state"] != "success":
+        return "checks not successful: " + info["checks"]["state"]
+    return ""
+
+
+def _update(board, caller, card_id, info):
+    with board.lead_write(caller, "sync a pull request"):
+        card = board.card(card_id)
+        pr = card.get("pr") or {}
+        before = (pr.get("state"), (pr.get("checks") or {}).get("state"))
+        pr.update(info, synced=clock.iso())
+        card["pr"] = pr
+        after = (info["state"], info["checks"]["state"])
+        if before != after:
+            board._note(card, caller.name, f"pull request #{pr['number']}: {after[0].lower()}, checks {after[1]}")
+            board._record(
+                "status",
+                caller.name,
+                f"pull request #{pr['number']} {after[0].lower()}, checks {after[1]}",
+                task=card_id,
+                data={"event": "pr_state", "state": after[0], "checks": info["checks"]},
+            )
+        board._save_card(card)
+        return card
+
+
+def _hold(board, caller, card_id, reason):
+    with board.lead_write(caller, "hold a merged pull request"):
+        card = board.card(card_id)
+        if card["pr"].get("held") != reason:
+            card["pr"]["held"] = reason
+            board._note(card, caller.name, f"merged but not done: {reason}")
+            board._record(
+                "status",
+                caller.name,
+                f"{card_id} merged but not done: {reason}",
+                task=card_id,
+                data={"event": "pr_merge_held", "reason": reason},
+            )
+            board._save_card(card)
+
+
+def _advance(board, caller, card, info):
+    reason = hold_reason(board, card, info)
+    if not reason:
+        try:
+            board.move(card["id"], "done", caller, note=f"merged as pull request #{card['pr']['number']}")
+            from .runners.runner import prune_runs
+
+            prune_runs(board, card["id"])
+            return "done", ""
+        except Precondition as exc:
+            reason = exc.message
+    _hold(board, caller, card["id"], reason)
+    return "held", reason
+
+
+def sync(board, caller, ids=None, min_interval=60, force=False):
+    """Lead: poll each linked PR once (respecting min_interval), record state and checks, and move merged cards to
+    done only through the done gate. Stops at the first rate limit."""
+    board._auth(caller)
+    board._require_lead(caller, "sync pull requests")
+    cards = board.cards()
+    if ids:
+        known = {c["id"]: c for c in cards}
+        for cid in ids:
+            if cid not in known:
+                raise Precondition(f"no card {cid}", card=cid)
+            if not known[cid].get("pr"):
+                raise Precondition(f"{cid} has no pull request", card=cid, hint=f"raidlock pr-link {cid} <number>")
+        cards = [known[cid] for cid in ids]
+    else:
+        cards = [c for c in cards if c.get("pr")]
+    out = {"synced": [], "skipped": [], "done": [], "held": [], "errors": [], "rate_limited": False}
+    for card in cards:
+        if not _due(card, min_interval, force):
+            out["skipped"].append(card["id"])
+            continue
+        try:
+            info = fetch(board, card)
+        except RateLimited:
+            out["rate_limited"] = True
+            break
+        except Precondition as exc:
+            out["errors"].append({"card": card["id"], "error": exc.message})
+            continue
+        with board.lead_write(caller, "sync a pull request"):
+            current = board.card(card["id"])
+            identity = ("number", "url", "linked", "opened", "repo")
+            if any((current.get("pr") or {}).get(k) != card["pr"].get(k) for k in identity):
+                out["errors"].append({"card": card["id"], "error": "pull request changed during sync"})
+                continue
+            card = _update(board, caller, card["id"], info)
+            out["synced"].append({"card": card["id"], "state": info["state"], "checks": info["checks"]["state"]})
+            if info["state"] == "MERGED" and card["lane"] != "done":
+                verdict, reason = _advance(board, caller, card, info)
+                if verdict == "done":
+                    out["done"].append(card["id"])
+                else:
+                    out["held"].append({"card": card["id"], "reason": reason})
+    return out
+
+
+def watch(board, caller, interval=60, max_polls=None, sleep=time.sleep, **kw):
+    """Repeat sync; double the wait after a rate limit, up to MAX_BACKOFF, and reset after a clean poll."""
+    polls, wait, last = 0, interval, None
+    while max_polls is None or polls < max_polls:
+        last = sync(board, caller, **kw)
+        polls += 1
+        wait = min(MAX_BACKOFF, wait * 2) if last["rate_limited"] else interval
+        if max_polls is not None and polls >= max_polls:
+            break
+        sleep(wait)
+    return {**(last or {}), "polls": polls, "next_wait": wait}
+
+
+def register_cli(add_command):
+    def link_setup(p):
+        p.add_argument("id", help="card id")
+        p.add_argument("ref", help="pull request number or URL")
+
+    def link_handler(ctx, a):
+        r = link(ctx.board, ctx.caller(), a.id, a.ref)
+        return r, f"Linked {a.id} to pull request #{r['pr']['number']}."
+
+    def sync_setup(p):
+        p.add_argument("ids", nargs="*", help="cards to sync (default: every card with a pull request)")
+        p.add_argument("--min-interval", type=float, default=60, help="seconds between polls of one PR")
+        p.add_argument("--force", action="store_true", help="poll even when recently synced or closed")
+        p.add_argument("--watch", type=float, default=None, metavar="SECONDS", help="keep polling at this interval")
+        p.add_argument("--max-polls", type=int, default=None)
+
+    def sync_handler(ctx, a):
+        kw = {"ids": a.ids, "min_interval": a.min_interval, "force": a.force}
+        if a.watch:
+            r = watch(ctx.board, ctx.caller(), interval=a.watch, max_polls=a.max_polls, **kw)
+        else:
+            r = sync(ctx.board, ctx.caller(), **kw)
+        lines = [f"{s['card']}: {s['state'].lower()}, checks {s['checks']}" for s in r["synced"]]
+        lines += [f"{cid}: merged, moved to done" for cid in r["done"]]
+        lines += [f"{h['card']}: merged, held: {h['reason']}" for h in r["held"]]
+        lines += [f"{e['card']}: {e['error']}" for e in r["errors"]]
+        if r["rate_limited"]:
+            lines.append("Stopped: GitHub rate limit reached; run again later.")
+        if not lines:
+            lines.append("Nothing to sync." + (f" Skipped: {', '.join(r['skipped'])}." if r["skipped"] else ""))
+        return {**r, "_exit": 2 if r["rate_limited"] or r["errors"] else 0}, "\n".join(lines)
+
+    add_command("pr-link", "lead: link a card to an existing pull request", link_setup, link_handler, True)
+    add_command(
+        "pr-sync",
+        "lead: poll linked pull requests; merged cards close only through the gates",
+        sync_setup,
+        sync_handler,
+        True,
+    )

raidlock/recipes/README.md

@@ -0,0 +1,34 @@
+# Built-in recipes
+
+The loader uses stdlib `importlib.resources` to read the packaged Markdown.
+The existing wheel configuration includes this directory as package data.
+
+The package exposes `read_plan(source, team=None, variables=None)`,
+`parse_variables(assignments)` and `list_recipes()`. The core CLI owns
+`plan import`, dispatches `recipe:` sources through `read_plan`, and retains
+ordinary file imports and their mutating authorization. This package's
+`register_cli(add_command)` registers only the read-only `recipes` listing.
+
+```sh
+raidlock recipes
+raidlock --lead-secret /printed/path plan import recipe:upgrade-deps --var repo=acme-shop
+raidlock --lead-secret /printed/path plan import recipe:security-audit --var repo=acme-shop
+raidlock --lead-secret /printed/path plan import recipe:docs-refresh --var repo=pocket-notes
+raidlock --lead-secret /printed/path plan import recipe:multi-repo-refactor --var repo=acme-shop --var other_repo=pocket-notes
+```
+
+Recipe imports require repository variables; ordinary file imports reject
+`--var`. Recipe IDs are stable, so importing the same recipe twice into a
+board requires resolving its existing cards first.
+
+Each checklist uses the existing `- [ ] Title | locks: repo/path, repo/path`
+format. The loader reads each preceding `Quest:` JSON paragraph for its stable
+ID, dependencies and scope. Ordinary Markdown import ignores those paragraphs;
+use the recipe loader to retain dependencies and assignment instructions.
+
+Variables are required repository names consisting of letters, digits, hyphens
+or underscores. Paths, whitespace and Markdown syntax are rejected. Adjust
+recipe lock paths to the target repository layout before assigning work.
+Security review quests require a different provider from their build quest;
+the lead must enforce the assignments described in scope. They produce separate
+reports after builds finish and do not substitute for board approval gates.

raidlock/recipes/__init__.py

@@ -0,0 +1,105 @@
+"""Built-in plans and an optional CLI registration hook."""
+
+import json
+import re
+from importlib.resources import files
+
+from raidlock.core import Precondition
+from raidlock.core.paths import parse_list
+
+_NAMES = ("docs-refresh", "multi-repo-refactor", "security-audit", "upgrade-deps")
+_VARIABLE = re.compile(r"\{([a-z][a-z0-9_]*)\}")
+
+
+def list_recipes():
+    return list(_NAMES)
+
+
+def load_recipe(source, variables=None):
+    name = source.removeprefix("recipe:")
+    if name not in _NAMES:
+        raise Precondition(f"unknown recipe: {name}", hint="raidlock recipes")
+    values = dict(variables or {})
+    text = files(__package__).joinpath(name + ".md").read_text(encoding="utf-8")
+    required = set(_VARIABLE.findall(text))
+    missing = required - values.keys()
+    if missing:
+        raise Precondition("missing recipe variables: " + ", ".join(sorted(missing)))
+    for key in required:
+        value = values[key]
+        if not isinstance(value, str) or not re.fullmatch(r"[a-zA-Z0-9_-]+", value):
+            raise Precondition(f"invalid recipe variable {key}: use a repository name")
+    return _VARIABLE.sub(lambda match: values[match[1]], text)
+
+
+def read_plan(source, team=None, variables=None):
+    from raidlock.cli import _md_item, _read_plan
+
+    if not source.startswith("recipe:"):
+        if variables:
+            raise Precondition("--var is supported only for recipes")
+        return _read_plan(source, team)
+    items = []
+    metadata = None
+    seen = set()
+    for line in load_recipe(source, variables).splitlines():
+        if line.startswith("Quest: "):
+            metadata = json.loads(line[7:])
+        elif line.startswith("- [ ] "):
+            if metadata is None:
+                raise Precondition("recipe quest is missing metadata")
+            item = {**_md_item(line), **metadata}
+            if item["id"] in seen or not set(item.get("depends", [])) <= seen:
+                raise Precondition("recipe dependencies must reference earlier unique quests")
+            seen.add(item["id"])
+            item["locks"] = parse_list(item["locks"])
+            if team:
+                item["team"] = team
+            items.append(item)
+            metadata = None
+    return items
+
+
+def parse_variables(assignments):
+    variables = {}
+    for assignment in assignments or []:
+        key, separator, value = assignment.partition("=")
+        if not separator or not key or key in variables:
+            raise Precondition(f"invalid or duplicate --var: {assignment}")
+        variables[key] = value
+    return variables
+
+
+def setup_plan(parser):
+    parser.add_argument("action", choices=["import", "recipes"])
+    parser.add_argument("file", nargs="?")
+    parser.add_argument("--team", default=None)
+    parser.add_argument("--var", action="append", default=[])
+
+
+def handle_plan(ctx, args):
+    if args.action == "recipes":
+        if args.file or args.var or args.team:
+            raise Precondition("plan recipes takes no import arguments")
+        names = list_recipes()
+        return {"recipes": names}, "\n".join(names)
+    if not args.file:
+        raise Precondition("plan import requires a file or recipe:<name>")
+    variables = parse_variables(args.var)
+    items = read_plan(args.file, args.team, variables)
+    cards = ctx.board.import_plan(ctx.caller(), items)
+    ids = [card["id"] for card in cards]
+    return {"cards": ids}, f"Imported {len(ids)} card(s): {', '.join(ids)}.\nNext: raidlock show"
+
+
+def setup_recipes(parser):
+    pass
+
+
+def handle_recipes(ctx, args):
+    names = list_recipes()
+    return {"recipes": names}, "\n".join(names)
+
+
+def register_cli(add_command):
+    add_command("recipes", "list built-in plan recipes", setup_recipes, handle_recipes)

raidlock/recipes/docs-refresh.md

@@ -0,0 +1,15 @@
+# docs-refresh
+
+Use when documentation has drifted from current behavior.
+
+Quest: {"id": "refresh-guide", "depends": [], "scope": "Check documented commands against current behavior and update examples."}
+
+- [ ] Refresh user guides for {repo} | locks: {repo}/docs
+
+Quest: {"id": "refresh-readme", "depends": ["refresh-guide"], "scope": "Update setup instructions and links to the refreshed guides."}
+
+- [ ] Refresh the README for {repo} | locks: {repo}/README.md
+
+Quest: {"id": "verify-docs", "depends": ["refresh-readme"], "scope": "Run examples, check links and correct inconsistencies."}
+
+- [ ] Verify documentation examples for {repo} | locks: {repo}/docs

raidlock/recipes/multi-repo-refactor.md

@@ -0,0 +1,15 @@
+# multi-repo-refactor
+
+Use for a shared contract change across two repositories. Keep the producer backward compatible until the consumer migrates.
+
+Quest: {"id": "refactor-producer", "depends": [], "scope": "Introduce the new contract while preserving the old interface and test both."}
+
+- [ ] Refactor the producer in {repo} | locks: {repo}/src, {repo}/tests
+
+Quest: {"id": "refactor-consumer", "depends": ["refactor-producer"], "scope": "Adopt the new contract and test compatibility with the producer."}
+
+- [ ] Migrate the consumer in {other_repo} | locks: {other_repo}/src, {other_repo}/tests
+
+Quest: {"id": "verify-contract", "depends": ["refactor-consumer"], "scope": "Run integration tests across both repositories and document rollout and rollback steps."}
+
+- [ ] Verify the contract across {repo} and {other_repo} | locks: {repo}/tests, {other_repo}/tests

raidlock/recipes/security-audit.md

@@ -0,0 +1,27 @@
+# security-audit
+
+Use for a security audit covering dependencies, authentication and input handling. Each area has one build quest and one independent review quest. The lead must assign builds to openai and reviews to anthropic; provider assignment is an instruction, not an importer-enforced field. Review quests follow completed builds and do not replace board approval gates.
+
+Quest: {"id": "build-dependencies", "depends": [], "scope": "Assign to provider openai. Audit dependencies and repair vulnerable versions with regression evidence."}
+
+- [ ] Build security fixes for dependencies in {repo} | locks: {repo}/pyproject.toml, {repo}/requirements.txt
+
+Quest: {"id": "review-dependencies", "depends": ["build-dependencies"], "scope": "Assign to provider anthropic, different from the build provider openai. Independently reproduce findings, inspect the patch and tests, and write a review report. Do not modify build files."}
+
+- [ ] Independently review dependencies fixes in {repo} | locks: {repo}/audit-reviews/dependencies.md
+
+Quest: {"id": "build-auth", "depends": [], "scope": "Assign to provider openai. Audit authentication and authorization boundaries and repair demonstrated flaws."}
+
+- [ ] Build security fixes for auth in {repo} | locks: {repo}/src/auth, {repo}/tests/auth
+
+Quest: {"id": "review-auth", "depends": ["build-auth"], "scope": "Assign to provider anthropic, different from the build provider openai. Independently reproduce findings, inspect the patch and tests, and write a review report. Do not modify build files."}
+
+- [ ] Independently review auth fixes in {repo} | locks: {repo}/audit-reviews/auth.md
+
+Quest: {"id": "build-inputs", "depends": [], "scope": "Assign to provider openai. Audit input validation and injection risks and add regression tests for fixes."}
+
+- [ ] Build security fixes for inputs in {repo} | locks: {repo}/src/inputs, {repo}/tests/inputs
+
+Quest: {"id": "review-inputs", "depends": ["build-inputs"], "scope": "Assign to provider anthropic, different from the build provider openai. Independently reproduce findings, inspect the patch and tests, and write a review report. Do not modify build files."}
+
+- [ ] Independently review inputs fixes in {repo} | locks: {repo}/audit-reviews/inputs.md

raidlock/recipes/upgrade-deps.md

@@ -0,0 +1,15 @@
+# upgrade-deps
+
+Use for dependency upgrades that need compatibility checks before release.
+
+Quest: {"id": "upgrade-runtime", "depends": [], "scope": "Update runtime constraints and lockfiles and record compatibility changes."}
+
+- [ ] Upgrade runtime dependencies in {repo} | locks: {repo}/pyproject.toml, {repo}/requirements.txt
+
+Quest: {"id": "upgrade-tooling", "depends": ["upgrade-runtime"], "scope": "Update development tools and regenerate affected lockfiles."}
+
+- [ ] Upgrade development tools in {repo} | locks: {repo}/pyproject.toml, {repo}/requirements-dev.txt
+
+Quest: {"id": "verify-upgrade", "depends": ["upgrade-tooling"], "scope": "Run the full suite and add regression tests for changed dependency behavior."}
+
+- [ ] Verify upgraded dependencies in {repo} | locks: {repo}/tests