higpertext-cli 0.8.0__py3-none-any.whl

higpertext/kernel/infrastructure/cli/capability_command_builder.py

@@ -0,0 +1,86 @@
+"""Construcción de comandos de subproceso para capacidades."""
+
+from __future__ import annotations
+
+import shutil
+import sys
+from pathlib import Path
+
+from higpertext.kernel.config_paths import WORKSPACE_DIR_NAME
+
+
+def extra_args(params: dict, prefix: str = "--") -> list[str]:
+    return [arg for key, value in params.items() for arg in [f"{prefix}{key}", str(value)]]
+
+
+def resolve_entrypoint(
+    entrypoint: str,
+    pkg_data_dir: Path,
+    workspace_root: Path,
+    base_dir: str = "",
+) -> Path:
+    """Resuelve el path del entrypoint manteniendo prioridad legacy."""
+    ep = Path(entrypoint)
+    if ep.is_absolute() and ep.exists():
+        return ep
+    if base_dir:
+        candidate = Path(base_dir).parent.parent / entrypoint
+        if candidate.exists():
+            return candidate
+    higpertext_relative = workspace_root / WORKSPACE_DIR_NAME / entrypoint
+    if higpertext_relative.exists():
+        return higpertext_relative
+    cwd_relative = workspace_root / entrypoint
+    if cwd_relative.exists():
+        return cwd_relative
+    return pkg_data_dir / entrypoint
+
+
+def build_command(
+    entrypoint: str,
+    language: str,
+    params: dict,
+    root_dir: Path,
+    pkg_data_dir: Path,
+    workspace_root: Path,
+    base_dir: str = "",
+    cap_id: str = "",
+) -> list[str]:
+    """Construye la lista de argumentos del subproceso."""
+    args = extra_args(params)
+    if language == "powershell":
+        path_to_script = resolve_entrypoint(entrypoint, pkg_data_dir, workspace_root, base_dir)
+        return build_powershell_command(path_to_script, params)
+    if language == "cli":
+        return entrypoint.split() + args
+    if language == "bash":
+        path_to_script = resolve_entrypoint(entrypoint, pkg_data_dir, workspace_root, base_dir)
+        script = entrypoint if Path(entrypoint).is_absolute() else str(path_to_script)
+        return ["bash", script] + args
+
+    htx_bin = _resolve_htx_bin(root_dir, pkg_data_dir)
+    runner = pkg_data_dir / "higpertext" / "capabilities" / "capabilities_runner.py"
+    if cap_id and runner.exists() and entrypoint.startswith("capabilities/"):
+        if Path(htx_bin).exists():
+            return [htx_bin, "task", cap_id] + args
+        return [sys.executable, str(runner), cap_id] + args
+    path_to_script = resolve_entrypoint(entrypoint, pkg_data_dir, workspace_root, base_dir)
+    return [sys.executable, str(path_to_script)] + args
+
+
+def build_powershell_command(path_to_script: Path, params: dict) -> list[str]:
+    pwsh = "powershell" if shutil.which("powershell") else "pwsh"
+    return [
+        pwsh,
+        "-ExecutionPolicy",
+        "Bypass",
+        "-File",
+        str(path_to_script),
+    ] + extra_args(params, prefix="-")
+
+
+def _resolve_htx_bin(root_dir: Path, pkg_data_dir: Path) -> str:
+    _ = root_dir
+    venv_htx = pkg_data_dir.parents[1] / ".venv" / "bin" / "htx"
+
+    return str(venv_htx) if venv_htx.exists() else (shutil.which("htx") or str(venv_htx))

higpertext/kernel/infrastructure/cli/capability_task_service.py

