higpertext-cli 0.8.0__py3-none-any.whl

higpertext/kernel/infrastructure/execution/resilience.py

@@ -0,0 +1,155 @@
+"""higpertext Resilience — Retry con backoff exponencial y Circuit Breaker por capability
+(Infraestructura)."""
+
+import time
+import threading
+from dataclasses import dataclass, field
+from enum import Enum
+
+from higpertext.kernel.infrastructure.logger import get_logger
+_log = get_logger()
+
+
+class CircuitState(Enum):
+    CLOSED = "closed"
+    OPEN = "open"
+    HALF_OPEN = "half_open"
+
+
+@dataclass
+class CircuitBreaker:
+    failure_threshold: int = 3
+    recovery_timeout: float = 60.0
+    success_threshold: int = 1
+
+    _state: CircuitState = field(default=CircuitState.CLOSED, init=False, repr=False)
+    _failure_count: int = field(default=0, init=False, repr=False)
+    _success_count: int = field(default=0, init=False, repr=False)
+    _opened_at: float = field(default=0.0, init=False, repr=False)
+    _lock: threading.Lock = field(default_factory=threading.Lock, init=False, repr=False)
+
+    @property
+    def state(self) -> CircuitState:
+        with self._lock:
+            if self._state == CircuitState.OPEN:
+                if time.monotonic() - self._opened_at >= self.recovery_timeout:
+                    self._state = CircuitState.HALF_OPEN
+                    self._success_count = 0
+            return self._state
+
+    def is_allowed(self) -> bool:
+        return self.state != CircuitState.OPEN
+
+    def record_success(self) -> None:
+        with self._lock:
+            self._failure_count = 0
+            if self._state == CircuitState.HALF_OPEN:
+                self._success_count += 1
+                if self._success_count >= self.success_threshold:
+                    self._state = CircuitState.CLOSED
+                    _log.info("[Circuit] Circuito CERRADO — servicio recuperado.")
+
+    def record_failure(self) -> None:
+        with self._lock:
+            self._failure_count += 1
+            if self._state == CircuitState.HALF_OPEN:
+                self._state = CircuitState.OPEN
+                self._opened_at = time.monotonic()
+                _log.info(
+f"[Circuit] Circuito ABIERTO nuevamente — reintentando en {
+                        self.recovery_timeout}s."
+                )
+            elif (
+                self._state == CircuitState.CLOSED and self._failure_count >= self.failure_threshold
+            ):
+                self._state = CircuitState.OPEN
+                self._opened_at = time.monotonic()
+                _log.error(
+f"[Circuit] Circuito ABIERTO tras {
+                        self._failure_count} fallos consecutivos — reintentando en {
+                        self.recovery_timeout}s."
+                )
+
+
+class ResilienceManager:
+    DEFAULT_MAX_RETRIES = 3
+    DEFAULT_BASE_DELAY = 2.0
+    DEFAULT_MAX_DELAY = 30.0
+    DEFAULT_JITTER = 0.5
+
+    def __init__(self) -> None:
+        self._breakers: dict[str, CircuitBreaker] = {}
+        self._lock = threading.Lock()
+
+    def get_breaker(self, capability_id: str) -> CircuitBreaker:
+        with self._lock:
+            if capability_id not in self._breakers:
+                self._breakers[capability_id] = CircuitBreaker()
+            return self._breakers[capability_id]
+
+    def execute_with_resilience(
+        self,
+        capability_id: str,
+        fn,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        base_delay: float = DEFAULT_BASE_DELAY,
+        max_delay: float = DEFAULT_MAX_DELAY,
+    ):
+        import random
+
+        breaker = self.get_breaker(capability_id)
+
+        if not breaker.is_allowed():
+            timeout_s = f"{breaker.recovery_timeout:.0f}s"
+            _log.info(
+                f"[Circuit] Capability '{capability_id}' bloqueada — circuito ABIERTO."
+                f" Reintentando automáticamente en {timeout_s}."
+            )
+            return None
+
+        for attempt in range(1, max_retries + 1):
+            result = fn()
+
+            if result is not None and result.returncode == 0:
+                breaker.record_success()
+                return result
+
+            breaker.record_failure()
+
+            if not breaker.is_allowed():
+                _log.info(f"[Retry] Circuito abierto — deteniendo reintentos para '{capability_id}'.")
+                return result
+
+            if attempt < max_retries:
+                delay = min(base_delay * (2 ** (attempt - 1)), max_delay)
+                jitter = delay * self.DEFAULT_JITTER * random.random()
+                wait = delay + jitter
+                _log.info(
+                    f"[Retry] Intento {attempt}/{max_retries} falló para '{capability_id}'."
+                    f" Reintentando en {wait:.1f}s..."
+                )
+                time.sleep(wait)
+            else:
+                _log.info(f"[Retry] Agotados {max_retries} intentos para '{capability_id}'.")
+
+        return result
+
+    def get_status(self) -> dict:
+        with self._lock:
+            return {
+                cap_id: {
+                    "state": breaker.state.value,
+                    "failures": breaker._failure_count,
+                }
+                for cap_id, breaker in self._breakers.items()
+            }
+
+
+_resilience_manager: ResilienceManager | None = None
+
+
+def get_resilience_manager() -> ResilienceManager:
+    global _resilience_manager
+    if _resilience_manager is None:
+        _resilience_manager = ResilienceManager()
+    return _resilience_manager

