higpertext-cli 0.8.0__py3-none-any.whl

higpertext/capabilities/common/scripts/doctor.py

@@ -0,0 +1,144 @@
+"""common.doctor — diagnóstico integral rápido del workspace higpertext."""
+
+from __future__ import annotations
+from higpertext.kernel.config_paths import WORKSPACE_DIR_NAME
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from higpertext.kernel.infrastructure.logger import get_logger
+_log = get_logger()
+
+
+def _read_json(path: Path) -> dict:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+def _check(name: str, ok: bool, message: str, severity: str = "critical") -> dict:
+    return {
+        "name": name,
+        "status": "ok" if ok else "fail",
+        "severity": "ok" if ok else severity,
+        "message": message,
+    }
+
+
+def run_doctor(root: Path) -> list[dict]:
+    """Ejecuta checks operativos sin requerir un asistente activo."""
+    checks = [
+        _check_htx(root),
+        _check_environment(root),
+        _check_capabilities(root),
+        _check_hooks(root),
+        _check_hook_sync(root),
+        _check_cache(root),
+        _check_reports(root),
+    ]
+    return checks
+
+
+def _check_htx(root: Path) -> dict:
+    candidates = [root / ".venv" / "bin" / "htx", root / "htx.py"]
+    return _check("htx", any(path.exists() for path in candidates), "launcher htx disponible")
+
+
+def _check_environment(root: Path) -> dict:
+    env = _read_json(root / WORKSPACE_DIR_NAME / "config" / "environment.json")
+    profile = env.get("active_profile") or env.get("profile")
+    assistant = env.get("assistant")
+    ok = bool(profile)
+    message = f"perfil={profile or '—'} assistant={assistant or '—'}"
+    return _check("environment", ok, message, "warning")
+
+
+def _check_capabilities(root: Path) -> dict:
+    cap_dir = root / "src" / "higpertext" / "capabilities"
+    invalid: list[str] = []
+    total = 0
+    for path in cap_dir.rglob("*.json") if cap_dir.exists() else []:
+        total += 1
+        if not _read_json(path):
+            invalid.append(str(path.relative_to(root)))
+    ok = total > 0 and not invalid
+    message = f"{total} capabilities JSON; inválidos={len(invalid)}"
+    return _check("capabilities", ok, message)
+
+
+def _check_hooks(root: Path) -> dict:
+    catalog = _read_json(root / "src" / "higpertext" / "hooks" / "hooks_catalog.json")
+    ids = {hook.get("id") for hook in catalog.get("hooks", [])}
+    required = {
+        "hook_bash_guard",
+        "hook_read_guard",
+        "hook_security_guard_pre",
+        "hook_security_guard_post",
+        "hook_post_observer",
+    }
+    missing = sorted(required - ids)
+    return _check("hooks", not missing, f"faltantes={missing or 'ninguno'}")
+
+
+def _check_hook_sync(root: Path) -> dict:
+    try:
+        from higpertext.capabilities.common.scripts.hook_sync_check import (
+            run_sync_check,
+        )
+    except ImportError:
+        return _check("hook_sync", False, "hook-sync-check no disponible", "warning")
+    result = run_sync_check(root)
+    drift = [item["assistant"] for item in result["assistants"] if item["status"] == "drift"]
+    missing = [item["assistant"] for item in result["assistants"] if item["status"] == "missing"]
+    ok = not drift
+    message = f"drift={drift or 'ninguno'} missing={missing or 'ninguno'}"
+    return _check("hook_sync", ok, message, "warning")
+
+
+def _check_cache(root: Path) -> dict:
+    cache_dir = root / WORKSPACE_DIR_NAME / "__cache__"
+    files = list(cache_dir.glob("*.json")) if cache_dir.exists() else []
+    stale = 0
+    for path in files:
+        data = _read_json(path)
+        if not data or "created_at" not in data:
+            stale += 1
+    ok = stale == 0
+    message = f"entradas={len(files)} corruptas={stale}"
+    return _check("cache", ok, message, "warning")
+
+
+def _check_reports(root: Path) -> dict:
+    reports = root / WORKSPACE_DIR_NAME / "reports"
+    expected = ["test_resolution_map.md"]
+    missing = [name for name in expected if not (reports / name).exists()]
+    return _check("reports", True, f"faltantes opcionales={missing or 'ninguno'}", "warning")
+
+
+def _print_human(checks: list[dict]) -> None:
+    _log.info("╔─ HIGPERTEXT · Doctor ─────────────────────────────────────")
+    for item in checks:
+        marker = "✓" if item["status"] == "ok" else "✗"
+        _log.info(f"│ {marker} {item['name']}: {item['message']}")
+    _log.info("╚────────────────────────────────────────────────────────────")
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(description="Diagnóstico integral higpertext")
+    parser.add_argument("--json", default="false", help="Emitir JSON estructurado")
+    args = parser.parse_args(argv)
+
+    checks = run_doctor(Path.cwd())
+    ok = all(item["status"] == "ok" or item["severity"] == "warning" for item in checks)
+    if args.json.lower() in {"true", "1", "yes"}:
+        print(json.dumps({"ok": ok, "checks": checks}, ensure_ascii=False, indent=2))
+    else:
+        _print_human(checks)
+    if not ok:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

