theus-cli 0.2.82 → 0.2.84

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

@@ -1,493 +0,0 @@
----
-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/)