mise-tool-management

name	mise-tool-management
description	Use mise (mise.jdx.dev) to manage binary CLI / build tools (swiftlint, swiftformat, xcbeautify, gitleaks, lefthook, etc.) on both dev machines and CI, sharing a single `.mise.toml` for version parity. Invoke when starting a new project, choosing a tool version manager (vs asdf / Homebrew / manual), writing `.mise.toml`, or when asked "how do I manage swiftlint / xcbeautify versions".

mise Tool Management

When to invoke

• Starting a new project and picking a version manager for binary CLI / build tools.
• Writing the first .mise.toml.
• Adding new binary tools (swiftlint, swiftformat, xcbeautify, gitleaks, lefthook, jq, yq, ...).
• Setting up CI (e.g. Xcode Cloud ci_scripts/) that needs to call tools.
• User asks "asdf vs mise", "why isn't Homebrew enough", "what about CI / local version drift".

Default decisions

• Adopt mise (mise.jdx.dev) to manage binary CLI / build tools.
• Dev machine and CI share the same .mise.toml, committed to git.
• Plugin backend priority: core plugin → aqua: → ubi: → asdf:.
• CI (Xcode Cloud ci_post_clone.sh) first line: mise install; subsequent tool invocations always go through mise exec <tool> -- <args>.

Rationale

• A single file (.mise.toml) is the single source of truth; version drift is eliminated at the root.
• mise manages multiple languages / tools at once, no need for a separate version manager per tool.
• Stronger than Homebrew: pin to minor / patch versions, not "latest is the version".
• Faster than asdf: written in Rust, with small shell-hook overhead.

Example .mise.toml

[tools]
swift = "system"
swiftlint = "0.54"
xcbeautify = "1"
"aqua:gitleaks/gitleaks" = "8"
"aqua:evilmartians/lefthook" = "1"
# Xcode version can also be managed via a mise plugin if you need to lock it

Deviation considerations

• Team already uses asdf heavily: keep it for now, but new repos go to mise; mise can read .tool-versions as a transition.
• Tool not in mise registry / aqua / ubi: install via Homebrew / SwiftPM build manually and note the exception in the README.
• CI runner already has the target version preinstalled: still run mise install to enforce parity; the extra overhead is small.
• macOS-only tools on a mixed-OS CI fleet (Xcode-project generators, macOS artifact bundlers — e.g. tuist, LicensePlist): guard them with an os field, "aqua:tuist/tuist" = { version = "4", os = ["macos"] }. A Linux CI job (L10n / lint / markdown gates run fine on Ubuntu) runs mise install which installs every tool; an unguarded macOS-only tool fails at setup (unsupported env: linux/amd64) before any gate runs, blocking all PRs. This can appear suddenly with no change of yours — an upstream registry can flip a tool to darwin-only mid-day, so earlier PRs pass and later identical ones fail at "install pinned tools". When CI dies at the mise-install step, read for unsupported env: linux/amd64 and add the os guard.

Verification checklist

• .mise.toml lives at the repo root, committed to git.
• After local mise install, mise exec <tool> -- --version matches CI log.
• CI scripts go through mise exec, never calling /usr/local/bin/<tool> or other preinstalled paths.
• New-contributor setup guide (docs/setup.md) starts with "install mise → mise install".

Related skills

• xcode-cloud-single-track-ci: ci_scripts/ activates tools through mise.
• apple-public-repo-security: gitleaks + lefthook installed through mise.