higpertext/capabilities/common/scripts/efficiency_meter.py

@@ -0,0 +1,83 @@
+"""Capability common.efficiency-meter — mide la eficiencia de una sesión.
+
+Cruza telemetry.jsonl + context_packs para calcular: tokens totales,
+exploration_waste_ratio, context_hit_rate y hook_intercepts.
+"""
+
+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()
+
+def _resolve_core() -> Path:
+    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="Mide la eficiencia de una sesión.")
+    parser.add_argument(
+        "--session",
+        required=False,
+        default="",
+        help="ID de sesión. Si no se indica, usa la sesión activa.",
+    )
+    parser.add_argument(
+        "--format",
+        default="table",
+        help="Formato de salida: table|json|markdown. Default: table.",
+    )
+    args = parser.parse_args()
+
+    core = _resolve_core()
+    if str(core) not in sys.path:
+        sys.path.insert(0, str(core))
+
+    from higpertext.context_engine.application.efficiency_meter import EfficiencyMeter
+
+    project_root = core.parent.parent
+
+    session_id = args.session
+    if not session_id:
+        session_file = project_root / WORKSPACE_DIR_NAME / "state" / "session.json"
+        if session_file.exists():
+            import json
+
+            data = json.loads(session_file.read_text(encoding="utf-8"))
+            session_id = data.get("session_id", "")
+    if not session_id:
+        _log.error("[ERROR] No se encontró sesión activa. Usa --session <id>.")
+        sys.exit(1)
+
+    meter = EfficiencyMeter(project_root)
+    report = meter.measure_session(session_id)
+
+    if args.format == "json":
+        import json
+
+        print(json.dumps(report.to_dict(), indent=2))
+    elif args.format == "markdown":
+        _log.info(report.to_markdown())
+    else:
+        waste_pct = f"{report.exploration_waste_ratio * 100:.1f}%"
+        hit_pct = f"{report.context_hit_rate * 100:.1f}%"
+        _log.info("╔─ HIGPERTEXT · Efficiency Report ────────────────────────────")
+        _log.info(f"│  Sesión          : {report.session_id}")
+        _log.info(f"│  Tokens totales  : {report.total_tokens:,}")
+        _log.info(f"│  Costo estimado  : ${report.total_cost_usd:.4f} USD")
+        _log.info(f"│  Exploration waste: {waste_pct}  ({report.exploration_reads} reads ciegos)")
+        _log.info(f"│  higpertext reads     : {report.higpertext_reads}")
+        _log.info(f"│  Hook intercepts : {report.hook_intercepts}")
+        _log.info(f"│  Context hit rate: {hit_pct}")
+        _log.info("╚───────────────────────────────────────────────────────")
+
+
+if __name__ == "__main__":
+    main()

higpertext/capabilities/common/scripts/env_catalog.py

@@ -0,0 +1,47 @@
+"""Capability common.env-catalog — lista templates y motores disponibles."""
+
+from __future__ import annotations
+
+import argparse
+
+from higpertext.capabilities.common.scripts._env_cli import print_json, service
+from higpertext.kernel.infrastructure import ComposeBackend
+
+from higpertext.kernel.infrastructure.logger import get_logger
+_log = get_logger()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Lista templates de entornos locales")
+    parser.add_argument("--engine", default="auto", choices=["auto", "docker", "podman"])
+    parser.add_argument("--json", default="false")
+    args = parser.parse_args()
+    templates = service().catalog()
+    payload = {
+        "engines": {
+            "docker": ComposeBackend("docker").available(),
+            "podman": ComposeBackend("podman").available(),
+        },
+        "templates": [
+            {
+                "id": item.id,
+                "description": item.description,
+                "source": str(item.source or ""),
+            }
+            for item in templates
+        ],
+    }
+    if args.json.lower() in {"true", "1", "yes"}:
+        print_json(payload)
+        return
+    _log.info("╔─ HIGPERTEXT · Env Catalog ─────────────────────────────────")
+    _log.info(f"│ Docker : {'ok' if payload['engines']['docker'] else 'no disponible'}")
+    _log.info(f"│ Podman : {'ok' if payload['engines']['podman'] else 'no disponible'}")
+    _log.info("╠─ Templates ────────────────────────────────────────────────")
+    for item in payload["templates"]:
+        _log.info(f"│ {item['id']}: {item['description']}")
+    _log.info("╚────────────────────────────────────────────────────────────")
+
+
+if __name__ == "__main__":
+    main()

