higpertext-cli 0.8.0__py3-none-any.whl

higpertext/kernel/domain/agent_registry.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Protocol
+
+@dataclass(frozen=True)
+class AgentRecord:
+    name: str
+    path: str
+    profile: str
+    registered_at: str
+
+
+@dataclass
+class SyncResult:
+    name: str
+    success: bool
+    message: str
+
+
+class IAgentRegistryRepository(Protocol):
+    def load(self) -> list[AgentRecord]: ...
+    def save(self, agents: list[AgentRecord]) -> None: ...
+    def find_by_name(self, name: str) -> AgentRecord | None: ...

higpertext/kernel/domain/commit_reporter.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+from collections import defaultdict
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+
+class CommitType(str, Enum):
+    FEAT = "feat"
+    FIX = "fix"
+    DOCS = "docs"
+    REFACTOR = "refactor"
+    TEST = "test"
+    CHORE = "chore"
+    PERF = "perf"
+    CI = "ci"
+    OTHER = "other"
+
+
+
+
+@dataclass(frozen=True)
+class ParsedCommitMessage:
+    type: str
+    scope: str | None
+    subject: str
+
+
+def parse_commit_message(message: str) -> ParsedCommitMessage | None:
+    """Parsea Conventional Commits en tiempo lineal, evitando regex con backtracking."""
+    prefix, separator, subject = message.partition(":")
+    if not separator or not subject.strip():
+        return None
+    scope: str | None = None
+    commit_type = prefix.strip()
+    if "(" in commit_type:
+        type_part, scope_part = commit_type.split("(", 1)
+        if not scope_part.endswith(")"):
+            return None
+        commit_type = type_part
+        scope = scope_part[:-1] or None
+    if not commit_type or not commit_type.replace("_", "").isalnum():
+        return None
+    return ParsedCommitMessage(commit_type, scope, subject.strip())
+
+
+@dataclass(frozen=True)
+class Commit:
+    hash: str
+    message: str
+    author: str
+    date: str
+
+    @property
+    def short_hash(self) -> str:
+        return self.hash[:7]
+
+    @property
+    def _parsed(self) -> ParsedCommitMessage | None:
+        return parse_commit_message(self.message)
+
+    @property
+    def commit_type(self) -> CommitType:
+        m = self._parsed
+        if not m:
+            return CommitType.OTHER
+        try:
+            return CommitType(m.type.lower())
+        except ValueError:
+            return CommitType.OTHER
+
+    @property
+    def scope(self) -> str | None:
+        m = self._parsed
+        return m.scope if m else None
+
+    @property
+    def subject(self) -> str:
+        m = self._parsed
+        return m.subject if m else self.message
+
+
+class Layer(str, Enum):
+    DOMAIN = "domain"
+    APPLICATION = "application"
+    INFRASTRUCTURE = "infrastructure"
+    TEST = "test"
+    CAPABILITY = "capability"
+    OTHER = "other"
+
+
+def _classify(path: str) -> Layer:
+    p = path.replace("\\", "/")
+    if p.startswith("tests/") or "/tests/" in p:
+        return Layer.TEST
+    if "capabilities/" in p:
+        return Layer.CAPABILITY
+    if "/domain/" in p:
+        return Layer.DOMAIN
+    if "/application/" in p:
+        return Layer.APPLICATION
+    if "/infrastructure/" in p:
+        return Layer.INFRASTRUCTURE
+    return Layer.OTHER
+
+
+@dataclass(frozen=True)
+class FileChange:
+    path: str
+    additions: int
+    deletions: int
+
+    @property
+    def layer(self) -> Layer:
+        return _classify(self.path)
+
+    @property
+    def net_lines(self) -> int:
+        return self.additions - self.deletions
+
+    @property
+    def filename(self) -> str:
+        return Path(self.path).name
+
+
+@dataclass
+class CommitReport:
+    commit: Commit
+    changes: list[FileChange]
+
+    @property
+    def total_additions(self) -> int:
+        return sum(c.additions for c in self.changes)
+
+    @property
+    def total_deletions(self) -> int:
+        return sum(c.deletions for c in self.changes)
+
+    @property
+    def changed_files_count(self) -> int:
+        return len(self.changes)
+
+    @property
+    def has_new_tests(self) -> bool:
+        return any(c.layer == Layer.TEST and c.additions > 0 for c in self.changes)
+
+    @property
+    def has_new_capabilities(self) -> bool:
+        return any(c.layer == Layer.CAPABILITY and c.additions > 0 for c in self.changes)
+
+    def files_by_layer(self) -> dict[Layer, list[FileChange]]:
+        groups: dict[Layer, list[FileChange]] = defaultdict(list)
+        for change in self.changes:
+            groups[change.layer].append(change)
+        return dict(groups)

