Desarrollo

Página para quien va a tocar el código. El repositorio trae material de sobra para ello —docs/architecture.md, CONTRIBUTING.md y un AGENTS.md de 15 KB con las convenciones completas— y esto recoge lo que hace falta saber antes de empezar.

El entorno de desarrollo

pip install -e ".[dev]"
pytest
ruff check . && ruff format .
mypy
bandit -r src/jaigent -ll
pip-audit

Cómo está organizado el código

Son 45 módulos .py bajo src/jaigent/ y 55 ficheros de pruebas en tests/. Las pruebas más grandes dicen dónde está el riesgo: test_cli_interactive.py (62 KB), test_updater.py (55 KB) y test_regressions.py (37 KB).

Probarlo sin gastar tokens

examples/mock_llm_server.py (5,9 KB) es un servidor diminuto compatible con OpenAI pensado exactamente para eso. Ignora la inteligencia del modelo y reproduce un plan fijo: listar el espacio de trabajo, escribir un resumen y responder. Admite peticiones con y sin streaming, así que ejercita los mismos caminos de código que un proveedor real.

python examples/mock_llm_server.py            # escucha en :8000

Y en otra terminal:

JAIGENT_BASE_URL=http://localhost:8000/v1 \
JAIGENT_API_KEY=not-a-real-key \
jaigent "summarise notes.md into summary.md" --verbose

examples/basic_usage.py (4,8 KB) es la otra cara: cómo usar jAIgent desde Python, con una clave real de por medio.

Los workflows y las releases

Lo que hay alrededor de la integración continua:

En packaging/ están además los dos instaladores (install.sh e install.ps1), la receta de PyInstaller (jaigent.spec), un lanzador (launcher.py), el generador de iconos (make_icon.py) y las imágenes de las que derivan.

Por qué existe activate-ci.sh

GitHub rechaza cualquier push que cree o edite un fichero bajo .github/workflows/ si el token no lleva el ámbito workflows. La cuenta de automatización que escribe esos ficheros no lo tiene, así que no podía empujar sus propias correcciones. El script existe para ejecutarlo desde una máquina propia, con credenciales propias, que sí tienen ese ámbito. Es seguro ejecutarlo varias veces: solo hace commit cuando algo cambió de verdad.

Las tres reparaciones, y su estado actual

docs/workflow-repair-v0.5.1.md arranca diciendo que main trae workflows que fallan en todas las plataformas. Eso era cierto cuando se escribió; hoy las tres reparaciones están aplicadas en main. Merece la pena saber cuáles fueron, porque las tres son trampas del runner de Windows y no del código:

1. ci.yml, «Smoke test the CLI», fallaba en los dos runners de Windows. El paso decía doctor || true. El shell por defecto en Windows es pwsh, y el runner antepone $ErrorActionPreference = 'stop' a cada paso de pwsh. doctor sale con 1 si no hay clave de API, pwsh intentaba entonces ejecutar true —que en Windows no es un comando— y el paso abortaba. Solución aplicada: el paso va fijado a shell: bash, con un comentario que explica por qué.
2. release.yml, «Smoke test the binary (windows)», salía con 1 teniendo un jaigent.exe bueno. El runner añade al final if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE } a cada paso de pwsh, y el último comando nativo del paso era doctor, que sale con 1 por diseño. El paso publicaba ese 1 como propio y el binario se descartaba. Solución aplicada: $PSNativeCommandUseErrorActionPreference = $false al principio y exit 0 al final; los throw siguen fallando ante problemas reales.
3. release.yml, el job macos-x64 nunca salía de la cola. macos-13 se retiró el 4 de diciembre de 2025 y los jobs sobre imágenes retiradas se quedan en cola para siempre. Solución aplicada: macos-15-intel, el sucesor x86_64 designado por GitHub.

Dónde seguir

• Seguridad — el modelo de amenazas y las versiones con soporte.
• Referencia de tools — la API de Python y cómo añadir una herramienta propia.
• Skills, plugins y horarios — las cuatro formas de ampliarlo con ficheros locales.