tfscout 0.1.0__py3-none-any.whl

tfscout/__init__.py

@@ -0,0 +1,3 @@
+"""tfscout - AI-assisted Terraform plan review and drift detection."""
+
+__version__ = "0.1.0"

tfscout/__main__.py

@@ -0,0 +1,3 @@
+from tfscout.cli import main
+
+raise SystemExit(main())

tfscout/analyze.py

@@ -0,0 +1,239 @@
+"""Orchestration: plan -> redaction -> rules -> (optional) LLM -> report."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import sys
+from dataclasses import dataclass, field
+from typing import Any
+
+from tfscout.diff import diff
+from tfscout.llm import LLMClient, LLMError
+from tfscout.plan import Change, Plan
+from tfscout.redact import redact_change
+from tfscout.rules import (
+    DRIFT_CLASSES,
+    SEVERITIES,
+    DriftItem,
+    Finding,
+    drift_rules,
+    review_rules,
+    sev_rank,
+)
+
+MAX_RESOURCES = 150
+MAX_DIFFS_PER_RESOURCE = 40
+CATEGORIES = {"security", "data-loss", "availability", "cost", "compliance", "other"}
+
+REVIEW_SYSTEM = """\
+You are tfscout, a senior platform engineer reviewing a Terraform plan attached to a pull request.
+Input: resource changes (secrets are already redacted as [REDACTED]) and findings produced by deterministic rules.
+
+Tasks:
+1. "summary": 2-5 short markdown bullet lines describing WHAT this change does and its blast radius, in plain English.
+2. "findings": ONLY risks the rules did not already report: downtime, data loss, security, cost,
+   compliance, surprising side-effects (e.g. a renamed resource causing destroy/create, forced replacement
+   attributes, changes to shared infrastructure). Never repeat a rule finding. Never invent problems:
+   if nothing else is notable return an empty list. Be concrete and reference attribute paths.
+
+Respond with a single JSON object and nothing else:
+{"summary": "- ...\\n- ...", "findings": [{"severity": "info|low|medium|high|critical",
+ "category": "security|data-loss|availability|cost|compliance|other", "resource": "<resource address>",
+ "title": "<short>", "detail": "<why>", "recommendation": "<what to do>"}]}
+"""
+
+DRIFT_SYSTEM = """\
+You are tfscout, a senior platform engineer analysing Terraform DRIFT: differences between the Terraform state
+and real infrastructure that were made outside Terraform. Secrets are redacted as [REDACTED].
+Each item has a preliminary classification from rules: noise | manual-change | risky.
+If "classification_is_final" is true, the rules proved it from the Terraform state: keep that classification
+and only explain it.
+
+For every item return:
+- "classification": noise (volatile/auto-managed values), manual-change (someone changed it by hand,
+  probably a hotfix that should be codified), or risky (weakens security, availability or compliance,
+  or looks unauthorised).
+- "explanation": 1-2 sentences on what changed and the likely cause.
+- "recommendation": either codify the change in Terraform (show the HCL attribute to set) or revert it by
+  running apply, or ignore it via lifecycle.ignore_changes for true noise.
+Also give an overall "summary" (2-4 markdown bullet lines).
+
+Respond with a single JSON object and nothing else:
+{"summary": "- ...", "items": [{"resource": "<address>", "classification": "noise|manual-change|risky",
+ "explanation": "...", "recommendation": "..."}]}
+"""
+
+
+def _warn(msg: str) -> None:
+    print(f"tfscout: warning: {msg}", file=sys.stderr)
+
+
+def _diff_payload(c: Change) -> list[dict[str, Any]]:
+    ds = diff(c.before, c.after, c.after_unknown)
+    out = [{"path": d.path, "before": d.before, "after": d.after} for d in ds[:MAX_DIFFS_PER_RESOURCE]]
+    if len(ds) > MAX_DIFFS_PER_RESOURCE:
+        out.append({"path": f"... {len(ds) - MAX_DIFFS_PER_RESOURCE} more attributes omitted"})
+    return out
+
+
+def _finding_dict(f: Finding) -> dict[str, str]:
+    return {"severity": f.severity, "category": f.category, "resource": f.resource, "title": f.title}
+
+
+# --------------------------------------------------------------------------- review
+
+
+@dataclass
+class ReviewReport:
+    summary: str
+    counts: dict[str, int]
+    findings: list[Finding]
+    changes: list[Change]
+    ai_used: bool = False
+    ai_error: str = ""
+
+    @property
+    def max_severity(self) -> str:
+        return max((f.severity for f in self.findings), key=sev_rank, default="none")
+
+
+def _count_actions(changes: list[Change]) -> dict[str, int]:
+    counts = {"create": 0, "update": 0, "replace": 0, "delete": 0}
+    for c in changes:
+        counts[c.action] = counts.get(c.action, 0) + 1
+    return counts
+
+
+def _parse_ai_findings(raw: Any, known: set[str]) -> list[Finding]:
+    out = []
+    for item in raw if isinstance(raw, list) else []:
+        if not isinstance(item, dict) or not item.get("title"):
+            continue
+        sev = str(item.get("severity", "info")).lower()
+        cat = str(item.get("category", "other")).lower()
+        res = str(item.get("resource", ""))
+        out.append(
+            Finding(
+                severity=sev if sev in SEVERITIES else "info",
+                category=cat if cat in CATEGORIES else "other",
+                resource=res if res in known else (res or "(plan)"),
+                title=str(item["title"])[:200],
+                detail=str(item.get("detail", ""))[:1000],
+                recommendation=str(item.get("recommendation", ""))[:1000],
+                source="ai",
+            )
+        )
+    return out
+
+
+def run_review(plan: Plan, client: LLMClient | None) -> ReviewReport:
+    changes = [redact_change(c) for c in plan.changes]
+    findings = review_rules(changes)
+    report = ReviewReport(summary="", counts=_count_actions(changes), findings=findings, changes=changes)
+    if not changes or client is None:
+        return report
+
+    payload = {
+        "terraform_version": plan.terraform_version,
+        "counts": report.counts,
+        "changes": [
+            {
+                "address": c.address,
+                "type": c.type,
+                "action": c.action,
+                "replace_paths": c.replace_paths,
+                "diff": _diff_payload(c),
+            }
+            for c in changes[:MAX_RESOURCES]
+        ],
+        "omitted_changes": max(0, len(changes) - MAX_RESOURCES),
+        "rule_findings": [_finding_dict(f) for f in findings],
+    }
+    try:
+        resp = client.complete_json(REVIEW_SYSTEM, json.dumps(payload, default=str))
+    except LLMError as e:
+        _warn(f"AI analysis skipped: {e}")
+        report.ai_error = str(e)
+        return report
+
+    report.ai_used = True
+    report.summary = str(resp.get("summary", "")).strip()
+    seen = {(f.resource, f.category) for f in findings}
+    for f in _parse_ai_findings(resp.get("findings"), {c.address for c in changes}):
+        if (f.resource, f.category) not in seen:
+            report.findings.append(f)
+            seen.add((f.resource, f.category))
+    report.findings.sort(key=lambda f: (-sev_rank(f.severity), f.source != "rule", f.resource))
+    return report
+
+
+# --------------------------------------------------------------------------- drift
+
+
+@dataclass
+class DriftReport:
+    items: list[DriftItem] = field(default_factory=list)
+    summary: str = ""
+    ai_used: bool = False
+    ai_error: str = ""
+
+    @property
+    def actionable(self) -> list[DriftItem]:
+        return [i for i in self.items if i.classification != "noise"]
+
+    @property
+    def fingerprint(self) -> str:
+        """Stable id of the actionable drift, so repeated runs don't spam new issues."""
+        key = sorted(
+            (i.resource, i.action, sorted((d.path, json.dumps(d.after, default=str)) for d in i.diffs))
+            for i in self.actionable
+        )
+        return hashlib.sha256(json.dumps(key).encode()).hexdigest()[:12] if key else ""
+
+
+def run_drift(plan: Plan, client: LLMClient | None) -> DriftReport:
+    report = DriftReport(items=drift_rules([redact_change(c) for c in plan.drift], plan.prior_resources))
+    if not report.items or client is None:
+        return report
+
+    payload = {
+        "items": [
+            {
+                "resource": i.resource,
+                "type": i.type,
+                "action": i.action,
+                "preliminary_classification": i.classification,
+                "classification_is_final": i.locked,
+                "reason": i.reason,
+                "diff": [{"path": d.path, "state": d.before, "real": d.after} for d in i.diffs][
+                    :MAX_DIFFS_PER_RESOURCE
+                ],
+            }
+            for i in report.items[:MAX_RESOURCES]
+        ]
+    }
+    try:
+        resp = client.complete_json(DRIFT_SYSTEM, json.dumps(payload, default=str))
+    except LLMError as e:
+        _warn(f"AI analysis skipped: {e}")
+        report.ai_error = str(e)
+        return report
+
+    report.ai_used = True
+    report.summary = str(resp.get("summary", "")).strip()
+    by_res = {i.resource: i for i in report.items}
+    for ai in resp.get("items") or []:
+        if not isinstance(ai, dict) or ai.get("resource") not in by_res:
+            continue
+        item = by_res[ai["resource"]]
+        cls = str(ai.get("classification", "")).lower()
+        # Rules are security-first: the model may escalate but never downgrade a risky item,
+        # and never overrides a classification proven from state.
+        if cls in DRIFT_CLASSES and item.classification != "risky" and not item.locked:
+            item.classification = cls
+        item.explanation = str(ai.get("explanation", ""))[:1000]
+        item.recommendation = str(ai.get("recommendation", ""))[:1500]
+    order = {k: i for i, k in enumerate(reversed(DRIFT_CLASSES))}
+    report.items.sort(key=lambda i: (order[i.classification], i.resource))
+    return report

