byox DocumentaciónAbrir la app

Empezar

Cómo funciona

byox no tiene un motor de cursos propio. Usa piezas que ya existen (Git, issues, Actions y Docker) y las coordina con un pequeño servicio. Esta página explica cómo encajan.

Dos tipos de repositorio

Cada curso existe dos veces.

El repositorio fuente vive en la organización cursos y es privado. Lo escribe un asistente a través del MCP, o una persona a mano. Contiene la portada, un archivo course.yaml con las etapas, el cuerpo de cada etapa, el esqueleto que recibirá el alumno y una solución de referencia que el alumno no ve.

El repositorio del alumno se llama <tu usuario>/<curso> y también es privado. Se crea cuando empiezas el curso: byox copia el esqueleto, crea un issue por etapa, enlaza las dependencias entre ellos y agrega los workflows de CI. A partir de ahí es tuyo; el código que escribes ahí no se toca nunca.

Fuente Alumno
Dónde cursos/<curso> <tu usuario>/<curso>
Quién lo crea El asistente (write_course_files) byox, al empezar el curso
Contiene Etapas, tests, esqueleto, solución Esqueleto, tus cambios, issues y workflows
Quién lo ve Administradores y autores Solo tú (y el bot que corre el CI)

Etapas y grafo

Cada etapa es un issue de Forgejo con un test asociado. Las etapas se agrupan en tramos (milestones) y declaran de qué otras etapas dependen. Una etapa está siempre en uno de tres estados:

Estado Significado
Completada Su issue está cerrado.
Disponible Todas sus dependencias están cerradas; puedes trabajar en ella.
Bloqueada Falta cerrar alguna dependencia.

Una etapa con dos dependencias, por ejemplo, queda bloqueada hasta que se cierren las dos. El mapa de etapas de cada curso muestra el grafo completo.

El ciclo de CI

En cada git push a main del repositorio del alumno, Forgejo Actions ejecuta tres jobs:

1 · push2 · plan3 · test4 · advance5 · resultado Tu códigogit push a main planissues abiertos testimagen del curso advancecierra y desbloquea Tu progresoweb, CLI, asistente las etapas desbloqueadas quedan listas para el siguiente push
  1. plan lista los issues abiertos del repositorio.
  2. test corre el test de cada uno dentro de la imagen de Docker del curso. Es el único paso que ejecuta tu código.
  3. advance cierra los issues cuyo test pasó y cuyas dependencias están cerradas, en cascada. Luego mueve las etiquetas bloqueado y disponible y avisa a byox para que actualice tu progreso.

El runner no distingue entre «el test falló» y «la etapa todavía no está empezada»: ambos casos dejan el issue abierto. byox los separa al leer la salida. Si el test llega al todo!() del esqueleto (o a un NotImplementedError en Python), la etapa figura como sin empezar y no como fallo.

Para cada etapa que falla, byox guarda el final de la salida del test, deduce el archivo y la línea del error y los muestra en la web, en el CLI y al asistente. Por eso no hace falta abrir el log del CI.

Probar en local

Los mismos tests corren en tu máquina, en la misma imagen que el CI:

sh .course/run.sh 7        # Linux, macOS, Git Bash: la etapa 7
sh .course/run.sh          # todas
.course\test 7             # Windows: corre en Docker
byox test 7                # con el CLI

Pistas

Cada etapa puede traer pistas ordenadas de lo conceptual a lo concreto. Se piden de una en una:

  • comentando /pista en el issue de la etapa;
  • con el botón «Pedir la pista» de la etapa, en la web;
  • con byox hint;
  • o dejando que el asistente la pida con get_hint.

Un workflow publica la siguiente pista como comentario. Las pistas no están en tu repositorio: viajan como un secreto de Actions (BYOX_HINTS), así que no se pueden leer de antemano.

Verificar un curso

Antes de que alguien pueda empezar un curso, byox comprueba que se puede completar. verify_course corre los tests de cada etapa dos veces, en la imagen del curso:

  1. Solo con el esqueleto (files/): todos los tests tienen que fallar.
  2. Con el esqueleto y la solución (files/ más solution/): todos tienen que pasar.

El resultado queda como estado del commit. start_course se niega a publicar un commit que no esté verificado, y si el curso cambia, hay que volver a verificarlo.

Arquitectura

Una instancia son tres servicios de Docker Compose. Todo lo demás son clientes.

Clientes Navegador/app AsistenteMCP con token CLI byoxAPI con token Tu instancia · docker compose byox · :3333web, API y servidor MCP Forgejo · :3000repos, issues y Actions Runnerejecuta los tests en Docker API admin jobs de Actions resultados
Servicio Puerto Qué hace
forgejo 3000 (web), 2222 (SSH) Guarda los repositorios, los issues y las cuentas. Ejecuta Actions.
runner — Toma los jobs de Forgejo y los corre en contenedores con el Docker del host.
mcp 3333 La app web, la API HTTP, el servidor MCP y la lógica de byox (empezar cursos, verificar, perfil, racha).

Los clientes nunca hablan con Forgejo a través de byox para hacer git push: eso va directo a Forgejo, con tu usuario y contraseña de Forgejo (o un token de acceso).

Dónde vive cada dato

Dato Dónde
Cuentas y contraseñas Forgejo (base de datos SQLite en el volumen forgejo-data)
Repositorios fuente y de alumnos Forgejo
Progreso Los issues cerrados de cada repositorio de alumno
Sesiones, tokens y resultados de tests Volumen mcp-data (archivos JSON; los tokens solo como huella)
Credenciales de la instancia Archivo .env junto a docker-compose.yml

Por defecto byox no usa una base de datos propia. Si borras el volumen mcp-data pierdes las sesiones, los tokens y los últimos resultados de tests; el progreso y el código siguen en Forgejo.

Para un servidor, docker-compose.cloud.yml guarda el estado de Forgejo y de byox en Postgres en vez de SQLite y archivos JSON (byox pasa a usar Postgres cuando tiene la variable DATABASE_URL). Las instrucciones están al principio de docker-compose.cloud.yml.