brew-cask: handling staged-file-dependent declarations such as AeroSpace's manpage glob

[soodoh]

Summary

How should mise handle valid cask declarations that depend on files only available after archive extraction?

AeroSpace is the example I encountered: its manpage glob prevents Ruby metadata extraction, blocking installation of the app and CLI even though mise currently skips static manpage artifacts. I'd like to agree on a general approach before opening another PR—not add an AeroSpace-specific exception or require changes to individual taps.

This follows the now-closed discussion #13163. The narrower fixes for HOMEBREW_PREFIX (#13199) and nested app names (#13200) have merged; the staged-file-dependent declaration remains a separate issue.

Concrete example

The intended configuration is:

[settings]
experimental = true

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

The AeroSpace 0.21.3-Beta cask contains:

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

Evaluating that unmodified cask with the metadata shim from mise commit 9caff417, using Ruby 4.0.7 and macOS/ARM metadata inputs, fails with:

unsupported cask metadata DSL `staged_path` (RuntimeError)

As a metadata-only experiment, defining staged_path as a nonexistent directory allows extraction to succeed with both ARM and Intel metadata inputs. It retains the app, CLI, three completion binaries, and two structured postflight commands, but the glob matches nothing and silently omits the manuals. No archive was downloaded or application installed in this test; it does not establish end-to-end compatibility.

I don't propose shipping that placeholder workaround: its result depends on filesystem state, and indiscriminately suppressing globs could also hide required app or binary declarations.

Why this needs a design decision

#10671 added explicit skipping of static manpage artifacts so casks containing them could install. That behavior remains in the cask artifact dispatcher.

Here, Ruby evaluates staged_path and the glob before that skip behavior can apply. Making manpage a no-op alone therefore cannot fix it. There are two separable questions: how to represent file-dependent declarations, and whether to install the resulting manuals.

Possible approaches

1. Preserve symbolic declarations; explicitly skip unsupported manpage installation. Represent staged paths and a supported subset of glob/iteration operations without reading the host filesystem. Retain the cask-provided pattern as metadata, then deliberately skip/report the manpage artifact. No hardcoded paths or cask names, and no manpage installer is required. Arbitrary Ruby filtering, transformations, and file reads would need defined semantics or explicit rejection—not guessed results.

2. Resolve deferred declarations and implement manpage installation. Preserve the pattern during metadata extraction, expand it against the extracted archive during installation, and install the manuals. This provides fuller cask support but also needs destination validation, ownership tracking, rollback, upgrade cleanup, and removal. My closed, unmerged #13165 explored this broader approach; I'm not assuming that scope is the preferred solution.

3. Introduce staged evaluation for file-dependent declarations. Discover download information first, then evaluate applicable declarations against real extracted files during installation. This could support more Ruby patterns than symbolic evaluation, but requires separating discovery from lifecycle execution, preserving sandboxing, and defining what dry-run can report without downloading the archive. Manpage installation could still be a separate decision.

Questions

• Would maintainers prefer a bounded symbolic approach or a staged-evaluation model for this class of cask declaration?
• Is explicit omission of dynamic manpages acceptable as an initial compatibility fix, consistent with current static-manpage behavior, or should support include installing them?
• What supported Ruby/glob subset and dry-run guarantees would make a focused first PR acceptable?

I'd like the solution to generalize to other valid casks without per-cask exceptions, while keeping unsupported behavior explicit and the initial scope reviewable.

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

[jdx]

Thanks for writing this up before opening another PR — that was the right call. I dug into it, and I think the framing of all three options is more elaborate than the problem actually needs. There's a fourth answer: match what Homebrew itself serializes.

staged_path is already a solved representation

This isn't an open design question upstream. Homebrew's own API generation expands staged_path into a literal, relocatable string:

// https://formulae.brew.sh/api/cask/cursor-cli.json
"binary": ["$HOMEBREW_PREFIX/Caskroom/cursor-cli/2026.09.15-d2fe57e/dist-package/cursor-agent", ...]

And mise already consumes exactly that shape — generated_caskroom_artifact in src/system/packages/brew/cask/mod.rs maps $HOMEBREW_PREFIX/Caskroom/<token>/<version>/... back onto the extract stage and the temporary caskroom. Combined with the HOMEBREW_PREFIX placeholder from #13199, the missing piece is just the shim method.

