higpertext-cli 0.8.0__py3-none-any.whl

higpertext/capabilities/common/scripts/code_skeletonizer.py

@@ -0,0 +1,225 @@
+#!/usr/bin/env python
+"""higpertext Code Skeletonizer — Genera un esqueleto de un archivo de código para ahorrar tokens.""" # noqa: E501
+
+import sys
+import argparse
+import ast
+import re
+from pathlib import Path
+
+from higpertext.kernel.infrastructure.logger import get_logger
+_log = get_logger()
+
+
+class SkeletonTransformer(ast.NodeTransformer):
+    """Transformador AST que conserva solo firmas, docstrings e imports."""
+
+    def visit_Module(self, node):
+        new_body = []
+        for stmt in node.body:
+            if isinstance(
+                stmt,
+                (
+                    ast.ClassDef,
+                    ast.FunctionDef,
+                    ast.AsyncFunctionDef,
+                    ast.Import,
+                    ast.ImportFrom,
+                ),
+            ):
+                new_body.append(self.visit(stmt))
+            elif isinstance(stmt, (ast.Assign, ast.AnnAssign)):
+                new_body.append(stmt)
+            elif (
+                isinstance(stmt, ast.Expr)
+                and isinstance(stmt.value, ast.Constant)
+                and isinstance(stmt.value.value, str)
+            ):
+                new_body.append(stmt)
+        node.body = new_body
+        return node
+
+    def visit_ClassDef(self, node):
+        new_body = []
+        for stmt in node.body:
+            if isinstance(stmt, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+                new_body.append(self.visit(stmt))
+            elif isinstance(stmt, (ast.Assign, ast.AnnAssign)):
+                new_body.append(stmt)
+            elif (
+                isinstance(stmt, ast.Expr)
+                and isinstance(stmt.value, ast.Constant)
+                and isinstance(stmt.value.value, str)
+            ):
+                new_body.append(stmt)
+        node.body = new_body
+        return node
+
+    def visit_FunctionDef(self, node):
+        # Conservar decoradores y firma, vaciar cuerpo conservando docstring si existe
+        docstring = ast.get_docstring(node)
+        new_body = []
+        if docstring is not None:
+            if (
+                node.body
+                and isinstance(node.body[0], ast.Expr)
+                and isinstance(node.body[0].value, ast.Constant)
+                and isinstance(node.body[0].value.value, str)
+            ):
+                new_body.append(node.body[0])
+        new_body.append(ast.Pass())
+        node.body = new_body
+        return node
+
+    def visit_AsyncFunctionDef(self, node):
+        return self.visit_FunctionDef(node)
+
+
+def skeletonize_python(source: str) -> str:
+    """Esqueletiza código Python usando AST."""
+    try:
+        tree = ast.parse(source)
+        transformer = SkeletonTransformer()
+        transformed_tree = transformer.visit(tree)
+        # Aseguramos que los nodos sean válidos y tengan line numbers si es necesario
+        ast.fix_missing_locations(transformed_tree)
+        return ast.unparse(transformed_tree)
+    except Exception as e:
+        return f"# [Error parseando AST Python: {e}]\n" + skeletonize_line_by_line(
+            source, comment_char="#"
+        )
+
+
+def skeletonize_line_by_line(source: str, comment_char: str = "#") -> str:
+    """Fallback heurístico basado en líneas para otros lenguajes."""
+    lines = source.splitlines()
+    output_lines = []
+    in_block = False
+    brace_depth = 0
+
+    # Heurística simple para lenguajes con llaves {} (JS, TS, C, Go, etc.)
+    is_brace_lang = comment_char == "//"
+
+    for line in lines:
+        stripped = line.strip()
+
+        # Mantener imports y paquetes
+        if any(
+            stripped.startswith(prefix) for prefix in ["import ", "from ", "package ", "require("]
+        ):
+            output_lines.append(line)
+            continue
+
+        if is_brace_lang:
+            # Detección de llaves
+            open_braces = stripped.count("{")
+            close_braces = stripped.count("}")
+
+            # Si estamos dentro de una función, omitimos su contenido
+            if in_block:
+                brace_depth += open_braces - close_braces
+                if brace_depth <= 0:
+                    in_block = False
+                    output_lines.append(re.sub(r"^[ \t]*", "", line))  # mantener el cierre }
+                continue
+
+            # Detectar firmas de funciones, clases o métodos
+            if (
+                any(
+                    p in stripped
+                    for p in [
+                        "function ",
+                        "class ",
+                        "interface ",
+                        "constructor",
+                        "const ",
+                        "let ",
+                        "export ",
+                    ]
+                )
+                and "{" in stripped
+            ):
+                output_lines.append(line)
+                brace_depth = open_braces - close_braces
+                if brace_depth > 0:
+                    in_block = True
+                    # Añadir indicador de elisión
+                    indent = len(line) - len(stripped)
+                    output_lines.append(" " * (indent + 4) + f"{comment_char} ...")
+                continue
+            else:
+                # Mantener comentarios de documentación externos
+                if (
+                    stripped.startswith("/*")
+                    or stripped.startswith("*")
+                    or stripped.startswith("//")
+                ):
+                    output_lines.append(line)
+                elif stripped == "":
+                    output_lines.append("")
+        else:
+            # Fallback genérico para scripts de Bash o similares
+            if (
+                stripped.startswith("function ")
+                or (stripped.endswith("()") or "()" in stripped)
+                or stripped.startswith("def ")
+            ):
+                output_lines.append(line)
+                output_lines.append(f"    {comment_char} ...")
+            elif stripped.startswith("#") or stripped == "":
+                output_lines.append(line)
+
+    return "\n".join(output_lines)
+
+
+def skeletonize_file(file_path: Path) -> str:
+    """Lee un archivo y lo esqueletiza según su tipo."""
+    content = file_path.read_text(encoding="utf-8")
+
+    if file_path.suffix == ".py":
+        return skeletonize_python(content)
+    elif file_path.suffix in [
+        ".js",
+        ".ts",
+        ".tsx",
+        ".jsx",
+        ".go",
+        ".c",
+        ".cpp",
+        ".java",
+    ]:
+        return skeletonize_line_by_line(content, comment_char="//")
+    else:
+        return skeletonize_line_by_line(content, comment_char="#")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Esqueletiza archivos de código para optimizar contexto."
+    )
+    parser.add_argument("--path", required=True, help="Ruta del archivo a esqueletizar")
+    parser.add_argument("--output", required=False, help="Archivo de destino opcional")
+    args = parser.parse_args()
+
+    input_path = Path(args.path)
+    if not input_path.exists() or not input_path.is_file():
+        _log.error(f"[ERROR] El archivo especificado no existe o no es válido: {args.path}")
+        sys.exit(1)
+
+    try:
+        skeleton = skeletonize_file(input_path)
+
+        if args.output:
+            output_path = Path(args.output)
+            output_path.parent.mkdir(parents=True, exist_ok=True)
+            output_path.write_text(skeleton, encoding="utf-8")
+            _log.ok(f"[SUCCESS] Esqueleto guardado con éxito en: {output_path}")
+        else:
+            _log.info(skeleton)
+    except Exception as e:
+        _log.error(f"[ERROR] Error procesando el archivo: {e}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

higpertext/capabilities/common/scripts/commit_report.py

@@ -0,0 +1,134 @@
+"""Capability common.commit-report — reporte explicativo de commits."""
+
+from __future__ import annotations
+from higpertext.kernel.application.commit_reporter import ReportBuilder, ImpactAnalyzer, CommitParser
+import argparse
+# Invoca git/htx con lista de argumentos y shell=False.
+import subprocess  # nosec B404
+import sys
+from pathlib import Path
+from higpertext.kernel.config_paths import WORKSPACE_DIR_NAME
+
+from higpertext.kernel.infrastructure.logger import get_logger
+_log = get_logger()
+
+_HERE = Path(__file__).resolve()
+_ROOT = next((p for p in _HERE.parents if (p / "src/config/htx_config.json").exists()), _HERE.parents[4])
+sys.path.insert(0, str(_ROOT / "src"))
+sys.path.insert(0, str(_ROOT))
+
+
+def _git(args: list[str]) -> str:
+    result = subprocess.run(["git"] + args, capture_output=True, text=True, cwd=_ROOT)
+    return result.stdout.strip()
+
+
+def _parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Genera reporte explicativo de commits.")
+    parser.add_argument("--commit", default="HEAD")
+    parser.add_argument("--range", dest="range_", default=None)
+    parser.add_argument("--format", dest="fmt", default="markdown", choices=["markdown", "html"])
+    parser.add_argument("--output", default=None)
+    parser.add_argument(
+        "--diff", action="store_true", help="Incluye el diff completo línea por línea."
+    )
+    return parser.parse_args()
+
+
+def _resolve_output(args: argparse.Namespace, short_hash: str) -> Path:
+    if args.output:
+        return Path(args.output)
+    ext = "html" if args.fmt == "html" else "md"
+    out_dir = _ROOT / WORKSPACE_DIR_NAME / "reports" / "commits"
+    out_dir.mkdir(parents=True, exist_ok=True)
+    return out_dir / f"{short_hash}_report.{ext}"
+
+
+def _build_show_output(ref: str) -> str:
+    header = _git(
+        [
+            "log",
+            "-1",
+            "--format=%h %s%nAuthor: %an <%ae>%nDate:   %ad",
+            "--date=short",
+            ref,
+        ]
+    )
+    stat = _git(["show", "--stat", "--format=", ref])
+    return header + "\n" + stat
+
+
+def _get_full_diff(ref: str) -> str:
+    return _git(["show", "--format=", "-p", "--unified=3", ref])
+
+
+def _handle_single(args: argparse.Namespace) -> None:
+    ref = args.commit
+    show_out = _build_show_output(ref)
+    parser = CommitParser()
+    report = parser.parse_show(show_out)
+    if report is None:
+        _log.error(f"[ERROR] No se pudo parsear el commit: {ref}")
+        sys.exit(1)
+    analysis = ImpactAnalyzer().analyze(report)
+    builder = ReportBuilder()
+    full_diff = _get_full_diff(ref) if args.diff else None
+    if args.fmt == "html":
+        content = builder.to_html(report, analysis, diff=full_diff)
+    else:
+        content = builder.to_markdown(report, analysis, diff=full_diff)
+    out = _resolve_output(args, report.commit.short_hash)
+    out.write_text(content, encoding="utf-8")
+    _print_summary(report, analysis, out)
+
+
+def _handle_range(args: argparse.Namespace) -> None:
+    log_out = _git(["log", "--format=%h|||%s|||%an <%ae>|||%ad", "--date=short", args.range_])
+    commits = CommitParser().parse_log(log_out)
+    if not commits:
+        _log.error(f"[ERROR] No se encontraron commits en el rango: {args.range_}")
+        sys.exit(1)
+    lines = [
+        f"# Commit Range Report — `{args.range_}`\n",
+        f"**{len(commits)} commits**\n\n---\n",
+    ]
+    for commit in commits:
+        show_out = _build_show_output(commit.hash)
+        report = CommitParser().parse_show(show_out)
+        if report is None:
+            continue
+        analysis = ImpactAnalyzer().analyze(report)
+        lines.append(ReportBuilder().to_markdown(report, analysis))
+        lines.append("\n---\n")
+    content = "\n".join(lines)
+    out = _resolve_output(args, "range")
+    out.write_text(content, encoding="utf-8")
+    _log.ok(f"[SUCCESS] Reporte de {len(commits)} commits escrito en: {out}")
+
+
+def _print_summary(report, analysis, out: Path) -> None:
+    c = report.commit
+    _log.info("╔─ HIGPERTEXT · Commit Report ────────────────────────────────")
+    _log.info(f"│  Commit   : {c.short_hash} ({c.commit_type.value})")
+    _log.info(f"│  Scope    : {c.scope or '—'}")
+    _log.info(f"│  Autor    : {c.author}")
+    _log.info(f"│  Fecha    : {c.date}")
+    _log.info(f"│  Archivos : {report.changed_files_count}")
+    _log.info(f"│  +Lines   : {report.total_additions}  -Lines: {report.total_deletions}")
+    _log.info(f"│  Tags     : {', '.join(analysis.impact_tags)}")
+    _log.info(f"│  Reporte  : {out.relative_to(_ROOT)}")
+    _log.info("╚───────────────────────────────────────────────────────")
+    _log.info(f"\n{analysis.summary}")
+    _log.ok(f"\n[SUCCESS] Reporte generado: {out}")
+
+
+def main() -> None:
+    args = _parse_args()
+    if args.range_:
+        _handle_range(args)
+    else:
+        _handle_single(args)
+
+
+if __name__ == "__main__":
+    main()

higpertext/capabilities/common/scripts/context_assembler.py

@@ -0,0 +1,70 @@
+"""Capability common.context-assembler — ensambla un context pack curado para una tarea.
+
+Dado un objetivo (--goal) y tipo (--type), selecciona del semantic graph los
+símbolos relevantes bajo un presupuesto de tokens y emite un artefacto Markdown
+en .higpertext/state/context_packs/ que el agente puede leer.
+"""
+
+from __future__ import annotations
+import argparse
+import sys
+from pathlib import Path
+from higpertext.kernel.infrastructure.logger import get_logger
+_log = get_logger()
+
+
+def _resolve_core() -> Path:
+    """Localiza src/core para importar el context_engine."""
+    here = Path(__file__).resolve()
+    for parent in here.parents:
+        core = parent / "src" / "core"
+        if core.exists():
+            return core
+    return here.parent
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Ensambla un context pack curado.")
+    parser.add_argument("--goal", required=True, help="Objetivo de la tarea.")
+    parser.add_argument(
+        "--type",
+        default="feature",
+        help="Tipo: refactor|feature|bugfix|review. Default: feature.",
+    )
+    parser.add_argument(
+        "--budget",
+        type=int,
+        default=8000,
+        help="Presupuesto de tokens del pack. Default: 8000.",
+    )
+    args = parser.parse_args()
+
+    core = _resolve_core()
+    if str(core) not in sys.path:
+        sys.path.insert(0, str(core))
+
+    from higpertext.context_engine.domain.task_intent import TaskIntent
+    from higpertext.context_engine.application.context_assembler import ContextAssembler
+    from higpertext.context_engine.infrastructure.pack_store import PackStore
+
+    project_root = core.parent.parent
+    intent = TaskIntent.from_goal(args.goal, args.type, token_budget=args.budget)
+    assembler = ContextAssembler(project_root)
+    pack = assembler.assemble(intent)
+
+    store = PackStore(project_root)
+    path = store.save(pack)
+
+    rel = path.relative_to(project_root).as_posix()
+    _log.box("HIGPERTEXT · Context Pack generado", [
+        f"│  Objetivo   : {intent.goal}",
+        f"│  Keywords   : {', '.join(intent.keywords) or '—'}",
+        f"│  Símbolos   : {len(pack.relevant_symbols)}",
+        f"│  Tokens~    : {pack.estimated_tokens} / {intent.token_budget}",
+        f"│  Artefacto  : {rel}",
+    ])
+    _log.ok(f"\n[SUCCESS] Pack disponible. Lee el archivo: {rel}")
+
+
+if __name__ == "__main__":
+    main()

higpertext/capabilities/common/scripts/context_budget_report.py

@@ -0,0 +1,53 @@
+"""common.context-budget-report — estima coste de contexto antes de leer/buscar."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from higpertext.kernel.infrastructure.logger import get_logger
+_log = get_logger()
+
+
+def estimate(path: Path, operation: str, budget: int) -> dict:
+    size = path.stat().st_size if path.exists() and path.is_file() else 0
+    tokens = max(1, size // (5 if operation == "skeleton" else 4))
+    recommendation = "read range"
+    if operation == "search":
+        recommendation = "grep"
+    elif operation == "skeleton" or tokens > budget:
+        recommendation = "skeleton"
+    if tokens > budget * 2:
+        recommendation = "summary"
+    return {
+        "path": str(path),
+        "operation": operation,
+        "bytes": size,
+        "estimated_tokens": tokens,
+        "budget": budget,
+        "recommendation": recommendation,
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Estima presupuesto de contexto")
+    parser.add_argument("--path", required=True)
+    parser.add_argument("--operation", default="read", choices=["read", "search", "skeleton"])
+    parser.add_argument("--budget", type=int, default=4000)
+    parser.add_argument("--json", default="false")
+    args = parser.parse_args()
+    report = estimate(Path(args.path), args.operation, args.budget)
+    if args.json.lower() in {"true", "1", "yes"}:
+        print(json.dumps(report, ensure_ascii=False, indent=2))
+        return
+    _log.info("╔─ HIGPERTEXT · Context Budget Report ───────────────────────")
+    _log.info(f"│ Archivo      : {report['path']}")
+    _log.info(f"│ Operación    : {report['operation']}")
+    _log.info(f"│ Tokens est.  : {report['estimated_tokens']} / {report['budget']}")
+    _log.info(f"│ Recomendado  : {report['recommendation']}")
+    _log.info("╚────────────────────────────────────────────────────────────")
+
+
+if __name__ == "__main__":
+    main()

higpertext/capabilities/common/scripts/dep_manager.py

@@ -0,0 +1,81 @@
+"""common.dep-manager — gestiona dependencias usando .venv del proyecto."""
+
+from __future__ import annotations
+from higpertext.kernel.config_paths import WORKSPACE_DIR_NAME
+
+import argparse
+import subprocess  # nosec B404
+import sys
+from pathlib import Path
+
+from higpertext.kernel.infrastructure.logger import get_logger
+_log = get_logger()
+
+_HERE = Path(__file__).resolve()
+_PROJECT_ROOT = next(
+    (p for p in _HERE.parents if (p / "src/config/htx_config.json").exists()),
+    _HERE.parents[4],
+)
+
+_VENV_PIP = _PROJECT_ROOT / ".venv" / "bin" / "pip"
+
+
+def _pip(args: list[str]) -> tuple[int, str, str]:
+    pip = str(_VENV_PIP) if _VENV_PIP.exists() else "pip"
+    res = subprocess.run([pip] + args, capture_output=True, text=True)  # nosec B603
+    return res.returncode, res.stdout, res.stderr
+
+
+def _update_requirements(packages: list[str]) -> None:
+    req = _PROJECT_ROOT / "requirements.txt"
+    if not req.exists():
+        return
+    rc, out, _ = _pip(["freeze"])
+    if rc == 0:
+        req.write_text(out, encoding="utf-8")
+        _log.ok(f"[*] requirements.txt actualizado ({len(out.splitlines())} paquetes)")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="higpertext Dependency Manager")
+    parser.add_argument("--action", required=True, choices=["install", "uninstall", "list"])
+    parser.add_argument("--packages", default="")
+    parser.add_argument("--dev", default="false")
+    args = parser.parse_args()
+
+    packages = [p.strip() for p in args.packages.replace(",", " ").split() if p.strip()]
+
+    if args.action == "install":
+        if not packages:
+            _log.error("[ERROR] --packages es requerido para install.")
+            sys.exit(1)
+        _log.info(f"[*] Instalando: {', '.join(packages)} en .venv...")
+        rc, out, err = _pip(["install"] + packages)
+        if rc != 0:
+            _log.error(f"[ERROR] {err}")
+            sys.exit(rc)
+        _log.info(out.strip())
+        _update_requirements(packages)
+        _log.ok(f"[SUCCESS] {len(packages)} paquete(s) instalado(s).")
+
+    elif args.action == "uninstall":
+        if not packages:
+            _log.error("[ERROR] --packages es requerido para uninstall.")
+            sys.exit(1)
+        _log.info(f"[*] Desinstalando: {', '.join(packages)}...")
+        rc, out, err = _pip(["uninstall", "-y"] + packages)
+        if rc != 0:
+            _log.error(f"[ERROR] {err}")
+            sys.exit(rc)
+        _log.info(out.strip())
+        _update_requirements([])
+        _log.ok(f"[SUCCESS] {len(packages)} paquete(s) desinstalado(s).")
+
+    elif args.action == "list":
+        rc, out, _ = _pip(["list", "--format=columns"])
+        _log.info(out)
+        _log.ok("[SUCCESS] Listado de dependencias completado.")
+
+
+if __name__ == "__main__":
+    main()