@@ -0,0 +1,234 @@
+
+"""Servicio de infraestructura para ejecutar capacidades desde el CLI."""
+
+from __future__ import annotations
+
+import json
+import os
+# Runner central usa listas de argumentos y shell=False.
+import subprocess  # nosec B404
+from pathlib import Path
+
+from higpertext.kernel.infrastructure.cli.capability_command_builder import build_command
+from higpertext.kernel.infrastructure.cli.task_result_reporter import (
+    build_memory_notes,
+    report_task_result,
+)
+
+
+class CapabilityTaskService:
+    """Resuelve, ejecuta y reporta capacidades técnicas."""
+
+    def __init__(self, engine, root_dir: Path, pkg_data_dir: Path, logger, dep) -> None:
+        self.engine = engine
+        self.root_dir = root_dir
+        self.pkg_data_dir = pkg_data_dir
+        self.logger = logger
+        self.dep = dep
+
+    def resolve_from_profiles(self, task_name: str, profiles: list[str]) -> tuple[dict | None, str | None]:
+        for profile_name in profiles:
+            ctx = self.engine.get_agent_context(profile_name)
+            cap = next(
+                (c for c in ctx["active_capabilities"] if c["id"].endswith(task_name)),
+                None,
+            )
+            if cap:
+                return cap, profile_name
+        return None, None
+
+    def resolve_custom_capability(self, task_name: str) -> tuple[dict | None, str | None]:
+        try:
+            cap = self.engine.capabilities.load_capability(task_name)
+            custom_dir = self.engine.capabilities._get_custom_capabilities_dir()
+            cap_file = next(
+                (
+                    f
+                    for f in self.engine.capabilities._get_all_capability_files()
+                    if f.stem.endswith(task_name)
+                ),
+                None,
+            )
+            if cap_file and custom_dir in cap_file.parents:
+                return cap, "custom"
+        except (OSError, StopIteration, AttributeError):  # nosec B110
+            pass
+        return None, None
+
+    def resolve_capability(self, task_name: str, active_profile: str) -> tuple[dict | None, str | None]:
+        profiles = [active_profile, "global"] if active_profile != "global" else ["global"]
+        cap, profile_name = self.resolve_from_profiles(task_name, profiles)
+        if cap:
+            return cap, profile_name
+        return self.resolve_custom_capability(task_name)
+
+    def build_cmd(
+        self,
+        entrypoint: str,
+        language: str,
+        params: dict,
+        base_dir: str = "",
+        cap_id: str = "",
+    ) -> list[str]:
+        return build_command(
+            entrypoint,
+            language,
+            params,
+            self.root_dir,
+            self.pkg_data_dir,
+            Path(os.getcwd()),
+            base_dir=base_dir,
+            cap_id=cap_id,
+        )
+
+    def get_active_profile(self) -> str:
+        try:
+            env_mgr = self.dep("EnvironmentManager")(Path.cwd())
+            if env_mgr.is_initialized():
+                return env_mgr.load_environment().get("active_profile", "global")
+        except (OSError, json.JSONDecodeError):  # nosec B110
+            pass
+        return "global"
+
+    def execute_task_cmd(
+        self, task_name: str, target_cap: dict, params: dict, stream_runner, stream: bool = False
+    ) -> subprocess.CompletedProcess:
+        cap_id = target_cap.get("id", task_name)
+        cmd = self.build_cmd(
+            target_cap["entrypoint"],
+            target_cap.get("language", "python"),
+            params,
+            base_dir=target_cap.get("_base_dir", ""),
+            cap_id=cap_id,
+        )
+        entrypoint = target_cap.get("entrypoint", "")
+
+        cache = self.dep("get_capability_cache")()
+        cached = cache.get(cap_id, params, entrypoint)
+        if cached is not None:
+            self.logger.info(f"[Cache] HIT para '{cap_id}' — usando resultado previo.")
+            return subprocess.CompletedProcess(
+                args=cmd,
+                returncode=cached.returncode,
+                stdout=cached.stdout,
+                stderr=cached.stderr,
+            )
+
+        self.logger.info(f"[>] Ejecutando: {' '.join(cmd)}")
+        resilience = self.dep("get_resilience_manager")()
+        max_retries = target_cap.get("retries", 1)
+
+        def _run_once() -> subprocess.CompletedProcess:
+            if stream:
+                return stream_runner(cmd)
+            return subprocess.run(  # nosec B603 B607
+                cmd, cwd=os.getcwd(), capture_output=True, text=True, check=False
+            )
+
+        result = resilience.execute_with_resilience(
+            capability_id=cap_id,
+            fn=_run_once,
+            max_retries=max_retries,
+        )
+        if result is None:
+            return subprocess.CompletedProcess(
+                args=cmd,
+                returncode=1,
+                stdout="",
+                stderr=f"[Circuit] '{cap_id}' bloqueado por circuit breaker.",
+            )
+
+        cache.set(
+            cap_id,
+            params,
+            stdout=result.stdout,
+            stderr=result.stderr,
+            returncode=result.returncode,
+            entrypoint=entrypoint,
+        )
+        return result
+
+    def validate_contract(
+        self, target_cap: dict, params: dict, result: subprocess.CompletedProcess
+    ) -> tuple[bool, list]:
+        if result.returncode != 0:
+            return True, []
+        return self.dep("ContractValidator").validate(
+            params, result.stdout, result.stderr, result.returncode, target_cap
+        )
+
+    def save_memory(
+        self,
+        task_name: str,
+        params: dict,
+        result: subprocess.CompletedProcess,
+        contract_success: bool,
+        contract_errors: list,
+    ) -> None:
+        try:
+            mem_script = (
+                self.pkg_data_dir
+                / "higpertext"
+                / "capabilities"
+                / "common"
+                / "scripts"
+                / "memory_manager.py"
+            )
+            status = "success" if result.returncode == 0 and contract_success else "failure"
+            notes = build_memory_notes(task_name, params, result, contract_success, contract_errors)
+            subprocess.run(  # nosec B603 B607
+                [
+                    "python",
+                    str(mem_script),
+                    "--action",
+                    f"Auto-run: {task_name}",
+                    "--status",
+                    status,
+                    "--notes",
+                    notes,
+                ],
+                capture_output=True,
+                check=False,
+            )
+        except OSError as mem_e:
+            self.logger.warning(f"[WARNING] Falló guardado de memoria: {mem_e}")
+
+    def warn_missing_pat(self, task_name: str) -> None:
+        if "ado" in task_name or "sre" in task_name and not os.getenv("ADO_PAT"):
+            self.logger.warning("[WARNING] No se detectó ADO_PAT en .env.")
+
+    def run_task(self, task_name: str, params: dict, stream_runner, stream: bool = False, no_cache: bool = False) -> bool:
+        try:
+            active_profile = self.get_active_profile()
+            target_cap, found_profile = self.resolve_capability(task_name, active_profile)
+            if not target_cap:
+                self.logger.warning(
+                    f"[!] Capacidad '{task_name}' no disponible para el perfil '{active_profile.upper()}'."
+                )
+                return False
+            self.logger.info(f"[*] Capacidad '{task_name}' resuelta: {found_profile.upper()}")
+            validation = self.dep("normalize_and_validate_params")(target_cap, params)
+            if not validation.ok:
+                self.logger.error(f"[ERROR] Parámetros inválidos para '{task_name}':")
+                for error in validation.errors:
+                    self.logger.info(f"    - {error}")
+                return False
+            for warning in validation.warnings:
+                self.logger.warning(f"[PARAM] {warning}")
+            params = validation.params
+            self.warn_missing_pat(task_name)
+            self.logger.info(f"[*] Ejecutando tarea: {task_name}")
+
+            if no_cache:
+                cache = self.dep("get_capability_cache")()
+                cache.invalidate(target_cap.get("id", task_name))
+
+            result = self.execute_task_cmd(task_name, target_cap, params, stream_runner, stream=stream)
+            ok, errors = self.validate_contract(target_cap, params, result)
+            status = report_task_result(task_name, result, ok, errors, self.logger)
+            if task_name != "memory-manager":
+                self.save_memory(task_name, params, result, ok, errors)
+            return status
+        except (OSError, ValueError) as exc:
+            self.logger.warning(f"[!] Error inesperado: {exc}")
+            return False

