feat: funcion docker_compose_remote_deploy bash

Funcion bash que despliega un stack Docker Compose en un host remoto via SSH.
Flujo: verificar SSH → git pull → docker-compose pull → docker-compose up -d → listar containers.
Soporta compose files adicionales y retorna JSON con status, containers y duracion.

bash/functions/infra/docker_compose_remote_deploy.md

@@ -0,0 +1,64 @@
+---
+name: docker_compose_remote_deploy
+kind: function
+lang: bash
+domain: infra
+version: "1.0.0"
+purity: impure
+signature: "docker_compose_remote_deploy(host: string, remote_dir: string, branch: string, compose_files: string) -> json"
+description: "Despliega un stack Docker Compose en un host remoto via SSH. Verifica conectividad, hace git pull del branch indicado, actualiza imagenes con docker-compose pull y levanta/recrea los servicios modificados con docker-compose up -d. Soporta compose files adicionales. Retorna JSON con status, containers corriendo y duracion."
+tags: [docker, compose, deploy, ssh, remote, git, infra, cicd]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: []
+params:
+  - name: host
+    desc: "alias SSH del host remoto definido en ~/.ssh/config (ej: prod-server)"
+  - name: remote_dir
+    desc: "ruta absoluta en el host donde esta el repo con docker-compose.yml (ej: /opt/apps/element)"
+  - name: branch
+    desc: "branch de git a hacer pull; default 'main'"
+  - name: compose_files
+    desc: "archivos compose adicionales separados por coma (ej: 'docker-compose.livekit.yml,docker-compose.monitoring.yml'); si vacio usa solo docker-compose.yml"
+output: "JSON con status ('ok'), host, remote_dir, branch, containers (array de nombres corriendo tras el deploy), duration_ms"
+tested: false
+tests: []
+test_file_path: ""
+file_path: "bash/functions/infra/docker_compose_remote_deploy.sh"
+---
+
+## Ejemplo
+
+```bash
+source bash/functions/infra/docker_compose_remote_deploy.sh
+
+# Deploy basico (solo docker-compose.yml, branch main)
+result=$(docker_compose_remote_deploy "prod-server" "/opt/apps/element")
+echo "$result"
+# {"status":"ok","host":"prod-server","remote_dir":"/opt/apps/element","branch":"main","containers":["element-web","synapse","postgres"],"duration_ms":4200}
+
+# Deploy con compose files adicionales y branch especifico
+result=$(docker_compose_remote_deploy "prod-server" "/opt/apps/element" "release" "docker-compose.livekit.yml,docker-compose.monitoring.yml")
+echo "$result"
+# {"status":"ok","host":"prod-server","remote_dir":"/opt/apps/element","branch":"release","containers":[...],"duration_ms":8100}
+
+# Uso desde un pipeline CI/CD
+source bash/functions/infra/docker_compose_remote_deploy.sh
+docker_compose_remote_deploy "$SSH_HOST" "$REMOTE_DIR" "$GIT_BRANCH" "$EXTRA_COMPOSE" || exit 1
+```
+
+## Notas
+
+- Flujo: verificar SSH → git pull → docker-compose pull → docker-compose up -d → listar containers.
+- La verificacion SSH usa `-o BatchMode=yes -o ConnectTimeout=5` para fallar rapido sin pedir password.
+- Los compose files adicionales se pasan como `-f file1.yml -f file2.yml` a todos los subcomandos compose.
+- `docker-compose up -d` solo recrea los servicios cuya imagen o config cambio (comportamiento nativo de compose).
+- La lista de containers al final incluye TODOS los containers corriendo en el host, no solo los del stack.
+- Requiere `jq` instalado en el host remoto para serializar la lista de containers. Si no esta, `containers` sera `[]`.
+- Los mensajes de progreso van a stderr; el JSON final va a stdout.
+- Exit code 1 en cualquier fallo (SSH, git pull, compose pull, compose up); el JSON de error NO se emite — el caller debe manejar el exit code.
+- El `host` se resuelve con `~/.ssh/config` incluyendo host, user, identityfile y puerto.
+- Diferencia con `rsync_deploy`: este flujo asume que el codigo ya esta en el remoto (via git) y usa compose. `rsync_deploy` sube archivos locales sin git.