Referencia de build.pl

builder/build.pl es el builder de site estático que Chinaski ejecuta después de cambios de contenido y settings. Lee el contenido de la base de datos, renderiza HTML a un directorio de staging, lo verifica y lo intercambia a live solo cuando el build es sano. No hay flags de línea de comandos: el builder se controla enteramente por variables de entorno, las settings que editas en el área de admin y los controles de build del dashboard.

Esta página cubre el ciclo de vida completo del build y los interruptores que puedes usar al ejecutar el builder a mano. (Invocación recomendada para corridas manuales: establece CHINASKI_DB y CHINASKI_OUTPUT primero, igual que como lo ejecuta el CMS.)

Barandillas

El builder se niega a correr como root: los archivos de salida no serían escribibles por el usuario de servicio chinaski. Corre como el usuario chinaski en su lugar (p. ej. sudo -u chinaski perl builder/build.pl).
El builder se niega a correr del todo si el archivo de base de datos no existe.

Dónde viven las cosas

Base de datos: CHINASKI_DB si está establecida; si no, chinaski.db en la raíz de la app.
Output: CHINASKI_OUTPUT si está establecida; si no, output en la raíz del repo.
Block templates: CHINASKI_BLOCK_TEMPLATES si está establecida; si no, builder/block_templates en el repo.
Un build completado conserva las últimas 100 filas del historial de builds (visible bajo Builds en el área de admin).

Builds completos vs incrementales

El build por defecto es incremental: reutiliza lo que ya está live.

Un build incremental solo se intenta cuando:

el modo incremental se pidió realmente,
hay registrado un build exitoso previo (y no marcado en el futuro),
el directorio de output live todavía existe y contiene un index.html,
el fingerprint de build almacenado no cambió (un desajuste de fingerprint significa un cambio global, como un cambio de theme; eso dispara un build completo),
y sembrar la copia de staging del árbol live tiene éxito; si la siembra falla, todo el build cae silenciosamente a completo.

Cualquier otra cosa causa un build completo, y la razón se registra en el historial de builds.

Para forzar un rebuild completo limpio: usa la casilla Full rebuild en el dashboard, establece CHINASKI_FORCE_FULL=1, o corre bin/force-full-build.pl, que limpia la cache de build y luego corre un build completo.

Prioridades y paralelismo

CHINASKI_JOBS establece cuántos workers en paralelo renderizan páginas. Debe ser un número simple; domina sobre la setting build_jobs en el área de admin, y ambas caen al conteo de tu CPU. El valor se sujeta al rango de 1 a 16. Un valor de 1 construye secuencialmente sin procesos extra.

El timeout

Cada build tiene un límite estricto de tiempo real de 30 minutos (1800 segundos). Cuando se alcanza el límite, los workers de render en curso se matan y el build muere con un mensaje de timeout; nada se promueve.

Cómo corre un build

Verificación de elegibilidad: incremental o completo se decide antes de que se escriba cualquier cosa, así que una verificación fallida nunca puede dañar el site live.
Render a staging: páginas, posts y todo lo demás se renderizan a <output>.next, un directorio de staging junto al output live. Los builds incrementales se saltan reescribir páginas sin cambios reutilizando archivos del build anterior.
Verificar calidad: el promotion guard compara este build contra el último promote sano (ver abajo). Los errores de render se recopilan conforme suceden.
Escribir el manifest firmado: una attestation firmada del output se produce solo después de que todas las verificaciones pasen, y solo si algún error no habría bloqueado ya el build. Si la firma falla, el build aborta y el manifest anterior se restaura, a menos que el manifest esté marcado como opcional.
Promote: el directorio de staging se intercambia a live. El intercambio es atómico (un solo rename), así que no hay ventana en la que el site esté a medio actualizar.

Cuando un build se niega a promover

El build nunca promueve sobre un resultado roto. Tres condiciones lo detienen:

Errores de render. Cualquier fallo de template o render bloquea la promoción. El output live queda intacto, el staging se descarta y los templates que fallan se reportan.
El promotion guard (modo enforce). El guard compara este build contra el último promote limpio: caída del conteo de páginas (umbral por defecto 80%), aumento de links rotos (por defecto 25) y aumento de problemas de accesibilidad (por defecto 10), más un límite absoluto opcional sobre blocks sin resolver. En modo enforce el promote se bloquea exactamente como un fallo de render. En modo warn (el predeterminado) el problema se loguea pero el build aún promueve. Los ajustes del guard viven bajo Settings → Workflow.
Fallo de manifest. Un build no puede promover sin un manifest firmado utilizable.

Anular un bloqueo del guard es posible para un build a la vez: el control Promote anyway en el dashboard, o CHINASKI_FORCE_PROMOTE=1. Forzar nunca actualiza los baselines de calidad; el próximo build ordinario aún compara contra el último promote limpio, así que un build malo forzado puede detectarse después.

Códigos de salida

El builder sale con 0 en una promoción que completó limpiamente con cero errores de render, y con 1 en cualquier otro caso: un bloqueo del guard, errores de render, un timeout, un fallo de manifest o un promote fallido. Las herramientas de deploy dependen de esto: una salida distinta de cero aborta un deploy estándar en lugar de reiniciar el servicio sobre output obsoleto.

Correr builds desde el área de admin

Normalmente no corres build.pl a mano:

Guardar settings que afectan el output, o cambiar el prefijo de URL de posts, despacha un build automáticamente.
El dashboard (vía Build) ofrece un build normal (incremental), un Full rebuild y Promote anyway, cada uno con su propio mensaje de confirmación.
Solo corre un build a la vez: iniciar un segundo es rechazado con "a build is already in progress". El lock también expira por sí solo si un build nunca reporta, así que no puede atascar los builds permanentemente.
Mientras corre un build, /admin/build/status reporta el progreso, y el historial de builds muestra los últimos 100 builds completados, incluidos los bloqueados y los que dieron error.
Si un correo de notificación de build está configurado bajo Settings → Email, se envía un mensaje cuando un build tiene éxito o falla (entregado por el relay SMTP, así que necesita SMTP configurado y se omite en modo air-gap).

Modo air-gap

Con CHINASKI_AIRGAP=1 establecida, el builder elimina todas las referencias externas de las páginas generadas: los analytics de GA4/GTM se quitan incluso si están configurados, y el código de snippets que referencia URLs externas se elimina. Las páginas construidas entonces no cargan nada de un CDN.

Referencia rápida de entorno

Variable	Efecto
`CHINASKI_DB`	Base de datos de la que leer (sobrescribe el default)
`CHINASKI_OUTPUT`	Dónde publicar
`CHINASKI_INCREMENTAL=1`	Pide incremental (puede caer aún a completo)
`CHINASKI_FORCE_FULL=1`	Fuerza un rebuild completo limpio
`CHINASKI_FORCE_PROMOTE=1`	Elude el promotion guard para este build
`CHINASKI_JOBS`	Conteo de workers en paralelo (1 a 16)
`CHINASKI_BLOCK_TEMPLATES`	Directorio de block templates
`CHINASKI_MANIFEST_OPTIONAL=1`	Degrada el fallo de manifest firmado a advertencia
`CHINASKI_AIRGAP`	Elimina analytics y referencias externas de snippets
`CHINASKI_TEST`	Válvula de escape en modo prueba (permite correr como root)

Ver la referencia de variables de entorno para antecedentes sobre las variables compartidas.