higpertext/capabilities/common/scripts/env_clean.py

@@ -0,0 +1,30 @@
+"""Capability common.env-clean — limpia metadata de runs finalizados."""
+
+from __future__ import annotations
+
+import argparse
+from higpertext.kernel.infrastructure.logger import get_logger
+_log = get_logger()
+
+from higpertext.capabilities.common.scripts._env_cli import (
+    parse_bool,
+    print_json,
+    service,
+)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Limpia runs de entorno")
+    parser.add_argument("--all", default="false")
+    parser.add_argument("--older_than", default="")
+    parser.add_argument("--json", default="false")
+    args = parser.parse_args()
+    count = service().clean(parse_bool(args.all))
+    if parse_bool(args.json):
+        print_json({"deleted": count})
+        return
+    _log.ok(f"[SUCCESS] {count} run(s) limpiado(s).")
+
+
+if __name__ == "__main__":
+    main()

higpertext/capabilities/common/scripts/env_logs.py

@@ -0,0 +1,32 @@
+"""Capability common.env-logs — lee logs compactos de un run."""
+
+from __future__ import annotations
+
+import argparse
+from higpertext.kernel.infrastructure.logger import get_logger
+_log = get_logger()
+
+from higpertext.capabilities.common.scripts._env_cli import (
+    parse_bool,
+    print_json,
+    service,
+)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Lee logs de entorno")
+    parser.add_argument("--run_id", required=True)
+    parser.add_argument("--service", default="")
+    parser.add_argument("--tail", type=int, default=200)
+    parser.add_argument("--errors_only", default="false")
+    parser.add_argument("--json", default="false")
+    args = parser.parse_args()
+    logs = service().logs(args.run_id, args.service, args.tail, parse_bool(args.errors_only))
+    if parse_bool(args.json):
+        print_json({"run_id": args.run_id, "logs": logs})
+        return
+    _log.info(logs)
+
+
+if __name__ == "__main__":
+    main()

higpertext/capabilities/common/scripts/env_runner.py

@@ -0,0 +1,53 @@
+"""Capability common.env-runner — ejecuta un entorno Docker/Podman."""
+
+from __future__ import annotations
+
+import argparse
+
+from higpertext.capabilities.common.scripts._env_cli import (
+    parse_bool,
+    parse_env,
+    print_json,
+    print_state,
+    service,
+    state_payload,
+)
+from higpertext.kernel.domain import RunSpec
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Ejecuta entornos locales Docker/Podman")
+    parser.add_argument("--template", required=True)
+    parser.add_argument("--engine", default="auto", choices=["auto", "docker", "podman"])
+    parser.add_argument("--task", default="")
+    parser.add_argument("--command", default="")
+    parser.add_argument("--service", default="")
+    parser.add_argument("--detach", default="false")
+    parser.add_argument("--parallel", default="false")
+    parser.add_argument("--timeout", type=int, default=300)
+    parser.add_argument("--keep_alive", default="false")
+    parser.add_argument("--cleanup", default="true")
+    parser.add_argument("--env", default="")
+    parser.add_argument("--json", default="false")
+    args = parser.parse_args()
+    spec = RunSpec(
+        template_id=args.template,
+        engine=args.engine,
+        task=args.task,
+        command=args.command,
+        service=args.service,
+        detach=parse_bool(args.detach),
+        timeout_seconds=args.timeout,
+        keep_alive=parse_bool(args.keep_alive),
+        cleanup=parse_bool(args.cleanup),
+        env=parse_env(args.env),
+    )
+    state = service().run(spec)
+    if parse_bool(args.json):
+        print_json(state_payload(state))
+        return
+    print_state(state)
+
+
+if __name__ == "__main__":
+    main()

higpertext/capabilities/common/scripts/env_status.py

