kcreate-scaffolding-gcp-script 0.0.0-stage → 0.2.1

package/vendor/github-proyect-tracking/scripts/tracking_core/github.py

@@ -0,0 +1,324 @@
+"""Transporte HTTP stdlib, credenciales y operaciones contra GitHub Issues."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import time
+import urllib.error
+import urllib.request
+import uuid
+
+from .common import (
+    AMBIGUOUS_HTTP_STATUSES, API_BASE, EXIT_NOT_FOUND, EXIT_NO_TOKEN,
+    EXIT_RUNTIME, EXIT_TOKEN_INSUFFICIENT, MAX_COMMENT_PAGES, TITLE_RE,
+    USER_AGENT, SkillError, issue_title,
+)
+from .events import events_from_comments, transition_metadata, with_transition_metadata
+
+
+def resolve_token(cli_token=None, state=None):
+    if cli_token:
+        return cli_token, "cli"
+    for variable in ("GITHUB_TRACKING_TOKEN", "GITHUB_TOKEN", "GH_TOKEN"):
+        value = os.environ.get(variable)
+        if value:
+            return value, f"env:{variable}"
+    executable = shutil.which("gh")
+    if executable:
+        try:
+            output = subprocess.run([executable, "auth", "token"],
+                                    capture_output=True, text=True, timeout=15)
+            if output.returncode == 0 and output.stdout.strip():
+                return output.stdout.strip(), "gh:auth"
+        except (OSError, subprocess.SubprocessError):
+            pass
+    if state and state.get("github_token"):
+        return state["github_token"], "state-file"
+    return None, None
+
+
+def check_issues_write(owner, repo, token):
+    try:
+        status, data, headers = api("GET", f"/repos/{owner}/{repo}", token)
+    except SkillError as error:
+        return False, error.code, error.message
+    if status == 401:
+        return False, "INVALID_TOKEN", "el token fue rechazado (401)"
+    if status == 403:
+        return False, "NO_REPO_ACCESS", "el token no tiene acceso al repositorio (403)"
+    if status == 404:
+        return False, "REPO_NOT_FOUND", (f"el repositorio {owner}/{repo} no existe "
+                                         "o es privado para este token (404)")
+    if status != 200:
+        return False, "API_ERROR", f"GET /repos devolvió {status}"
+    if data.get("has_issues") is False:
+        return False, "INSUFFICIENT_PERMISSION", (
+            "el repositorio tiene los Issues deshabilitados (has_issues=false)")
+    scopes = headers.get("X-OAuth-Scopes") or ""
+    permissions = data.get("permissions") or {}
+    can_write_issues = any(
+        permissions.get(key) is True
+        for key in ("triage", "push", "maintain", "admin"))
+    if scopes:
+        available = {scope.strip() for scope in scopes.split(",") if scope.strip()}
+        if not ({"repo", "public_repo"} & available):
+            return False, "INSUFFICIENT_SCOPE", (
+                f"el token classic tiene scopes [{scopes}] pero necesita 'repo' "
+                "(o 'public_repo' para repos públicos) para escribir Issues")
+        if can_write_issues:
+            return True, "OK", ("token classic con scope suficiente y rol con "
+                                "capacidad de gestionar Issues")
+        if permissions:
+            return False, "INSUFFICIENT_PERMISSION", (
+                "el token tiene scope suficiente, pero el repositorio reporta "
+                "un rol sin permiso para gestionar Issues")
+        return True, "UNVERIFIED", (
+            "token classic con scope suficiente; la API no reportó permisos "
+            "efectivos, la escritura se confirmará al crear el Issue")
+    if can_write_issues:
+        return True, "UNVERIFIED", (
+            "token fine-grained/app con permisos de escritura sobre el "
+            "repositorio; el permiso granular Issues:write no es verificable "
+            "en preflight y se confirmará al crear el Issue")
+    return True, "UNVERIFIED", (
+        "token fine-grained/app: el permiso granular Issues:write no es "
+        "verificable en preflight; se confirmará al crear el Issue "
+        "(un 403 en la creación se clasifica como ISSUES_WRITE_FAILED)")
+
+
+def _raw_api(method, path, token, body=None):
+    url = path if path.startswith("http://") or path.startswith("https://") \
+        else API_BASE + path
+    data = None
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Accept": "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+        "User-Agent": USER_AGENT,
+    }
+    if body is not None:
+        data = json.dumps(body).encode("utf-8")
+        headers["Content-Type"] = "application/json"
+    request = urllib.request.Request(url, data=data, headers=headers, method=method)
+    with urllib.request.urlopen(request, timeout=30) as response:
+        raw = response.read().decode("utf-8", errors="replace")
+        parsed = json.loads(raw) if raw.strip() else {}
+        return response.status, parsed, response.headers
+
+
+def api(method, path, token, body=None, retries=3):
+    idempotent = method in ("GET", "HEAD", "PUT", "PATCH", "DELETE")
+    attempt = 0
+    while True:
+        attempt += 1
+        try:
+            status, data, headers = _raw_api(method, path, token, body)
+        except urllib.error.HTTPError as error:
+            raw = error.read().decode("utf-8", errors="replace")
+            try:
+                payload = json.loads(raw) if raw.strip() else {}
+            except json.JSONDecodeError:
+                payload = {"message": raw[:500]}
+            status, data, headers = error.code, payload, error.headers
+        except (urllib.error.URLError, TimeoutError, ConnectionError, OSError) as error:
+            if idempotent and attempt < retries:
+                time.sleep(min(2 ** attempt, 8) * 0.5)
+                continue
+            raise SkillError(EXIT_RUNTIME, "NETWORK_ERROR",
+                             f"API de GitHub inalcanzable ({method} {path}): {error}",
+                             {"hint": "si la operación pudo aplicarse en el servidor, "
+                              "el comando reconciliará con el estado remoto o "
+                              "indicará cómo recuperarlo"})
+        remaining = headers.get("X-RateLimit-Remaining") if headers else None
+        if status in (403, 429) and remaining == "0":
+            reset = int((headers.get("X-RateLimit-Reset") if headers else 0) or 0)
+            if attempt <= retries:
+                time.sleep(min(max(reset - time.time(), 1), 90))
+                continue
+            raise SkillError(EXIT_RUNTIME, "RATE_LIMITED",
+                             "límite de la API de GitHub agotado",
+                             {"reset_epoch": reset})
+        if status in AMBIGUOUS_HTTP_STATUSES and idempotent and attempt < retries:
+            retry_after = headers.get("Retry-After") if headers else None
+            delay = (int(retry_after) if (retry_after or "").isdigit()
+                     else min(2 ** attempt, 8) * 0.5)
+            time.sleep(min(delay, 30))
+            continue
+        return status, data, headers
+
+
+def parse_link_next(link_header):
+    if not link_header:
+        return None
+    for part in link_header.split(","):
+        segments = part.split(";")
+        if len(segments) >= 2 and 'rel="next"' in segments[1]:
+            import re
+            match = re.search(r"<([^>]+)>", segments[0])
+            if match:
+                return match.group(1)
+    return None
+
+
+def fetch_issue(owner, repo, number, token):
+    status, data, _ = api("GET", f"/repos/{owner}/{repo}/issues/{number}", token)
+    if status == 404:
+        raise SkillError(EXIT_NOT_FOUND, "ISSUE_NOT_FOUND",
+                         f"el Issue #{number} no existe en {owner}/{repo}")
+    if status != 200:
+        raise SkillError(EXIT_RUNTIME, "ISSUE_FETCH_FAILED",
+                         f"GET issue devolvió {status}: {data.get('message', '')}")
+    return data
+
+
+def fetch_all_comments(owner, repo, number, token):
+    url = (f"{API_BASE}/repos/{owner}/{repo}/issues/{number}/comments"
+           f"?per_page=100")
+    output, pages = [], 0
+    while url:
+        pages += 1
+        if pages > MAX_COMMENT_PAGES:
+            raise SkillError(EXIT_RUNTIME, "COMMENTS_TOO_MANY",
+                             f"el Issue #{number} supera {MAX_COMMENT_PAGES * 100} "
+                             "comentarios; no se puede garantizar cuál es el "
+                             "último evento",
+                             {"hint": "archiva el Issue y comienza uno nuevo, o "
+                              "eleva tracking.MAX_COMMENT_PAGES con criterio"})
+        status, data, headers = api("GET", url, token)
+        if status != 200:
+            raise SkillError(EXIT_RUNTIME, "COMMENTS_FETCH_FAILED",
+                             f"GET comments devolvió {status}: "
+                             f"{data.get('message', '')}")
+        output.extend(data if isinstance(data, list) else [])
+        url = parse_link_next(headers.get("Link") if headers else None)
+    return output
+
+
+def _classify_post_failure(status, data, what):
+    message = data.get("message", "")
+    if status == 403:
+        return SkillError(EXIT_TOKEN_INSUFFICIENT, "ISSUES_WRITE_FAILED",
+                          f"no se pudo {what} ({status}): {message} — el token no "
+                          "puede escribir en este repositorio (issues:write)")
+    return SkillError(EXIT_RUNTIME, "COMMENT_FAILED",
+                      f"no se pudo {what} ({status}): {message}")
+
+
+def post_comment(owner, repo, number, body, token,
+                 baseline_ids=None, execution_id=None, sequence=None):
+    path = f"/repos/{owner}/{repo}/issues/{number}/comments"
+    transition_id = uuid.uuid4().hex
+    wire_body = body if execution_id is None else with_transition_metadata(
+        body, execution_id, sequence or 1, transition_id)
+
+    def result(comment, reconciled):
+        return {"comment_id": comment.get("id"),
+                "comment_url": comment.get("html_url"),
+                "transition_id": transition_id,
+                "reconciled": reconciled}
+
+    def matching(comments, baseline):
+        for comment in reversed(comments):
+            if baseline is not None and comment.get("id") in baseline:
+                continue
+            if execution_id is not None:
+                if transition_metadata(comment.get("body") or "").get(
+                        "transition_id") == transition_id:
+                    return comment
+            elif (comment.get("body") or "").strip() == body.strip():
+                return comment
+        return None
+
+    lost = None
+    try:
+        status, data, _ = api("POST", path, token, {"body": wire_body})
+        if status in (200, 201):
+            return result(data, False)
+        if status not in AMBIGUOUS_HTTP_STATUSES:
+            raise _classify_post_failure(status, data, "publicar el comentario")
+        lost = SkillError(EXIT_RUNTIME, "COMMENT_AMBIGUOUS",
+                          f"el servidor devolvió {status}; el comentario pudo "
+                          "haberse aplicado")
+    except SkillError as error:
+        if error.code != "NETWORK_ERROR":
+            raise
+        lost = error
+
+    try:
+        comments = fetch_all_comments(owner, repo, number, token)
+    except SkillError:
+        raise lost
+    comment = matching(comments, baseline_ids)
+    if comment:
+        return result(comment, True)
+
+    second_baseline = frozenset(comment.get("id") for comment in comments)
+    second_error = None
+    try:
+        status, data, _ = api("POST", path, token, {"body": wire_body})
+        if status in (200, 201):
+            return result(data, False)
+        if status not in AMBIGUOUS_HTTP_STATUSES:
+            raise _classify_post_failure(status, data, "publicar el comentario")
+        second_error = _classify_post_failure(
+            status, data, "confirmar el comentario tras una respuesta ambigua")
+    except SkillError as error:
+        if error.code != "NETWORK_ERROR":
+            raise
+        second_error = error
+
+    try:
+        second_comments = fetch_all_comments(owner, repo, number, token)
+    except SkillError:
+        raise second_error
+    comment = matching(second_comments, second_baseline)
+    if comment:
+        return result(comment, True)
+    raise second_error
+
+
+def close_issue(owner, repo, number, token):
+    status, data, _ = api("PATCH", f"/repos/{owner}/{repo}/issues/{number}",
+                          token, {"state": "closed"})
+    if status == 403:
+        raise SkillError(EXIT_TOKEN_INSUFFICIENT, "ISSUES_WRITE_FAILED",
+                         f"no se pudo cerrar el Issue (403): "
+                         f"{data.get('message', '')}")
+    if status != 200:
+        raise SkillError(EXIT_RUNTIME, "ISSUE_CLOSE_FAILED",
+                         f"no se pudo cerrar el Issue ({status}): "
+                         f"{data.get('message', '')}")
+    return data
+
+
+def find_issue_by_title(owner, repo, title, token):
+    # v0.5.0: title ya viene construido con issue_title()
+    url = (f"{API_BASE}/repos/{owner}/{repo}/issues?state=all&sort=created"
+           "&direction=desc&per_page=100")
+    seen = set()
+    while url and url not in seen:
+        seen.add(url)
+        status, data, headers = api("GET", url, token)
+        if status != 200 or not isinstance(data, list):
+            return None
+        for issue in data:
+            if (issue.get("title") or "").strip() == title:
+                return issue
+        url = parse_link_next(headers.get("Link") if headers else None)
+    return None
+
+
+def canonical_title_match(issue, execution_id, process_name=None):
+    """v0.5.0: casa el título canónico con o sin nombre de proceso; el
+    exec_id debe coincidir EXACTO y, si se indica process_name, también."""
+    match = TITLE_RE.match((issue.get("title") or "").strip())
+    if not match or match.group("exec_id").lower() != execution_id.lower():
+        return False
+    if process_name:
+        found = match.group("process_name")
+        if (found or "").strip().lower() != str(process_name).strip().lower():
+            return False
+    return True