Skip to content
Apothem
Ejemplos

Crear un adaptador de entorno

Guía paso a paso para crear un nuevo adaptador de entorno de Apothem.

Esta guía recorre la creación de un adaptador de entorno de Apothem desde cero, usando el protocolo HarnessAdapter.

Requisitos previos

Paso 1: Crear el paquete del adaptador

mkdir apothem-myadapter
cd apothem-myadapter
# pyproject.toml
[project]
name = "apothem-myadapter"
version = "X.Y.Z"
requires-python = ">=3.10"

Paso 2: Implementar el adaptador

# src/apothem_myadapter/adapter.py
from pathlib import Path
from typing import Any

from apothem.harnesses import HarnessAdapter


class MyHarnessAdapter(HarnessAdapter):
    """Implements the HarnessAdapter protocol for "My Harness".

    First-party adapters in the apothem tree usually delegate to the
    ``make_user_scope_adapter`` / ``make_project_scope_adapter`` factories in
    ``apothem.harnesses._shared.wrapper_factories`` and declare their install
    rules in ``src/apothem/lib/propagation-manifest.yaml``. Implementing the
    protocol directly, as shown here, is the clearest way to read its surface.
    """

    @property
    def name(self) -> str:
        return "my-harness"

    @property
    def output_path(self) -> Path:
        # The single native config file this adapter owns on disk.
        return Path.home() / ".myharness" / "config.md"

    def install(self, profile: dict[str, Any]) -> object:
        # ``profile`` is the loaded shared-profile dict (rules, skills, hooks...).
        self.output_path.parent.mkdir(parents=True, exist_ok=True)
        self.output_path.write_text(self._render(profile), encoding="utf-8")
        return self.output_path

    def update(self, profile: dict[str, Any]) -> object:
        return self.install(profile)  # idempotent re-materialization

    def uninstall(self) -> None:
        self.output_path.unlink(missing_ok=True)

    def is_installed(self) -> bool:
        return self.output_path.is_file()

    def verify(self) -> bool:
        return self.output_path.is_file() and self.output_path.stat().st_size > 0

    def _render(self, profile: dict[str, Any]) -> str:
        # Translate the profile into the harness's native format.
        rules = profile.get("rules", [])
        return "\n\n".join(str(rule) for rule in rules)

Apothem no descubre adaptadores de terceros. Primero, añade el adaptador al registro estático de entornos en src/apothem/lib/harness_registry.py, dentro de un checkout de Apothem. Hasta entonces, apothem install --harness my-harness rechaza el identificador.

Paso 3: Instalar y probar

apothem install --harness my-harness
apothem verify --harness my-harness

Paso 4: Añadir a la documentación de pyproject.toml

Documenta el entorno en site/content/docs/harnesses/my-harness.mdx siguiendo la plantilla de página de entorno.

Paso 5: Enviar para inclusión

Abre una pull request en el repositorio de Apothem con:

  • El paquete del adaptador (o un enlace a él)
  • La página de documentación
  • Una prueba de verificación en tests/packaging/test_myadapter_install.py

On this page