@@ -0,0 +1,38 @@
+"""Capability common.env-status — consulta estado de ejecuciones."""
+
+from __future__ import annotations
+
+import argparse
+from higpertext.kernel.infrastructure.logger import get_logger
+_log = get_logger()
+
+from higpertext.capabilities.common.scripts._env_cli import (
+    parse_bool,
+    print_json,
+    print_state,
+    service,
+    state_payload,
+)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Consulta estado de env runs")
+    parser.add_argument("--run_id", default="")
+    parser.add_argument("--json", default="false")
+    args = parser.parse_args()
+    result = service().status(args.run_id or None)
+    if parse_bool(args.json):
+        payload = state_payload(result) if args.run_id else [state_payload(item) for item in result]
+        print_json(payload)
+        return
+    if args.run_id:
+        print_state(result)
+        return
+    _log.info("╔─ HIGPERTEXT · Env Runs ────────────────────────────────────")
+    for state in result:
+        _log.info(f"│ {state.run_id} · {state.template_id} · {state.status} · {state.engine}")
+    _log.info("╚────────────────────────────────────────────────────────────")
+
+
+if __name__ == "__main__":
+    main()

higpertext/capabilities/common/scripts/env_stop.py

@@ -0,0 +1,30 @@
+"""Capability common.env-stop — detiene un entorno."""
+
+from __future__ import annotations
+
+import argparse
+
+from higpertext.capabilities.common.scripts._env_cli import (
+    parse_bool,
+    print_json,
+    print_state,
+    service,
+    state_payload,
+)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Detiene entorno local")
+    parser.add_argument("--run_id", required=True)
+    parser.add_argument("--volumes", default="false")
+    parser.add_argument("--json", default="false")
+    args = parser.parse_args()
+    state = service().stop(args.run_id, parse_bool(args.volumes))
+    if parse_bool(args.json):
+        print_json(state_payload(state))
+        return
+    print_state(state)
+
+
+if __name__ == "__main__":
+    main()

higpertext/capabilities/common/scripts/env_template.py

@@ -0,0 +1,73 @@
+"""Capability common.env-template — valida o muestra templates."""
+
+from __future__ import annotations
+from higpertext.kernel.config_paths import WORKSPACE_DIR_NAME
+
+import argparse
+from higpertext.kernel.infrastructure.logger import get_logger
+_log = get_logger()
+
+from higpertext.capabilities.common.scripts._env_cli import (
+    parse_bool,
+    print_json,
+    project_root,
+    service,
+)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Gestiona templates de entorno")
+    parser.add_argument("--action", required=True, choices=["validate", "show", "create"])
+    parser.add_argument("--template", required=True)
+    parser.add_argument("--json", default="false")
+    args = parser.parse_args()
+    if args.action == "create":
+        target = project_root() / WORKSPACE_DIR_NAME / "env" / "templates" / f"{args.template}.yaml"
+        target.parent.mkdir(parents=True, exist_ok=True)
+        if not target.exists():
+            target.write_text(_starter_template(args.template), encoding="utf-8")
+        _log.ok(f"[SUCCESS] Template disponible en: {target}")
+        return
+    template = service().validate_template(args.template)
+    payload = {
+        "id": template.id,
+        "description": template.description,
+        "source": str(template.source or ""),
+        "services": list(template.services),
+    }
+    if parse_bool(args.json):
+        print_json(payload)
+        return
+    if args.action == "show":
+        print_json(payload)
+    else:
+        _log.ok(f"Template válido: {template.id}")
+
+
+def _starter_template(template_id: str) -> str:
+    return f"""id: {template_id}
+description: Custom local environment
+services:
+  app:
+    image: alpine:3.20
+    working_dir: /workspace
+    volumes:
+      - .:/workspace
+    command: sleep infinity
+tasks:
+  test:
+    service: app
+    command: echo 'custom task'
+defaults:
+  service: app
+  task: test
+  timeout_seconds: 300
+  cleanup: true
+security:
+  network: isolated
+  privileged: false
+"""
+
+
+if __name__ == "__main__":
+    main()

higpertext/capabilities/common/scripts/error_context_locator.py

