brew-cask: AeroSpace tap Ruby metadata evaluation lacks HOMEBREW_PREFIX on 2026.9.7

[soodoh]

Problem

On mise 2026.9.7, a dry-run for
brew-cask:nikitabobko/tap/aerospace fails while evaluating the tap's Ruby
definition:

Casks/aerospace.rb:22:in 'block in <main>': uninitialized constant HOMEBREW_PREFIX (NameError)

Expected: resolve the cask metadata and produce a dry-run plan.

Actual: metadata evaluation fails before installation or lifecycle execution.

Environment

• macOS 26.6.2 (25G83), arm64
• mise 2026.9.7 macos-arm64 (2026-09-13)
• Ruby 4.0.6 (03b6d3f889, precompiled arm64-darwin23)
• Fish 4.8.1

I reproduced this with an isolated home and isolated mise config, data, cache,
and state directories under /private/tmp. The mise and Ruby installations
were copied into that isolated data directory, and their real binaries—not
shims—were placed on PATH.

The command was run twice and exited 1 both times; the first run used a fresh
cache. No package was installed, upgraded, or removed.

Reproduction

Minimal mise.toml:

min_version = "2026.9.7"

[settings]
experimental = true

[tools]
ruby = "4.0.6"

[bootstrap.packages]
"brew-cask:nikitabobko/tap/aerospace" = { version = "latest", os = "macos" }

With Ruby 4.0.6 already installed and its real binary on PATH:

ruby --version
mise --version
mise --verbose bootstrap packages apply --dry-run \
  brew-cask:nikitabobko/tap/aerospace

The verbose output shows the expected API-first lookup returning 404, followed
by successful retrieval of the pinned Ruby cask:

GET https://raw.githubusercontent.com/nikitabobko/homebrew-tap/HEAD/api/cask/aerospace.json
404 Not Found

GET https://raw.githubusercontent.com/nikitabobko/homebrew-tap/9ac0bfc08904719c52a63101fa7e1e133a23bda2/Casks/aerospace.rb
200 OK

Ruby metadata evaluation then fails:

Casks/aerospace.rb:22:in 'block in <main>': uninitialized constant HOMEBREW_PREFIX (NameError)
        from -e:320:in 'BasicObject#instance_eval'
        from -e:320:in 'Object#cask'
        from Casks/aerospace.rb:1:in '<main>'
        from -e:323:in 'Kernel#eval'
        from -e:323:in '<main>'

Error:
   0: published cask metadata was unavailable (failed to fetch Homebrew cask 'aerospace') and mise could not evaluate Casks/aerospace.rb
   1: failed to evaluate Casks/aerospace.rb
   2: sandbox-exec exited with non-zero status: exit code 1

The pinned AeroSpace cask uses HOMEBREW_PREFIX when declaring shell-completion
binary targets:

https://github.com/nikitabobko/homebrew-tap/blob/9ac0bfc08904719c52a63101fa7e1e133a23bda2/Casks/aerospace.rb#L21-L28

For example:

binary "AeroSpace-v#{version}/shell-completion/zsh/_aerospace",
    target: "#{HOMEBREW_PREFIX}/share/zsh/site-functions/_aerospace"

Reduced metadata-only test

I also tested the unmodified
v2026.9.7 tap_cask_metadata.rb
directly with this fixture:

cask "example" do
  version "1.0"
  sha256 "0000000000000000000000000000000000000000000000000000000000000000"
  url "https://example.invalid/example.zip"
  binary "example", target: "#{HOMEBREW_PREFIX}/bin/example"
end

With the required MISE_BREW_* metadata environment variables set, the shim
exits 1:

Casks/example.rb:5:in 'block in <main>': uninitialized constant HOMEBREW_PREFIX (NameError)

Adding only this line before the cask block:

HOMEBREW_PREFIX = "/opt/homebrew"

allows the same shim to exit 0 and serialize the binary target as:

{"binary":["example",{"target":"/opt/homebrew/bin/example"}]}

This reduced test performs metadata extraction only; it does not fetch or
install the example package.

Related work and question

• Discussion #13053 reported
  the previous AeroSpace metadata failure involving postflight_steps.
• PR #13060 added structured flight-step
  extraction and explicitly noted that it did not establish full AeroSpace
  compatibility because evaluation then reached this separate
  HOMEBREW_PREFIX error.
• PR #12774 introduced fallback
  evaluation of third-party tap Ruby definitions when API JSON is unavailable.

Should the tap cask metadata evaluator expose a HOMEBREW_PREFIX value so
target interpolation can be serialized, or is a tap cask using this constant
intentionally unsupported unless the tap publishes api/cask/<token>.json?

If exposing the constant is intended, should it resolve to mise's
architecture-appropriate Homebrew prefix (/opt/homebrew on arm64 and
/usr/local on Intel), or should metadata preserve a relocatable prefix
placeholder for later resolution?

mise doctor

Full output

version: 2026.9.7 macos-arm64 (2026-09-13)
activated: no
shims_on_path: no
self_update_available: yes