higpertext/kernel/domain/compilers.py

@@ -0,0 +1,7 @@
+from abc import ABC, abstractmethod
+
+class ICompiler(ABC):
+    @abstractmethod
+    def compile(self, *args, **kwargs) -> bool:
+        """Ejecuta el proceso de compilación/generación para la actividad."""
+        pass

higpertext/kernel/domain/context_engine.py

@@ -0,0 +1,319 @@
+"""Context Engine Domain layer — ContextPack, EfficiencyReport, TaskGraph, TaskIntent, TaskNode, and WindowState."""
+
+from __future__ import annotations
+import json
+import os
+import re
+import time
+from collections import Counter
+from dataclasses import dataclass, field, asdict
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class SymbolRef:
+    """Referencia a un símbolo del semantic graph (clase o función)."""
+
+    file: str
+    name: str
+    kind: str  # "class" | "function" | "method"
+    doc: str = ""
+
+
+@dataclass(frozen=True)
+class FileSkeleton:
+    """Esqueleto comprimido de un archivo (firmas sin cuerpos)."""
+
+    file: str
+    skeleton: str
+
+
+_CE_CONFIG_PATH = Path(__file__).resolve().parents[4] / "src" / "config" / "context_engine.json"
+_CE_CFG: dict = json.loads(_CE_CONFIG_PATH.read_text(encoding="utf-8"))
+
+_STOPWORDS = frozenset(_CE_CFG["stopwords"])
+_MD = _CE_CFG["markdown"]
+_RM = _CE_CFG["roadmap"]
+
+
+@dataclass(frozen=True)
+class TaskIntent:
+    """Intención de tarea: objetivo, tipo y keywords derivados."""
+
+    goal: str
+    task_type: str
+    keywords: tuple[str, ...] = field(default_factory=tuple)
+    token_budget: int = 8000
+
+    @classmethod
+    def from_goal(cls, goal: str, task_type: str, token_budget: int = 8000) -> TaskIntent:
+        keywords = tuple(cls._extract_keywords(goal))
+        return cls(goal=goal, task_type=task_type, keywords=keywords, token_budget=token_budget)
+
+    @staticmethod
+    def _extract_keywords(goal: str, top_n: int = 8) -> list[str]:
+        tokens = re.findall(r"[^\W\d_][\w]{2,}", goal.lower(), re.UNICODE)
+        filtered = [t for t in tokens if t not in _STOPWORDS]
+        counts = Counter(filtered)
+        return [t for t, _ in counts.most_common(top_n)]
+
+
+@dataclass
+class ContextPack:
+    """Conjunto curado de assets relevantes para una TaskIntent."""
+
+    intent: TaskIntent
+    relevant_symbols: list[SymbolRef] = field(default_factory=list)
+    applicable_memories: list[str] = field(default_factory=list)
+    skeletons: list[FileSkeleton] = field(default_factory=list)
+    estimated_tokens: int = 0
+
+    def _header_lines(self) -> list[str]:
+        return [
+            f"# Context Pack — {self.intent.task_type}",
+            f"> **Objetivo**: {self.intent.goal}",
+            f"> **Keywords**: {', '.join(self.intent.keywords) or '—'}",
+            f"> **Tokens estimados**: {self.estimated_tokens} / {self.intent.token_budget}",
+            "",
+        ]
+
+    def _symbols_lines(self) -> list[str]:
+        if not self.relevant_symbols:
+            return []
+
+        lines = [_MD["symbols_header"], ""]
+        by_file: dict[str, list[SymbolRef]] = {}
+        for s in self.relevant_symbols:
+            by_file.setdefault(s.file, []).append(s)
+        for file, symbols in by_file.items():
+            lines.append(f"### [{file}](file:///{file})")
+            for s in symbols:
+                doc = f" — {s.doc}" if s.doc else ""
+                lines.append(f"- `{s.kind} {s.name}`{doc}")
+            lines.append("")
+        return lines
+
+    def _memories_lines(self) -> list[str]:
+        if not self.applicable_memories:
+            return []
+
+        lines = [_MD["memories_header"], ""]
+        for m in self.applicable_memories:
+            lines.append(f"- {m}")
+        lines.append("")
+        return lines
+
+    def _skeletons_lines(self) -> list[str]:
+        if not self.skeletons:
+            return []
+
+        lines = [_MD["skeletons_header"], ""]
+        for sk in self.skeletons:
+            lines += [f"### {sk.file}", "```", sk.skeleton, "```", ""]
+        return lines
+
+    def to_markdown(self) -> str:
+        lines = self._header_lines()
+        lines += self._symbols_lines()
+        lines += self._memories_lines()
+        lines += self._skeletons_lines()
+        return "\n".join(lines)
+
+
+@dataclass
+class EfficiencyReport:
+    """Métricas calculadas al cierre de sesión para medir el valor del contexto."""
+
+    session_id: str
+    total_tokens: int
+    total_cost_usd: float
+    exploration_reads: int
+    higpertext_reads: int
+    hook_intercepts: int
+    context_hit_rate: float
+    exploration_waste_ratio: float
+    window_usage_pct: float = 0.0
+    peak_window_tokens: int = 0
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    def to_markdown(self) -> str:
+        waste_pct = f"{self.exploration_waste_ratio * 100:.1f}%"
+        hit_pct = f"{self.context_hit_rate * 100:.1f}%"
+        win_pct = f"{self.window_usage_pct * 100:.1f}%"
+        return "\n".join(
+            [
+                _MD["efficiency_report_title"].format(session_id=self.session_id),
+                "",
+                _MD["efficiency_table_header"][0],
+                _MD["efficiency_table_header"][1],
+                f"| Tokens totales | {self.total_tokens:,} |",
+                f"| Costo estimado | ${self.total_cost_usd:.4f} USD |",
+                f"| Lecturas de exploración (sin higpertext) | {self.exploration_reads} |",
+                f"| Lecturas vía higpertext | {self.higpertext_reads} |",
+                f"| Hook intercepts | {self.hook_intercepts} |",
+                f"| Context hit rate | {hit_pct} |",
+                f"| Exploration waste ratio | {waste_pct} |",
+                f"| Pico de uso de ventana | {win_pct} ({self.peak_window_tokens:,} tokens) |",
+            ]
+        )
+
+
+@dataclass
+class TaskNode:
+    """Unidad atómica de trabajo: descripción, dependencias y pack de contexto."""
+
+    id: str
+    description: str
+    depends_on: list[str] = field(default_factory=list)
+    context_pack_ref: str = ""
+    status: str = "pending"  # pending | active | done
+    skills: list[str] = field(default_factory=list)
+    subagents: list[str] = field(default_factory=list)
+
+
+@dataclass
+class TaskGraph:
+    """Grafo dirigido acíclico (DAG) de tareas con orden de ejecución."""
+
+    nodes: list[TaskNode] = field(default_factory=list)
+    goal: str = ""
+
+    def is_acyclic(self) -> bool:
+        ids = {n.id for n in self.nodes}
+        deps = {n.id: [d for d in n.depends_on if d in ids] for n in self.nodes}
+        WHITE, GRAY, BLACK = 0, 1, 2
+        color = {nid: WHITE for nid in ids}
+
+        def visit(nid: str) -> bool:
+            if color[nid] == GRAY:
+                return False
+            if color[nid] == BLACK:
+                return True
+            color[nid] = GRAY
+            for dep in deps.get(nid, []):
+                if not visit(dep):
+                    return False
+            color[nid] = BLACK
+            return True
+
+        return all(visit(nid) for nid in ids if color[nid] == WHITE)
+
+    def topological_order(self) -> list[TaskNode]:
+        ids = {n.id: n for n in self.nodes}
+        deps = {n.id: [d for d in n.depends_on if d in ids] for n in self.nodes}
+        visited: set[str] = set()
+        result: list[TaskNode] = []
+
+        def visit(nid: str) -> None:
+            if nid in visited:
+                return
+            visited.add(nid)
+            for dep in deps.get(nid, []):
+                visit(dep)
+            result.append(ids[nid])
+
+        for nid in ids:
+            visit(nid)
+        return result
+
+    def to_roadmap_dict(self) -> dict:
+        all_skills: list[str] = []
+        all_subagents: list[str] = []
+        phases = []
+        for node in self.topological_order():
+            for s in node.skills:
+                if s not in all_skills:
+                    all_skills.append(s)
+            for sa in node.subagents:
+                if sa not in all_subagents:
+                    all_subagents.append(sa)
+            phases.append(
+                {
+                    "id": node.id,
+                    "name": node.description[:_RM["name_truncation"]],
+                    "description": node.description,
+                    "status": node.status,
+                    "skills": node.skills,
+                    "subagents": node.subagents,
+                    "depends_on": node.depends_on,
+                    "context_pack_ref": node.context_pack_ref,
+                }
+            )
+        return {
+            "version": _RM["version"],
+            "project": self.goal[:_RM["project_truncation"]] if self.goal else _RM["default_project"],
+            "created_at": _today(),
+            "session_resources": {
+                "skills": all_skills or list(_RM["fallback_skills"]),
+                "subagents": all_subagents or list(_RM["fallback_subagents"]),
+            },
+            "phases": phases,
+        }
+
+
+def _today() -> str:
+    import datetime
+    return datetime.date.today().isoformat()
+
+
+_STATE_FILE = Path(_CE_CFG["state_file_path"])
+
+
+def _window_limit() -> int:
+    try:
+        return int(os.environ.get(_CE_CFG["window_limit"]["env_var"], _CE_CFG["window_limit"]["default_str"]))
+    except ValueError:
+        return _CE_CFG["window_limit"]["default_int"]
+
+
+@dataclass
+class WindowState:
+    accumulated_tokens: int = 0
+    peak_tokens: int = 0
+    turn: int = 0
+    last_updated: float = 0.0
+
+    def add(self, tokens: int) -> None:
+        self.accumulated_tokens += tokens
+        if self.accumulated_tokens > self.peak_tokens:
+            self.peak_tokens = self.accumulated_tokens
+        self.last_updated = time.time()
+
+    def usage_pct(self, window_limit: int) -> float:
+        if window_limit <= 0:
+            return 0.0
+        return min(self.accumulated_tokens / window_limit, 1.0)
+
+
+def load_window_state(root: Path) -> WindowState:
+    path = root / _STATE_FILE
+    if not path.exists():
+        return WindowState()
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return WindowState(**{k: data[k] for k in WindowState.__dataclass_fields__ if k in data})
+    except (json.JSONDecodeError, TypeError, OSError):
+        return WindowState()
+
+
+def save_window_state(root: Path, state: WindowState) -> None:
+    path = root / _STATE_FILE
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(".tmp")
+    tmp.write_text(json.dumps(asdict(state), indent=2, ensure_ascii=False), encoding="utf-8")
+    tmp.replace(path)
+
+
+def reset_window_state(root: Path, turn: int | None = None) -> WindowState:
+    prev = load_window_state(root)
+    new_turn = (prev.turn + 1) if turn is None else turn
+    fresh = WindowState(
+        accumulated_tokens=0,
+        peak_tokens=prev.peak_tokens,
+        turn=new_turn,
+        last_updated=time.time(),
+    )
+    save_window_state(root, fresh)
+    return fresh

