Saltar al contenido principal

Wiedii — Política de Gestión de Herramientas con mise

⚠️ Verificar versiones antes de usar — los números de versión de herramientas en esta nota pueden estar desactualizados. Usar mise ls-remote <herramienta> | tail -5 para consultar las versiones disponibles. Ver politicas-core.

mise es el gestor centralizado de herramientas. Toda herramienta binaria disponible en el registro de mise debe instalarse via mise. Los entornos deben ser 100% reproducibles: versiones exactas fijadas y lockfiles mise.lock son obligatorios.

1. Orden de prioridad de backends​

Obligatorio: antes de agregar o actualizar cualquier herramienta en mise.toml, abrir https://mise-versions.jdx.dev/ y confirmar qué backends la soportan y qué versiones están disponibles. Nunca asumir un backend — siempre verificar.

Core tools (runtimes del lenguaje) — node, bun, python, go, ruby, rust, deno, java, swift, zig, elixir, erlang — se escriben con su nombre corto, SIN prefijo (node = "24.1.0", no "core:node"). El prefijo core: es redundante; no es una "opción", es donde viven los runtimes.

Resto de herramientas (CLIs/binarios) — prioridad de backend, con prefijo OBLIGATORIO:

PrioridadBackendCuándo usarlo
1ºaqua:Preferido siempre. Registro curado de mise con checksums verificados.
2ºnpm:CLI del ecosistema JS que NO va en package.json.
3ºpipx:CLI de Python que NO va en pyproject.toml.
4ºcargo:CLI de Rust no disponible en aqua.
5ºasdf:Último recurso — plugins heredados.

Otros backends (vfox:, go:, gem:, ubi:, dotnet:…) solo si la herramienta únicamente existe ahí.

Regla del gestor nativo: si la herramienta pertenece al ecosistema del lenguaje del proyecto (prettier/eslint → package.json, ruff/mypy → pyproject.toml), va en su gestor nativo, NO en mise. Excepción: las CLIs de Go siempre van en mise.toml (go.mod solo registra librerías importadas, no ejecutables).

2. Valores de versión prohibidos​

latest y lts están prohibidos. Todas las versiones deben ser exactas: "X.Y.Z".

# ❌ Prohibido
bun = "latest"

# ✅ Requerido
bun = "1.3.14"

Nota sobre bun: es un core tool nativo de mise — bun = "x.y.z" es equivalente a "core:bun" = "x.y.z". El registro de mise mapea automáticamente el alias corto. La forma sin prefijo es la canónica según los docs oficiales de mise.

3. Config global del sistema (~/.config/mise/config.toml)​

El config global debe forzar el determinismo. El bloque de abajo es la plantilla base mínima — cada developer la extiende con las herramientas globales que necesite, respetando las reglas de esta sección:

[settings]
experimental = true        # necesario para los [hooks] (postinstall) — NO para el lockfile
lockfile = true            # habilita lectura/escritura de mise.lock (NO lo crea: usar `mise lock`)
all_compile = false        # evita instalaciones implícitas por compilación

[tools]
# Herramientas globales gestionadas por mise (versiones exactas, backends explícitos).
# IMPORTANTE: las herramientas que Homebrew ya gestiona NO van aquí — evitar duplicados.
# Ejemplos: git, git-flow-next, glab → Homebrew. bun, node → mise (versiones por proyecto).
node = "24.13.0"   # core tool → nombre corto, sin prefijo
bun  = "1.3.14"    # core tool → nombre corto, sin prefijo

4. Template estándar de mise.toml por proyecto​

Cada proyecto debe tener un mise.toml en la raíz con:

  • Prefijos de backend explícitos
  • Versiones exactas fijadas
  • Bloque [env] para variables de entorno del proyecto
  • [hooks] para instalar lefthook automáticamente tras mise install
  • [tasks.setup] para onboarding reproducible
[tools]
bun                          = "1.3.14"
"aqua:evilmartians/lefthook" = "2.1.3"
# git-flow-next es GLOBAL — no agregar aquí; ver ~/.config/mise/config.toml
"aqua:tamasfe/taplo"         = "0.9.3"
"aqua:hadolint/hadolint"     = "2.12.0"
"aqua:mvdan/sh"              = "3.9.0"     # shfmt
"aqua:koalaman/shellcheck"   = "0.10.0"
# Agregar según stack:
# "aqua:astral-sh/ruff"        = "0.4.5"   # Python
# "cargo:mypy"                 = "1.10.0"  # tipos estáticos Python
# "aqua:golangci/golangci-lint" = "1.59.0" # Go
# "aqua:aquasecurity/trivy"    = "0.52.0"  # escaneo de seguridad
# "aqua:snyk/snyk"             = "1.1295.0" # seguridad de dependencias

[env]
# variables de entorno a nivel de proyecto
# NODE_ENV = "development"

[hooks]
# postinstall es un hook experimental de mise — no requiere mise activate
# CI=true lo setean GitLab CI, GitHub Actions y la mayoría de sistemas CI
# En local $CI está vacío → lefthook install corre normalmente
postinstall = "[ -z \"$CI\" ] && lefthook install || true"

[tasks.setup]
description = "Setup completo: herramientas, lock, hooks y dependencias"
# ⚠️ Una sola cadena con && (NO array): el hook `toml` con reorder_arrays=true reordenaría
# alfabéticamente los pasos al commitear y rompería el orden de ejecución. Ver [mise](../herramientas/mise.md) y [wiedii-configs](../herramientas/wiedii-configs.md).
run = "mise trust && mise install --yes && mise lock && pkg=$(find . -maxdepth 2 -name 'package.json' ! -path '*/node_modules/*' | head -1) && { [ -n \"$pkg\" ] && bun install --cwd \"$(dirname \"$pkg\")\" || true; }"