higpertext/kernel/infrastructure/file_repositories.py

@@ -0,0 +1,213 @@
+"""Implementaciones concretas de repositorios JSON (Infraestructura)."""
+
+from __future__ import annotations
+from higpertext.kernel.config_paths import WORKSPACE_DIR_NAME, FILE_EXTENSION
+import json
+import os
+from pathlib import Path
+from higpertext.kernel.application.ports import (
+    IProfileRepository,
+    ICapabilityRepository,
+    IWorkflowRepository,
+    ISessionRepository,
+)
+from higpertext.kernel.domain.entities import Profile, Capability, Workflow, Session
+
+
+class FileProfileRepository(IProfileRepository):
+    def __init__(self, base_profiles_dir: Path):
+        self.profiles_dir = base_profiles_dir
+
+    def _get_custom_profiles_dir(self) -> Path:
+        return Path(os.getcwd()).resolve() / WORKSPACE_DIR_NAME / "profiles"
+
+    def _get_project_profiles_dir(self) -> Path:
+        return Path(os.getcwd()).resolve() / "src" / "config" / "profiles"
+
+    def _get_all_files(self) -> list[Path]:
+        pattern = f"*{FILE_EXTENSION}"
+        files = list(self.profiles_dir.glob(pattern))
+        for extra_dir in (
+            self._get_custom_profiles_dir(),
+            self._get_project_profiles_dir(),
+        ):
+            if extra_dir.exists():
+                files.extend(extra_dir.glob(pattern))
+        return files
+
+    def load(self, name: str) -> Profile:
+        filename = f"{name}{FILE_EXTENSION}"
+        candidates = [
+            self._get_custom_profiles_dir() / filename,
+            self._get_project_profiles_dir() / filename,
+            self.profiles_dir / filename,
+        ]
+        p = next((c for c in candidates if c.exists()), None)
+        if p is None:
+            raise FileNotFoundError(f"Perfil no encontrado: {name}")
+        data = json.loads(p.read_text(encoding="utf-8"))
+        return Profile(
+            name=data.get("name", name),
+            description=data.get("description", ""),
+            system_prompt=data.get("system_prompt", ""),
+            capabilities=data.get("capabilities", []),
+            session_skills=data.get("session_skills", []),
+            session_subagents=data.get("session_subagents", []),
+            governance_access=data.get("governance_access", False),
+            extends=data.get("extends"),
+            model=data.get("model"),
+        )
+
+    def list_all(self) -> list[str]:
+        seen = set()
+        result = []
+        for p in self._get_all_files():
+            if p.stem not in seen:
+                seen.add(p.stem)
+                result.append(p.stem)
+        return result
+
+
+class FileCapabilityRepository(ICapabilityRepository):
+    def __init__(self, base_capabilities_dir: Path):
+        self.caps_dir = base_capabilities_dir
+
+    def _get_custom_capabilities_dir(self) -> Path:
+        return Path(os.getcwd()).resolve() / WORKSPACE_DIR_NAME / "capabilities"
+
+    def _get_project_capabilities_dir(self) -> Path:
+        return Path(os.getcwd()).resolve() / "src" / "higpertext" / "capabilities"
+
+    def _get_all_files(self) -> list[Path]:
+        pattern = f"*{FILE_EXTENSION}"
+        files = list(self.caps_dir.rglob(pattern))
+        for extra_dir in (
+            self._get_custom_capabilities_dir(),
+            self._get_project_capabilities_dir(),
+        ):
+            if extra_dir.exists() and extra_dir != self.caps_dir:
+                files.extend(extra_dir.rglob(pattern))
+        return files
+
+    def load(self, cap_id: str) -> Capability:
+        f = next(
+            (f for f in self._get_all_files() if f.stem == cap_id or cap_id.endswith(f".{f.stem}")),
+            None,
+        )
+
+        if not f or not f.exists():
+            raise FileNotFoundError(f"Capacidad no encontrada: {cap_id}")
+        data = json.loads(f.read_text(encoding="utf-8"))
+        return Capability(
+            id=data.get("id", cap_id),
+            version=data.get("version", "1.0.0"),
+            name=data.get("name", ""),
+            description=data.get("description", ""),
+            entrypoint=data.get("entrypoint", ""),
+            language=data.get("language", "python"),
+            parameters=data.get("parameters", []),
+            security=data.get("security", {}),
+            hook_task_id=data.get("hook_task_id"),
+        )
+
+    def list_all(self) -> list[Capability]:
+        caps = []
+        for f in self._get_all_files():
+            try:
+                data = json.loads(f.read_text(encoding="utf-8"))
+                caps.append(
+                    Capability(
+                        id=data.get("id", f.stem),
+                        version=data.get("version", "1.0.0"),
+                        name=data.get("name", ""),
+                        description=data.get("description", ""),
+                        entrypoint=data.get("entrypoint", ""),
+                        language=data.get("language", "python"),
+                        parameters=data.get("parameters", []),
+                        security=data.get("security", {}),
+                        hook_task_id=data.get("hook_task_id"),
+                    )
+                )
+            except Exception:  # nosec B110
+                pass
+        return caps
+
+
+class FileWorkflowRepository(IWorkflowRepository):
+    def __init__(self, workflows_dir: Path):
+        self.wf_dir = workflows_dir
+
+    def _get_project_workflows_dir(self) -> Path:
+        return Path(os.getcwd()).resolve() / "src" / "workflows"
+
+    def _get_all_workflow_files(self) -> list[Path]:
+        pattern = f"*{FILE_EXTENSION}"
+        files = list(self.wf_dir.glob(pattern)) if self.wf_dir.exists() else []
+        project_dir = self._get_project_workflows_dir()
+        if project_dir.exists() and project_dir != self.wf_dir:
+            files.extend(project_dir.glob(pattern))
+        return files
+
+    def list_all(self) -> list[Workflow]:
+        wfs = []
+        for f in self._get_all_workflow_files():
+            try:
+                data = json.loads(f.read_text(encoding="utf-8"))
+                wfs.append(
+                    Workflow(
+                        id=data.get("id", f.stem),
+                        name=data.get("name", ""),
+                        description=data.get("description", ""),
+                        steps=data.get("steps", []),
+                        required_profile=data.get("required_profile", ""),
+                    )
+                )
+            except Exception:  # nosec B110
+                pass
+        return wfs
+
+
+class FileSessionRepository(ISessionRepository):
+    def __init__(self, session_file: Path):
+        self.session_file = session_file
+
+    def load_active(self) -> Session | None:
+        if not self.session_file.exists():
+            return None
+        try:
+            data = json.loads(self.session_file.read_text(encoding="utf-8"))
+            return Session(
+                session_id=data.get("session_id", ""),
+                profile=data.get("profile", ""),
+                assistant=data.get("assistant", ""),
+                status=data.get("status", "inactive"),
+                created_at=data.get("created_at", ""),
+                active_skills=data.get("active_skills", []),
+                active_subagents=data.get("active_subagents", []),
+                tasks=data.get("tasks", []),
+            )
+        except Exception:
+            return None
+
+    def save(self, session: Session) -> None:
+        self.session_file.parent.mkdir(parents=True, exist_ok=True)
+        data = {
+            "session_id": session.session_id,
+            "profile": session.profile,
+            "assistant": session.assistant,
+            "status": session.status,
+            "created_at": session.created_at,
+            "active_skills": session.active_skills,
+            "active_subagents": session.active_subagents,
+            "tasks": session.tasks,
+        }
+        self.session_file.write_text(
+            json.dumps(data, indent=4, ensure_ascii=False), encoding="utf-8"
+        )
+
+    def delete(self) -> None:
+        if self.session_file.exists():
+            try:
+                self.session_file.unlink()
+            except OSError:  # nosec B110
+                pass