@@ -0,0 +1,138 @@
+"""common.error-context-locator — localiza contexto mínimo desde errores/trazas."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from higpertext.kernel.infrastructure.logger import get_logger
+_log = get_logger()
+
+_PY_TRACE = re.compile(r'File "(?P<file>[^"]+)", line (?P<line>\d+)')
+_GENERIC = re.compile(
+    r"(?P<file>[\w./\\-]+\.(?:py|js|ts|tsx|jsx|json|yaml|yml|toml|md))[:(](?P<line>\d+)"
+)
+
+
+@dataclass(frozen=True)
+class ErrorLocation:
+    file: str
+    line: int
+    message: str = ""
+
+
+def _read_error(args: argparse.Namespace) -> str:
+    if args.error_file:
+        return Path(args.error_file).read_text(encoding="utf-8", errors="ignore")
+    return args.error or sys.stdin.read()
+
+
+def extract_locations(text: str, include_tests: bool = True) -> list[ErrorLocation]:
+    """Extrae ubicaciones file:line de trazas comunes."""
+    results: list[ErrorLocation] = []
+    for pattern in (_PY_TRACE, _GENERIC):
+        for match in pattern.finditer(text):
+            file = match.group("file").replace("\\", "/")
+            if not include_tests and _is_test_file(file):
+                continue
+            line = int(match.group("line"))
+            message = _nearby_error_line(text, match.start())
+            item = ErrorLocation(file=file, line=line, message=message)
+            if item not in results:
+                results.append(item)
+    return results
+
+
+def _is_test_file(file: str) -> bool:
+    parts = set(Path(file).parts)
+    return bool(parts & {"tests", "test", "__tests__"}) or Path(file).name.startswith("test_")
+
+
+def _nearby_error_line(text: str, index: int) -> str:
+    prefix = text[:index].splitlines()[-3:]
+    suffix = text[index:].splitlines()[:3]
+    for line in reversed(prefix + suffix):
+        stripped = line.strip()
+        if stripped and any(
+            token in stripped.lower() for token in ("error", "exception", "failed", "assert")
+        ):
+            return stripped[:240]
+    return ""
+
+
+def _context_for(root: Path, location: ErrorLocation, max_context: int) -> str:
+    path = Path(location.file)
+    if not path.is_absolute():
+        path = root / path
+    if not path.exists() or not path.is_file():
+        return "    [archivo no encontrado]"
+    lines = path.read_text(encoding="utf-8", errors="ignore").splitlines()
+    start = max(1, location.line - max_context)
+    end = min(len(lines), location.line + max_context)
+    output = []
+    for lineno in range(start, end + 1):
+        marker = ">>>" if lineno == location.line else "   "
+        output.append(f"    {marker} L{lineno:>4}: {lines[lineno - 1][:220]}")
+    return "\n".join(output)
+
+
+def build_report(text: str, root: Path, max_context: int, include_tests: bool) -> str:
+    locations = extract_locations(text, include_tests)
+    if not locations:
+        return "[NOT FOUND] No se detectaron ubicaciones file:line en el error."
+    lines = ["╔─ HIGPERTEXT · Error Context Locator ───────────────────────"]
+    lines.append(f"│ Ubicaciones detectadas: {len(locations)}")
+    lines.append("╠────────────────────────────────────────────────────────────")
+    for loc in locations[:20]:
+        lines.append(f"│ {loc.file}:{loc.line}")
+        if loc.message:
+            lines.append(f"│   Error: {loc.message}")
+        lines.append("│   Contexto:")
+        lines.append(_context_for(root, loc, max_context))
+        lines.append("│   Sugerencia:")
+        lines.append(
+            f"│     htx task common.smart-read --path {loc.file} --around_line {loc.line} --limit {max_context}" # noqa: E501
+        )
+    lines.append("╚────────────────────────────────────────────────────────────")
+    return "\n".join(lines)
+
+
+def _json_report(text: str, root: Path, max_context: int, include_tests: bool) -> dict:
+    locations = extract_locations(text, include_tests)
+    return {
+        "locations": [loc.__dict__ for loc in locations],
+        "suggestions": [
+            f"htx task common.smart-read --path {loc.file} --around_line {loc.line} --limit {max_context}" # noqa: E501
+            for loc in locations
+        ],
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Localiza contexto mínimo desde trazas de error")
+    parser.add_argument("--error", default="")
+    parser.add_argument("--error_file", default="")
+    parser.add_argument("--max_context", type=int, default=5)
+    parser.add_argument("--include_tests", default="true")
+    parser.add_argument("--json", default="false")
+    args = parser.parse_args()
+    text = _read_error(args)
+    include_tests = args.include_tests.lower() in {"true", "1", "yes"}
+    if args.json.lower() in {"true", "1", "yes"}:
+        _log.info(
+            json.dumps(
+                _json_report(text, Path.cwd(), args.max_context, include_tests),
+                ensure_ascii=False,
+                indent=2,
+            )
+        )
+        return
+    _log.info(build_report(text, Path.cwd(), args.max_context, include_tests))
+
+
+if __name__ == "__main__":
+    main()