higpertext-cli 0.8.0__py3-none-any.whl

higpertext/capabilities/common/scripts/memory_manager.py

@@ -0,0 +1,210 @@
+"""higpertext Memory Manager — persiste acciones, aprendizajes y contexto del agente en .memory/."""
+
+import json
+import argparse
+import secrets
+import time
+from datetime import datetime
+from pathlib import Path
+
+from higpertext.kernel.infrastructure.logger import get_logger
+_log = get_logger()
+
+
+def generate_action_id() -> str:
+    """Genera un action_id único con timestamp y sufijo criptográfico."""
+    timestamp = int(time.time())
+    rand_suffix = secrets.token_hex(2)
+    return f"act_{timestamp}_{rand_suffix}"
+
+
+def _parse_csv(value: str | None) -> list[str]:
+    """Parsea una cadena separada por comas en una lista limpia."""
+    if not value:
+        return []
+    return [item.strip() for item in value.split(",") if item.strip()]
+
+
+def _build_entry(
+    action: str,
+    status: str,
+    notes: str,
+    action_id: str,
+    learned: list,
+    tags: list,
+    failure_root_cause: str | None,
+) -> dict:
+    """Construye el diccionario de entrada para el journal."""
+    return {
+        "action_id": action_id,
+        "timestamp": datetime.now().isoformat(),
+        "action": action,
+        "status": status,
+        "tags": tags,
+        "notes": notes,
+        "learned": learned,
+        "failure_root_cause": failure_root_cause if status == "failure" else None,
+    }
+
+
+def _load_json_file(path: Path, default):
+    """Carga un archivo JSON; retorna default si no existe o hay error."""
+    if not path.exists():
+        return default
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return default
+
+
+def _update_learnings(learnings: dict, tags: list, entry: dict, learned: list, notes: str) -> None:
+    """Actualiza el dict de learnings con la nueva entrada por cada tag."""
+    for tag in tags:
+        if tag not in learnings:
+            learnings[tag] = []
+        if learned or notes:
+            learnings[tag].append(
+                {
+                    "action_id": entry["action_id"],
+                    "timestamp": entry["timestamp"],
+                    "action": entry["action"],
+                    "status": entry["status"],
+                    "notes": notes,
+                    "learned": learned,
+                    "failure_root_cause": entry["failure_root_cause"],
+                }
+            )
+
+
+def save_memory(
+    action: str,
+    status: str,
+    notes: str,
+    action_id: str | None = None,
+    learned_str: str | None = None,
+    failure_root_cause: str | None = None,
+    tags_str: str | None = None,
+) -> None:
+    """Persiste una acción en journal.json, learnings.json y regenera context.md."""
+    memory_dir = Path(".memory")
+    memory_dir.mkdir(exist_ok=True)
+
+    journal_file = memory_dir / "journal.json"
+    learnings_file = memory_dir / "learnings.json"
+    context_file = memory_dir / "context.md"
+
+    action_id = action_id or generate_action_id()
+    learned = _parse_csv(learned_str)
+    tags = _parse_csv(tags_str) or ["general"]
+    tags = [t.lower() for t in tags]
+
+    entry = _build_entry(action, status, notes, action_id, learned, tags, failure_root_cause)
+
+    journal: list = _load_json_file(journal_file, [])
+    journal.append(entry)
+    journal_file.write_text(json.dumps(journal, indent=2, ensure_ascii=False), encoding="utf-8")
+
+    learnings: dict = _load_json_file(learnings_file, {})
+    _update_learnings(learnings, tags, entry, learned, notes)
+    learnings_file.write_text(json.dumps(learnings, indent=2, ensure_ascii=False), encoding="utf-8")
+
+    regenerate_context_markdown(journal, learnings, context_file)
+    _log.ok(f"[SUCCESS] Memoria registrada en .memory/. Action ID: {action_id}")
+
+
+def _render_learnings_section(learnings: dict) -> list[str]:
+    """Renderiza la sección de aprendizajes agrupados por categoría."""
+    lines = ["\n## Aprendizajes y Lecciones Clave"]
+    has_learnings = False
+    for tag, items in sorted(learnings.items()):
+        tag_entries = [lrn for item in items for lrn in item.get("learned", [])]
+        if not tag_entries:
+            continue
+        has_learnings = True
+        lines.append(f"\n### Categoría: `{tag.upper()}`")
+        for entry in sorted(set(tag_entries)):
+            lines.append(f"- {entry}")
+    if not has_learnings:
+        lines.append(
+            "\n*No se han registrado aprendizajes específicos aún. "
+            "Los aprendizajes se acumulan a través del parámetro `--learned`.*"
+        )
+    return lines
+
+
+def _render_failures_section(journal: list) -> list[str]:
+    """Renderiza la sección de historial de fallas con causa raíz."""
+    lines = ["\n---\n\n## Historial de Fallas y Causa Raíz"]
+    failures = [j for j in journal if j["status"] == "failure"]
+    if not failures:
+        lines.append("\n*No se han registrado fallas de ejecución en el historial de memoria.*")
+        return lines
+    lines.append("\n| ID | Acción | Causa Raíz | Notas | Timestamp |")
+    lines.append("|---|---|---|---|---|")
+    for f in reversed(failures[-10:]):
+        root_cause = f.get("failure_root_cause") or "No especificada"
+        lines.append(
+            f"| `{f['action_id']}` | `{f['action']}` | **{root_cause}** "
+            f"| {f['notes']} | `{f['timestamp']}` |"
+        )
+    return lines
+
+
+def _render_journal_section(journal: list) -> list[str]:
+    """Renderiza la sección del historial secuencial reciente."""
+    lines = ["\n---\n\n## Historial Reciente de Operaciones"]
+    lines.append("\n| ID | Timestamp | Acción | Estado | Tags |")
+    lines.append("|---|---|---|---|---|")
+    for j in reversed(journal[-15:]):
+        tags_str = ", ".join(f"`{t}`" for t in j.get("tags", []))
+        symbol = "SUCCESS" if j["status"] == "success" else "FAILURE"
+        lines.append(
+            f"| `{j['action_id']}` | `{j['timestamp'][:19]}` "
+            f"| `{j['action']}` | {symbol} | {tags_str} |"
+        )
+    return lines
+
+
+def regenerate_context_markdown(journal: list, learnings: dict, context_file: Path) -> None:
+    """Genera un reporte Markdown limpio y estructurado de la memoria acumulada."""
+    lines = [
+        "# Registro de Memoria y Aprendizaje del Agente",
+        "\nEste archivo es autogenerado por el `memory-manager` de higpertext.",
+        "\n---",
+    ]
+    lines.extend(_render_learnings_section(learnings))
+    lines.extend(_render_failures_section(journal))
+    lines.extend(_render_journal_section(journal))
+    context_file.write_text("\n".join(lines), encoding="utf-8")
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """Construye el parser CLI compatible con capabilities_runner."""
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--action", required=True)
+    parser.add_argument("--status", required=True, choices=("success", "failure"))
+    parser.add_argument("--notes", required=True)
+    parser.add_argument("--action_id", required=False)
+    parser.add_argument("--learned", required=False)
+    parser.add_argument("--failure_root_cause", required=False)
+    parser.add_argument("--tags", required=False)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Punto de entrada de la capability common.memory-manager."""
+    args = _build_parser().parse_args(argv)
+
+    save_memory(
+        action=args.action,
+        status=args.status,
+        notes=args.notes,
+        action_id=args.action_id,
+        learned_str=args.learned,
+        failure_root_cause=args.failure_root_cause,
+        tags_str=args.tags,
+    )
+
+
+if __name__ == "__main__":
+    main()

higpertext/capabilities/common/scripts/presentation_engine.py

@@ -0,0 +1,63 @@
+"""higpertext Presentation Engine — convierte Markdown en presentaciones HTML Premium."""
+
+import argparse
+import shutil
+from pathlib import Path
+
+from higpertext.kernel.infrastructure.logger import get_logger
+_log = get_logger()
+
+_SCRIPT_DIR = Path(__file__).parent.absolute()
+_CAP_ROOT = _SCRIPT_DIR.parent
+_ASSETS_DIR = _CAP_ROOT / "assets"
+
+
+def _copy_js_assets(output_file: Path) -> None:
+    """Copia las librerías JS al directorio de salida."""
+    output_js_dir = output_file.parent / "assets" / "js"
+    output_js_dir.mkdir(parents=True, exist_ok=True)
+    source_js_dir = _ASSETS_DIR / "js"
+    if source_js_dir.exists():
+        for js_file in source_js_dir.glob("*.js"):
+            shutil.copy(js_file, output_js_dir)
+
+
+def _copy_css_assets(output_file: Path) -> None:
+    """Copia los archivos CSS al directorio de salida."""
+    output_css_dir = output_file.parent / "assets" / "css"
+    output_css_dir.mkdir(parents=True, exist_ok=True)
+    source_css_dir = _ASSETS_DIR / "css"
+    if source_css_dir.exists():
+        for css_file in source_css_dir.glob("*.css"):
+            shutil.copy(css_file, output_css_dir)
+
+
+def generate_presentation(md_path: str, output_path: str) -> None:
+    """Genera una presentación HTML a partir de un archivo Markdown."""
+    input_file = Path(md_path)
+    if not input_file.exists():
+        _log.error(f"Error: Archivo {md_path} no encontrado.")
+        return
+
+    template_path = _ASSETS_DIR / "base-template.html"
+    if not template_path.exists():
+        _log.error(f"Error: No se encuentra la plantilla base en {template_path}")
+        return
+
+    md_content = input_file.read_text(encoding="utf-8")
+    html_template = template_path.read_text(encoding="utf-8")
+    final_html = html_template.replace("{{SLIDES_CONTENT}}", md_content)
+
+    output_file = Path(output_path)
+    _copy_js_assets(output_file)
+    _copy_css_assets(output_file)
+    output_file.write_text(final_html, encoding="utf-8")
+    _log.ok(f"[SUCCESS] Presentación generada en: {output_path}")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--input", required=True)
+    parser.add_argument("--output", default="presentation.html")
+    args = parser.parse_args()
+    generate_presentation(args.input, args.output)

higpertext/capabilities/common/scripts/quality_scan.py

@@ -0,0 +1,132 @@
+"""common.quality-scan — genera un reporte Markdown básico de calidad Python."""
+
+from __future__ import annotations
+
+import argparse
+import ast
+from dataclasses import dataclass
+from pathlib import Path
+from higpertext.kernel.infrastructure.logger import get_logger
+_log = get_logger()
+
+
+@dataclass
+class FileQuality:
+    path: Path
+    score: int
+    penalties: list[str]
+
+
+def scan_python_file(path: Path, max_function_lines: int, max_class_lines: int) -> FileQuality:
+    penalties: list[str] = []
+    try:
+        source = path.read_text(encoding="utf-8")
+        tree = ast.parse(source)
+    except (OSError, SyntaxError) as exc:
+        return FileQuality(path, 50, [f"No se pudo parsear el archivo: {exc}"])
+
+    lines = source.splitlines()
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            length = _node_length(node)
+            if length > max_function_lines:
+                penalties.append(f"Función `{
+                        node.name}` excede {max_function_lines} líneas L{
+                        node.lineno}-L{
+                        getattr(
+                            node,
+                            'end_lineno',
+                            node.lineno)}")
+        if isinstance(node, ast.ClassDef):
+            length = _node_length(node)
+            if length > max_class_lines:
+                penalties.append(f"Clase `{
+                        node.name}` excede {max_class_lines} líneas L{
+                        node.lineno}-L{
+                        getattr(
+                            node,
+                            'end_lineno',
+                            node.lineno)}")
+
+    if lines and not _has_module_docstring(tree):
+        penalties.append("Sin comentarios/docstring de módulo")
+
+    score = max(0, 100 - (len(penalties) * 10))
+    return FileQuality(path, score, penalties)
+
+
+def scan_tree(root: Path, max_function_lines: int, max_class_lines: int) -> list[FileQuality]:
+    try:
+        from higpertext.kernel.config_paths import WORKSPACE_DIR_NAME
+    except ImportError:
+        WORKSPACE_DIR_NAME = ".higpertext"
+    ignored = {".git", ".venv", "venv", "__pycache__", "node_modules", WORKSPACE_DIR_NAME}
+    files = [path for path in root.rglob("*.py") if not ignored.intersection(path.parts)]
+    return [scan_python_file(path, max_function_lines, max_class_lines) for path in sorted(files)]
+
+
+def write_report(results: list[FileQuality], root: Path, output: Path) -> None:
+    output.parent.mkdir(parents=True, exist_ok=True)
+    lines = ["# Code Quality Report", "", f"Archivos analizados: `{len(results)}`", ""]
+    for result in results:
+        rel = _relative(result.path, root)
+        icon = "🟢" if result.score >= 90 else "🟡" if result.score >= 70 else "🔴"
+        lines += [
+            f"### {icon} `{rel}` — {result.score}/100",
+            "",
+            "**Penalizaciones aplicadas:**",
+        ]
+        if result.penalties:
+            lines.extend(f"- {penalty}" for penalty in result.penalties)
+        else:
+            lines.append("- Sin penalizaciones")
+        lines += ["", "---", ""]
+    output.write_text("\n".join(lines), encoding="utf-8")
+
+
+def _node_length(node: ast.AST) -> int:
+    return int(
+        getattr(node, "end_lineno", getattr(node, "lineno", 0)) - getattr(node, "lineno", 0) + 1
+    )
+
+
+def _has_module_docstring(tree: ast.Module) -> bool:
+    return ast.get_docstring(tree) is not None
+
+
+def _relative(path: Path, root: Path) -> str:
+    try:
+        return path.relative_to(root).as_posix()
+    except ValueError:
+        return path.as_posix()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Genera reporte de calidad Python")
+    parser.add_argument("--target", default="src", help="Directorio o archivo objetivo")
+    parser.add_argument("--output", default=".higpertext/reports/code_quality_report.md")
+    parser.add_argument("--max_function_lines", type=int, default=30)
+    parser.add_argument("--max_class_lines", type=int, default=200)
+    args = parser.parse_args()
+
+    root = Path.cwd()
+    target = Path(args.target)
+    if not target.is_absolute():
+        target = root / target
+    output = Path(args.output)
+    if not output.is_absolute():
+        output = root / output
+
+    results = (
+        [scan_python_file(target, args.max_function_lines, args.max_class_lines)]
+        if target.is_file()
+        else scan_tree(target, args.max_function_lines, args.max_class_lines)
+    )
+    write_report(results, root, output)
+    violations = sum(1 for result in results if result.penalties)
+    _log.ok(f"[SUCCESS] Reporte de calidad generado en: {output}")
+    _log.info(f"[*] Archivos analizados: {len(results)} · con violaciones: {violations}")
+
+
+if __name__ == "__main__":
+    main()

higpertext/capabilities/common/scripts/rag_index.py

@@ -0,0 +1,39 @@
+"""Capacidad para indexar el proyecto para RAG Semántico."""
+
+from __future__ import annotations
+import argparse
+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="Indexa el proyecto para búsqueda semántica (RAG).")
+    parser.add_argument("--root", type=str, default=".", help="Ruta al proyecto.")
+    args = parser.parse_args()
+
+    project_root = Path(args.root).resolve()
+    print(f"[*] Iniciando indexación semántica en: {project_root}")
+    
+    try:
+        embedder = GeminiEmbeddingProvider(project_root)
+        store = LocalVectorStore(project_root)
+        service = RAGService(embedder, store)
+
+        chunks_indexed = service.index_project(project_root)
+        print(f"[+] Indexación completada. {chunks_indexed} fragmentos semánticos indexados con éxito.")
+        sys.exit(0)
+    except Exception as e:
+        print(f"[ERROR] Falló la indexación: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

higpertext/capabilities/common/scripts/report_viewer.py

@@ -0,0 +1,106 @@
+"""Capacidad common.report-viewer — Dashboard HTML Interactivo de Reportes."""
+
+from __future__ import annotations
+import argparse
+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()
+
+# Resuelve raíz del proyecto
+_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"))
+
+try:
+    from higpertext.kernel.infrastructure.output_store import OutputStore
+except ImportError:
+    OutputStore = None
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="higpertext Premium Report Dashboard Compiler")
+    parser.add_argument(
+        "--output",
+        default=".higpertext/reports/index.html",
+        help="Ruta de destino del dashboard HTML resultante.",
+    )
+    args = parser.parse_args()
+
+    out_path = _ROOT / args.output
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # 1. Leer los componentes Markdown
+    telemetry_file = _ROOT / WORKSPACE_DIR_NAME / "reports" / "common_telemetry_report.txt"
+    rationale_file = _ROOT / WORKSPACE_DIR_NAME / "reports" / "commit_rationale_history.md"
+    drift_file = _ROOT / WORKSPACE_DIR_NAME / "reports" / "architecture_drift.md"
+
+    telemetry_content = (
+        telemetry_file.read_text(encoding="utf-8")
+        if telemetry_file.exists()
+        else "Sin datos de telemetría."
+    )
+    rationale_content = (
+        rationale_file.read_text(encoding="utf-8")
+        if rationale_file.exists()
+        else "Sin diario de decisiones."
+    )
+    drift_content = (
+        drift_file.read_text(encoding="utf-8")
+        if drift_file.exists()
+        else "Sin análisis de desviación."
+    )
+
+    # 2. Generar el documento Markdown consolidado con formato ATX
+    # Las secciones usan '##' para convertirse en slides del HTML Presentation Engine
+    slides = [
+        "# Dashboard de Entrega & Decisiones Técnicas",
+        "Resumen ejecutivo de telemetría, diario de decisiones de diseño y análisis de desviación del higpertext Engine.", # noqa: E501
+        "",
+        "## Resumen de Telemetría (Consumo & ROI)",
+        "<!-- tipo: grid -->",
+        f"```text\n{telemetry_content}\n```",
+        "",
+        "## Análisis de Desviación Arquitectónica",
+        "---",
+        drift_content,
+        "",
+        "## Diario Histórico de Decisiones",
+        "---",
+        rationale_content,
+    ]
+
+    temp_md_path = out_path.parent / "temp_dashboard.md"
+    temp_md_path.write_text("\n".join(slides), encoding="utf-8")
+
+    # 3. Invocar al motor de presentaciones HTML local
+    try:
+        from higpertext.capabilities.common.scripts.presentation_engine import (
+            generate_presentation,
+        )
+
+        generate_presentation(str(temp_md_path), str(out_path))
+    except Exception as e:
+        _log.error(f"[ERROR] No se pudo generar la presentación HTML: {e}")
+    finally:
+        # Limpiar archivo markdown temporal
+        if temp_md_path.exists():
+            try:
+                temp_md_path.unlink()
+            except OSError:  # nosec B110
+                pass
+
+    if OutputStore:
+        OutputStore(_ROOT).write(
+            "common.report-viewer", out_path.read_text(encoding="utf-8"), fmt="html"
+        )
+
+    _log.ok(f"[SUCCESS] Dashboard Premium HTML compilado en: {args.output}")
+
+
+if __name__ == "__main__":
+    main()

higpertext/capabilities/common/scripts/roadmap_report.py

@@ -0,0 +1,73 @@
+"""Capability common.roadmap-report — reporte explicativo del roadmap activo."""
+
+from __future__ import annotations
+from higpertext.kernel.application.roadmap_reporter import RoadmapReportBuilder, ProgressAnalyzer, RoadmapParser
+import argparse
+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 _parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Genera reporte explicativo del roadmap.")
+    parser.add_argument("--roadmap", default=str(_ROOT / WORKSPACE_DIR_NAME / "roadmap.json"))
+    parser.add_argument("--format", dest="fmt", default="markdown", choices=["markdown", "html"])
+    parser.add_argument("--output", default=None)
+    return parser.parse_args()
+
+
+def _resolve_output(args: argparse.Namespace, roadmap_id: str) -> Path:
+    if args.output:
+        return Path(args.output)
+    ext = "html" if args.fmt == "html" else "md"
+    out_dir = _ROOT / WORKSPACE_DIR_NAME / "reports" / "roadmap"
+    out_dir.mkdir(parents=True, exist_ok=True)
+    return out_dir / f"{roadmap_id}_report.{ext}"
+
+
+def _print_summary(report, analysis, out: Path) -> None:
+    r = report.roadmap
+    _log.info("╔─ HIGPERTEXT · Roadmap Report ───────────────────────────────")
+    _log.info(f"│  Roadmap  : {r.name} ({r.id})")
+    _log.info(f"│  Fases    : {report.done_phases}/{report.total_phases} completadas")
+    _log.info(f"│  Progreso : {analysis.completion_pct:.0f}%")
+    _log.info(f"│  Tags     : {', '.join(analysis.impact_tags)}")
+    _log.info(f"│  Skills   : {', '.join(report.all_skills_used) or '—'}")
+    _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()
+    roadmap_path = Path(args.roadmap)
+    if not roadmap_path.exists():
+        _log.error(f"[ERROR] Roadmap no encontrado: {roadmap_path}")
+        sys.exit(1)
+    try:
+        report = RoadmapParser().parse_file(roadmap_path)
+    except ValueError as exc:
+        _log.error(f"[ERROR] {exc}")
+        sys.exit(1)
+    analysis = ProgressAnalyzer().analyze(report)
+    builder = RoadmapReportBuilder()
+    content = (
+        builder.to_html(report, analysis)
+        if args.fmt == "html"
+        else builder.to_markdown(report, analysis)
+    )
+    out = _resolve_output(args, report.roadmap.id)
+    out.write_text(content, encoding="utf-8")
+    _print_summary(report, analysis, out)
+
+
+if __name__ == "__main__":
+    main()