higpertext/kernel/infrastructure/governance.py

@@ -0,0 +1,198 @@
+"""Implementaciones de infraestructura para gobernanza."""
+
+from __future__ import annotations
+import json
+from pathlib import Path
+from datetime import datetime, timezone
+
+from higpertext.kernel.config_paths import WORKSPACE_DIR_NAME
+from higpertext.kernel.domain.governance import Rule, RuleOverride, Scope, Severity, Verdict
+
+
+_SECTION_RULES_PATH = Path(__file__).resolve().parents[3] / "config" / "governance" / "section_rules.json"
+
+
+def _load_section_rules() -> dict:
+    """Carga section_rules.json una sola vez. Devuelve dict vacío si no existe."""
+    try:
+        return json.loads(_SECTION_RULES_PATH.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+def _rule_id(section: str, index: int) -> str:
+    return f"{section}.rule-{index:02d}"
+
+
+class ContractLoader:
+    """Carga y mergea reglas de gobernanza global + perfil activo."""
+
+    def __init__(self, project_root: Path) -> None:
+        self._root = project_root
+        self._contract_path = (
+            project_root / "src" / "config" / "governance" / "guidelines_contract.json"
+        )
+        _rules = _load_section_rules()
+        # section -> (Scope, Severity)
+        self._section_map: dict[str, tuple[Scope, Severity]] = {
+            section: (Scope(cfg["scope"]), Severity(cfg["severity"]))
+            for section, cfg in _rules.get("section_map", {}).items()
+        }
+        # frozenset of (section, index) pairs that are auto-checkable
+        self._automated_positions: frozenset[tuple[str, int]] = frozenset(
+            (entry["section"], entry["index"])
+            for entry in _rules.get("automated_rule_positions", [])
+        )
+        # (section, index) -> canonical rule ID
+        self._canonical_ids: dict[tuple[str, int], str] = {
+            (entry["section"], entry["index"]): entry["id"]
+            for entry in _rules.get("canonical_ids", [])
+        }
+
+    def load(self, profile: str = "") -> list[Rule]:
+        """Retorna las reglas efectivas para el perfil dado."""
+        base_rules = self._load_base_rules()
+        if not profile:
+            return base_rules
+
+        overrides = self._load_profile_overrides(profile)
+        additions = self._load_profile_additions(profile)
+
+        merged = _merge_rules(base_rules, overrides)
+        return merged + additions
+
+    def load_raw_contract(self) -> dict:
+        if not self._contract_path.exists():
+            return {}
+        try:
+            data = json.loads(self._contract_path.read_text(encoding="utf-8"))
+            security = self._load_domain_file("security_guardrails")
+            if security:
+                data["security_guardrails"] = security
+            return data
+        except (OSError, json.JSONDecodeError):
+            return {}
+
+    def load_security_guardrails(self) -> dict:
+        return self._load_domain_file("security_guardrails")
+
+    def load_branching_strategy(self) -> dict:
+        return self._load_domain_file("branching_strategy")
+
+    def load_quality_gates(self) -> dict:
+        return self._load_domain_file("quality_gates")
+
+    def load_deployment_gates(self) -> dict:
+        return self._load_domain_file("deployment_gates")
+
+    def _load_domain_file(self, name: str) -> dict:
+        path = self._root / "src" / "config" / "governance" / f"{name}.json"
+        if not path.exists():
+            return {}
+        try:
+            return json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            return {}
+
+    def _load_base_rules(self) -> list[Rule]:
+        contract = self.load_raw_contract()
+        guidelines = contract.get("guidelines", {})
+        rules: list[Rule] = []
+        for section, entries in guidelines.items():
+            scope, severity = self._section_map.get(section, (Scope.ANY, Severity.MEDIUM))
+            for i, text in enumerate(entries, 1):
+                pos = (section, i)
+                rid = self._canonical_ids.get(pos, _rule_id(section, i))
+                automated = pos in self._automated_positions
+                rules.append(
+                    Rule(
+                        id=rid,
+                        description=text,
+                        severity=severity,
+                        scopes=(scope,),
+                        automated=automated,
+                        source="global",
+                    )
+                )
+        return rules
+
+    def _profile_governance_path(self, profile: str) -> Path:
+        return self._root / WORKSPACE_DIR_NAME / "governance" / f"{profile}.json"
+
+    def _load_profile_overrides(self, profile: str) -> list[RuleOverride]:
+        path = self._profile_governance_path(profile)
+        if not path.exists():
+            return []
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            overrides = []
+            for rule_id, cfg in data.get("overrides", {}).items():
+                overrides.append(
+                    RuleOverride(
+                        rule_id=rule_id,
+                        source=profile,
+                        numeric_threshold=cfg.get("threshold"),
+                        description=cfg.get("description"),
+                    )
+                )
+            return overrides
+        except (OSError, json.JSONDecodeError):
+            return []
+
+    def _load_profile_additions(self, profile: str) -> list[Rule]:
+        path = self._profile_governance_path(profile)
+        if not path.exists():
+            return []
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            rules: list[Rule] = []
+            for section, entries in data.get("additions", {}).items():
+                scope, severity = self._section_map.get(section, (Scope.ANY, Severity.MEDIUM))
+                for i, entry in enumerate(entries, 1):
+                    if isinstance(entry, str):
+                        text, cfg = entry, {}
+                    else:
+                        text = entry.get("rule", "")
+                        cfg = entry
+                    rid = cfg.get("id", f"{profile}.{section}.rule-{i:02d}")
+                    rules.append(
+                        Rule(
+                            id=rid,
+                            description=text,
+                            severity=Severity(cfg.get("severity", severity.value)),
+                            scopes=(Scope(cfg.get("scope", scope.value)),),
+                            automated=cfg.get("automated", False),
+                            capability=cfg.get("capability"),
+                            source=profile,
+                        )
+                    )
+            return rules
+        except (OSError, json.JSONDecodeError):
+            return []
+
+
+def _merge_rules(base: list[Rule], overrides: list[RuleOverride]) -> list[Rule]:
+    override_map = {o.rule_id: o for o in overrides}
+    return [rule.merge(override_map[rule.id]) if rule.id in override_map else rule for rule in base]
+
+
+class AuditLog:
+    def __init__(self, project_root: Path) -> None:
+        self._store = project_root / WORKSPACE_DIR_NAME / "state" / "governance_audit.jsonl"
+
+    def record(self, verdict: Verdict, profile: str, triggered_by: str = "") -> None:
+        entry = {
+            "ts": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+            "profile": profile,
+            "scope": verdict.scope,
+            "status": verdict.status.value,
+            "triggered_by": triggered_by,
+            "findings": len(verdict.findings),
+            "blocked": len(verdict.blocking_findings),
+        }
+        try:
+            self._store.parent.mkdir(parents=True, exist_ok=True)
+            with self._store.open("a", encoding="utf-8") as fh:
+                fh.write(json.dumps(entry, ensure_ascii=False) + "\n")
+        except OSError:
+            pass

higpertext/kernel/infrastructure/hook_config_loader.py

@@ -0,0 +1,53 @@
+"""Utilidad compartida para cargar y guardar hooks_config.json."""
+
+from __future__ import annotations
+from higpertext.kernel.config_paths import WORKSPACE_DIR_NAME
+import json
+from pathlib import Path
+from higpertext.kernel.pkg_resources import pkg_data_root
+
+_EMPTY: dict = {"hooks": [], "profile_hooks": {}, "webhooks": []}
+
+# Ruta canónica del estado activo dentro del proyecto destino
+_CONFIG_PATH = Path(WORKSPACE_DIR_NAME) / "config" / "hooks_config.json"
+# Catálogo canónico de definiciones de hooks, empaquetado junto al código del engine
+_CATALOG_REL_PATH = Path("hooks") / "hooks_catalog.json"
+
+
+def load_hooks_config(project_root: Path) -> dict:
+    """Carga el estado activo del proyecto (profile_hooks, webhooks, hooks del proyecto)."""
+    config_path = project_root / _CONFIG_PATH
+    if not config_path.exists():
+        return dict(_EMPTY)
+    try:
+        return json.loads(config_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return dict(_EMPTY)
+
+
+def load_hook_definitions(engine_root: Path) -> list[dict]:
+    """Carga el catálogo canónico de definiciones de hooks del engine.
+
+    Busca primero en el árbol de fuente (modo dev), y si no existe ahí,
+    cae a los recursos empaquetados (higpertext_data) cuando se instala como CLI.
+    """
+    candidates = [engine_root / "src" / "higpertext" / _CATALOG_REL_PATH]
+    pkg_root = pkg_data_root()
+    if pkg_root is not None:
+        candidates.append(pkg_root / "higpertext" / _CATALOG_REL_PATH)
+
+    for definitions_path in candidates:
+        if not definitions_path.exists():
+            continue
+        try:
+            data = json.loads(definitions_path.read_text(encoding="utf-8"))
+            return data.get("hooks", [])
+        except (OSError, json.JSONDecodeError):
+            continue
+    return []
+
+
+def save_hooks_config(project_root: Path, data: dict) -> None:
+    config_path = project_root / _CONFIG_PATH
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    config_path.write_text(json.dumps(data, indent=2, ensure_ascii=False), encoding="utf-8")

higpertext/kernel/infrastructure/hook_webhook_dispatcher.py

@@ -0,0 +1,61 @@
+"""WebhookDispatcher — emite eventos HTTP a sistemas externos sin dependencias extra."""
+
+from __future__ import annotations
+import json
+import os
+import re
+import urllib.request
+import urllib.error
+from pathlib import Path
+
+from higpertext.kernel.application.hook_registry import HookRegistry
+
+_VAR_RE = re.compile(r"\$\{(\w+)\}")
+
+
+def _resolve_env(value: str) -> str:
+    return _VAR_RE.sub(lambda m: os.environ.get(m.group(1), ""), value)
+
+
+def _render_payload(template: dict, context: dict) -> dict:
+    """Sustituye {{key}} en valores del template con valores del contexto."""
+    result: dict = {}
+    for k, v in template.items():
+        if isinstance(v, str):
+            for ctx_key, ctx_val in context.items():
+                v = v.replace(f"{{{{{ctx_key}}}}}", str(ctx_val))
+            result[k] = v
+        else:
+            result[k] = v
+    return result
+
+
+class WebhookDispatcher:
+    def __init__(self, project_root: Path) -> None:
+        self.registry = HookRegistry(project_root)
+
+    def dispatch(self, event: str, assistant: str, context: dict) -> None:
+        """Emite webhooks activos para el evento dado."""
+        webhooks = self.registry.get_webhooks_for(assistant)
+        for wh in webhooks:
+            if wh.event != event:
+                continue
+            url = _resolve_env(wh.url)
+            if not url:
+                continue
+            payload = _render_payload(wh.payload_template, context)
+            self._post(url, payload, wh.timeout)
+
+    def _post(self, url: str, payload: dict, timeout: int) -> None:
+        body = json.dumps(payload).encode("utf-8")
+        req = urllib.request.Request(
+            url,
+            data=body,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=timeout):
+                pass
+        except urllib.error.URLError:  # nosec B110
+            pass  # Webhook failures are non-blocking