Configuración como datos

Cuando una actualización de Arch, un martes por la mañana, requiere una nueva solución alternativa para una iGPU de Intel concreta, ¿qué hace un instalador tradicional? Nada, hasta que alguien parchea el script de bash que lo controla, publica una ISO nueva (1-3 GB) y espera a que los usuarios la descarguen. Días en el mejor de los casos; semanas, lo más habitual.

Ditana adopta un enfoque fundamentalmente distinto: configuración como datos.

Tres piezas separadas

La arquitectura de Ditana se divide en tres repositorios:

1. El motor (ditana-installer): un programa pequeño y genérico que sabe cómo dibujar diálogos, particionar discos, detectar hardware y ejecutar pacstrap.

2. La base de conocimiento (ditana-config): una base de datos estructurada escrita en KDL v2. Declara cada opción, cada peculiaridad del hardware, cada dependencia de paquetes, cada script del ciclo de vida y las relaciones lógicas entre ellos.

3. La canalización de paquetes (ditana-build): lo que compila los paquetes que nombra la base de conocimiento. El repositorio de Ditana se apoya en el de Arch, y esa canalización recompila desde las fuentes, revisa y firma las recetas de ese repositorio, en lugar de tomarlas tal como vienen.

Cuando usted arranca la ISO de Ditana, el motor se conecta a GitHub y descarga la versión más reciente de la base de conocimiento (y, si no tiene conexión a internet, recurre como reserva a una copia sin conexión incluida en la ISO).

También conviene saber lo que la descarga en tiempo de ejecución no cubre. El propio motor y el convertidor con el que lee KDL están en el medio y solo cambian con uno nuevo. Y el canal transporta un error con la misma facilidad que una corrección: una configuración que nombra un paquete que el repositorio de un medio anterior no puede proporcionar hace que ese medio ya no pueda instalar, que es exactamente lo que ocurrió cuando Arch retiró bubblewrap-suid en septiembre de 2026.

Por qué es importante

Tres ventajas, por orden de impacto inmediato:

• Actualizaciones sin generar una ISO nueva. Si alguien informa de que una actualización reciente de Arch requiere una nueva solución alternativa, la corrección llega a ditana-config como una pequeña edición en KDL. La siguiente persona que arranque una ISO de Ditana descarga automáticamente la lógica actualizada. La corrección llega a los usuarios de inmediato, sin que nadie tenga que descargar una ISO nueva.
• Razonamiento transparente. Como las opciones se declaran como datos estructurados con condiciones explícitas, las reglas se pueden auditar de principio a fin. Cualquiera puede leer los archivos KDL y ver exactamente por qué se instala un paquete, qué combinación de opciones hace que se implemente un archivo de configuración o qué propiedad del hardware condiciona una opción. Sin trabajo de detective en bash.
• Contribuciones fáciles de bifurcar. Agregar una solución alternativa para un hardware, un nuevo ajuste del escritorio o una nueva elección de empaquetado suele implicar la modificación de un solo archivo KDL. Sin modificaciones en el motor del instalador y, fuera de los detectores de hardware, que son expresiones de Raku de una línea, nada de Raku. El README de ditana-config guía a quienes contribuyen a través del esquema; la mayoría de las solicitudes de incorporación de cambios modifican un solo archivo.

Por qué KDL y no JSON o YAML

La base de conocimiento podría haber usado cualquier formato estructurado. Se eligió KDL porque tiene las propiedades que la configuración de Ditana realmente necesita:

• Comentarios nativos. Tanto YAML como JSON tienen dificultades aquí: YAML tiene comentarios, pero la compatibilidad de las herramientas es desigual; JSON no los tiene en absoluto. Las opciones de Ditana incluyen extensos comentarios de justificación que explican por qué un valor predeterminado es el que es. Esos comentarios son precisamente lo que importa.
• Cadenas sin formato. Los fragmentos de shell incrustados, las expresiones de sed y los patrones de expresiones regulares son elementos de pleno derecho. No hay que escapar dos veces " y \ para satisfacer al analizador.
• Jerárquico sin ceremonias. Los nodos hijos, las propiedades y los argumentos conviven sin problemas. El mismo nodo puede describir una opción y contener subnodos para sus paquetes, scripts y archivos.
• Adecuado para diffs. Se conserva el orden de inserción. En una revisión de código, una adición de una línea muestra un diff de una línea, no una estructura reordenada.

Un pequeño convertidor escrito en Rust (json-kdl-converter, cuyas versiones también se gestionan junto al esquema) analiza el formato antes de que el instalador en Raku lo consuma como JSON. La siguiente sección explica cómo se validan los datos de principio a fin antes de todo eso.

Cómo se ve esto en la práctica

Una opción completa y funcional de ditana-config tiene este aspecto:

// XFCE fallback for Wayland-only primary terminals (foot, cosmic-term).
// Fires when the user picks a Wayland-native terminal AND also installs
// XFCE. Writes to xfce-xdg-terminals.list only; xdg-terminals.list still
// points at the primary terminal for Wayland sessions.
- name="fallback-kitty-for-xfce" \
  default-value="`(install-foot OR install-cosmic-term) AND install-xfce`" {
    arch-packages "kitty" \
                  "imagemagick" \
                  "python-pygments" \
                  "libcanberra" \
                  "xdg-terminal-exec-git"
    files "/etc/xdg/kitty/kitty.conf" \
          "/usr/share/pixmaps/ditana-logo-tiny.png"
    chroot-script "mkdir -p /etc/xdg" \
                  "echo kitty.desktop >/etc/xdg/xfce-xdg-terminals.list"
}