higpertext/kernel/domain/entities.py

@@ -0,0 +1,51 @@
+"""Modelos e invariantes del Dominio del Kernel de higpertext."""
+
+from __future__ import annotations
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class Profile:
+    name: str
+    description: str
+    system_prompt: str
+    capabilities: list[str] = field(default_factory=list)
+    session_skills: list[str] = field(default_factory=list)
+    session_subagents: list[str] = field(default_factory=list)
+    governance_access: bool = False
+    extends: str | None = None
+    model: str | None = None
+
+
+@dataclass(frozen=True)
+class Capability:
+    id: str
+    version: str
+    name: str
+    description: str
+    entrypoint: str
+    language: str
+    parameters: list[dict] = field(default_factory=list)
+    security: dict = field(default_factory=dict)
+    hook_task_id: str | None = None
+
+
+@dataclass(frozen=True)
+class Workflow:
+    id: str
+    name: str
+    description: str
+    steps: list[dict] = field(default_factory=list)
+    required_profile: str = ""
+
+
+@dataclass(frozen=True)
+class Session:
+    session_id: str
+    profile: str
+    assistant: str
+    status: str
+    created_at: str
+    active_skills: list[str] = field(default_factory=list)
+    active_subagents: list[str] = field(default_factory=list)
+    tasks: list[dict] = field(default_factory=list)

