Saltar a contenido

Requisitos para plugins first-party

Runtime

Requisito Detalle
Python 3.12+
Empaquetado hatchling / uv workspace; wheel publicable
Dependencia SPI cortex-core (evitar cortex-framework directo salvo excepción documentada)

Persistencia

Modo Cuándo
Alembic {plugin_id}_* Plugin con tablas propias
stateless: true en descriptor Sin tablas PG (válido solo sin dominio persistente)

Orden sugerido de migración en sandbox Reservas: clients → resources → booking → payments.

Tests

  • pytest en el repo del plugin; TDD obligatorio.
  • Aislamiento: create_test_app(enabled_plugins="mi-plugin") sin depender de otros dominios.
  • Ruff en CI del monorepo (scope plugins al publicar wheel).

Documentación obligatoria (docs/plugins/<id>/)

Fuente canónica en cortex-docs. Los repos plugin mantienen solo un docs/README.md de redirección al sitio.

Archivo Contenido
index.md Resumen y estado de implementación (ex README.md)
api.md Contrato REST
dependencies.md requires, provides, HTTP cross-plugin
events.md Events emitidos y escuchados (si aplica)
ui.md Módulos CUS y pantallas
operations.md Activación, migraciones, variables
design.md Decisiones de dominio (opcional; antes ADR en cortex-docs)

Validación en CI: ./scripts/validate-composition-docs.sh exige index.md y dependencies.md por plugin del grafo de referencia.

Checklist “plugin real” (ADR 023)

  1. Instalable sin monorepo (entry point cortex.plugins)
  2. Descriptor con requires / provides / stateless
  3. API bajo /api/v1/{namespace} con guard de plugin enabled
  4. Bootstrap UI solo si enabled
  5. Tests de aislamiento
  6. Alembic o stateless: true explícito