Ese nodo declara una opción derivada sin diálogo propio, una expresión lógica sobre otras tres opciones, los paquetes que se instalan cuando se cumple y el archivo que hace que XFCE los use. El razonamiento está junto a la regla, donde quien la revise puede ver el porqué. La documentación completa del esquema está en el README de ditana-config.

La misma estructura contiene cosas que no son paquetes en absoluto. Un programa que necesita un espacio de nombres de usuario sin privilegios para su espacio aislado lo indica junto a su propia definición:

- name="flatpak" default-value=#true {
    arch-packages "flatpak"
    // Every Flatpak, not only the browsers, runs bwrap to build its outer
    // sandbox, and bwrap needs a user namespace. This is the declaration
    // that buys it one.
    userns-allow "/usr/bin/bwrap"
  }

Ditana no concede espacios de nombres de usuario sin privilegios a cualquier programa. Un programa BPF mínimo, ditana-userns-guard, está conectado al propio hook userns_create del kernel y niega un espacio de nombres a cualquier ejecutable para el que ninguna opción lo haya solicitado. Un hook de ese tipo solo puede negar, nunca conceder; por eso el sysctl que desactiva los espacios de nombres solo se eleva una vez cargado el programa: una máquina que no puede cargarlo los mantiene completamente desactivados. Este es el estado predeterminado de una opción de System Hardening; si la desactiva, los espacios de nombres quedan abiertos a todo, como en la mayoría de las distribuciones.

Ditana niega los espacios de nombres de usuario a todo lo que no los haya pedido. Lo que hace viable este enfoque es que la solicitud es local: se escribe donde se elige el paquete, de modo que no hace falta mantener sincronizada ninguna lista central, y al desactivar la opción desaparece también el permiso. El instalador recopila las declaraciones de las opciones que finalmente quedan activadas y genera a partir de ellas la lista de permitidos.

Validación: detectar errores antes de que se publiquen

Una base de conocimiento tan grande necesita salvaguardas. Cada commit —tanto en local mediante hooks de pre-commit como en remoto en GitHub Actions— pasa por una canalización de validación en capas que detecta los errores que una persona podría pasar por alto al revisar:

• Sintaxis KDL (kdlfmt): el archivo se puede analizar, para empezar.
• Validación del esquema (ditana-schema.json): cada campo tiene el tipo correcto, no hay propiedades desconocidas ni faltan campos obligatorios. Detecta errores tipográficos en nombres de campos, como arc-packages en lugar de arch-packages.
• Integridad de las referencias a archivos: cada archivo al que hace referencia una opción existe realmente en folders/; a la inversa, cada archivo de folders/ está referenciado por al menos una opción. Los archivos huérfanos se señalan. Las referencias a directorios (que no harían nada sin avisar, porque el instalador usa cp sin -R) se rechazan.
• Corrección del ciclo de vida: se rechazan las líneas de chroot-script que afectan a /etc/skel/, porque la cuenta de usuario se crea después de que se ejecute chroot-script; el campo correcto es early-chroot-script. Es un error sutil que, de lo contrario, produciría un sistema en el que el directorio personal de la nueva cuenta no tiene los archivos esperados.
• Validez de los scripts de shell: cada fragmento de shell de cualquiera de los campos de listas de scripts pasa por bash -n para la sintaxis y por shellcheck para la calidad. Unas comillas que faltan o un error del tipo [ "$x" = $y ] se detectan en el momento del commit, no en la primera instalación.
• Permisos declarados y ajustes del kernel: una entrada userns-allow debe ser una ruta absoluta, y una entrada sysctl debe nombrar algo que sea una clave de sysctl y darle un valor que el kernel acepte. Ambos campos se agregaron en la 0.9.4 y están declarados en ditana-schema.json.
• Ajustes del kernel contradictorios: dos opciones que escriben la misma clave de sysctl con valores distintos detienen la instalación, y el mensaje nombra a ambas. Cuando esto se ensamblaba como texto de shell, como antes de la 0.9.4, simplemente ganaba la última línea escrita y no se avisaba a nadie.
• Integridad de las expresiones lógicas: las comillas invertidas deben estar emparejadas; cada nombre de opción al que se hace referencia en una expresión default-value o available debe existir realmente en algún lugar de la base de conocimiento. Un error tipográfico como install-cosmik en lugar de install-cosmic se detecta en el momento del commit, en lugar de producir un cierre inesperado y silencioso en tiempo de ejecución.

La comprobación completa se ejecuta en local en segundos con pre-commit run --all-files, y de nuevo en cada envío de cambios a GitHub. Verde en local significa verde en la CI; los commits defectuosos nunca llegan a una versión publicada.

Adónde ir a continuación

• Lea cómo dependen las opciones unas de otras: en available y default-value reside la lógica de la base de conocimiento.
• Explore el repositorio ditana-config para ver cómo se organizan las reglas por diálogo y por tema.
• Lea el README de ditana-config para conocer el modelo de datos: cómo se relacionan las opciones, los scripts, los diálogos y los archivos.
• Consulte el código fuente de ditana-installer si quiere ver el motor que lee la configuración y actúa en consecuencia.