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

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

@@ -0,0 +1,208 @@
+"""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.6.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,
+)
+# Título dual (v0.5.0): con o sin nombre de proceso.
+#   [Process Tracking][Mi Skill] Execution ID: exec-...
+#   [Process Tracking] Execution ID: exec-...           (formato <=0.4.x)
+TITLE_RE = re.compile(
+    r"^\[Process Tracking\]"
+    r"(?:\[(?P<process_name>"
+    r"(?:[^\[\]\r\n]|\[RED[Aa]ctado:[^\[\]]*\]){1,200}"
+    r")\])?"
+    r"\s*(?:-\s*)?Execution ID:\s*(?P<exec_id>\S+?)\s*$",
+    re.IGNORECASE,
+)
+MAX_PROCESS_NAME_LEN = 100
+
+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]@"),
+]
+
+
+def normalize_process_name(name):
+    """Normaliza el nombre del proceso (skill padre) para título y cuerpo
+    del Issue. Orden V2-aprendido: validar la entrada CRUDA (longitud y
+    corchetes) ANTES de sanitizar — los marcadores [REDactado:...] que
+    introduce la sanitización son legítimos y TITLE_RE los acepta."""
+    if name is None:
+        return None
+    text = str(name).strip()
+    if not text:
+        return None
+    if len(text) > MAX_PROCESS_NAME_LEN:
+        raise SkillError(
+            EXIT_VALIDATION, "VALIDATION_ERROR",
+            f"el nombre del proceso no puede exceder {MAX_PROCESS_NAME_LEN} "
+            f"caracteres (recibido: {len(text)})")
+    if any(ch in text for ch in "[]\r\n"):
+        raise SkillError(EXIT_VALIDATION, "VALIDATION_ERROR",
+                         "el nombre del proceso no puede contener '[', ']' "
+                         "ni saltos de línea (rompe el título canónico)")
+    clean, _ = sanitize_text(text)
+    clean = clean.strip()
+    if not clean:
+        raise SkillError(EXIT_VALIDATION, "VALIDATION_ERROR",
+                         "el nombre del proceso quedó vacío tras sanitizar")
+    return clean
+
+
+def issue_title(execution_id, process_name=None):
+    """Título canónico del Issue con el nombre del proceso (v0.5.0).
+    El nombre debe venir YA normalizado (normalize_process_name); aquí no
+    se re-valida porque los marcadores [REDactado:...] son legítimos."""
+    if process_name:
+        return f"[Process Tracking][{process_name}] Execution ID: {execution_id}"
+    return f"[Process Tracking] Execution ID: {execution_id}"
+
+
+
+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/vendor/github-proyect-tracking/scripts/tracking_core/events.py

@@ -0,0 +1,233 @@
+"""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 _normalized_inputs(process_inputs):
+    """Normaliza los parámetros de entrada a pares (clave, valor) ordenados,
+    con ambos convertidos a cadena. Devuelve [] si no hay inputs."""
+    if not process_inputs:
+        return []
+    if not isinstance(process_inputs, dict):
+        return []
+    entries = []
+    for key in sorted(process_inputs, key=str):
+        value = process_inputs[key]
+        entries.append((str(key).strip(), str(value)))
+    return [(k, v) for k, v in entries if k]
+
+
+def build_issue_body(url, execution_id, plan, process_name=None,
+                     process_inputs=None):
+    lines = [
+        "Proceso rastreado por el skill `github-proyect-tracking`.",
+        "",
+        f"- **Execution ID:** `{execution_id}`",
+    ]
+    if process_name:
+        lines.append(f"- **Proceso:** {process_name}")
+    lines += [
+        f"- **Proyecto:** {url}",
+        f"- **Iniciado (UTC):** {now_iso()}",
+    ]
+
+    # v0.6.0: parámetros de entrada del proceso — la única forma de saber
+    # exactamente qué tarea estaba realizando esta ejecución.
+    entries = _normalized_inputs(process_inputs)
+    if entries:
+        lines += ["", "## Parámetros de entrada", ""]
+        lines += [f"- **{key}:** `{value}`" for key, value in entries]
+
+    lines += [
+        "",
+        "## 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."}