Saltar a contenido

Repositorios de plugins

Cada plugin Python first-party vive en un repositorio Git privado de la org cortex-ia-com-co y se enlaza en el monorepo cortex-hive como submódulo bajo plugins/<id>/.

La documentación del sitio MkDocs vive en el repositorio cortex-docs, enlazado como submódulo en docs/.

El workspace uv del monorepo sigue resolviendo dependencias entre core, framework y plugins como antes; solo cambia el control de versiones del código de cada dominio.

Documentación por capa

Repositorio Documentación
cortex-docs (docs/) Plataforma: framework, guías transversales, ADRs
cortex-plugin-{id} (plugins/{id}/docs/) Dominio del plugin: API, eventos, dependencias, CUS

El framework no conoce los plugins en código ni documenta su negocio en cortex-docs. Cada plugin documenta su ámbito y puede referenciar el framework y los plugins de su grafo de dependencias. Detalle: Documentación framework vs plugins.

Cuándo leer esta página

  • Clonas cortex-hive y plugins/ aparece vacío o incompleto.
  • Vas a desarrollar o publicar un plugin en su repo propio.
  • Necesitas entender la relación entre GitHub, Cloudsmith y el monorepo.

Mapa de repositorios

Directorio Repositorio GitHub Paquete pip
docs/ cortex-docs — (contenido MkDocs)
plugins/helloworld cortex-plugin-helloworld cortex-plugin-helloworld
plugins/panel cortex-plugin-panel cortex-plugin-panel
plugins/trainer cortex-plugin-trainer cortex-plugin-trainer
plugins/accounting cortex-plugin-accounting cortex-plugin-accounting
plugins/control cortex-plugin-control cortex-plugin-control
plugins/booking cortex-plugin-booking cortex-plugin-booking
plugins/resources cortex-plugin-resources cortex-plugin-resources
plugins/clients cortex-plugin-clients cortex-plugin-clients
plugins/pricing cortex-plugin-pricing cortex-plugin-pricing
plugins/payments cortex-plugin-payments cortex-plugin-payments
plugins/discounts cortex-plugin-discounts cortex-plugin-discounts
plugins/events cortex-plugin-events cortex-plugin-events
plugins/subscriptions cortex-plugin-subscriptions cortex-plugin-subscriptions
plugins/sales cortex-plugin-sales cortex-plugin-sales
plugins/store cortex-plugin-store cortex-plugin-store
plugins/billing cortex-plugin-billing cortex-plugin-billing
plugins/admin cortex-plugin-admin cortex-plugin-admin
plugins/ai-agents cortex-plugin-ai-agents cortex-plugin-ai-agents
plugins/_template cortex-plugin-template cortex-plugin-template

Convención: repo cortex-plugin-{id} → carpeta plugins/{id}/ → paquete Python cortex-plugin-{id}.

Clonar el monorepo

git clone --recurse-submodules git@github.com:cortex-ia-com-co/cortex-hive.git
cd cortex-hive
uv sync --all-packages

Si ya clonaste sin submódulos:

git submodule update --init --recursive

Comprueba que cada plugin tiene código:

git submodule status
ls plugins/booking/pyproject.toml

Flujo de desarrollo diario

Cambios en la documentación

  1. Entra al submódulo: cd docs
  2. Crea rama, commitea y pushea a cortex-docs.
  3. En la raíz de cortex-hive, actualiza el puntero:
cd /ruta/a/cortex-hive
git add docs
git commit -m "chore(docs): bump cortex-docs submodule"

Para publicar el sitio, ver Publicar la documentación (build, Cloudflare Pages y CI).

Cambios en un plugin existente

  1. Entra al submódulo: cd plugins/booking
  2. Crea rama, commitea y pushea al repo del plugin: git push origin main (o PR en cortex-plugin-booking).
  3. En la raíz de cortex-hive, actualiza el puntero del submódulo:
cd /ruta/a/cortex-hive
git add plugins/booking
git commit -m "chore(plugins): bump booking submodule"

Nuevo plugin de dominio

  1. Copia plugins/_template o crea repo desde cortex-plugin-template.
  2. Añade el submódulo en cortex-hive:
git submodule add git@github.com:cortex-ia-com-co/cortex-plugin-mi-modulo.git plugins/mi-modulo
  1. Registra el miembro en [tool.uv.workspace] del pyproject.toml raíz, en [tool.uv.sources], en extras pip si aplica, y en testpaths de pytest.
  2. Si el plugin pertenece al producto UnoSportClub: actualiza REFERENCE_GRAPH / BUNDLE_PROFILES en products/unosportclub/ según checklist CI/TDD.

Trabajar solo en el repo del plugin

Puedes clonar cortex-plugin-booking aislado para CI del plugin, pero para integrar con el framework necesitas cortex-core y cortex-framework (vía workspace en cortex-hive o wheels de Cloudsmith en pyproject.toml):

[tool.uv.sources]
cortex-core = { index = "cloudsmith" }
cortex-framework = { index = "cloudsmith" }

En el monorepo, workspace = true sigue siendo el camino habitual.

Publicación

Artefacto Dónde Script / notas
Wheel del plugin Cloudsmith (cortex-u044/cortex-hive) scripts/publish-cloudsmith.sh desde cortex-hive, o uv build en el repo del plugin
Código fuente GitHub privado Push al repo cortex-plugin-*
Integración monorepo Puntero submódulo en cortex-hive Commit que actualiza plugins/{id}

Ver Instalación pip para consumo sin clonar todo el monorepo.

CI

Los workflows de GitHub Actions deben clonar con submódulos:

- uses: actions/checkout@v7
  with:
    submodules: recursive

Sin esto, uv sync --all-packages y pytest fallan porque plugins/* estarían vacíos.

Extracción inicial (mantenimiento)

  • scripts/migrate-plugins-to-submodules.sh — plugins históricos → repos cortex-plugin-*.
  • scripts/migrate-docs-to-submodule.sh — contenido docs/ → repo cortex-docs (una sola vez).

No hace falta ejecutarlos en clones normales.

Referencias