tfscout/cli.py

@@ -0,0 +1,182 @@
+"""Command line interface: `tfscout review` and `tfscout drift`."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from tfscout import __version__
+from tfscout.analyze import run_drift, run_review
+from tfscout.github import GitHub, GitHubError, pr_number_from_event
+from tfscout.llm import PROVIDERS, LLMError, make_client
+from tfscout.plan import PlanError, load_plan
+from tfscout.render import (
+    drift_json,
+    drift_marker,
+    render_drift_md,
+    render_review_md,
+    review_json,
+    review_marker,
+)
+from tfscout.rules import SEVERITIES, sev_rank
+
+EXIT_FAIL_ON = 3
+EXIT_DRIFT = 2
+
+
+def _common(p: argparse.ArgumentParser) -> None:
+    p.add_argument("plan", help="plan file: JSON from `terraform show -json`, or a binary plan (-out=...)")
+    p.add_argument("--name", default="", help="label for this root module (e.g. 'prod/us-east-1')")
+    p.add_argument(
+        "--provider",
+        default=os.environ.get("TFSCOUT_PROVIDER", "none"),
+        choices=PROVIDERS,
+        help="LLM provider; 'none' = deterministic rules only (default: $TFSCOUT_PROVIDER or none)",
+    )
+    p.add_argument("--model", default=os.environ.get("TFSCOUT_MODEL", ""), help="override the model name")
+    p.add_argument(
+        "--base-url", default=os.environ.get("TFSCOUT_BASE_URL", ""), help="override the OpenAI-compatible endpoint"
+    )
+    p.add_argument("--api-key", default="", help="API key (prefer env TFSCOUT_API_KEY or provider env var)")
+    p.add_argument(
+        "--timeout",
+        type=float,
+        default=float(os.environ.get("TFSCOUT_TIMEOUT", "90")),
+        help="seconds to wait for the LLM per attempt (default: 90)",
+    )
+    p.add_argument(
+        "--reasoning-effort",
+        default=os.environ.get("TFSCOUT_REASONING_EFFORT", ""),
+        help="reasoning_effort for thinking models: minimal|low|medium|high (gemini default: low)",
+    )
+    p.add_argument("--format", choices=["markdown", "json"], default="markdown")
+    p.add_argument("--output", "-o", default="", help="write the report to a file instead of stdout")
+    p.add_argument("--terraform-bin", default="terraform", help="terraform/tofu binary for binary plans")
+    p.add_argument("--chdir", default=None, help="working dir for `terraform show` on binary plans")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="tfscout", description="AI-assisted Terraform plan review and drift detection."
+    )
+    parser.add_argument("--version", action="version", version=f"tfscout {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    r = sub.add_parser("review", help="review a plan: risks, security, data loss")
+    _common(r)
+    r.add_argument("--github-comment", action="store_true", help="create/update a PR comment")
+    r.add_argument("--pr", type=int, default=None, help="PR number (default: from GITHUB_EVENT_PATH)")
+    r.add_argument(
+        "--fail-on",
+        choices=["none", *SEVERITIES],
+        default="none",
+        help=f"exit {EXIT_FAIL_ON} if a finding has at least this severity",
+    )
+
+    d = sub.add_parser("drift", help="analyse drift from `terraform plan -refresh-only`")
+    _common(d)
+    d.add_argument("--github-issue", action="store_true", help="create/update/close a drift issue")
+    d.add_argument("--exit-code", action="store_true", help=f"exit {EXIT_DRIFT} when actionable drift is found")
+    return parser
+
+
+def _emit(text: str, output: str) -> None:
+    if output:
+        Path(output).write_text(text + "\n", encoding="utf-8")
+    else:
+        print(text)
+
+
+def _gh_output(**values: str) -> None:
+    path = os.environ.get("GITHUB_OUTPUT")
+    if path:
+        with open(path, "a", encoding="utf-8") as f:
+            for k, v in values.items():
+                f.write(f"{k}={v}\n")
+
+
+def _gh_summary(markdown: str) -> None:
+    path = os.environ.get("GITHUB_STEP_SUMMARY")
+    if path:
+        with open(path, "a", encoding="utf-8") as f:
+            f.write(markdown + "\n\n")
+
+
+def _cmd_review(args: argparse.Namespace, plan, client) -> int:
+    report = run_review(plan, client)
+    md = render_review_md(report, args.name)
+    _emit(md if args.format == "markdown" else review_json(report), args.output)
+    _gh_summary(md)
+    _gh_output(**{"max-severity": report.max_severity, "findings-count": str(len(report.findings))})
+
+    if args.github_comment:
+        pr = args.pr or pr_number_from_event()
+        if not pr:
+            print("tfscout: --github-comment needs a pull_request event or --pr", file=sys.stderr)
+        else:
+            try:
+                url = GitHub.from_env().upsert_pr_comment(pr, review_marker(args.name or "default"), md)
+                print(f"tfscout: PR comment: {url}", file=sys.stderr)
+            except GitHubError as e:
+                print(f"tfscout: failed to comment on PR: {e}", file=sys.stderr)
+                return 1
+
+    if args.fail_on != "none" and report.findings and sev_rank(report.max_severity) >= sev_rank(args.fail_on):
+        print(f"tfscout: findings at or above '{args.fail_on}' severity", file=sys.stderr)
+        return EXIT_FAIL_ON
+    return 0
+
+
+def _cmd_drift(args: argparse.Namespace, plan, client) -> int:
+    report = run_drift(plan, client)
+    md = render_drift_md(report, args.name)
+    _emit(md if args.format == "markdown" else drift_json(report), args.output)
+    _gh_summary(md)
+    has_drift = bool(report.actionable)
+    _gh_output(
+        **{
+            "drift-detected": str(has_drift).lower(),
+            "fingerprint": report.fingerprint,
+            "findings-count": str(len(report.actionable)),
+        }
+    )
+
+    if args.github_issue:
+        title = f"Terraform drift detected{f': {args.name}' if args.name else ''}"
+        try:
+            action, url = GitHub.from_env().sync_drift_issue(
+                drift_marker(args.name or "default"), title, md, report.fingerprint
+            )
+            print(f"tfscout: drift issue {action}{f': {url}' if url else ''}", file=sys.stderr)
+        except GitHubError as e:
+            print(f"tfscout: failed to sync drift issue: {e}", file=sys.stderr)
+            return 1
+
+    return EXIT_DRIFT if args.exit_code and has_drift else 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        plan = load_plan(args.plan, args.terraform_bin, args.chdir)
+    except PlanError as e:
+        print(f"tfscout: error: {e}", file=sys.stderr)
+        return 1
+    try:
+        client = make_client(
+            args.provider,
+            args.model,
+            args.base_url,
+            args.api_key,
+            timeout=args.timeout,
+            reasoning_effort=args.reasoning_effort,
+        )
+    except LLMError as e:
+        # e.g. secrets are not available to pull requests from forks: still produce the rules-only report
+        print(f"tfscout: warning: AI disabled: {e}", file=sys.stderr)
+        client = None
+    if args.command == "review":
+        return _cmd_review(args, plan, client)
+    return _cmd_drift(args, plan, client)

tfscout/diff.py

@@ -0,0 +1,113 @@
+"""Attribute-level diff between `before` and `after` of a resource change."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+UNKNOWN = "(known after apply)"
+_MISSING = object()
+
+
+@dataclass(frozen=True)
+class AttrDiff:
+    path: str
+    before: Any
+    after: Any
+
+
+def _flatten(value: Any, prefix: str, out: dict[str, Any]) -> None:
+    if isinstance(value, dict) and value:
+        for k, v in value.items():
+            _flatten(v, f"{prefix}.{k}" if prefix else str(k), out)
+    elif isinstance(value, list) and value and any(isinstance(v, (dict, list)) for v in value):
+        for i, v in enumerate(value):
+            _flatten(v, f"{prefix}[{i}]", out)
+    else:
+        out[prefix] = value
+
+
+def flatten(value: Any) -> dict[str, Any]:
+    out: dict[str, Any] = {}
+    if value is not None:
+        _flatten(value, "", out)
+    return out
+
+
+def _unknown_paths(after_unknown: Any) -> set[str]:
+    return {p for p, v in flatten(after_unknown).items() if v is True}
+
+
+def _short(v: Any, limit: int) -> Any:
+    if isinstance(v, (dict, list)):
+        v = json.dumps(v, sort_keys=True)
+    if isinstance(v, str) and len(v) > limit:
+        return v[:limit] + f"...(+{len(v) - limit} chars)"
+    return v
+
+
+def _is_object_list(v: Any) -> bool:
+    return isinstance(v, list) and bool(v) and all(isinstance(x, dict) for x in v)
+
+
+def _canon(v: Any) -> str:
+    return json.dumps(v, sort_keys=True, default=str)
+
+
+def _split_object_lists(before: Any, after: Any, prefix: str, extra: list[AttrDiff], sets: set[str]) -> tuple:
+    """Diff lists of objects (e.g. SG ingress, nested blocks) as sets, not by index.
+
+    Matching elements are dropped, the rest are reported as `path[-]` (removed) / `path[+]` (added),
+    so adding one rule doesn't show up as every rule after it "changing".
+    """
+    if not (isinstance(before, dict) and isinstance(after, dict)):
+        return before, after
+    nb: dict[str, Any] = {}
+    na: dict[str, Any] = {}
+    for k in before.keys() | after.keys():
+        path = f"{prefix}.{k}" if prefix else str(k)
+        vb, va = before.get(k, _MISSING), after.get(k, _MISSING)
+        sides_ok = all(x is _MISSING or x is None or isinstance(x, list) for x in (vb, va))
+        if sides_ok and (_is_object_list(vb) or _is_object_list(va)):
+            sets.add(path)
+            lb = vb if isinstance(vb, list) else []
+            la = va if isinstance(va, list) else []
+            kb, ka = [_canon(x) for x in lb], [_canon(x) for x in la]
+            extra += [AttrDiff(f"{path}[-]", x, None) for x, c in zip(lb, kb, strict=True) if c not in ka]
+            extra += [AttrDiff(f"{path}[+]", None, x) for x, c in zip(la, ka, strict=True) if c not in kb]
+            continue
+        rb, ra = _split_object_lists(vb, va, path, extra, sets)
+        if vb is not _MISSING:
+            nb[k] = rb
+        if va is not _MISSING:
+            na[k] = ra
+    return nb, na
+
+
+def diff(before: Any, after: Any, after_unknown: Any = None, value_limit: int = 200) -> list[AttrDiff]:
+    extra: list[AttrDiff] = []
+    sets: set[str] = set()
+    before, after = _split_object_lists(before, after, "", extra, sets)
+    b, a = flatten(before), flatten(after)
+    unknown = {p for p in _unknown_paths(after_unknown) if not any(p.startswith(s + "[") for s in sets)}
+    result: list[AttrDiff] = [
+        AttrDiff(d.path, _short(d.before, value_limit), _short(d.after, value_limit)) for d in extra
+    ]
+    for path in sorted(set(b) | set(a) | unknown):
+        bv = b.get(path, _MISSING)
+        av = UNKNOWN if path in unknown else a.get(path, _MISSING)
+        if bv == av:
+            continue
+        # Treat null / empty / missing as equivalent to avoid noisy diffs
+        if bv in (_MISSING, None, "", [], {}) and av in (_MISSING, None, "", [], {}):
+            continue
+        result.append(
+            AttrDiff(
+                path=path,
+                before=None if bv is _MISSING else _short(bv, value_limit),
+                after=None if av is _MISSING else _short(av, value_limit),
+            )
+        )
+    result.sort(key=lambda d: d.path)
+    return result