build_info:
  Target: aarch64-apple-darwin
  Features: openssl, rustls-native-roots, self_update
  Built: Sun, 13 Sep 2026 22:58:46 +0000
  Rust Version: rustc 1.98.1 (48a229cea 2026-09-01)
  Profile: release

shell:
  /opt/homebrew/bin/fish
  fish, version 4.8.1

aqua:
  baked in registry: aquaproj/aqua-registry@8223fac92626614415ffc5cd87c1aa6b76a6ba6d
  baked in registry tools: 2301

dirs:
  cache: <REPRO>/cache
  config: <REPRO>/config
  data: <REPRO>/data
  shims: <REPRO>/data/shims
  system_shims: /usr/local/share/mise/shims
  state: <REPRO>/state

config_files:
  <REPRO>/system.toml
  <REPRO>/global.toml
  <REPRO>/config/mise.toml

env_files:
  (none)

ignored_config_files: (none)

backends:
  aqua
  asdf
  cargo
  conda
  core
  dotnet
  forgejo
  gem
  github
  gitlab
  go
  npm
  packslip
  pypi
  pkgx
  spm
  http
  s3
  ubi
  vfox

plugins:

toolset:
  core:ruby@4.0.6

path:
  <REPRO>/data/installs/ruby/4.0.6/bin
  <REPRO>/bin
  /usr/bin
  /bin
  /usr/sbin
  /sbin

Casks/aerospace.rb:22:in 'block in <main>': uninitialized constant HOMEBREW_PREFIX (NameError)
        from -e:320:in 'BasicObject#instance_eval'
        from -e:320:in 'Object#cask'
        from Casks/aerospace.rb:1:in '<main>'
        from -e:323:in 'Kernel#eval'
        from -e:323:in '<main>'

system_packages:

env_vars:
  MISE_CONFIG_DIR=<REPRO>/config
  MISE_SHELL=fish
  MISE_DATA_DIR=<REPRO>/data
  MISE_CACHE_DIR=<REPRO>/cache
  MISE_STATE_DIR=<REPRO>/state
  MISE_GLOBAL_CONFIG_FILE=<REPRO>/global.toml
  MISE_SYSTEM_CONFIG_FILE=<REPRO>/system.toml
  MISE_TRUSTED_CONFIG_PATHS=<REPRO>
  MISE_COLOR=0

settings:
  experimental  true <REPRO>/config/mise.toml

1 warning found:

1. failed to check brew-cask system packages: published cask metadata was unavailable (failed to fetch Homebrew cask 'aerospace') and mise could not evaluate Casks/aerospace.rb

1 problem found:

1. mise is not activated, run mise help activate or
   read the activation documentation. Alternatively, add the isolated shims
   directory to PATH.

The activation warning is expected because this reproduction deliberately uses
an explicit PATH containing the copied real mise and Ruby binaries.

AI-assisted — Tool: Pi; model: openai-codex/gpt-5.6-sol; version: 0.85.1.

[soodoh]

Follow-up: I tested the full pinned AeroSpace cask after manually supplying the missing HOMEBREW_PREFIX constant. Fixing that constant alone does not complete metadata extraction; evaluation advances to a second error:

Casks/aerospace.rb:29:in 'block in <main>': unsupported cask metadata DSL `staged_path` (RuntimeError)

The triggering declaration is:

Dir["#{staged_path}/AeroSpace-v#{version}/manpage/*"].each { |man| manpage man }

https://github.com/nikitabobko/homebrew-tap/blob/9ac0bfc08904719c52a63101fa7e1e133a23bda2/Casks/aerospace.rb#L29

The v2026.9.7 tap metadata evaluator does not define staged_path; current main does not appear to define it either:

https://github.com/jdx/mise/blob/v2026.9.7/src/system/packages/brew/tap_cask_metadata.rb

For isolation, I then supplied both:

HOMEBREW_PREFIX = "/opt/homebrew"

class CaskMetadata
  def staged_path = "/mise-metadata-staged-path"
end

With that inert, nonexistent staged path, the full cask evaluates successfully and emits six artifacts: the structured postflight steps, app, CLI binary, and three completion binaries. The Dir[...] glob matches nothing, however, so all manpage artifacts are silently omitted.

There also does not appear to be a manpage branch in the v2026.9.7 cask artifact parser; an extracted manpage artifact would otherwise fall through to unsupported artifact type:

https://github.com/jdx/mise/blob/v2026.9.7/src/system/packages/brew/cask/artifacts.rs#L3-L59

This was metadata-only testing; no archive was downloaded and no package was installed. It suggests full AeroSpace compatibility needs either support for deferred staged_path glob/manpage declarations or an explicit policy for omitting dynamic manpages, in addition to defining HOMEBREW_PREFIX.

AI-assisted — Tool: Pi; model: openai-codex/gpt-5.6-sol; version: 0.85.1.

[soodoh]

Opened 2 narrowly scoped PRs to address these issues so far:
#13199
#13200

[soodoh]

Will open a separate discussion thread for the dynamic manpages issue seen by the Aerospace homebrew cask.