fn_registry/docs/capabilities/onlyoffice.md

Capability group: onlyoffice

Operar ONLYOFFICE Desktop Editors (binario /usr/bin/onlyoffice-desktopeditors) en Linux/X11 desde terminal, gestionando la ventana de los archivos sin perturbar la instancia personal del usuario.

Este grupo NO es el ONLYOFFICE Document Server (web/Docker) — para eso ver start_documentserver_bash_infra, documentserver_health_go_infra, onlyoffice_command_service_go_infra y compañia. Este grupo es el editor de escritorio.

Convencion de instancia aislada (slot)

ONLYOFFICE Desktop es single-instance por usuario: un segundo onlyoffice-desktopeditors <file> se reenvia a la instancia viva y abre el archivo como PESTAÑA en su ventana, no como ventana nueva. El lock single-instance NO se rompe con XDG_CONFIG_HOME, pero SI se rompe lanzando con HOME y XDG_RUNTIME_DIR propios.

Por eso las 3 funciones comparten un "slot" nombrado por instance (string, default demo):

HOME=/tmp/oo_<instance>
XDG_RUNTIME_DIR=/tmp/oo_<instance>_run      (mkdir -p + chmod 700)
XDG_CONFIG_HOME=/tmp/oo_<instance>/.config

Lanzamiento canonico (identico en open y reload):

env HOME=/tmp/oo_<instance> XDG_RUNTIME_DIR=/tmp/oo_<instance>_run \
    XDG_CONFIG_HOME=/tmp/oo_<instance>/.config \
    setsid onlyoffice-desktopeditors <file> >/tmp/oo_<instance>.log 2>&1 </dev/null &

Usar el MISMO instance en todas las operaciones del slot: asi el relaunch reenvia a la instancia aislada viva y reabre rapido en vez de arrancar el motor de cero.

Funciones

ID	Firma corta	Que hace
open_onlyoffice_file_bash_shell	open_onlyoffice_file <file> [instance]	Abre un archivo existente en el slot aislado; espera la ventana por basename (~25s); JSON con wid/status. Idempotente, NO crea archivos.
reload_onlyoffice_file_bash_shell	reload_onlyoffice_file <file> [instance]	Funcion estrella: cierra (wmctrl -ic) y reabre el archivo en el slot para mostrar datos editados EN DISCO (ONLYOFFICE no tiene reload nativo, Issue #2313). JSON con wid_old/wid_new/elapsed_s/status. NO edita el archivo.
close_onlyoffice_instance_bash_shell	close_onlyoffice_instance [instance] [--purge]	Mata los procesos DesktopEditors del slot (por HOME=/tmp/oo_ en /proc), SIGTERM->SIGKILL; con --purge borra /tmp/oo_*. JSON con killed_pids/status.

Ejemplo canonico (end-to-end)

Flujo completo "abrir -> editar el archivo en disco -> recargar la vista -> cerrar", todo sobre un slot aislado demo que no toca la instancia personal del usuario:

cd /home/enmanuel/fn_registry

# 0. El caller prepara el archivo (esta funcion NO crea archivos)
printf 'a,b\n1,2\n' > /tmp/demo_reload.csv

# 1. Abrir en el slot aislado 'demo' -> ventana propia
./fn run open_onlyoffice_file_bash_shell /tmp/demo_reload.csv demo
# {"instance":"demo","file":"/tmp/demo_reload.csv","wid":"0x3c00007","pid":12345,"status":"open"}

# 2. El caller edita el archivo EN DISCO (script, generador, otra herramienta)
printf 'a,b\n1,2\n3,4\n5,6\n' > /tmp/demo_reload.csv

# 3. Recargar la ventana para que muestre los datos nuevos (cierra+reabre)
./fn run reload_onlyoffice_file_bash_shell /tmp/demo_reload.csv demo
# {"instance":"demo","file":"/tmp/demo_reload.csv","wid_old":"0x3c00007","wid_new":"0x3c0000b","reopened":true,"elapsed_s":4,"status":"reloaded"}

# 4. Cerrar la instancia aislada y limpiar su estado
./fn run close_onlyoffice_instance_bash_shell demo --purge
# {"instance":"demo","killed_pids":[12345],"purged":true,"status":"closed"}

Fronteras (que NO hace el grupo)

• NO edita ni crea archivos. Solo gestiona la VENTANA (abrir, cerrar+reabrir, matar proceso). El contenido lo prepara y modifica el caller en disco.
• NO es el Document Server (web/Docker/JWT/Command Service). Eso es otro conjunto de funciones (*documentserver*, *onlyoffice_jwt*, onlyoffice_command_service_*).
• NO recarga in-place: ONLYOFFICE Desktop no soporta reload de cambios externos (Issue #2313 abierto). reload_onlyoffice_file lo emula con cerrar+reabrir; no hay alternativa "sin parpadeo".
• NO toca la instancia personal del usuario: todo opera sobre el slot aislado (HOME=/tmp/oo_). close solo mata procesos cuyo HOME es del slot.

Prerequisitos

• Linux con X11 (o XWayland). En Wayland puro sin XWayland, xdotool/wmctrl no encuentran la ventana.
• Binarios en PATH: onlyoffice-desktopeditors, wmctrl, xdotool. Cada funcion comprueba command -v y falla con exit !=0 si falta alguno.

Notas

• Las esperas son por evento (xdotool search + read -t), nunca sleep en foreground, para no colgar bajo fn run ni tests.
• El slot vive en /tmp y se pierde al reiniciar el PC (estado desechable). --purge lo borra explicitamente.
• wmctrl -ic puede disparar el dialogo "Guardar cambios" SOLO si se edito dentro de la app con cambios sin guardar; el flujo previsto edita en disco, asi que la ventana no tiene estado pendiente.