Saltar a contenido

Checklist CI/TDD por plugin (Fase 0)

Referencia: ADR 023, plantilla pip plugins/_template/ y builtin core/cortex_core/template/.

Antes de escribir código de producción

  1. Crear tests/test_{plugin_id}_api.py con casos de éxito y error.
  2. Verificar que la prueba falla por la razón correcta (RED).
  3. Implementar el mínimo para pasar (GREEN).
  4. Refactorizar manteniendo pruebas en verde.

Checklist de plugin productivo

  • [ ] pyproject.toml con entry point cortex.plugins
  • [ ] PluginDescriptor con requires, optional_requires, provides, stateless
  • [ ] Si el plugin forma parte de un producto ensamblado: actualizar REFERENCE_GRAPH en el paquete de producto (cortex-product-unosportclub) y dependency-contracts
  • [ ] create_plugin() factory
  • [ ] api_router() bajo /api/v1/{namespace}
  • [ ] register_resources() (preferido) o register_dashboards()
  • [ ] register_widget_types() si aporta widgets de dominio
  • [ ] mcp_tools.py con convención ADR 006
  • [ ] Alembic + prefijo {plugin_id}_* o stateless: true
  • [ ] Producción: plugins con tablas Alembic deben tener stateless: false y store PG; prohibido depender de _STORE global como única fuente en CORTEX_PLUGIN_STORAGE=postgres
  • [ ] Repositorio/store (memory para tests, postgres para prod)
  • [ ] Fixtures solo como seeders de test, no store runtime
  • [ ] ui/manifest.json sincronizado con resources.py
  • [ ] Tests API: namespace, panel module, CRUD crítico
  • [ ] Sin imports cruzados entre plugins (solo HTTP) — validado por test_no_cross_plugin_imports

CI local

uv run pytest plugins/{id}/tests -v
uv run ruff check plugins/{id}
./scripts/validate-plugin-manifests.sh

CI repositorio

  • python-ci.yml: checkout con submódulos (submodules: recursive), pytest global + ruff + validate manifests + pip smoke
  • python-ci.yml job test-postgres: pytest con CORTEX_PLUGIN_STORAGE=postgres y PostgreSQL 16
  • Manifests validados con validate_manifest / validate_dashboard

Submódulos privados en GitHub Actions

Si los repos cortex-docs y cortex-plugin-* son privados, el checkout debe usar un PAT con acceso a la org:

- uses: actions/checkout@v7
  with:
    submodules: recursive
    token: ${{ secrets.GH_SUBMODULES_PAT }}

Secret GH_SUBMODULES_PAT en el repositorio cortex-hive. Sin esto, CI falla con Repository not found al clonar submódulos.

Desarrollo en repo aislado del plugin: ejecuta uv run pytest dentro de plugins/{id} tras uv sync en la raíz del monorepo, o configura dependencias vía wheels Cloudsmith (ver repositorios).