github-proyect-tracking 0.0.0-stage → 0.4.0

package/skill/scripts/tracking_core/common.py

@@ -0,0 +1,163 @@
+"""Constantes, errores y utilidades compartidas por el CLI."""
+
+from __future__ import annotations
+
+import json
+import re
+import uuid
+from datetime import datetime, timezone
+
+VERSION = "0.4.0"
+API_BASE = "https://api.github.com"
+USER_AGENT = f"github-proyect-tracking/{VERSION}"
+
+STATE_DIR_ENV = "GITHUB_TRACKING_STATE"
+SCHEMA_VERSION = 2
+SUPPORTED_SCHEMA_VERSIONS = (1, SCHEMA_VERSION)
+PROCESS_STATES = ("RUNNING", "ERROR", "FINALIZED", "CANCELADO",
+                  "CLEARED", "ABORTED")
+
+STATUS_INICIANDO = "INICIANDO"
+STATUS_ERROR = "ERROR"
+STATUS_COMPLETADO = "COMPLETADO"
+STATUS_FINALIZADO = "FINALIZADO"
+STATUS_CANCELADO = "CANCELADO"
+
+EXIT_OK = 0
+EXIT_RUNTIME = 1
+EXIT_VALIDATION = 2
+EXIT_TOKEN_INSUFFICIENT = 3
+EXIT_NO_TOKEN = 4
+EXIT_NO_PROCESS = 5
+EXIT_NOT_FOUND = 6
+EXIT_RESUME_REQUIRED = 7
+EXIT_CONFLICT = 8
+
+MAX_STEP_LEN = 200
+MAX_DETAILS_LEN = 60000
+MAX_PLAN_STEPS = 100
+MAX_COMMENT_PAGES = 100
+LOCK_STALE_SECONDS = 120
+LOCK_WAIT_SECONDS = 10
+AMBIGUOUS_HTTP_STATUSES = {500, 502, 503, 504}
+
+REPO_URL_RE = re.compile(
+    r"^https://(?:www\.)?github\.com/"
+    r"(?P<owner>[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?)/"
+    r"(?P<repo>[A-Za-z0-9._-]+?)(?:\.git)?/?$",
+    re.IGNORECASE,
+)
+TITLE_RE = re.compile(
+    r"^\[Process Tracking\]\s*(?:-\s*)?Execution ID:\s*(?P<exec_id>\S+?)\s*$",
+    re.IGNORECASE,
+)
+
+SECRET_REDACTIONS = [
+    (re.compile(r"(?i)\b(authorization|proxy-authorization)\s*[:=]\s*"
+                r"(?:bearer|token|basic)?\s*[A-Za-z0-9._\-+/=~]{8,}"),
+     "[REDactado:authorization]"),
+    (re.compile(r"(?i)\bbearer\s+[A-Za-z0-9._\-+/=]{8,}"), "[REDactado:bearer]"),
+    (re.compile(r"github_pat_[A-Za-z0-9_]{22,}"), "[REDACTADO:github-pat]"),
+    (re.compile(r"\bgh[pousr]_[A-Za-z0-9]{16,}\b"), "[REDactado:github-token]"),
+    (re.compile(r"\bAKIA[0-9A-Z]{16}\b"), "[REDactado:aws-key]"),
+    (re.compile(r"(?i)\b(password|passwd|pwd|secret|api[_-]?key|apikey|"
+                r"client[_-]?secret)\b\s*[=:]\s*['\"]?[A-Za-z0-9._\-+/=~]{6,}"),
+     "[REDactado:secret]"),
+    (re.compile(r"(?i)([a-z][a-z0-9+.\-]*://)[^/@\s]+@"),
+     r"\1[REDactado]@"),
+]
+
+
+class SkillError(Exception):
+    """Error operativo que se serializa como un único objeto JSON."""
+
+    def __init__(self, exit_code, code, message, extra=None):
+        super().__init__(message)
+        self.exit_code = exit_code
+        self.code = code
+        self.message = message
+        self.extra = extra or {}
+
+    def to_json(self):
+        error = {"code": self.code, "message": self.message}
+        error.update(self.extra)
+        return {"ok": False, "error": error}
+
+
+def emit(obj):
+    print(json.dumps(obj, indent=2, ensure_ascii=False), flush=True)
+
+
+def now_iso():
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def new_execution_id():
+    return (f"exec-{datetime.now(timezone.utc):%Y%m%dT%H%M%SZ}-"
+            f"{uuid.uuid4().hex[:12]}")
+
+
+def ordered_unique(items):
+    seen, output = set(), []
+    for item in items:
+        if item and item not in seen:
+            seen.add(item)
+            output.append(item)
+    return output
+
+
+def validate_repo_url(url):
+    if not isinstance(url, str):
+        return None
+    match = REPO_URL_RE.match(url.strip())
+    if not match:
+        return None
+    owner, repo = match.group("owner").lower(), match.group("repo").lower()
+    if ".." in repo or repo.startswith(".") or repo.endswith("."):
+        return None
+    return owner, repo
+
+
+def redact_url(url):
+    if not isinstance(url, str):
+        return repr(url)
+    output = re.sub(r"(?i)([a-z][a-z0-9+.\-]*://)[^/@\s]+@",
+                    r"\1[REDactado]@", url)
+    output = re.sub(r"#.*$", "#[REDactado]", output)
+    return re.sub(r"\?.*$", "?[REDactado]", output)
+
+
+def sanitize_text(text):
+    if not text:
+        return (text or ""), 0
+    output, total = text, 0
+    for regex, replacement in SECRET_REDACTIONS:
+        output, count = regex.subn(replacement, output)
+        total += count
+    return output, total
+
+
+def _step_name_unsafe(name):
+    if not isinstance(name, str) or not name.strip():
+        raise SkillError(EXIT_VALIDATION, "VALIDATION_ERROR",
+                         "nombre de paso requerido (no vacío)")
+    if len(name) > MAX_STEP_LEN:
+        raise SkillError(EXIT_VALIDATION, "VALIDATION_ERROR",
+                         f"nombre de paso demasiado largo (>{MAX_STEP_LEN} caracteres)")
+    if "\n" in name or "\r" in name:
+        raise SkillError(EXIT_VALIDATION, "VALIDATION_ERROR",
+                         "el nombre del paso no puede contener saltos de línea")
+    return name
+
+
+def normalize_step_name(name):
+    normalized = _step_name_unsafe(name).strip()
+    if re.search(r"(?i)\bdetalles\b\s*:", normalized):
+        raise SkillError(EXIT_VALIDATION, "VALIDATION_ERROR",
+                         "el nombre del paso no puede contener 'Detalles:' en "
+                         "ninguna capitalización (rompe el parser de reanudación)")
+    clean, _ = sanitize_text(normalized)
+    if not clean.strip():
+        raise SkillError(EXIT_VALIDATION, "VALIDATION_ERROR",
+                         "el nombre del paso quedó vacío tras sanitizar")
+    return clean.strip()

