feat(brew-cask): add MISE_BREW_CASK_OPT_APPDIR

docs/bootstrap/packages/brew.md

@@ -67,6 +67,27 @@ installs app bundles into `/Applications` while recording the version under
 "brew-cask:homebrew/cask/visual-studio-code" = "latest"
 ```
 
+### Overriding the application directory
+
+By default `app` artifacts are installed into `/Applications`, matching
+Homebrew. Set the `MISE_BREW_CASK_OPT_APPDIR` environment variable to install
+them somewhere else — for example a user-writable `~/Applications` that does not
+require elevation:
+
+```sh
+MISE_BREW_CASK_OPT_APPDIR="$HOME/Applications" mise bootstrap packages apply brew-cask:firefox
+```
+
+The value must be an absolute path, must not contain `..`, and must not resolve
+to the filesystem root. It is resolved to a real path (symlinks are followed)
+before use, so it acts as a fixed containment boundary for the app links mise
+creates. An empty value is ignored and falls back to `/Applications`. When the
+override is set, a cask that targets the default `/Applications` (as most do) is
+relocated into the override directory, preserving any subdirectories the cask
+requests; targets that a cask anchors under `$HOMEBREW_PREFIX/Applications` are
+left in the Homebrew prefix and are never relocated. This mirrors Homebrew's own
+`--appdir` install option.
+
 On Linux, initial cask support is limited to font-only casks without lifecycle
 hooks or structured `preflight_steps` or `postflight_steps` — concepts from
 Homebrew's cask DSL, documented in the

e2e/cli/test_system_install_brew_cask_appdir_slow

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+
+# Verifies MISE_BREW_CASK_OPT_APPDIR relocates a cask's app artifact out of the
+# default /Applications and into an override directory. Needs a macOS CI runner
+# with network, and is kept out of local runs so it never touches a developer's
+# installed applications.
+if [[ "$(uname)" != "Darwin" ]] || [[ ${CI:-} != "true" ]]; then
+  exit 0
+fi
+
+# The hiddenbar cask hardcodes an absolute `/Applications/Hidden Bar.app`
+# target, which is the exact shape the override has to relocate.
+default_app="/Applications/Hidden Bar.app"
+caskroom="/opt/homebrew/Caskroom/hiddenbar"
+appdir="$PWD/Applications"
+override_app="$appdir/Hidden Bar.app"
+
+# Never run if it would disturb a real installation of this cask.
+if [[ -e $default_app ]] || [[ -e $caskroom ]]; then
+  exit 0
+fi
+
+cleanup() {
+  shopt -s nullglob
+  local app_work_paths=(
+    "$appdir"/Hidden\ Bar.mise-old-*
+    "$appdir"/Hidden\ Bar.mise-tmp-*
+  )
+  chmod -RN "$override_app" "${app_work_paths[@]}" 2>/dev/null || true
+  rm -rf "$override_app" "$caskroom" "$appdir" "${app_work_paths[@]}"
+}
+trap cleanup EXIT
+
+export MISE_BREW_CASK_OPT_APPDIR="$appdir"
+
+cat <<EOF >mise.toml
+[bootstrap.packages]
+"brew-cask:hiddenbar" = "latest"
+EOF
+
+assert_contains "mise bootstrap packages status" "missing"
+mise bootstrap packages apply --yes
+
+# The app must land under the override directory, and must NOT be created in the
+# default /Applications location.
+assert_directory_exists "$override_app"
+assert_directory_exists "$caskroom"
+assert_fail "test -e '$default_app'"
+assert_contains "mise bootstrap packages status" "installed"