I patched a copy of tap_cask_metadata.rb with a small StagedPath string wrapper plus:

def staged_path
  StagedPath.new("$HOMEBREW_PREFIX/Caskroom/#{@token}/#{@version}")
end

and ran it against the unmodified pinned AeroSpace cask (Ruby 4.0.5, macOS arm64 metadata inputs). Extraction succeeds and yields the app, the CLI binary, all three completion binaries with $HOMEBREW_PREFIX targets, and both postflight steps. No Rust changes were needed.

As a parity check on the hardest form — gcloud-cli's uninstall trash: staged_path.dirname/"latest" — the wrapper produces $HOMEBREW_PREFIX/Caskroom/gcloud-cli/latest, byte-identical to Homebrew's published JSON for that cask.

The part to get right: two contexts, two spellings

This is the one real subtlety, and it isn't mentioned in the discussion or in #13165. Homebrew serializes staged_path differently depending on where it appears:

• artifact and uninstall stanzas → the expanded literal $HOMEBREW_PREFIX/Caskroom/<token>/<version>
• flight steps → the unexpanded {{staged_path}} template, or base: "staged_path" (see gcloud-cli's preflight_steps/postflight_steps)

That distinction is load-bearing here. expand_cask_template in cask/flight.rs resolves {{staged_path}} to the temporary staging directory at install time, while $HOMEBREW_PREFIX resolves to the final prefix. So adding a staged_path method to CaskFlightSteps that returns the expanded literal would make a tap cask's #{staged_path} inside a flight block silently point at the wrong directory. Flight context must emit {{staged_path}}.

The Dir[...] glob is a population of one

I cloned homebrew-cask and grepped the whole tap:

• 0 of 7,772 casks use Dir[ at all
• 63 use staged_path, all as plain string interpolation into binary, uninstall, or flight arguments
• 21 of 5,134 declare manpage at all — an artifact type mise has deliberately skipped since feat(brew): add support for font artifact types and extend non-install artifacts #10671

So the glob is an AeroSpace-specific spelling, not a class of cask we're failing to support. Once staged_path is defined, Dir["#{staged_path}/..."] matches nothing and the manpages drop out — which is precisely what Homebrew's own API generator produces for a cask written that way. That's parity with upstream metadata, not a workaround, and it doesn't need a defined glob subset or a staged-evaluation model.

On your concern that the placeholder's "result depends on filesystem state": that's mostly already handled. metadata_sandbox() in tap.rs runs the shim with deny_read: true and an empty allow_read. It isn't perfectly hermetic, though — /tmp, /opt/homebrew and the mise data dir stay readable, and the glob path is relative, so it is CWD-sensitive in principle. I confirmed a directory literally named $HOMEBREW_PREFIX in the working directory does make the glob match. Absurd in practice, but if we want the evaluator to be a guaranteed pure function of (source, token, version, os/arch) rather than incidentally one, stubbing Dir.glob/Dir.[] to return [] is a few more lines.

Answers to your three questions

1. Bounded symbolic, not staged evaluation. Don't separate discovery from lifecycle execution for this. Approach 3's cost isn't justified by one third-party cask.
2. Yes, omitting dynamic manpages is acceptable — and consistent, since static ones are already skipped. Keep manpage installation as a genuinely separate decision; with 21 casks affected and none needing the glob, I'd leave it skipped for now.
3. A focused first PR would be shim-only:
   • staged_path on CaskMetadata returning the expanded $HOMEBREW_PREFIX/Caskroom/<token>/<version> literal
   • staged_path on CaskFlightSteps returning {{staged_path}}, not the literal
   • optionally, stubbed Dir reads for hermetic evaluation
   • a docs note that dynamic manpages are omitted, alongside the existing static-manpage behavior
   • tests alongside the existing tap metadata fixtures in tap.rs

No Rust changes, no new DSL semantics, no per-cask exceptions. That should be very reviewable.

One thing I did not verify: I only ran metadata extraction. No archive was downloaded and nothing was installed, so this doesn't establish end-to-end AeroSpace compatibility — worth confirming in the PR.

AI-assisted — Tool: Claude Code; model: anthropic/claude-opus-5; version: 2.1.236.

[soodoh]

Thanks for the thorough response! Good call, your proposed solution is much simpler & I was able to confirm this should unblock the Aerospace brew-cask example I mentioned.

Opened up a PR for this here: #13369