tfscout/github.py

@@ -0,0 +1,130 @@
+"""Tiny GitHub REST client (stdlib only) for PR comments and drift issues."""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from typing import Any
+
+MAX_BODY = 65000
+DRIFT_LABEL = "tfscout-drift"
+
+
+class GitHubError(Exception):
+    pass
+
+
+def _truncate(body: str) -> str:
+    if len(body) <= MAX_BODY:
+        return body
+    return body[: MAX_BODY - 200] + "\n\n…\n\n_Report truncated (GitHub size limit). See the workflow artifact._"
+
+
+@dataclass
+class GitHub:
+    token: str
+    repo: str
+    api_url: str = "https://api.github.com"
+
+    @classmethod
+    def from_env(cls, token: str = "") -> GitHub:
+        token = token or os.environ.get("GITHUB_TOKEN", "")
+        repo = os.environ.get("GITHUB_REPOSITORY", "")
+        if not token or not repo:
+            raise GitHubError("GITHUB_TOKEN and GITHUB_REPOSITORY must be set")
+        return cls(token, repo, os.environ.get("GITHUB_API_URL", "https://api.github.com"))
+
+    def _req(self, method: str, path: str, body: Any = None, params: dict[str, Any] | None = None) -> Any:
+        url = f"{self.api_url.rstrip('/')}{path}"
+        if params:
+            url += "?" + urllib.parse.urlencode(params)
+        data = json.dumps(body).encode() if body is not None else None
+        req = urllib.request.Request(
+            url,
+            data=data,
+            method=method,
+            headers={
+                "Authorization": f"Bearer {self.token}",
+                "Accept": "application/vnd.github+json",
+                "X-GitHub-Api-Version": "2022-11-28",
+                "User-Agent": "tfscout",
+                **({"Content-Type": "application/json"} if data else {}),
+            },
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=30) as resp:
+                raw = resp.read()
+                return json.loads(raw) if raw else None
+        except urllib.error.HTTPError as e:
+            raise GitHubError(f"{method} {path}: HTTP {e.code} {e.read().decode(errors='replace')[:300]}") from e
+
+    def _paginate(self, path: str, params: dict[str, Any] | None = None, limit: int = 10):
+        for page in range(1, limit + 1):
+            items = self._req("GET", path, params={**(params or {}), "per_page": 100, "page": page})
+            if not items:
+                return
+            yield from items
+            if len(items) < 100:
+                return
+
+    # ------------------------------------------------------------------ PR comments
+
+    def upsert_pr_comment(self, pr: int, marker: str, body: str) -> str:
+        body = _truncate(body)
+        for c in self._paginate(f"/repos/{self.repo}/issues/{pr}/comments"):
+            if marker in (c.get("body") or ""):
+                self._req("PATCH", f"/repos/{self.repo}/issues/comments/{c['id']}", {"body": body})
+                return c["html_url"]
+        return self._req("POST", f"/repos/{self.repo}/issues/{pr}/comments", {"body": body})["html_url"]
+
+    # ------------------------------------------------------------------ drift issues
+
+    def _find_issue(self, marker: str) -> dict[str, Any] | None:
+        params = {"state": "open", "labels": DRIFT_LABEL}
+        for issue in self._paginate(f"/repos/{self.repo}/issues", params):
+            if "pull_request" not in issue and marker in (issue.get("body") or ""):
+                return issue
+        return None
+
+    def sync_drift_issue(self, marker: str, title: str, body: str, fingerprint: str) -> tuple[str, str]:
+        """Create/update/close the drift issue. Returns (action, url)."""
+        issue = self._find_issue(marker)
+        base = f"/repos/{self.repo}/issues"
+        if not fingerprint:
+            if issue:
+                self._req(
+                    "POST",
+                    f"{base}/{issue['number']}/comments",
+                    {"body": "✅ Drift resolved — infrastructure matches Terraform state again."},
+                )
+                self._req("PATCH", f"{base}/{issue['number']}", {"state": "closed", "state_reason": "completed"})
+                return "closed", issue["html_url"]
+            return "none", ""
+        body = _truncate(body)
+        if issue:
+            if f"`{fingerprint}`" in (issue.get("body") or ""):
+                return "unchanged", issue["html_url"]
+            self._req("PATCH", f"{base}/{issue['number']}", {"title": title, "body": body})
+            self._req(
+                "POST",
+                f"{base}/{issue['number']}/comments",
+                {"body": f"🔄 Drift changed (fingerprint `{fingerprint}`). Report updated above."},
+            )
+            return "updated", issue["html_url"]
+        created = self._req("POST", base, {"title": title, "body": body, "labels": [DRIFT_LABEL]})
+        return "created", created["html_url"]
+
+
+def pr_number_from_event() -> int | None:
+    path = os.environ.get("GITHUB_EVENT_PATH")
+    if not path or not os.path.isfile(path):
+        return None
+    with open(path, encoding="utf-8") as f:
+        event = json.load(f)
+    pr = event.get("pull_request") or {}
+    num = pr.get("number") or (event.get("issue") or {}).get("number")
+    return int(num) if num else None