higpertext-cli 0.8.0__py3-none-any.whl

higpertext/capabilities/common/scripts/search_router.py

@@ -0,0 +1,111 @@
+"""common.search-router — recomienda la capacidad óptima para buscar/leer contexto."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from higpertext.kernel.infrastructure.logger import get_logger
+_log = get_logger()
+
+
+def route(query: str, intent: str, scope: str, preset: str, budget: int) -> list[dict]:
+    """Construye plan de búsqueda/lectura según intención."""
+    steps: list[dict] = []
+    if intent == "error" or any(
+        token in query.lower() for token in ("traceback", "error", "exception", "failed")
+    ):
+        steps.append(
+            {
+                "capability": "common.error-context-locator",
+                "params": {"error": query, "max_context": 5},
+            }
+        )
+    if _looks_like_path(query):
+        steps.append(
+            {
+                "capability": "common.smart-read",
+                "params": {"path": query, "mode": "auto", "max_tokens": budget},
+            }
+        )
+    if intent in {"feature", "refactor", "symbol"}:
+        steps.append(
+            {
+                "capability": "common.graph-query",
+                "params": {"symbol": query, "depth": 2, "budget": budget},
+            }
+        )
+    # RAG Semántico como primer fallback general
+    steps.append(
+        {
+            "capability": "common.semantic-search",
+            "params": {"query": query, "limit": 5, "root": scope or "."},
+        }
+    )
+    steps.append(
+        {
+            "capability": "common.grep-search",
+            "params": {
+                "pattern": query,
+                "path": scope or ".",
+                "preset": preset,
+                "max_results": 50,
+                "max_per_file": 5,
+            },
+        }
+    )
+    return _dedupe(steps)
+
+
+def _dedupe(steps: list[dict]) -> list[dict]:
+    seen = set()
+    result = []
+    for step in steps:
+        key = (step["capability"], json.dumps(step["params"], sort_keys=True))
+        if key not in seen:
+            seen.add(key)
+            result.append(step)
+    return result
+
+
+def _looks_like_path(query: str) -> bool:
+    value = query.strip().strip("\"'")
+    if any(space in value for space in (" ", "\n", "\t")):
+        return False
+    return "/" in value or Path(value).suffix != ""
+
+
+def _format_plan(steps: list[dict]) -> str:
+    lines = ["╔─ HIGPERTEXT · Search Router ───────────────────────────────"]
+    for index, step in enumerate(steps, 1):
+        params = " ".join(
+            f"--{k} {json.dumps(v, ensure_ascii=False)}" for k, v in step["params"].items()
+        )
+        lines.append(f"│ {index}. htx task {step['capability']} {params}")
+    lines.append("╚────────────────────────────────────────────────────────────")
+    return "\n".join(lines)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Orquesta búsqueda inteligente")
+    parser.add_argument("--query", required=True)
+    parser.add_argument(
+        "--intent",
+        default="general",
+        choices=["error", "feature", "refactor", "docs", "symbol", "general"],
+    )
+    parser.add_argument("--scope", default=".")
+    parser.add_argument("--preset", default="code")
+    parser.add_argument("--budget", type=int, default=4000)
+    parser.add_argument("--json", default="false")
+    args = parser.parse_args()
+    steps = route(args.query, args.intent, args.scope, args.preset, args.budget)
+    if args.json.lower() in {"true", "1", "yes"}:
+        print(json.dumps({"steps": steps}, ensure_ascii=False, indent=2))
+        return
+    _log.info(_format_plan(steps))
+
+
+if __name__ == "__main__":
+    main()

higpertext/capabilities/common/scripts/semantic_diff.py

@@ -0,0 +1,166 @@
+"""higpertext Semantic Diff — detecta funciones/clases cambiadas entre commits via AST."""
+
+import ast
+import sys
+import json
+import argparse
+import subprocess  # nosec B404
+
+from higpertext.kernel.infrastructure.logger import get_logger
+_log = get_logger()
+
+
+def run_cmd(cmd: list[str]) -> tuple[int, str, str]:
+    res = subprocess.run(cmd, capture_output=True, text=True)  # nosec B603
+    return res.returncode, res.stdout, res.stderr
+
+
+def _extract_symbols(source: str) -> dict[str, set[str]]:
+    """Extrae nombres de funciones y clases de código fuente Python via AST."""
+    symbols: dict[str, set[str]] = {
+        "functions": set(),
+        "classes": set(),
+        "methods": set(),
+    }
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return symbols
+    for node in ast.walk(tree):
+        if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef):
+            symbols["functions"].add(node.name)
+        elif isinstance(node, ast.ClassDef):
+            symbols["classes"].add(node.name)
+            for item in node.body:
+                if isinstance(item, ast.FunctionDef | ast.AsyncFunctionDef):
+                    symbols["methods"].add(f"{node.name}.{item.name}")
+    return symbols
+
+
+def _get_file_content_at(ref: str, filepath: str) -> str | None:
+    """Obtiene el contenido de un archivo en un commit dado."""
+    ret, out, _ = run_cmd(["git", "show", f"{ref}:{filepath}"])
+    return out if ret == 0 else None
+
+
+def _get_changed_files(base: str, head: str, files_filter: list[str] | None) -> list[str]:
+    """Lista archivos .py que cambiaron entre base y head."""
+    ret, out, _ = run_cmd(["git", "diff", "--name-only", base, head])
+    if ret != 0:
+        return []
+    changed = [f for f in out.splitlines() if f.endswith(".py")]
+    if files_filter:
+        changed = [f for f in changed if any(f.endswith(ff) or ff in f for ff in files_filter)]
+    return changed
+
+
+def _diff_symbols(base: str, head: str, filepath: str) -> dict:
+    """Compara símbolos AST entre dos versiones de un archivo."""
+    content_base = _get_file_content_at(base, filepath)
+    content_head = _get_file_content_at(head, filepath)
+
+    if content_base is None and content_head is None:
+        return {}
+
+    sym_base = _extract_symbols(content_base or "")
+    sym_head = _extract_symbols(content_head or "")
+
+    result: dict[str, list] = {}
+    for kind in ("functions", "classes", "methods"):
+        b = sym_base[kind]
+        h = sym_head[kind]
+        added = sorted(h - b)
+        removed = sorted(b - h)
+        # Modified = same name but content changed (line-level heuristic per symbol)
+        common = b & h
+        modified = _detect_modified(content_base or "", content_head or "", common, kind)
+
+        if added or removed or modified:
+            result[kind] = {
+                "added": added,
+                "removed": removed,
+                "modified": sorted(modified),
+            }
+    return result
+
+
+def _detect_modified(src_base: str, src_head: str, names: set[str], kind: str) -> set[str]:
+    """Heurística: extrae el bloque de cada símbolo y compara su hash."""
+    modified = set()
+    for name in names:
+        block_b = _extract_block(src_base, name, kind)
+        block_h = _extract_block(src_head, name, kind)
+        if block_b != block_h:
+            modified.add(name)
+    return modified
+
+
+def _extract_block(source: str, name: str, kind: str) -> str:
+    """Extrae el cuerpo de una función/clase por nombre."""
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return ""
+    lines = source.splitlines()
+    for node in ast.walk(tree):
+        node_name = getattr(node, "name", None)
+        if node_name != name.split(".")[-1]:
+            continue
+        if kind == "functions" and not isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef):
+            continue
+        if kind == "classes" and not isinstance(node, ast.ClassDef):
+            continue
+        start = node.lineno - 1
+        end = node.end_lineno if hasattr(node, "end_lineno") else start + 1
+        return "\n".join(lines[start:end])
+    return ""
+
+
+def _print_text(results: dict[str, dict]) -> None:
+    if not results:
+        _log.info("[*] No se detectaron cambios semánticos en símbolos Python.")
+        return
+    _log.info("=" * 60)
+    _log.info("DIFF SEMÁNTICO — Símbolos modificados")
+    _log.info("=" * 60)
+    for filepath, kinds in results.items():
+        _log.info(f"\n📄 {filepath}")
+        for kind, changes in kinds.items():
+            for action, names in changes.items():
+                if names:
+                    icon = {"added": "✚", "removed": "✖", "modified": "~"}.get(action, "?")
+                    label = f"  [{icon} {action.upper()} {kind}]"
+                    for n in names:
+                        _log.info(f"{label}: {n}")
+    _log.info("\n" + "=" * 60)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="higpertext Semantic Diff")
+    parser.add_argument("--base", default="HEAD~1")
+    parser.add_argument("--head", default="HEAD")
+    parser.add_argument("--files", default=None)
+    parser.add_argument("--format", default="text", choices=["text", "json"])
+    args = parser.parse_args()
+
+    files_filter = [f.strip() for f in args.files.split(",") if f.strip()] if args.files else None
+    changed_files = _get_changed_files(args.base, args.head, files_filter)
+
+    if not changed_files:
+        _log.info("[*] No hay archivos Python modificados entre los commits especificados.")
+        sys.exit(0)
+
+    results: dict[str, dict] = {}
+    for fp in changed_files:
+        diff = _diff_symbols(args.base, args.head, fp)
+        if diff:
+            results[fp] = diff
+
+    if args.format == "json":
+        print(json.dumps(results, indent=2))
+    else:
+        _print_text(results)
+
+
+if __name__ == "__main__":
+    main()

higpertext/capabilities/common/scripts/semantic_search.py

@@ -0,0 +1,43 @@
+"""Capacidad para buscar fragmentos de código semánticamente mediante RAG."""
+
+from __future__ import annotations
+import argparse
+import json
+import sys
+from pathlib import Path
+
+# Configurar path para importar higpertext
+_ROOT = Path(__file__).resolve().parents[5]
+sys.path.insert(0, str(_ROOT / "src"))
+
+from higpertext.kernel.infrastructure.llm.providers.gemini_embeddings import GeminiEmbeddingProvider
+from higpertext.kernel.infrastructure.database.local_vector_store import LocalVectorStore
+from higpertext.kernel.application.rag_service import RAGService
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Busca código semánticamente mediante RAG.")
+    parser.add_argument("--query", type=str, required=True, help="Texto o concepto a buscar.")
+    parser.add_argument("--limit", type=int, default=5, help="Límite de resultados.")
+    parser.add_argument("--root", type=str, default=".", help="Ruta al proyecto.")
+    args = parser.parse_args()
+
+    project_root = Path(args.root).resolve()
+    
+    try:
+        embedder = GeminiEmbeddingProvider(project_root)
+        store = LocalVectorStore(project_root)
+        service = RAGService(embedder, store)
+
+        hits = service.search_context(args.query, limit=args.limit)
+        
+        # Output en JSON estructurado para el Framework
+        print(json.dumps({"hits": hits}, indent=2, ensure_ascii=False))
+        sys.exit(0)
+    except Exception as e:
+        print(json.dumps({"error": str(e)}), file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

higpertext/capabilities/common/scripts/session_control.py

@@ -0,0 +1,136 @@
+"""higpertext Session Control — inicia y limpia sesiones de desarrollo del agente."""
+
+import sys
+import json
+import argparse
+from higpertext.kernel.session_manager import SessionManager  # noqa: E402
+from higpertext.kernel.config_paths import WORKSPACE_DIR_NAME
+from pathlib import Path
+from higpertext.kernel.infrastructure.logger import get_logger
+_log = get_logger()
+
+ROOT_DIR = Path(__file__).parents[4]
+if str(ROOT_DIR / "src" / "core") not in sys.path:
+    sys.path.append(str(ROOT_DIR / "src" / "core"))
+
+def _load_roadmap_resources(project_root: Path) -> tuple:
+    """Lee session_resources mergeando roadmaps activos en roadmaps/active.json.
+
+    Fallback a roadmap.json único para compatibilidad hacia atrás.
+    """
+    roadmaps_dir = project_root / WORKSPACE_DIR_NAME / "config" / "roadmaps"
+    active_index = roadmaps_dir / "active.json"
+
+    if active_index.exists():
+        try:
+            active_ids: list = json.loads(active_index.read_text(encoding="utf-8")).get(
+                "active", []
+            )
+        except (OSError, json.JSONDecodeError):
+            return None, None
+
+        if not active_ids:
+            return None, None
+
+        merged_skills: list = []
+        merged_subagents: list = []
+        loaded: list = []
+
+        for rid in active_ids:
+            rf = roadmaps_dir / f"{rid}.json"
+            if not rf.exists():
+                continue
+            try:
+                data = json.loads(rf.read_text(encoding="utf-8"))
+                res = data.get("session_resources", {})
+                for s in res.get("skills", []):
+                    if s not in merged_skills:
+                        merged_skills.append(s)
+                for sa in res.get("subagents", []):
+                    if sa not in merged_subagents:
+                        merged_subagents.append(sa)
+                loaded.append(data.get("project", rid))
+            except (OSError, json.JSONDecodeError):
+                continue
+
+        if not loaded:
+            return None, None
+
+        projects_str = ", ".join(f"'{p}'" for p in loaded)
+        _log.info(
+f"[*] Roadmaps activos: {projects_str}"
+            f" — montando {len(merged_skills)} skill(s) y {len(merged_subagents)} subagente(s)."
+        )
+        return merged_skills or None, merged_subagents or None
+
+    # Fallback: roadmap.json único
+    roadmap_file = project_root / WORKSPACE_DIR_NAME / "config" / "roadmap.json"
+    if not roadmap_file.exists():
+        return None, None
+    try:
+        data = json.loads(roadmap_file.read_text(encoding="utf-8"))
+        resources = data.get("session_resources", {})
+        skills = resources.get("skills", [])
+        subagents = resources.get("subagents", [])
+        if skills or subagents:
+            _log.info(
+f"[*] Roadmap detectado: '{data.get('project', '')}' "
+                f"— montando {len(skills)} skill(s) y {len(subagents)} subagente(s)."
+            )
+            return skills, subagents
+        return None, None
+    except (OSError, json.JSONDecodeError):
+        return None, None
+
+
+def _load_profile_session_resources(profile_name: str, root_dir: Path) -> tuple:
+    """Fallback: lee session_skills y session_subagents del perfil JSON."""
+    profile_file = root_dir / "src" / "config" / "profiles" / f"{profile_name}.json"
+    if not profile_file.exists():
+        return [], []
+    try:
+        data = json.loads(profile_file.read_text(encoding="utf-8"))
+        return data.get("session_skills", []), data.get("session_subagents", [])
+    except (OSError, json.JSONDecodeError):
+        return [], []
+
+
+def main() -> None:
+    """Punto de entrada de session-control."""
+    parser = argparse.ArgumentParser(description="higpertext Session Control Capability")
+    parser.add_argument("--action", required=True, choices=["start", "clean"])
+    parser.add_argument("--profile", help="Active profile name")
+    parser.add_argument("--assistant", help="Assistant name (claude, gemini, antigravity, copilot)")
+    parser.add_argument("--skills", help="Comma-separated skills (overrides roadmap and profile)")
+    parser.add_argument(
+        "--subagents", help="Comma-separated subagents (overrides roadmap and profile)"
+    )
+    args = parser.parse_args()
+
+    project_root = Path.cwd()
+    session_mgr = SessionManager(project_root, ROOT_DIR)
+
+    if args.action == "start":
+        env_assistant, active_profile = session_mgr.get_assistant_and_profile()
+        assistant = args.assistant or env_assistant
+        profile = args.profile or active_profile
+
+        # Prioridad: args explícitos, de lo contrario SessionManager resolverá
+        # roadmap/perfil/fallback
+        skills_list = (
+            [s.strip() for s in args.skills.split(",") if s.strip()] if args.skills else None
+        )
+        subagents_list = (
+            [sa.strip() for sa in args.subagents.split(",") if sa.strip()]
+            if args.subagents
+            else None
+        )
+
+        session_mgr.start_session(profile, assistant, skills_list, subagents_list)
+
+    elif args.action == "clean":
+        session_mgr.clean_session()
+
+
+if __name__ == "__main__":
+    main()

higpertext/capabilities/common/scripts/smart_read.py

@@ -0,0 +1,232 @@
+"""common.smart-read — lectura segura y compacta para LLM."""
+
+from __future__ import annotations
+
+import argparse
+import ast
+import json
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+try:
+    from higpertext.capabilities.common.scripts.code_skeletonizer import (
+        skeletonize_file,
+    )
+except ImportError:  # pragma: no cover - fallback para ejecución directa
+    from code_skeletonizer import skeletonize_file  # type: ignore
+
+from higpertext.kernel.infrastructure.logger import get_logger
+_log = get_logger()
+
+_CODE_SUFFIXES = {".py", ".js", ".jsx", ".ts", ".tsx", ".go", ".java", ".cs", ".rs"}
+_DEFAULT_MAX_BYTES = 100 * 1024
+_DEFAULT_LIMIT = 120
+
+
+@dataclass(frozen=True)
+class SymbolSpan:
+    """Rango aproximado de un símbolo dentro de un archivo."""
+
+    name: str
+    kind: str
+    start: int
+    end: int
+
+
+def _read_lines(path: Path) -> list[str]:
+    return path.read_text(encoding="utf-8", errors="ignore").splitlines()
+
+
+def _estimate_tokens(text: str) -> int:
+    return max(1, len(text) // 4)
+
+
+def _is_large(path: Path, max_bytes: int) -> bool:
+    return max_bytes > 0 and path.stat().st_size > max_bytes
+
+
+def _line_map(path: Path) -> list[SymbolSpan]:
+    if path.suffix != ".py":
+        return _regex_line_map(_read_lines(path))
+    try:
+        tree = ast.parse(path.read_text(encoding="utf-8", errors="ignore"))
+    except SyntaxError:
+        return _regex_line_map(_read_lines(path))
+    spans: list[SymbolSpan] = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ClassDef):
+            spans.append(
+                SymbolSpan(
+                    node.name,
+                    "class",
+                    node.lineno,
+                    getattr(node, "end_lineno", node.lineno),
+                )
+            )
+        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            kind = "async def" if isinstance(node, ast.AsyncFunctionDef) else "def"
+            spans.append(
+                SymbolSpan(
+                    node.name,
+                    kind,
+                    node.lineno,
+                    getattr(node, "end_lineno", node.lineno),
+                )
+            )
+    return sorted(spans, key=lambda item: item.start)
+
+
+def _regex_line_map(lines: list[str]) -> list[SymbolSpan]:
+    spans: list[SymbolSpan] = []
+    for index, line in enumerate(lines, 1):
+        stripped = line.strip()
+        if stripped.startswith("class "):
+            spans.append(
+                SymbolSpan(stripped.split()[1].split("(")[0].rstrip(":"), "class", index, index)
+            )
+        elif stripped.startswith(("def ", "async def ", "function ")):
+            name = stripped.replace("async def ", "def ", 1).split()[1].split("(")[0]
+            spans.append(SymbolSpan(name, "def", index, index))
+    return spans
+
+
+def _format_range(lines: list[str], start: int, end: int, line_limit: int = 240) -> str:
+    start = max(1, start)
+    end = min(len(lines), end)
+    rendered = []
+    for lineno in range(start, end + 1):
+        text = lines[lineno - 1]
+        if line_limit and len(text) > line_limit:
+            text = text[: line_limit - 3] + "..."
+        rendered.append(f"{lineno:>5}: {text}")
+    return "\n".join(rendered)
+
+
+def _symbol_range(path: Path, symbol: str, around: int) -> tuple[int, int] | None:
+    for span in _line_map(path):
+        if span.name == symbol or symbol.lower() in span.name.lower():
+            return max(1, span.start - around), span.end + around
+    return None
+
+
+def _summary(path: Path, max_bytes: int) -> str:
+    spans = _line_map(path)
+    lines = [
+        "╔─ HIGPERTEXT · Smart Read Summary ─────────────────────────",
+        f"│ Archivo : {path}",
+        f"│ Tamaño  : {path.stat().st_size} bytes",
+        f"│ Grande  : {'sí' if _is_large(path, max_bytes) else 'no'}",
+        f"│ Símbolos: {len(spans)}",
+        "╠────────────────────────────────────────────────────────────",
+    ]
+    for span in spans[:80]:
+        lines.append(f"│ L{span.start}-{span.end}: {span.kind} {span.name}")
+    if len(spans) > 80:
+        lines.append(f"│ ... {len(spans) - 80} símbolo(s) omitidos")
+    lines.append("╚────────────────────────────────────────────────────────────")
+    return "\n".join(lines)
+
+
+def smart_read(
+    path: Path,
+    mode: str,
+    symbol: str = "",
+    offset: int = 1,
+    limit: int = _DEFAULT_LIMIT,
+    around_line: int = 0,
+    max_bytes: int = _DEFAULT_MAX_BYTES,
+) -> str:
+    """Devuelve contenido curado según modo solicitado."""
+    if not path.exists() or not path.is_file():
+        raise FileNotFoundError(str(path))
+    resolved_mode = mode
+    if mode == "auto":
+        resolved_mode = (
+            "skeleton" if path.suffix in _CODE_SUFFIXES and _is_large(path, max_bytes) else "range"
+        )
+    if resolved_mode == "summary":
+        return _summary(path, max_bytes)
+    if resolved_mode == "skeleton":
+        return skeletonize_file(path)
+
+    lines = _read_lines(path)
+    if resolved_mode == "symbol":
+        if not symbol:
+            raise ValueError("--symbol es requerido para mode=symbol")
+        span = _symbol_range(path, symbol, around_line or 3)
+        if not span:
+            return f"[NOT FOUND] Símbolo no encontrado: {symbol}\n\n{_summary(path, max_bytes)}"
+        return _format_range(lines, span[0], span[1])
+    if resolved_mode == "full":
+        if _is_large(path, max_bytes):
+            return "\n".join(
+                [
+                    "[BLOCKED] Archivo grande; usa --mode skeleton, summary, symbol o range.",
+                    f"Archivo: {path}",
+                    f"Tamaño: {path.stat().st_size} bytes > {max_bytes} bytes",
+                ]
+            )
+        return _format_range(lines, 1, len(lines))
+    if around_line > 0:
+        return _format_range(lines, around_line - limit, around_line + limit)
+    return _format_range(lines, offset, offset + limit - 1)
+
+
+def _json_payload(path: Path, content: str, mode: str) -> dict:
+    return {
+        "path": str(path),
+        "mode": mode,
+        "bytes": path.stat().st_size,
+        "estimated_tokens": _estimate_tokens(content),
+        "content": content,
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Lectura segura y optimizada para LLM")
+    parser.add_argument("--path", required=True)
+    parser.add_argument(
+        "--mode",
+        default="auto",
+        choices=["auto", "skeleton", "range", "symbol", "full", "summary"],
+    )
+    parser.add_argument("--symbol", default="")
+    parser.add_argument("--offset", type=int, default=1)
+    parser.add_argument("--limit", type=int, default=_DEFAULT_LIMIT)
+    parser.add_argument("--around_line", type=int, default=0)
+    parser.add_argument("--max_bytes", type=int, default=_DEFAULT_MAX_BYTES)
+    parser.add_argument("--max_tokens", type=int, default=0)
+    parser.add_argument("--json", default="false")
+    args = parser.parse_args()
+
+    try:
+        path = Path(args.path)
+        content = smart_read(
+            path,
+            args.mode,
+            args.symbol,
+            args.offset,
+            args.limit,
+            args.around_line,
+            args.max_bytes,
+        )
+        if args.max_tokens > 0 and _estimate_tokens(content) > args.max_tokens:
+            content = smart_read(path, "summary", max_bytes=args.max_bytes)
+        if args.json.lower() in {"true", "1", "yes"}:
+            _log.info(
+                json.dumps(
+                    _json_payload(path, content, args.mode),
+                    ensure_ascii=False,
+                    indent=2,
+                )
+            )
+        else:
+            _log.info(content)
+    except Exception as exc:
+        _log.error(f"[ERROR] {exc}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()