5. Requisito de lockfile​

Verificar antes de fijar: antes de commitear cualquier versión en mise.toml, confirmar que la versión existe para el backend elegido en https://mise-versions.jdx.dev/.

⚠️ El lockfile NO se crea solo. lockfile = true solo le dice a mise que lea y escriba mise.lock: mantiene actualizado un archivo que ya exista, pero NO lo genera. Hay que crearlo una vez con mise lock y commitearlo. (El setting experimental no tiene que ver con el lock — es para los [hooks].)

Al crear el repo (una vez): generar el lock y commitearlo.

mise lock                                   # crea mise.lock para la plataforma actual
# Reproducibilidad mac (dev) + linux (CI/Docker): fijar ambas plataformas
mise lock --platform macos-arm64,linux-x64
git add mise.toml mise.lock

Después, el lock se mantiene solo en cada cambio de herramienta:

mise use aqua:tool/name@x.y.z   # cambia mise.toml y actualiza mise.lock
mise install                    # instala y actualiza mise.lock (si ya existe)
mise upgrade                    # sube versiones dentro del rango + actualiza el lock
git add mise.toml mise.lock

mise install y mise use solo actualizan un mise.lock existente; no lo crean. Por eso el mise lock inicial es obligatorio. El mise run setup de Wiedii ya incluye mise lock para que el archivo nunca falte.

6. Comandos de auditoría y limpieza​

mise ls              # listar herramientas instaladas y su backend
mise outdated        # identificar herramientas con actualizaciones disponibles vs. versión fijada
mise prune           # eliminar binarios huérfanos que no están en el lockfile

7. Resolución de conflictos (mise.toml vs mise.lock)​

  1. Cambio solicitado por el usuario: actualizar mise.toml, luego regenerar con mise install.
  2. Sin instrucción de cambio: respetar mise.lock — no modificar el entorno.
  3. Siempre reportar si se usó un backend de menor prioridad cuando uno de mayor prioridad estaba disponible.

8. Reglas de invocación de herramientas​

Tipo de herramientaCómo invocarEjemplo
Binarios gestionados por misemise exec -- <tool>mise exec -- taplo fmt file.toml
Paquetes instalados por bunbun <package>bun eslint src/
Paquetes puntuales (no instalados)bunxbunx --yes some-package

Nunca usar bunx para paquetes instalados en node_modules.

9. Scripts requeridos en package.json​

{
  "type": "module",
  "scripts": {
    "commit": "bun --bun czg"
  },
  "devDependencies": {
    "@commitlint/cli": "21.0.1",
    "@commitlint/config-conventional": "21.0.1",
    "cz-git": "1.13.1",
    "czg": "1.13.1"
  },
  "engines": {
    "bun": "1.3.14",
    "node": "Please use Bun instead of Node to install dependencies",
    "npm": "Please use Bun instead of NPM to install dependencies",
    "pnpm": "Please use Bun instead of PNPM to install dependencies",
    "yarn": "Please use Bun instead of Yarn to install dependencies"
  }
}
  • "type": "module" — todos los repos nuevos en Wiedii usan ESM. Las configs JS (commitlint.config.js, changelog.config.js) usan import/export default. ⚠️ Excepción monorepo Nx: el package.json de la RAÍZ de un workspace Nx NO debe llevar "type": "module" (rompe los generators/migraciones de Nx). En ese caso, dejar la raíz sin type, declarar "type": "module" solo en cada packages/*, y usar extensión .mjs/.cjs explícita para las configs de la raíz. Ver nx-monorepo.
  • "commit": "bun --bun czg" — bun commit abre el wizard de commits semánticos. bun --bun fuerza el runtime de Bun (más rápido). czg es el binario que instala czg.
  • cz-git se agrega como dep directa porque commitlint.config.js la importa explícitamente (import { defineConfig } from 'cz-git'). commitizen no se usa — solo bun commit → czg.
  • engines — patrón Wiedii: mensajes de error en los campos de versión hacen explícito que solo se usa Bun.
  • lefthook install no va en package.json — se gestiona exclusivamente via [hooks].postinstall en mise.toml. Esto garantiza que los hooks se instalan en cualquier proyecto, sea Node o no, y nunca en CI.

10. Herramientas que son SIEMPRE globales (no agregar al mise.toml del proyecto)​

Estas herramientas nunca van en el mise.toml de un proyecto individual porque son transversales a todos los repos o las gestiona Homebrew:

HerramientaGestorMotivo
gitHomebrewHerramienta base del sistema
git-flow-nextHomebrewBranching cross-proyecto — brew install git-flow-next
glabHomebrewCLI de GitLab — brew install glab
docker / docker composeOrbStack (Homebrew)Runtime de contenedores
miseHomebrewNo puede gestionarse a sí mismo
CLIs de IA (claude, claude-code)HomebrewHerramientas de desarrollo global

Regla: si una herramienta ya está en Homebrew y se usa en todos los proyectos, no duplicarla en mise. Si mise es el gestor correcto (versiones por proyecto, como bun o node), entonces sí va en el config global de mise — pero nunca en el mise.toml del proyecto individual.

11. Setup inicial tras clonar​

mise run setup
# Equivale a:
#   mise trust
#   mise install --yes   → instala herramientas + ejecuta lefthook install (si no es CI)
#   mise lock            → crea/actualiza mise.lock (commitearlo al repo)
#   bun install          → solo si existe package.json

lefthook install se ejecuta una sola vez, via [hooks].postinstall de mise, después de mise install --yes. No se ejecuta en entornos CI ($CI=true). No depende de que el proyecto use Node.

Referencias​