github-proyect-tracking 0.0.0-stage → 0.4.0

package/skill/scripts/tracking_core/state.py

@@ -0,0 +1,379 @@
+"""Persistencia local, esquema v2, migración v1 y locks con heartbeat."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import threading
+import time
+import uuid
+from datetime import datetime
+from pathlib import Path
+
+from .common import (
+    EXIT_NO_PROCESS, EXIT_RUNTIME, EXIT_VALIDATION, LOCK_STALE_SECONDS,
+    LOCK_WAIT_SECONDS, PROCESS_STATES, SCHEMA_VERSION, STATE_DIR_ENV,
+    SUPPORTED_SCHEMA_VERSIONS, SkillError, now_iso, validate_repo_url,
+)
+
+
+def state_dir():
+    override = os.environ.get(STATE_DIR_ENV)
+    if override:
+        return Path(override).expanduser()
+    return Path.home() / ".github-proyect-tracking"
+
+
+def state_file_for(owner, repo):
+    return state_dir() / f"{owner}__{repo}.json"
+
+
+def _corrupt(path, why):
+    return SkillError(EXIT_RUNTIME, "STATE_CORRUPT",
+                      f"archivo de estado corrupto ({path}): {why}",
+                      {"hint": "usa 'clear --hard' para regenerarlo y 'adopt' "
+                               "para recuperar el Issue remoto"})
+
+
+def _valid_state_timestamp(value):
+    if not isinstance(value, str) or not value:
+        return False
+    try:
+        datetime.fromisoformat(value.replace("Z", "+00:00"))
+        return True
+    except ValueError:
+        return False
+
+
+def migrate_state(state):
+    if state.get("schema_version") != 1:
+        return state
+    migrated = dict(state)
+    migrated["schema_version"] = SCHEMA_VERSION
+    if migrated.get("completed_steps") is None:
+        migrated["completed_steps"] = []
+    if migrated.get("history") is None:
+        migrated["history"] = []
+    migrated["history"] = [dict(item) if isinstance(item, dict) else item
+                           for item in migrated["history"]]
+    for item in migrated["history"]:
+        if isinstance(item, dict) and "outcome" not in item:
+            item["outcome"] = "CANCELADO" if item.get("forced") else "FINALIZADO"
+    return migrated
+
+
+def validate_state(state, path):
+    if not isinstance(state, dict):
+        raise _corrupt(path, "no es un objeto JSON")
+    version = state.get("schema_version")
+    if version not in SUPPORTED_SCHEMA_VERSIONS:
+        raise SkillError(EXIT_RUNTIME, "STATE_SCHEMA",
+                         f"schema_version {version!r} no soportado "
+                         f"(esperado 1 o {SCHEMA_VERSION}) en {path}",
+                         {"hint": "usa clear --hard y adopt para reconstruir"})
+
+    def require_string(key, allow_none=True, allow_empty=False):
+        value = state.get(key)
+        if value is None and allow_none:
+            return
+        if (not isinstance(value, str)
+                or (not allow_empty and not value.strip())):
+            raise _corrupt(path, f"{key} inválido")
+
+    active = state.get("active_process_id")
+    if active is not None and (type(active) is not int or active <= 0):
+        raise _corrupt(path, f"active_process_id inválido: {active!r}")
+    process_state = state.get("process_state")
+    if process_state not in PROCESS_STATES:
+        raise _corrupt(path, f"process_state inválido: {process_state!r}")
+    if active is not None and process_state not in ("RUNNING", "ERROR"):
+        raise _corrupt(path, "un proceso activo debe estar RUNNING o ERROR")
+    if active is None and process_state in ("RUNNING", "ERROR"):
+        raise _corrupt(path, "un proceso RUNNING o ERROR requiere active_process_id")
+    for key in ("owner", "repo"):
+        require_string(key, allow_none=False)
+    for key in ("execution_id", "issue_url", "current_step"):
+        require_string(key)
+    if active is not None:
+        require_string("execution_id", allow_none=False)
+    if state.get("github_project_url") is not None:
+        require_string("github_project_url")
+        target = validate_repo_url(state["github_project_url"])
+        if target != (state["owner"].lower(), state["repo"].lower()):
+            raise _corrupt(path, "github_project_url no coincide con owner/repo")
+
+    for key in ("plan", "completed_steps"):
+        value = state.get(key)
+        if value is None and key == "plan":
+            continue
+        if (not isinstance(value, list)
+                or not all(isinstance(item, str) and item.strip()
+                           for item in value)):
+            raise _corrupt(path, f"{key} inválido (lista de cadenas no vacías)")
+        if len(value) != len(set(value)):
+            raise _corrupt(path, f"{key} contiene elementos duplicados")
+    require_string("github_token", allow_empty=True)
+    for key in ("created_at", "updated_at", "cleared_at"):
+        if state.get(key) is not None and not _valid_state_timestamp(state[key]):
+            raise _corrupt(path, f"{key} no es una fecha ISO válida")
+    if state.get("adopted") is not None and not isinstance(state["adopted"], bool):
+        raise _corrupt(path, "adopted debe ser booleano")
+
+    history = state.get("history")
+    if history is not None:
+        if not isinstance(history, list):
+            raise _corrupt(path, "history inválido (lista de objetos)")
+        for item in history:
+            if not isinstance(item, dict):
+                raise _corrupt(path, "history contiene una entrada que no es objeto")
+            number = item.get("issue_number")
+            if type(number) is not int or number <= 0:
+                raise _corrupt(path, "history.issue_number inválido")
+            for key in ("execution_id", "issue_url"):
+                if (not isinstance(item.get(key), str)
+                        or not item.get(key).strip()):
+                    raise _corrupt(path, f"history.{key} inválido")
+            if not _valid_state_timestamp(item.get("finished_at")):
+                raise _corrupt(path, "history.finished_at inválido")
+            if not isinstance(item.get("forced"), bool):
+                raise _corrupt(path, "history.forced debe ser booleano")
+            if item.get("outcome") not in ("FINALIZADO", "CANCELADO"):
+                raise _corrupt(path, "history.outcome inválido")
+            if item["forced"] != (item["outcome"] == "CANCELADO"):
+                raise _corrupt(path, "history.forced contradice history.outcome")
+
+    aborted = state.get("aborted")
+    if aborted is not None:
+        if (not isinstance(aborted, dict)
+                or type(aborted.get("issue_number")) is not int
+                or aborted["issue_number"] <= 0
+                or not isinstance(aborted.get("issue_url"), str)
+                or not _valid_state_timestamp(aborted.get("at"))):
+            raise _corrupt(path, "aborted inválido")
+    last_error = state.get("last_error")
+    if last_error is not None:
+        if (not isinstance(last_error, dict)
+                or not isinstance(last_error.get("step"), str)
+                or not last_error["step"].strip()
+                or not _valid_state_timestamp(last_error.get("at"))):
+            raise _corrupt(path, "last_error inválido")
+    resumed = state.get("last_resume")
+    if resumed is not None:
+        if not isinstance(resumed, dict):
+            raise _corrupt(path, "last_resume inválido")
+        if type(resumed.get("issue_number")) is not int \
+                or resumed["issue_number"] <= 0 \
+                or not _valid_state_timestamp(resumed.get("at")):
+            raise _corrupt(path, "last_resume requiere Issue y fecha válidos")
+        if resumed.get("verdict") not in (
+                "NONE", "ABORTED_EXTERNALLY", "START_FIRST", "FINISH_CLEANUP",
+                "RERUN_STEP", "NEXT_STEP", "ALL_STEPS_DONE",
+                "NEXT_STEP_AGENT_DEFINED"):
+            raise _corrupt(path, "last_resume.verdict inválido")
+        value = resumed.get("event_comment_id")
+        if value is not None and (type(value) is not int or value <= 0):
+            raise _corrupt(path, "last_resume.event_comment_id inválido")
+        for key in ("event_transition_id", "failed_step"):
+            value = resumed.get(key)
+            if value is not None and (not isinstance(value, str) or not value):
+                raise _corrupt(path, f"last_resume.{key} inválido")
+
+
+def load_state(path):
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return None
+    except OSError as error:
+        raise SkillError(EXIT_RUNTIME, "STATE_UNREADABLE",
+                         f"no se pudo leer {path}: {error}")
+    try:
+        state = json.loads(raw)
+    except json.JSONDecodeError as error:
+        raise _corrupt(path, f"JSON inválido: {error}")
+    state = migrate_state(state)
+    validate_state(state, path)
+    return state
+
+
+def save_state(path, state):
+    state["schema_version"] = SCHEMA_VERSION
+    state["updated_at"] = now_iso()
+    validate_state(state, path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        os.chmod(path.parent, 0o700)
+    except OSError:
+        pass
+    tmp = path.with_name(f"{path.name}.{os.getpid()}.{uuid.uuid4().hex[:6]}.tmp")
+    try:
+        descriptor = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+        with os.fdopen(descriptor, "w", encoding="utf-8") as stream:
+            stream.write(json.dumps(state, indent=2, ensure_ascii=False) + "\n")
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(tmp, path)
+    except OSError as error:
+        tmp.unlink(missing_ok=True)
+        raise SkillError(EXIT_RUNTIME, "STATE_SAVE_FAILED",
+                         f"no se pudo guardar {path}: {error}")
+
+
+class StateLock:
+    """Candado por repositorio con propietario y heartbeat durante toda su vida."""
+
+    HEARTBEAT_INTERVAL = 5.0
+    STALE_SECONDS = LOCK_STALE_SECONDS
+    WAIT_SECONDS = LOCK_WAIT_SECONDS
+
+    def __init__(self, path):
+        self.lockdir = path.parent / (path.name + ".lock")
+        self._owner_file = self.lockdir / "owner.json"
+        self._token = f"{os.getpid()}-{uuid.uuid4().hex[:8]}"
+        self._lost = False
+        self._stop_event = threading.Event()
+        self._worker = None
+
+    def _write_owner(self):
+        tmp = self.lockdir / f"owner.{self._token}.tmp"
+        with tmp.open("w", encoding="utf-8") as stream:
+            json.dump({"token": self._token, "pid": os.getpid(),
+                       "ts": time.time()}, stream)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(tmp, self._owner_file)
+        os.utime(self.lockdir, None)
+
+    def _still_owner(self):
+        try:
+            data = json.loads(self._owner_file.read_text(encoding="utf-8"))
+            return isinstance(data, dict) and data.get("token") == self._token
+        except (OSError, json.JSONDecodeError):
+            return False
+
+    def heartbeat(self):
+        if self._lost:
+            return
+        if not self._still_owner():
+            self._lost = True
+            return
+        try:
+            self._write_owner()
+        except OSError:
+            self._lost = True
+
+    def _heartbeat_loop(self):
+        while not self._stop_event.wait(self.HEARTBEAT_INTERVAL):
+            self.heartbeat()
+            if self._lost:
+                return
+
+    def _steal_stale_lock(self):
+        try:
+            age = time.time() - self.lockdir.stat().st_mtime
+        except OSError:
+            return True
+        if age <= self.STALE_SECONDS:
+            return False
+        shutil.rmtree(self.lockdir, ignore_errors=True)
+        return True
+
+    def __enter__(self):
+        self.lockdir.parent.mkdir(parents=True, exist_ok=True)
+        deadline = time.monotonic() + self.WAIT_SECONDS
+        while True:
+            try:
+                os.mkdir(self.lockdir, 0o700)
+                self._write_owner()
+                self._worker = threading.Thread(
+                    target=self._heartbeat_loop,
+                    name=f"tracking-lock-{os.getpid()}", daemon=True)
+                self._worker.start()
+                return self
+            except FileExistsError:
+                if self._steal_stale_lock():
+                    continue
+                if time.monotonic() > deadline:
+                    raise SkillError(EXIT_RUNTIME, "STATE_LOCKED",
+                                     f"otro comando está escribiendo el estado "
+                                     f"({self.lockdir}); reintenta en unos segundos")
+                time.sleep(0.2)
+            except OSError as error:
+                shutil.rmtree(self.lockdir, ignore_errors=True)
+                raise SkillError(EXIT_RUNTIME, "STATE_LOCK_FAILED",
+                                 f"no se pudo adquirir {self.lockdir}: {error}")
+
+    def __exit__(self, *exc):
+        self._stop_event.set()
+        if self._worker is not None:
+            self._worker.join(timeout=self.HEARTBEAT_INTERVAL + 1)
+        if not self._lost and self._still_owner():
+            shutil.rmtree(self.lockdir, ignore_errors=True)
+        return False
+
+    def ensure_owner(self):
+        if self._lost or not self._still_owner():
+            self._lost = True
+            raise SkillError(EXIT_RUNTIME, "STATE_LOCK_LOST",
+                             "el candado de estado fue tomado por otro proceso "
+                             "durante la operación; NO se escribió el estado local. "
+                             "Ejecuta resume para re-sincronizar desde el Issue")
+
+
+def is_unfinished(state):
+    return bool(state) \
+        and state.get("active_process_id") is not None \
+        and state.get("process_state") in ("RUNNING", "ERROR")
+
+
+def list_state_files():
+    directory = state_dir()
+    if not directory.is_dir():
+        return []
+    output = []
+    for path in directory.glob("*.json"):
+        try:
+            raw = json.loads(path.read_text(encoding="utf-8"))
+            if (isinstance(raw, dict)
+                    and raw.get("schema_version") in SUPPORTED_SCHEMA_VERSIONS):
+                output.append(path)
+        except (OSError, json.JSONDecodeError):
+            continue
+    return output
+
+
+def _repos_of(paths):
+    return [path.name[:-5].replace("__", "/") for path in paths]
+
+
+def select_state_path(allow_recent=True):
+    files = list_state_files()
+    if not files:
+        raise SkillError(EXIT_NO_PROCESS, "NO_STATE",
+                         "no hay archivo de estado; pasa --url "
+                         "https://github.com/{owner}/{repo} o ejecuta init")
+    unfinished = []
+    for path in files:
+        if is_unfinished(load_state(path)):
+            unfinished.append(path)
+    if len(unfinished) == 1:
+        return unfinished[0]
+    if len(unfinished) > 1:
+        raise SkillError(EXIT_VALIDATION, "CONTEXT_AMBIGUOUS",
+                         "hay varios procesos activos; indica el repositorio con --url",
+                         {"active_repos": _repos_of(unfinished)})
+    if not allow_recent and len(files) > 1:
+        raise SkillError(EXIT_VALIDATION, "CONTEXT_AMBIGUOUS",
+                         "hay varios estados locales; clear requiere --url",
+                         {"repos": _repos_of(files)})
+    return max(files, key=lambda path: path.stat().st_mtime)
+
+
+def public_state(state):
+    if not state:
+        return None
+    output = dict(state)
+    if output.get("github_token"):
+        output["github_token"] = "<stored>"
+    return output