speccycle 1.0.0__py3-none-any.whl

speccycle/__init__.py

@@ -0,0 +1,79 @@
+__version__ = "1.0.0"
+
+from speccycle.i18n import _
+
+PHASES = [
+    {
+        "id": "discovery",
+        "n": 1,
+        "name": "Discovery",
+        "agent": "Discovery Agent",
+        "artifact": "discovery.md",
+        "command": "/scycle:discovery",
+        "desc": _("phase_discovery_desc")
+    },
+    {
+        "id": "intent",
+        "n": 2,
+        "name": "Intent",
+        "agent": "Intent Agent",
+        "artifact": "intent.md",
+        "command": "/scycle:intent",
+        "desc": _("phase_intent_desc")
+    },
+    {
+        "id": "behavior",
+        "n": 3,
+        "name": "Behavior",
+        "agent": "Behavior Agent",
+        "artifact": "behaviors.md",
+        "command": "/scycle:behavior",
+        "desc": _("phase_behavior_desc")
+    },
+    {
+        "id": "blueprint",
+        "n": 4,
+        "name": "Blueprint",
+        "agent": "Blueprint Agent",
+        "artifact": "blueprint.md",
+        "command": "/scycle:blueprint",
+        "desc": _("phase_blueprint_desc")
+    },
+    {
+        "id": "breakdown",
+        "n": 5,
+        "name": "Breakdown",
+        "agent": "Breakdown Agent",
+        "artifact": "breakdown.md",
+        "command": "/scycle:breakdown",
+        "desc": _("phase_breakdown_desc")
+    },
+    {
+        "id": "build",
+        "n": 6,
+        "name": "Build",
+        "agent": "Build Agent",
+        "artifact": "build-log.md",
+        "command": "/scycle:build",
+        "desc": _("phase_build_desc")
+    },
+    {
+        "id": "quality",
+        "n": 7,
+        "name": "Quality",
+        "agent": "Quality Agent",
+        "artifact": "quality-report.md",
+        "command": "/scycle:quality",
+        "desc": _("phase_quality_desc")
+    },
+    {
+        "id": "learning",
+        "n": 8,
+        "name": "Learning",
+        "agent": "Learning Agent",
+        "artifact": "learnings.md",
+        "command": "/scycle:learn",
+        "desc": _("phase_learning_desc")
+    }
+]
+

speccycle/approvals.py

@@ -0,0 +1,156 @@
+"""Persistência do ``approvals.json`` da volta, segura entre processos.
+
+Quem escreve nesse arquivo: o ``approve`` da CLI, o dashboard (aprovar gate,
+iniciar fase), o ``prompt-gate`` ao reiniciar o Build e a sessão de Quality
+reprovada. São processos distintos, às vezes no mesmo segundo. Toda escrita
+passa por :func:`update_approvals`, que:
+
+1. toma um lock do sistema operacional (``msvcrt``/``fcntl``), liberado
+   sozinho se o processo morrer — sem arquivo de lock órfão;
+2. relê o arquivo **dentro** do lock, para nunca regravar uma leitura antiga;
+3. grava num temporário e troca com ``os.replace``, para nenhum leitor ver um
+   arquivo pela metade;
+4. recusa-se a sobrescrever um arquivo que não parseia — melhor falhar com
+   mensagem do que apagar aprovações.
+"""
+
+import contextlib
+import json
+import os
+import sys
+import time
+
+APPROVALS_FILE = "approvals.json"
+LOCK_FILE = "approvals.lock"
+LOCK_TIMEOUT = 15.0
+
+
+class ApprovalsLocked(TimeoutError):
+    """Outro processo segurou o approvals.json por mais tempo que o limite."""
+
+
+class ApprovalsCorrupt(ValueError):
+    """O approvals.json existe mas não é JSON válido; não vai ser sobrescrito."""
+
+
+def approvals_path(cycle_path):
+    return os.path.join(cycle_path, APPROVALS_FILE)
+
+
+def _lock_path(cycle_path):
+    # cycles/NNN-slug -> <raiz>/.speccycle/approvals.lock
+    project_root = os.path.dirname(os.path.dirname(os.path.abspath(cycle_path)))
+    speccycle_dir = os.path.join(project_root, ".speccycle")
+    if not os.path.isdir(speccycle_dir):
+        return os.path.join(os.path.abspath(cycle_path), "." + LOCK_FILE)
+    return os.path.join(speccycle_dir, LOCK_FILE)
+
+
+if sys.platform == "win32":
+    import msvcrt
+
+    def _try_lock(fd):
+        try:
+            msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
+            return True
+        except OSError:
+            return False
+
+    def _unlock(fd):
+        try:
+            msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
+        except OSError:
+            pass
+else:
+    import fcntl
+
+    def _try_lock(fd):
+        try:
+            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            return True
+        except OSError:
+            return False
+
+    def _unlock(fd):
+        try:
+            fcntl.flock(fd, fcntl.LOCK_UN)
+        except OSError:
+            pass
+
+
+@contextlib.contextmanager
+def locked(cycle_path, timeout=LOCK_TIMEOUT):
+    """Lock exclusivo entre processos para o approvals.json desta volta."""
+    lock_path = _lock_path(cycle_path)
+    os.makedirs(os.path.dirname(lock_path), exist_ok=True)
+    fd = os.open(lock_path, os.O_RDWR | os.O_CREAT)
+    try:
+        deadline = time.monotonic() + timeout
+        while not _try_lock(fd):
+            if time.monotonic() > deadline:
+                raise ApprovalsLocked(
+                    f"approvals.json ocupado por outro processo há mais de {timeout:.0f}s ({lock_path})"
+                )
+            time.sleep(0.02)
+        try:
+            yield
+        finally:
+            _unlock(fd)
+    finally:
+        os.close(fd)
+
+
+def _load(path, strict):
+    if not os.path.isfile(path):
+        return {}
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+    except ValueError as e:
+        if strict:
+            raise ApprovalsCorrupt(
+                f"{path} não é JSON válido ({e}); corrija ou remova o arquivo"
+            ) from e
+        return {}
+    except OSError:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def read_approvals(cycle_path):
+    """Leitura sem lock: um arquivo inexistente ou ilegível vale ``{}``."""
+    return _load(approvals_path(cycle_path), strict=False)
+
+
+def _atomic_write(path, data):
+    tmp = f"{path}.{os.getpid()}.tmp"
+    with open(tmp, "w", encoding="utf-8") as f:
+        json.dump(data, f, ensure_ascii=False, indent=2)
+        f.flush()
+        os.fsync(f.fileno())
+    # No Windows, os.replace falha enquanto um leitor tiver o arquivo aberto;
+    # leituras são curtas, então basta insistir por alguns instantes.
+    for attempt in range(50):
+        try:
+            os.replace(tmp, path)
+            return
+        except PermissionError:
+            if attempt == 49:
+                raise
+            time.sleep(0.02)
+
+
+def update_approvals(cycle_path, mutate, timeout=LOCK_TIMEOUT):
+    """Aplica ``mutate(approvals)`` ao arquivo atual, sob lock e de forma atômica.
+
+    ``mutate`` recebe o dict recém-lido e o altera no lugar (ou devolve um
+    novo dict). Devolve o conteúdo gravado.
+    """
+    path = approvals_path(cycle_path)
+    with locked(cycle_path, timeout=timeout):
+        current = _load(path, strict=True)
+        result = mutate(current)
+        if not isinstance(result, dict):
+            result = current
+        _atomic_write(path, result)
+        return result