higpertext/kernel/infrastructure/cli/cli_search.py

@@ -0,0 +1,234 @@
+"""higpertext CLI — Knowledge search mixin (Infraestructura)."""
+
+from __future__ import annotations
+import os
+import json
+from collections.abc import Iterable
+from pathlib import Path
+
+from higpertext.kernel.infrastructure.logger import get_logger
+_log = get_logger()
+
+
+class HigpertextSearchMixin:
+    """Provides knowledge-base search capabilities to HigpertextHub."""
+
+    def _search_guidelines_contract(self, full_path: Path, query_terms: Iterable[str]) -> list:
+        matches = []
+        try:
+            data = json.loads(full_path.read_text(encoding="utf-8"))
+            for section, rules in data.get("guidelines", {}).items():
+                for rule in rules:
+                    if any(t in rule.lower() or t in section.lower() for t in query_terms):
+                        label = section.upper().replace("_", " ")
+                        card = f"⚖️ [CONTRATO: {label}]\n" f"    Regla: {rule}"
+                        matches.append((0, card))
+        except (OSError, json.JSONDecodeError):  # nosec B110
+            pass
+        return matches
+
+    def _search_learnings_json(self, full_path: Path, query_terms: Iterable[str]) -> list:
+        matches = []
+        try:
+            data = json.loads(full_path.read_text(encoding="utf-8"))
+            if not isinstance(data, dict):
+                return matches
+            for tag, entries in data.items():
+                for entry in entries:
+                    blob = self._entry_blob(entry, [tag])
+                    if any(t in blob for t in query_terms):
+                        learned = ", ".join(entry.get("learned", []))
+                        card = (
+                            f"💡 [MEMORIA: APRENDIZAJE] (Tag: {tag})\n"
+                            f"    Acción: {entry.get('action')} "
+                            f"({entry.get('action_id')})\n"
+                            f"    Aprendido: {learned or 'N/A'}\n"
+                            f"    Notas: {entry.get('notes')}"
+                        )
+                        matches.append((0, card))
+        except (OSError, json.JSONDecodeError):  # nosec B110
+            pass
+        return matches
+
+    def _search_journal_json(self, full_path: Path, query_terms: Iterable[str]) -> list:
+        matches = []
+        try:
+            data = json.loads(full_path.read_text(encoding="utf-8"))
+            if not isinstance(data, list):
+                return matches
+            for entry in data:
+                blob = self._entry_blob(entry, [])
+                if any(t in blob for t in query_terms):
+                    matches.append((0, self._journal_card(entry)))
+        except (OSError, json.JSONDecodeError):  # nosec B110
+            pass
+        return matches
+
+    @staticmethod
+    def _entry_blob(entry: dict, extra: list) -> str:
+        parts = (
+            extra
+            + [entry.get("action", ""), entry.get("notes", "")]
+            + entry.get("tags", [])
+            + entry.get("learned", [])
+        )
+        if entry.get("failure_root_cause"):
+            parts.append(entry["failure_root_cause"])
+        return " ".join(str(v).lower() for v in parts)
+
+    @staticmethod
+    def _journal_card(entry: dict) -> str:
+        tags_str = ", ".join(entry.get("tags", []))
+        status = "🟢 SUCCESS" if entry.get("status") == "success" else "🔴 FAILURE"
+        ts = (entry.get("timestamp") or "")[:19]
+        card = (
+            f"🪵 [MEMORIA: JOURNAL] ({ts})\n"
+            f"    Acción: {entry.get('action')} "
+            f"({entry.get('action_id')}) -> {status}\n"
+            f"    Tags: {tags_str}\n"
+            f"    Notas: {entry.get('notes')}"
+        )
+        if entry.get("failure_root_cause"):
+            card += f"\n    Causa Raíz: {entry['failure_root_cause']}"
+        return card
+
+    def _search_text_file(self, full_path: Path, query_terms: list[str]) -> list:
+        matches = []
+        try:
+            lines = full_path.read_text(encoding="utf-8", errors="ignore").splitlines()
+            for idx, line in enumerate(lines, 1):
+                if any(t in line.lower() for t in query_terms):
+                    matches.append((idx, line.strip()))
+        except OSError:  # nosec B110
+            pass
+        return matches
+
+    def _search_file(self, full_path: Path, query_terms: list[str]) -> list:
+        name = full_path.name
+        if name == "guidelines_contract.json":
+            return self._search_guidelines_contract(full_path, query_terms)
+        if name == "learnings.json":
+            return self._search_learnings_json(full_path, query_terms)
+        if name == "journal.json":
+            return self._search_journal_json(full_path, query_terms)
+        if name.endswith((".md", ".txt")):
+            return self._search_text_file(full_path, query_terms)
+        return []
+
+    def _search_semantic_graph(
+        self, graph_path: Path, query_terms: list[str], root_dir: Path
+    ) -> dict:
+        try:
+            data = json.loads(graph_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            return {}
+
+        matches: dict = {}
+        files = data.get("files", {})
+
+        for rel_path, file_data in files.items():
+            hits: list[tuple[int, str]] = []
+
+            summary = file_data.get("summary", "").lower()
+            if summary and any(t in summary for t in query_terms):
+                hits.append((0, f"📝 módulo: {file_data['summary'].strip()[:120]}"))
+
+            # Buscar en clases y sus métodos
+            hits.extend(self._search_code_elements(file_data.get("classes", []), query_terms, "🔷 class", "methods"))
+
+            # Buscar en funciones
+            hits.extend(self._search_code_elements(file_data.get("functions", []), query_terms, "🔹 def"))
+            
+            for imp in file_data.get("imports", []):
+                if any(t in imp.lower() for t in query_terms):
+                    hits.append((0, f"📦 import {imp}"))
+
+            if hits:
+                try:
+                    key = f"[grafo] ./{Path(rel_path).as_posix()}"
+                except ValueError:
+                    key = f"[grafo] {rel_path}"
+                matches[key] = hits
+
+        return matches
+
+    def _walk_search(
+        self, search_paths: list[Path], query_terms: list[str], root_dir: Path
+    ) -> dict:
+        matches: dict = {}
+        query_terms_set = set(query_terms)
+
+        for path in search_paths:
+            if not path.exists():
+                continue
+            for full_path in path.rglob("*"):  # Use rglob for recursive search
+                if not self._is_searchable_file(full_path):
+                    continue
+                try:
+                    found = self._search_file(full_path, query_terms_set)
+                    if not found:
+                        continue
+                    key = self._make_search_key(full_path, root_dir)
+                    matches[key] = found
+                except OSError:  # nosec B110
+                    pass
+        return matches
+
+    @staticmethod
+    def _is_searchable_file(full_path: Path) -> bool:
+        if not full_path.is_file() or full_path.suffix not in (".md", ".txt", ".json"):
+            return False
+        try:
+            return full_path.stat().st_size <= 1024 * 1024
+        except OSError:
+            return False
+
+    @staticmethod
+    def _make_search_key(full_path: Path, root_dir: Path) -> str:
+        return f"./{full_path.relative_to(root_dir)}" if root_dir in full_path.parents else str(full_path)
+
+    @staticmethod
+    def _print_search_results(matches: dict) -> None:
+        if not matches:
+            _log.warning("[!] No se encontró información relevante.")
+            _log.info(
+                "[TIP] Consulta al administrador de gobernanza si buscas " "una norma no listada."
+            )
+            return
+        _log.ok("[SUCCESS] Se encontraron coincidencias:")
+        for filepath, snippets in list(matches.items())[:5]:
+            _log.info(f"\n📄 Coincidencias en {filepath}:")
+            for line_num, snippet in snippets[:3]:
+                if line_num == 0:
+                    _log.info(f"{snippet}")
+                else:
+                    if len(snippet) > 120:
+                        snippet = snippet[:117] + "..."
+                    _log.info(f"    L{line_num}: {snippet}")
+            if len(snippets) > 3:
+                _log.info(f"    ... y {len(snippets) - 3} coincidencias más.")
+
+    @staticmethod
+    def _search_code_elements(
+        elements: list[dict],
+        query_terms: list[str],
+        prefix: str,
+        nested_key: str | None = None,
+    ) -> list[tuple[int, str]]:
+        hits = []
+        for elem in elements:
+            name = elem.get("name", "")
+            doc = elem.get("docstring", "")
+            if any(t in name.lower() or t in doc.lower() for t in query_terms):
+                doc_snippet = f" — *{doc.strip()[:60]}*" if doc else ""
+                hits.append((0, f"{prefix} {name}{doc_snippet}"))
+            
+            if nested_key:
+                nested_elements = elem.get(nested_key, [])
+                for ne in nested_elements:
+                    ne_name = ne.get("name", "")
+                    ne_doc = ne.get("docstring", "")
+                    if any(t in ne_name.lower() or t in ne_doc.lower() for t in query_terms):
+                        ne_doc_snippet = f" — *{ne_doc.strip()[:60]}*" if ne_doc else ""
+                        hits.append((0, f"  └─ def {ne_name}{ne_doc_snippet}"))
+        return hits

higpertext/kernel/infrastructure/cli/parameter_contracts.py

@@ -0,0 +1,83 @@
+"""Contratos y aliases de parámetros para capabilities higpertext."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+_ALIASES: dict[str, tuple[str, ...]] = {
+    "path": (
+        "file",
+        "file_path",
+        "filePath",
+        "source",
+        "source_path",
+        "tests_path",
+        "target",
+    ),
+    "tests_path": ("path", "test_path", "test", "target"),
+    "source_path": ("path", "source", "target"),
+    "target": ("path", "source_path", "target_dir"),
+    "output": ("output_report", "report_path", "out"),
+    "json": ("as_json", "format_json"),
+}
+
+
+@dataclass(frozen=True)
+class ParameterValidation:
+    params: dict[str, Any]
+    errors: list[str]
+    warnings: list[str]
+
+    @property
+    def ok(self) -> bool:
+        return not self.errors
+
+
+def normalize_and_validate_params(capability: dict, params: dict[str, Any]) -> ParameterValidation:
+    """Normaliza aliases declarados y valida parámetros requeridos."""
+    declared = _declared_parameters(capability)
+    normalized = dict(params)
+    warnings: list[str] = []
+
+    for canonical in declared:
+        if canonical in normalized:
+            continue
+        alias = _first_present_alias(canonical, normalized)
+        if alias:
+            normalized[canonical] = normalized[alias]
+            normalized.pop(alias, None)
+            warnings.append(f"Alias --{alias} normalizado a --{canonical}")
+
+    errors = _missing_required_errors(capability, normalized)
+    return ParameterValidation(params=normalized, errors=errors, warnings=warnings)
+
+
+def _declared_parameters(capability: dict) -> set[str]:
+    return {item.get("name", "") for item in capability.get("parameters", []) if item.get("name")}
+
+
+def _first_present_alias(canonical: str, params: dict[str, Any]) -> str:
+    for alias in _ALIASES.get(canonical, ()):
+        if alias in params:
+            return alias
+    return ""
+
+
+def _missing_required_errors(capability: dict, params: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+    for item in capability.get("parameters", []):
+        name = item.get("name", "")
+        if not name or not item.get("required", False):
+            continue
+        if params.get(name) not in (None, ""):
+            continue
+        errors.append(_format_missing_required(name, item))
+    return errors
+
+
+def _format_missing_required(name: str, spec: dict) -> str:
+    description = spec.get("description", "sin descripción")
+    aliases = ", ".join(f"--{alias}" for alias in _ALIASES.get(name, ()))
+    alias_hint = f" Alias aceptados: {aliases}." if aliases else ""
+    return f"Falta parámetro requerido --{name}: {description}.{alias_hint}"