higpertext/kernel/domain/env_runtime.py

@@ -0,0 +1,62 @@
+"""Modelos del runtime local de entornos (Dominio)."""
+
+from __future__ import annotations
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True)
+class EnvironmentTemplate:
+    """Plantilla declarativa de un ambiente ejecutable."""
+
+    id: str
+    description: str
+    services: dict[str, dict[str, Any]]
+    defaults: dict[str, Any] = field(default_factory=dict)
+    tasks: dict[str, dict[str, Any]] = field(default_factory=dict)
+    limits: dict[str, Any] = field(default_factory=dict)
+    security: dict[str, Any] = field(default_factory=dict)
+    source: Path | None = None
+
+
+@dataclass(frozen=True)
+class RunSpec:
+    """Solicitud de ejecución de un entorno."""
+
+    template_id: str
+    engine: str = "auto"
+    task: str = ""
+    command: str = ""
+    service: str = ""
+    detach: bool = False
+    timeout_seconds: int = 300
+    keep_alive: bool = False
+    cleanup: bool = True
+    env: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass
+class RunState:
+    """Estado persistido de una ejecución."""
+
+    run_id: str
+    template_id: str
+    engine: str
+    status: str
+    project_name: str
+    run_dir: str
+    service: str
+    command: str
+    exit_code: int | None = None
+    started_at: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    finished_at: str = ""
+    summary: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return self.__dict__.copy()
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "RunState":
+        return cls(**data)