package/skill/scripts/tracking_core/events.py

@@ -0,0 +1,204 @@
+"""Contrato visible de comentarios, metadatos y planner de reanudación."""
+
+from __future__ import annotations
+
+import json
+import re
+
+from .common import (
+    EXIT_VALIDATION, STATUS_CANCELADO, STATUS_COMPLETADO, STATUS_ERROR,
+    STATUS_FINALIZADO, STATUS_INICIANDO, SkillError, now_iso, ordered_unique,
+)
+
+COMMENT_RE = re.compile(
+    r"\[STATUS:\s*(?P<status>INICIANDO|ERROR|COMPLETADO|FINALIZADO|CANCELADO)\]\s*-\s*"
+    r"(?:Paso:\s*(?P<step>[^\r\n]*?)\s*(?:-\s*Detalles:\s*(?P<details>.*))?[\r\n]*$"
+    r"|(?P<final>El\s+proceso\s+concluy[oó]\s+exitosamente\.?)"
+    r"|(?P<canceled>El\s+proceso\s+fue\s+cerrado\s+anticipadamente.*))",
+    re.IGNORECASE | re.DOTALL | re.MULTILINE,
+)
+PLAN_LINE_RE = re.compile(r"^\s*\d+\.\s+(.+?)\s*$", re.MULTILINE)
+TRANSITION_RE = re.compile(
+    r"\n<!--\s*github-proyect-tracking:\s*(?P<meta>\{.*\})\s*-->\s*$",
+    re.DOTALL,
+)
+
+
+def fmt_iniciando(step):
+    return f"[STATUS: INICIANDO] - Paso: {step}"
+
+
+def fmt_error(step, details):
+    return f"[STATUS: ERROR] - Paso: {step} - Detalles: {details}"
+
+
+def fmt_completado(step):
+    return f"[STATUS: COMPLETADO] - Paso: {step}"
+
+
+def fmt_finalizado():
+    return "[STATUS: FINALIZADO] - El proceso concluyó exitosamente."
+
+
+def fmt_cancelado(pending):
+    if pending:
+        items = ", ".join(pending[:10]) + ("…" if len(pending) > 10 else "")
+        return ("[STATUS: CANCELADO] - El proceso fue cerrado anticipadamente "
+                f"(--force). Pasos pendientes: {items}.")
+    return "[STATUS: CANCELADO] - El proceso fue cerrado anticipadamente (--force)."
+
+
+def transition_metadata(body):
+    match = TRANSITION_RE.search(body or "")
+    if not match:
+        return {}
+    try:
+        data = json.loads(match.group("meta"))
+    except json.JSONDecodeError:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def with_transition_metadata(body, execution_id, sequence, transition_id):
+    metadata = json.dumps({
+        "execution_id": execution_id,
+        "sequence": sequence,
+        "transition_id": transition_id,
+    }, ensure_ascii=False, separators=(",", ":"))
+    return f"{body}\n<!-- github-proyect-tracking: {metadata} -->"
+
+
+def parse_status_comment(body):
+    events = []
+    visible_body = TRANSITION_RE.sub("", body or "")
+    for match in COMMENT_RE.finditer(visible_body):
+        events.append({
+            "status": (match.group("status") or "").upper(),
+            "step": match.group("step").strip() if match.group("step") else None,
+            "details": (match.group("details") or "").strip()
+            if match.group("details") is not None else None,
+        })
+    return events
+
+
+def events_from_comments(comments):
+    events = []
+    for comment in comments or []:
+        body = comment.get("body") or ""
+        metadata = transition_metadata(body)
+        for event in parse_status_comment(body):
+            event["comment_id"] = comment.get("id")
+            event["created_at"] = comment.get("created_at")
+            event["transition_id"] = metadata.get("transition_id")
+            event["execution_id"] = metadata.get("execution_id")
+            event["sequence"] = metadata.get("sequence")
+            events.append(event)
+    events.sort(key=lambda event: (
+        event.get("created_at") or "", event.get("comment_id") or 0))
+    return events
+
+
+def build_issue_body(url, execution_id, plan):
+    lines = [
+        "Proceso rastreado por el skill `github-proyect-tracking`.",
+        "",
+        f"- **Execution ID:** `{execution_id}`",
+        f"- **Proyecto:** {url}",
+        f"- **Iniciado (UTC):** {now_iso()}",
+        "",
+        "## Plan de pasos",
+    ]
+    if plan:
+        lines += [f"{index}. {step}" for index, step in enumerate(plan, 1)]
+    else:
+        lines.append("_(sin plan explícito — los pasos los define el agente "
+                     "durante la ejecución)_")
+    lines += [
+        "",
+        "> El avance se registra como comentarios con el contrato `[STATUS: ...]`.",
+        "> El ÚLTIMO comentario es la fuente de verdad para reanudar.",
+    ]
+    return "\n".join(lines) + "\n"
+
+
+def parse_plan_from_body(body):
+    match = re.search(r"##\s*Plan de pasos(.*?)(?=\n##\s|\Z)", body or "",
+                      re.DOTALL | re.IGNORECASE)
+    if not match:
+        return []
+    return PLAN_LINE_RE.findall(match.group(1))
+
+
+def _validate_resume_plan(plan):
+    plan = list(plan or [])
+    if len(plan) != len(set(plan)):
+        raise SkillError(
+            EXIT_VALIDATION, "PLAN_AMBIGUOUS",
+            "el plan contiene pasos duplicados y no permite una reanudación "
+            "determinista",
+            {"hint": "edita el cuerpo del Issue para asignar un nombre único a "
+                     "cada paso; no se modificó ningún evento"})
+    return plan
+
+
+def plan_resume(events, plan, issue_state="open"):
+    plan = _validate_resume_plan(plan)
+    completed = ordered_unique(
+        event["step"] for event in events
+        if event["status"] == STATUS_COMPLETADO and event.get("step"))
+    output = {
+        "completed_steps": completed,
+        "issue_state": issue_state,
+        "plan": plan,
+        "event_count": len(events),
+    }
+    if issue_state == "closed":
+        if events and events[-1]["status"] == STATUS_FINALIZADO:
+            return {**output, "action": "NONE", "outcome": "FINALIZADO",
+                    "reason": "El proceso ya finalizó y el Issue está cerrado."}
+        if events and events[-1]["status"] == STATUS_CANCELADO:
+            return {**output, "action": "NONE", "outcome": "CANCELADO",
+                    "reason": "El proceso fue CANCELADO (--force) y el Issue "
+                              "está cerrado."}
+        return {**output, "action": "ABORTED_EXTERNALLY", "resume_from_step": None,
+                "reason": "El Issue fue cerrado sin comentario de cierre; "
+                          "consultar al usuario antes de reabrir o iniciar uno nuevo."}
+    if not events:
+        return {**output, "action": "START_FIRST",
+                "resume_from_step": plan[0] if plan else None,
+                "reason": "El Issue no tiene comentarios: comenzar desde el primer paso."}
+    last = events[-1]
+    output["last_status"] = last["status"]
+    if last["status"] == STATUS_FINALIZADO:
+        return {**output, "action": "FINISH_CLEANUP", "resume_from_step": None,
+                "outcome": "FINALIZADO",
+                "reason": "Último comentario FINALIZADO pero el Issue sigue abierto: "
+                          "ejecutar finalize (idempotente) para cerrarlo y limpiar memoria."}
+    if last["status"] == STATUS_CANCELADO:
+        return {**output, "action": "FINISH_CLEANUP", "outcome": "CANCELADO",
+                "reason": "El proceso fue CANCELADO (--force); el Issue sigue "
+                          "abierto: ejecutar finalize (idempotente) para "
+                          "cerrarlo y limpiar memoria."}
+    if last["status"] in (STATUS_ERROR, STATUS_INICIANDO):
+        reason = ("El último paso registró ERROR: re-ejecutar ese paso (o el que "
+                  "generó el error) y continuar con los siguientes."
+                  if last["status"] == STATUS_ERROR else
+                  "El último paso quedó en INICIANDO sin COMPLETADO: re-ejecutar ese paso.")
+        result = {**output, "action": "RERUN_STEP",
+                  "resume_from_step": last.get("step"), "reason": reason}
+        if last["status"] == STATUS_ERROR:
+            result["failed_step"] = last.get("step")
+            result["error_details"] = (last.get("details") or "")[:2000]
+        return result
+    done = set(completed)
+    remaining = [step for step in plan if step not in done]
+    if remaining:
+        return {**output, "action": "NEXT_STEP", "resume_from_step": remaining[0],
+                "remaining_steps": remaining,
+                "reason": "Paso completado: continuar con el siguiente paso del plan."}
+    if plan:
+        return {**output, "action": "ALL_STEPS_DONE", "resume_from_step": None,
+                "reason": "Todos los pasos del plan están COMPLETADO: ejecutar finalize."}
+    return {**output, "action": "NEXT_STEP_AGENT_DEFINED", "resume_from_step": None,
+            "reason": "Sin plan explícito: el agente define el siguiente paso "
+                      "o ejecuta finalize."}

package/skill/scripts/tracking_core/github.py

@@ -0,0 +1,315 @@
+"""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,
+)
+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):
+    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):
+    match = TITLE_RE.match((issue.get("title") or "").strip())
+    return bool(match and match.group("exec_id").lower() == execution_id.lower())