theus-cli-linux-x64 0.2.84

package/vendor/theus-arsenal/skills/entornos-flox/SKILL.md

@@ -0,0 +1,493 @@
+---
+name: entornos-flox
+description: Crea entornos de desarrollo reproducibles y multiplataforma (macOS/Linux) con Flox,
+  un gestor declarativo basado en Nix. Úsala para montar toolchains de proyecto, instalar
+  dependencias de sistema (compiladores, bases de datos, librerías nativas), fijar versiones
+  exactas para un equipo, correr servicios locales (PostgreSQL, Redis, Kafka) o resolver el
+  clásico "en mi máquina funciona". También cuando aparezcan .flox/, manifest.toml, flox activate o FloxHub.
+---
+
+# Entornos Flox
+
+Flox crea entornos de desarrollo reproducibles definidos en un único manifiesto TOML. Cada persona del equipo obtiene los mismos paquetes, herramientas y configuración — en macOS y Linux — sin contenedores ni máquinas virtuales. Está construido sobre Nix, con acceso a más de 150 000 paquetes.
+
+## Cuándo usarla
+
+Usa esta skill cuando el usuario tenga un problema de gestión de entornos — incluso si no ha mencionado Flox. Flox es la herramienta adecuada cuando:
+
+- El proyecto necesita **paquetes a nivel de sistema** (compiladores, bases de datos, herramientas CLI) junto a dependencias del lenguaje
+- **La reproducibilidad importa** — el setup debe funcionar igual en la máquina de otra persona, en CI o en un portátil recién estrenado
+- Hay que hacer **convivir varias herramientas** — p. ej. Python 3.11 + PostgreSQL 16 + Redis + Node.js en un mismo entorno
+- Se necesita **soporte multiplataforma** (macOS y Linux desde la misma configuración)
+- **El agente necesita instalar herramientas** — Flox permite añadir paquetes a un entorno acotado al proyecto sin sudo, sin contaminar el sistema y sin chocar con restricciones de sandbox
+
+Si el usuario solo necesita un runtime de lenguaje sin dependencias de sistema, las herramientas estándar (nvm, pyenv, rustup) pueden bastar. Si necesita aislamiento total a nivel de SO, los contenedores pueden ser más apropiados. Flox ocupa el punto medio: entornos declarativos y reproducibles sin el peso de los contenedores.
+
+**Prerequisito:** Flox debe estar instalado primero — ver [flox.dev/docs](https://flox.dev/docs/install-flox/install/) para macOS, Linux y Docker.
+
+## Conceptos clave
+
+Los entornos Flox se definen en `.flox/env/manifest.toml` y se activan con `flox activate`. El manifiesto declara paquetes, variables de entorno, hooks de preparación y configuración de shell — todo lo necesario para reproducir el entorno en cualquier sitio.
+
+**Rutas importantes:**
+- `.flox/env/manifest.toml` — definición del entorno (commitéalo)
+- `$FLOX_ENV` — ruta en tiempo de ejecución a los paquetes instalados (como `/usr` — contiene `bin/`, `lib/`, `include/`)
+- `$FLOX_ENV_CACHE` — almacenamiento local persistente para cachés, venvs, datos (sobrevive a los rebuilds)
+- `$FLOX_ENV_PROJECT` — raíz del proyecto (donde vive `.flox/`)
+
+## Comandos esenciales
+
+```bash
+flox init                       # Crear un entorno nuevo
+flox search <paquete> [--all]   # Buscar paquetes
+flox show <paquete>             # Ver versiones disponibles
+flox install <paquete>          # Añadir un paquete
+flox list                       # Listar paquetes instalados
+flox activate                   # Entrar al entorno
+flox activate -- <cmd>          # Ejecutar un comando en el entorno sin abrir subshell
+flox edit                       # Editar el manifiesto interactivamente
+```
+
+## Estructura del manifiesto
+
+```toml
+# .flox/env/manifest.toml
+
+[install]
+# Paquetes a instalar — el núcleo del entorno
+ripgrep.pkg-path = "ripgrep"
+jq.pkg-path = "jq"
+
+[vars]
+# Variables de entorno estáticas
+DATABASE_URL = "postgres://localhost:5432/myapp"
+
+[hook]
+# Scripts de preparación no interactivos (corren en cada activación)
+on-activate = """
+  echo "Entorno listo"
+"""
+
+[profile]
+# Funciones y aliases de shell (disponibles en la shell interactiva)
+common = """
+  alias dev="npm run dev"
+"""
+
+[options]
+# Plataformas soportadas
+systems = ["x86_64-linux", "aarch64-linux", "x86_64-darwin", "aarch64-darwin"]
+```
+
+## Patrones de instalación de paquetes
+
+### Instalación básica
+
+```toml
+[install]
+nodejs.pkg-path = "nodejs"
+python.pkg-path = "python311"
+rustup.pkg-path = "rustup"
+```
+
+### Fijar versiones
+
+```toml
+[install]
+nodejs.pkg-path = "nodejs"
+nodejs.version = "^20.0"          # Rango semver: último 20.x
+
+postgres.pkg-path = "postgresql"
+postgres.version = "16.2"         # Versión exacta
+```
+
+### Paquetes por plataforma
+
+```toml
+[install]
+# Herramientas solo Linux
+valgrind.pkg-path = "valgrind"
+valgrind.systems = ["x86_64-linux", "aarch64-linux"]
+
+# Frameworks de macOS
+Security.pkg-path = "darwin.apple_sdk.frameworks.Security"
+Security.systems = ["x86_64-darwin", "aarch64-darwin"]
+
+# Herramientas GNU en macOS (donde los defaults BSD difieren)
+coreutils.pkg-path = "coreutils"
+coreutils.systems = ["x86_64-darwin", "aarch64-darwin"]
+```
+
+### Resolver conflictos entre paquetes
+
+Cuando dos paquetes instalan el mismo binario, usa `priority` (el número más bajo gana):
+
+```toml
+[install]
+gcc.pkg-path = "gcc12"
+gcc.priority = 3
+
+clang.pkg-path = "clang_18"
+clang.priority = 5               # gcc gana los conflictos de archivos
+```
+
+Usa `pkg-group` para agrupar paquetes que deben resolver versiones en conjunto:
+
+```toml
+[install]
+python.pkg-path = "python311"
+python.pkg-group = "python-stack"
+
+pip.pkg-path = "python311Packages.pip"
+pip.pkg-group = "python-stack"    # Se resuelve junto con python
+```
+
+## Recetas por lenguaje
+
+### Python con uv
+
+```toml
+[install]
+python.pkg-path = "python311"
+uv.pkg-path = "uv"
+
+[vars]
+UV_CACHE_DIR = "$FLOX_ENV_CACHE/uv-cache"
+PIP_CACHE_DIR = "$FLOX_ENV_CACHE/pip-cache"
+
+[hook]
+on-activate = """
+  venv="$FLOX_ENV_CACHE/venv"
+  if [ ! -d "$venv" ]; then
+    uv venv "$venv" --python python3
+  fi
+  if [ -f "$venv/bin/activate" ]; then
+    source "$venv/bin/activate"
+  fi
+
+  if [ -f requirements.txt ] && [ ! -f "$FLOX_ENV_CACHE/.deps_installed" ]; then
+    uv pip install --python "$venv/bin/python" -r requirements.txt --quiet
+    touch "$FLOX_ENV_CACHE/.deps_installed"
+  fi
+"""
+```
+
+### Node.js
+
+```toml
+[install]
+nodejs.pkg-path = "nodejs"
+nodejs.version = "^20.0"
+
+[hook]
+on-activate = """
+  if [ -f package.json ] && [ ! -d node_modules ]; then
+    npm install --silent
+  fi
+"""
+```
+
+### Rust
+
+```toml
+[install]
+rustup.pkg-path = "rustup"
+pkg-config.pkg-path = "pkg-config"
+openssl.pkg-path = "openssl"
+
+[vars]
+RUSTUP_HOME = "$FLOX_ENV_CACHE/rustup"
+CARGO_HOME = "$FLOX_ENV_CACHE/cargo"
+
+[profile]
+common = """
+  export PATH="$CARGO_HOME/bin:$PATH"
+"""
+```
+
+### Go
+
+```toml
+[install]
+go.pkg-path = "go"
+gopls.pkg-path = "gopls"
+delve.pkg-path = "delve"
+
+[vars]
+GOPATH = "$FLOX_ENV_CACHE/go"
+GOBIN = "$FLOX_ENV_CACHE/go/bin"
+
+[profile]
+common = """
+  export PATH="$GOBIN:$PATH"
+"""
+```
+
+### C/C++
+
+```toml
+[install]
+gcc.pkg-path = "gcc13"
+gcc.pkg-group = "compilers"
+
+# IMPORTANTE: gcc por sí solo no expone las cabeceras de libstdc++ — necesitas gcc-unwrapped
+gcc-unwrapped.pkg-path = "gcc-unwrapped"
+gcc-unwrapped.pkg-group = "libraries"
+
+cmake.pkg-path = "cmake"
+cmake.pkg-group = "build"
+
+gnumake.pkg-path = "gnumake"
+gnumake.pkg-group = "build"
+
+gdb.pkg-path = "gdb"
+gdb.systems = ["x86_64-linux", "aarch64-linux"]
+```
+
+## Hooks y profile
+
+### Hooks — preparación no interactiva
+
+Los hooks corren en cada activación. Mantenlos rápidos e idempotentes. Regla práctica: **si debe ocurrir automáticamente, va en `[hook]`; si el usuario debe poder teclearlo, va en `[profile]`.**
+
+```toml
+[hook]
+on-activate = """
+  setup_database() {
+    if [ ! -d "$FLOX_ENV_CACHE/pgdata" ]; then
+      initdb -D "$FLOX_ENV_CACHE/pgdata" --no-locale --encoding=UTF8
+    fi
+  }
+  setup_database
+"""
+```
+
+### Profile — configuración de shell interactiva
+
+El código de profile queda disponible en la sesión de shell del usuario.
+
+```toml
+[profile]
+common = """
+  dev() { npm run dev; }
+  test() { npm run test -- "$@"; }
+"""
+```
+
+## Antipatrones
+
+### Rutas absolutas
+
+```toml
+# MAL — rompe en otras máquinas
+[vars]
+PROJECT_DIR = "/home/alice/projects/myapp"
+
+# BIEN — usa las variables de entorno de Flox
+[vars]
+PROJECT_DIR = "$FLOX_ENV_PROJECT"
+```
+
+### Usar exit en hooks
+
+```toml
+# MAL — mata la shell
+[hook]
+on-activate = """
+  if [ ! -f config.json ]; then
+    echo "Falta la configuración"
+    exit 1
+  fi
+"""
+
+# BIEN — retorna desde el hook, no salgas
+[hook]
+on-activate = """
+  if [ ! -f config.json ]; then
+    echo "Falta la configuración — ejecuta primero el setup"
+    return 1
+  fi
+"""
+```
+
+### Guardar secretos en el manifiesto
+
+```toml
+# MAL — el manifiesto se commitea a git
+[vars]
+API_KEY = "<fijado-en-tiempo-de-ejecucion>"
+
+# BIEN — referencia configuración externa o pásala en tiempo de ejecución
+# Uso: API_KEY="<tu-api-key>" flox activate
+[vars]
+API_KEY = "${API_KEY:-}"
+```
+
+### Hooks lentos sin guardas de idempotencia
+
+```toml
+# MAL — reinstala en cada activación
+[hook]
+on-activate = """
+  pip install -r requirements.txt
+"""
+
+# BIEN — omite si ya está instalado
+[hook]
+on-activate = """
+  if [ ! -f "$FLOX_ENV_CACHE/.deps_installed" ]; then
+    uv pip install -r requirements.txt --quiet
+    touch "$FLOX_ENV_CACHE/.deps_installed"
+  fi
+"""
+```
+
+### Poner comandos de usuario en hooks
+
+```toml
+# MAL — las funciones del hook no están disponibles en la shell interactiva
+[hook]
+on-activate = """
+  deploy() { kubectl apply -f k8s/; }
+"""
+
+# BIEN — usa [profile] para funciones invocables por el usuario
+[profile]
+common = """
+  deploy() { kubectl apply -f k8s/; }
+"""
+```
+
+## Ejemplo full-stack
+
+Un entorno completo para una API en Python con PostgreSQL:
+
+```toml
+[install]
+python.pkg-path = "python311"
+uv.pkg-path = "uv"
+postgresql.pkg-path = "postgresql_16"
+redis.pkg-path = "redis"
+jq.pkg-path = "jq"
+curl.pkg-path = "curl"
+
+[vars]
+UV_CACHE_DIR = "$FLOX_ENV_CACHE/uv-cache"
+DATABASE_URL = "postgres://localhost:5432/myapp"
+REDIS_URL = "redis://localhost:6379"
+
+[hook]
+on-activate = """
+  if [ ! -d "$FLOX_ENV_CACHE/pgdata" ]; then
+    initdb -D "$FLOX_ENV_CACHE/pgdata" --no-locale --encoding=UTF8
+  fi
+
+  venv="$FLOX_ENV_CACHE/venv"
+  if [ ! -d "$venv" ]; then
+    uv venv "$venv" --python python3
+  fi
+  if [ -f "$venv/bin/activate" ]; then
+    source "$venv/bin/activate"
+  fi
+
+  if [ -f requirements.txt ] && [ ! -f "$FLOX_ENV_CACHE/.deps_installed" ]; then
+    uv pip install --python "$venv/bin/python" -r requirements.txt --quiet
+    touch "$FLOX_ENV_CACHE/.deps_installed"
+  fi
+"""
+
+[profile]
+common = """
+  serve() { uvicorn app.main:app --reload --host 0.0.0.0 --port 8000; }
+  migrate() { alembic upgrade head; }
+"""
+
+[services]
+postgres.command = "postgres -D $FLOX_ENV_CACHE/pgdata -k $FLOX_ENV_CACHE"
+redis.command = "redis-server --port 6379 --daemonize no"
+
+[options]
+systems = ["x86_64-linux", "aarch64-linux", "x86_64-darwin", "aarch64-darwin"]
+```
+
+Activar con servicios: `flox activate --start-services`
+
+## Compartir entornos
+
+Los entornos Flox son nativos de git. Commitea el directorio `.flox/` y cada colaborador obtiene el mismo entorno:
+
+```bash
+git add .flox/
+git commit -m "Añadir entorno Flox"
+# El resto del equipo solo ejecuta:
+git clone <repo> && cd <repo> && flox activate
+```
+
+Para entornos base reutilizables entre proyectos, publícalos en FloxHub:
+
+```bash
+flox push                         # Publicar el entorno en FloxHub
+flox activate -r owner/env-name   # Activar un entorno remoto en cualquier sitio
+```
+
+Compón entornos con `[include]`:
+
+```toml
+[include]
+base.floxhub = "myorg/python-base"
+
+[install]
+# Añadidos específicos del proyecto sobre la base
+fastapi.pkg-path = "python311Packages.fastapi"
+```
+
+## Flujos con agentes
+
+Flox encaja de forma natural en el desarrollo asistido por agentes. Cuando el agente necesita una herramienta que no está disponible en el entorno actual — un compilador, una base de datos, un linter, una utilidad CLI — puede añadirla al manifiesto Flox del proyecto sin requerir sudo, sin contaminar los paquetes del sistema y sin chocar con restricciones de sandbox.
+
+**Por qué importa para los agentes:**
+- **Sin sudo** — `flox install` funciona íntegramente en espacio de usuario
+- **Acotado al proyecto** — los paquetes se instalan solo en el entorno del proyecto; proyectos distintos pueden tener versiones distintas sin conflicto
+- **Compatible con sandbox** — agentes en entornos restringidos pueden seguir instalando lo que necesitan vía Flox
+- **Reversible** — cada cambio queda registrado en `manifest.toml`; los paquetes indeseados se eliminan limpiamente sin residuo en el sistema
+- **Reproducible** — cuando el agente prepara un entorno, ese setup exacto se commitea a git y funciona para todo el equipo
+
+**Patrón de flujo del agente:**
+
+```bash
+# El agente descubre que necesita una herramienta (p. ej. jq para procesar JSON)
+flox search jq                    # Verificar que el paquete existe
+flox install jq                   # Instalarlo en el entorno del proyecto
+
+# O, para más control, editar el manifiesto directamente
+tmp_manifest="$(mktemp)"
+flox list -c > "$tmp_manifest"
+# Añadir el paquete a la sección [install] y aplicar
+flox edit -f "$tmp_manifest"
+
+# Ejecutar un comando con la herramienta disponible
+flox activate -- jq '.results[]' data.json
+```
+
+Esto hace de Flox un encaje natural para cualquier flujo donde Theus u otros agentes necesiten preparar el tooling del proyecto sobre la marcha.
+
+## Depuración
+
+```bash
+flox list -c                      # Ver el manifiesto crudo
+flox activate -- which python     # Comprobar qué binario resuelve
+flox activate -- env | grep FLOX  # Ver las variables de entorno de Flox
+flox search <paquete> --all       # Búsqueda amplia (sensible a mayúsculas)
+```
+
+**Problemas comunes:**
+- **Paquete no encontrado:** la búsqueda distingue mayúsculas — prueba `flox search --all`
+- **Conflictos de archivos entre paquetes:** añade `priority` al paquete que debe ganar
+- **Fallos en hooks:** usa `return`, no `exit`; protege con `${FLOX_ENV_CACHE:-}`
+- **Dependencias obsoletas:** borra el archivo bandera `$FLOX_ENV_CACHE/.deps_installed`
+
+## Skills relacionadas
+
+El proyecto Flox mantiene skills adicionales en su propio plugin agéntico ([github.com/flox/flox-agentic](https://github.com/flox/flox-agentic)) para servicios, builds, contenedores, composición de entornos y CUDA. No forman parte de este plugin — instálalas desde ese repositorio si las necesitas.
+
+Documentación: [flox.dev/docs](https://flox.dev/docs/install-flox/install/)