higpertext-cli 0.8.0__py3-none-any.whl

higpertext/adapters/open_code_adapter/open_code_adapter.py

@@ -0,0 +1,480 @@
+"""higpertext OpenCode Adapter — genera AGENTS.md y definición de agente para opencode.ai."""
+
+import json
+from pathlib import Path
+from higpertext.kernel.config_paths import WORKSPACE_DIR_NAME
+from higpertext.adapters.adapter_utils import (
+    HTX_CMD,
+    HTX_WORKFLOW_CMD,
+    load_session,
+    guidelines_lines,
+    session_lines,
+    capabilities_section,
+    workflows_section,
+    delegation_rule_lines,
+    workflow_trigger_lines,
+    hooks_section,
+    loop_guard_lines,
+    reasoning_style_lines,
+    project_refs_lines,
+)
+from higpertext.kernel.app_config import ADAPTERS_CONFIG
+_CFG = ADAPTERS_CONFIG["opencode"]
+
+
+class OpenCodeAdapter:
+    """Genera archivos de configuración para OpenCode (opencode.ai).
+
+    OpenCode lee varias fuentes de instrucciones y configuración:
+    - opencode.json — configuración global del proyecto.
+    - AGENTS.md en la raíz del proyecto — instrucciones del workspace (auto-inyectadas).
+    - .opencode/agents/{workflow}.md — definición del agente por workflow (con frontmatter YAML).
+    - .opencode/rules/{name}.md — reglas derivadas del perfil.
+    """
+
+    @staticmethod
+    def generate_rules(context: dict, target_dir: Path) -> Path:
+        profile = context["profile"]
+        agent_name = profile["name"]
+        capabilities = context["active_capabilities"]
+        workflows = context.get("active_workflows", [])
+
+        # ── 1. AGENTS.md en la raíz del proyecto (índice liviano) ────────────
+        agents_file = target_dir / "AGENTS.md"
+        agents_file.write_text(OpenCodeAdapter._agents_md_index(profile), encoding="utf-8")
+
+        # ── 2. .opencode/rules/{name}.md (perfil como regla) ─────────────────
+        opencode_rules_dir = target_dir / ".opencode" / "rules"
+        opencode_rules_dir.mkdir(parents=True, exist_ok=True)
+        rule_md = OpenCodeAdapter._build_rule_md(profile, capabilities, workflows, target_dir)
+        rule_file = opencode_rules_dir / f"{agent_name}.md"
+        rule_file.write_text(rule_md, encoding="utf-8")
+
+        # ── 3. .opencode/agents/{workflow}.md (workflows como agentes) ────────
+        opencode_agents_dir = target_dir / ".opencode" / "agents"
+        if opencode_agents_dir.exists():
+            for f in opencode_agents_dir.glob("*.md"):
+                try:
+                    f.unlink()
+                except OSError:  # nosec B110
+                    pass
+        opencode_agents_dir.mkdir(parents=True, exist_ok=True)
+        playbooks = ("spec", "plan", "build", "review", "testworkflow")
+        # Alias: workflows whose id suffix maps to a different output filename
+        _alias = {
+            "higpertext-plan": "plan",
+            "higpertext-build": "build",
+            "higpertext-review": "review",
+        }
+        for wf in workflows:
+            wf_name = wf["id"].split(".")[-1]
+            out_name = _alias.get(wf_name, wf_name)
+            if out_name not in playbooks:
+                continue
+            wf_agent_md = OpenCodeAdapter._build_workflow_agent_md(wf, profile)
+            (opencode_agents_dir / f"{out_name}.md").write_text(wf_agent_md, encoding="utf-8")
+
+        # ── 4. opencode.json ──────────────────────────────────────────────────
+        opencode_json = OpenCodeAdapter._build_opencode_json(profile)
+        (target_dir / "opencode.json").write_text(opencode_json, encoding="utf-8")
+
+        # ── 5. Reglas adicionales de contexto controlado ──────────────────────
+        (opencode_rules_dir / "htx-workflow.md").write_text(
+            OpenCodeAdapter._build_htx_workflow_rules_md(), encoding="utf-8"
+        )
+        (opencode_rules_dir / "repository-boundaries.md").write_text(
+            OpenCodeAdapter._build_boundary_rules_md(), encoding="utf-8"
+        )
+
+        # ── 6. Eliminar guía obsoleta ─────────────────────────────────────────
+        guide_file = target_dir / ".opencode" / "OPENCODE.md"
+        if guide_file.exists():
+            guide_file.unlink()
+
+        return rule_file
+
+    # ── Builders ──────────────────────────────────────────────────────────────
+
+    @staticmethod
+    def _agents_md_index(profile: dict) -> str:
+        """Genera AGENTS.md liviano — índice que apunta a .opencode/rules/ como fuente de verdad.
+
+        OpenCode carga AGENTS.md + .opencode/rules/*.md en el mismo contexto; duplicar el
+        contenido completo en ambos infla el contexto ~38KB por sesión sin aportar información
+        nueva.
+        """
+        agent_name = profile["name"]
+        return "\n".join(
+            [
+                line.format(
+                    agent_name=agent_name,
+                    agent_name_upper=agent_name.upper(),
+                    description=profile["description"],
+                    htx_cmd=HTX_CMD,
+                    htx_workflow_cmd=HTX_WORKFLOW_CMD,
+                )
+                for line in _CFG["agents_md_index"]
+            ]
+        )
+
+    @staticmethod
+    def _build_agents_md(
+        profile: dict, capabilities: list, workflows: list, target_dir: Path
+    ) -> str:
+        """Genera AGENTS.md — instrucciones del workspace que OpenCode inyecta automáticamente."""
+        governance = [_CFG["agents_md_governance_header"]]
+        for rule in _CFG["agents_md_governance_lines"]:
+            governance.append(rule)
+        if profile.get("governance_access"):
+            governance.append(_CFG["agents_md_governance_enabled"])
+
+        lines = [
+            line.format(
+                agent_name=profile["name"],
+                agent_name_upper=profile["name"].upper(),
+                description=profile["description"],
+                system_prompt=profile["system_prompt"],
+            )
+            for line in _CFG["agents_md_header"]
+        ]
+        lines += governance + ["", "---", ""]
+
+        guide_lines = guidelines_lines(Path(__file__))
+        if guide_lines:
+            lines += ["## Lineamientos activos de gobernanza", ""]
+            lines += [
+                "Estas reglas son de cumplimiento obligatorio en todo el desarrollo:",
+                "",
+            ]
+            lines += guide_lines
+            lines += ["---", ""]
+
+        lines += loop_guard_lines()
+        lines += reasoning_style_lines()
+        
+        exec_lines = [
+            line.format(htx_cmd=HTX_CMD)
+            for line in _CFG["execution_protocol_lines"]
+        ]
+        lines += exec_lines
+        lines += delegation_rule_lines()
+        lines += workflow_trigger_lines(workflows)
+        
+        token_rules = [
+            line.format(
+                htx_cmd=HTX_CMD,
+                htx_workflow_cmd=HTX_WORKFLOW_CMD,
+            )
+            for line in _CFG["token_rules_lines"]
+        ]
+        lines += token_rules
+        
+        session = load_session(target_dir)
+        lines += session_lines(session, target_dir, ".opencode/skills")
+        lines += capabilities_section(capabilities)
+        lines += workflows_section(workflows)
+        lines.append(
+            "*higpertext Engine v5.0 — auto-generated workspace instructions."
+            " Do not edit manually.*"
+        )
+        return "\n".join(lines)
+
+    @staticmethod
+    def _build_rule_md(profile: dict, capabilities: list, workflows: list, target_dir: Path) -> str:
+        """Genera .opencode/rules/{name}.md — reglas derivadas del perfil."""
+        agent_name = profile["name"]
+        higpertext_cmd = "htx"
+
+        lines = [
+            line.format(
+                agent_name_upper=agent_name.upper(),
+                description=profile["description"],
+                system_prompt=profile["system_prompt"],
+            )
+            for line in _CFG["profile_rules_header"]
+        ]
+        if profile.get("governance_access"):
+            lines.append(_CFG["profile_rules_governance_access"])
+
+        lines += ["", "---", ""]
+        lines += loop_guard_lines()
+        lines += reasoning_style_lines()
+        lines += project_refs_lines(
+            target_dir,
+            _CFG["project_refs_header"],
+        )
+        lines += delegation_rule_lines()
+        lines += workflow_trigger_lines(workflows)
+        
+        lines += list(_CFG["token_rules_summary"])
+        
+        session = load_session(target_dir)
+        lines += session_lines(session, target_dir, ".opencode/skills")
+        lines += hooks_section(target_dir, "opencode", agent_name)
+
+        lines += ["## Capacidades asignadas", ""]
+        for cap in capabilities:
+            short_id = cap["id"].split(".")[-1]
+            lines.append(f"- **`{cap['id']}`**: {cap['description']}")
+            lines.append(f"  - Comando: `{higpertext_cmd} task {short_id} [--params]`")
+
+        if workflows:
+            lines += ["", "## Workflows asignados (Playbooks)", ""]
+            for wf in workflows:
+                short_id = wf["id"].split(".")[-1]
+                lines.append(f"- **`{wf['id']}` ({wf['name']})**: {wf['description']}")
+                lines.append(f"  - Comando: `{higpertext_cmd} workflow run {short_id} [--params]`")
+
+        lines += [
+            "",
+            "",
+            "> Los contratos técnicos completos y parámetros de cada capacidad y workflow"
+            " están en `AGENTS.md`.",
+            "",
+            "*higpertext Engine v5.0 — auto-generated rule. Do not edit manually.*",
+        ]
+        return "\n".join(lines)
+
+    @staticmethod
+    def _build_workflow_agent_md(wf: dict, profile: dict) -> str:
+        """Genera .opencode/agents/{workflow}.md — definición del agente para un workflow."""
+        wf_id = wf["id"]
+        wf_name = wf_id.split(".")[-1]
+
+        lines = [
+            line.format(
+                wf_name=wf_name,
+                wf_name_upper=wf_name.upper(),
+                description=wf["description"],
+                name=wf["name"],
+                wf_id=wf_id,
+                htx_workflow_cmd=HTX_WORKFLOW_CMD,
+            )
+            for line in _CFG["workflow_agent_header"]
+        ]
+
+        if profile.get("model"):
+            lines.insert(4, f"model: {profile['model']}")
+
+        if wf.get("execution_chain"):
+            lines += ["## Cadena de Ejecución", ""]
+            for step in wf["execution_chain"]:
+                lines.append(f"- `Paso {step['step']}`: Ejecuta capacidad `{step['task']}`")
+            lines.append("")
+
+        if wf_name in {"plan", "higpertext-plan"}:
+            lines += [
+                "## Semantic Graph Check",
+                "",
+                "- Antes de proponer arquitectura, roadmap o cambios cross-file,"
+                " consulta el grafo semántico.",
+                "- Usa `htx task common.graph-query --symbol <keyword> --depth 2`"
+                " para símbolos relevantes.",
+                "- Si `.higpertext/state/semantic_graph.json` no existe, solicita o"
+                " ejecuta `htx task common.graph-rebuild` primero.",
+                "- Declara en el plan qué símbolos/módulos del grafo delimitan el impacto.",
+                "",
+            ]
+
+        if wf.get("parameters"):
+            lines += ["## Parámetros", ""]
+            for p in wf["parameters"]:
+                req = "REQUERIDO" if p.get("required") else "opcional"
+                default_str = f" — default: `{p['default']}`" if "default" in p else ""
+                lines.append(f"- `--{p['name']}` ({req}): {p['description']}{default_str}")
+            lines.append("")
+
+        lines += [
+            "---",
+            "",
+            "*higpertext Engine v5.0 — auto-generated workflow agent. Do not edit manually.*",
+        ]
+        return "\n".join(lines)
+
+    @staticmethod
+    def _build_opencode_json(profile: dict) -> str:
+        """Genera el archivo opencode.json con la configuración del proyecto."""
+        config = {
+            "$schema": "https://opencode.ai/config.json",
+            "instructions": ["AGENTS.md", ".opencode/rules/*.md"],
+            "command": {
+                "spec": {
+                    "description": "Define technical specifications using HTX.",
+                    "template": "Usa el flujo HTX de especificación. Llama a higpertext_workflow"
+                    " con name='spec'. No hagas exploración manual masiva; identifica primero"
+                    " los archivos mínimos necesarios.",
+                },
+                "plan": {
+                    "description": "Design architecture and execution plans using HTX.",
+                    "template": "Usa el flujo HTX de planeación. Llama a higpertext_workflow"
+                    " con name='plan'. No modifiques código; entrega plan, riesgos y archivos"
+                    " probables.",
+                },
+                "build": {
+                    "description": "Implement code using HTX.",
+                    "template": "Usa el flujo HTX de implementación."
+                    " Llama a higpertext_workflow con name='build'."
+                    " Haz cambios mínimos y muestra diff/resumen al final.",
+                },
+                "review": {
+                    "description": "Review quality and compliance using HTX.",
+                    "template": "Usa el flujo HTX de revisión."
+                    " Llama a higpertext_workflow con name='review'."
+                    " No modifiques código salvo autorización explícita.",
+                },
+            },
+            "skills": {"paths": [".opencode/skills"]},
+            "plugin": ["./.opencode/plugin/higpertext-hooks.js"],
+            "permission": {
+                "bash": {"./.venv/bin/htx *": "allow", "*": "ask"},
+                "read": {
+                    "./.opencode/**": "allow",
+                    "./{WORKSPACE_DIR_NAME}/**": "allow",
+                    "./AGENTS.md": "allow",
+                    "./opencode.json": "allow",
+                    "./src/**": "ask",
+                    "*": "deny",
+                },
+                "edit": "ask",
+                "glob": "deny",
+                "grep": "deny",
+                "task": "deny",
+                "external_directory": "ask",
+                "webfetch": "deny",
+                "websearch": "deny",
+                "question": "allow",
+                "todowrite": "allow",
+                "higpertext_task": "allow",
+                "higpertext_workflow": "allow",
+            },
+            "logLevel": "ERROR",
+            "tool_output": {"max_lines": 120, "max_bytes": 8000},
+            "compaction": {"auto": True, "tail_turns": 8},
+        }
+        if profile.get("model"):
+            config["model"] = profile["model"]
+        return json.dumps(config, indent=2)
+
+    @staticmethod
+    def _build_htx_workflow_rules_md() -> str:
+        return "\n".join(
+            [
+                "# HTX Workflow Rules",
+                "",
+                "Para tareas de especificación, planeación, implementación y revisión,"
+                " usa el flujo HTX como fuente principal de decisión.",
+                "",
+                "## Comandos principales",
+                "",
+                "- Spec: `higpertext_workflow` con `name='spec'`",
+                "- Plan: `higpertext_workflow` con `name='plan'`",
+                "- Build: `higpertext_workflow` con `name='build'`",
+                "- Review: `higpertext_workflow` con `name='review'`",
+                "",
+                "## Reglas",
+                "",
+                "1. No reemplaces el flujo HTX con exploración manual del repositorio.",
+                "2. Antes de leer muchos archivos, explica qué necesitas revisar.",
+                "3. En este workspace, invoca HTX con `./.venv/bin/htx`; no uses `htx` sin ruta.",
+                "4. Para búsqueda, diff, tests, calidad, memoria o tareas con capacidad asignada,"
+                " usa `./.venv/bin/htx task <capability>`.",
+                "5. No uses `ls`, `grep`, `glob`, `find`, `rg`, `git diff/status`"
+                " ni búsquedas nativas si existe capacidad HTX equivalente.",
+                "6. Si una capacidad HTX falla por PATH o entorno, no hagas fallback"
+                " a herramientas generales; corrige el launcher o pregunta.",
+                "7. Usa `read` solo para archivos explícitos y directamente relacionados;"
+                " no lo uses como mecanismo de búsqueda.",
+                "8. No uses subagentes salvo autorización explícita.",
+                "9. No ejecutes comandos bash largos sin aprobación.",
+                "10. No uses búsquedas web salvo que el usuario lo pida.",
+                "11. Antes de modificar código, presenta un plan breve.",
+                "12. Después de modificar código, muestra resumen de cambios.",
+                "",
+                "*higpertext Engine v5.0 — auto-generated. Do not edit manually.*",
+            ]
+        )
+
+    @staticmethod
+    def _build_boundary_rules_md() -> str:
+        excluded = [
+            "node_modules/",
+            "dist/",
+            "build/",
+            "coverage/",
+            ".next/",
+            ".nuxt/",
+            ".turbo/",
+            ".cache/",
+            "logs/",
+            "tmp/",
+            ".git/",
+            "vendor/",
+            "target/",
+            "__pycache__/",
+            ".venv/",
+            "venv/",
+        ]
+        preferred = [
+            "package.json",
+            "pyproject.toml",
+            "README.md",
+            "AGENTS.md",
+            "opencode.json",
+            ".opencode/rules/*.md",
+            ".opencode/plugin/*.js",
+            "archivos de configuración relacionados con la tarea",
+        ]
+        excl_lines = "\n".join(f"- `{d}`" for d in excluded)
+        pref_lines = "\n".join(f"- `{f}`" for f in preferred)
+        return "\n".join(
+            [
+                "# Repository Boundaries",
+                "",
+                "No leer ni indexar de forma masiva los siguientes directorios:",
+                "",
+                excl_lines,
+                "",
+                "## Archivos preferidos para contexto inicial",
+                "",
+                pref_lines,
+                "",
+                "Si necesitas explorar más, pide autorización y explica por qué.",
+                "",
+                "*higpertext Engine v5.0 — auto-generated. Do not edit manually.*",
+            ]
+        )
+
+    @staticmethod
+    def on_init(context: dict, target_dir: Path) -> None:
+        """Gancho de inicialización de proyecto para OpenCode."""
+        profile = context["profile"]
+        opencode_json = OpenCodeAdapter._build_opencode_json(profile)
+        (target_dir / "opencode.json").write_text(opencode_json, encoding="utf-8")
+
+    @staticmethod
+    def on_session_start(context: dict, target_dir: Path) -> None:
+        """Gancho de inicio de sesión para OpenCode."""
+        OpenCodeAdapter.generate_rules(context, target_dir)
+
+    @staticmethod
+    def on_session_clean(target_dir: Path) -> None:
+        """Gancho de limpieza de sesión para OpenCode."""
+        rules_dir = target_dir / ".opencode" / "rules"
+        if rules_dir.exists():
+            try:
+                import shutil
+
+                shutil.rmtree(rules_dir)
+            except OSError:  # nosec B110
+                pass
+
+        agents_dir = target_dir / ".opencode" / "agents"
+        if agents_dir.exists():
+            # Standard playbooks to preserve
+            playbooks = ("spec", "plan", "build", "review")
+            for f in agents_dir.glob("*.md"):
+                if f.stem not in playbooks:
+                    try:
+                        f.unlink()
+                    except OSError:  # nosec B110
+                        pass