Structured cask install steps run in a sandbox that denies network
access. This breaks casks whose upstream setup commands must retrieve
installation-time dependencies, including `gcloud-cli` virtualenv
creation.
- Add a serialised `network_access:` option to `run` steps.
- Omit the option from API data when it retains the default denial.
- Enable network access only when an explicit run requests it.
- Preserve network denial for existing steps and generated completions.
- Document the opt-in and cover both sandbox policies in tests.
This avoids disabling network restrictions for all cask operations while
giving affected casks an explicit, auditable escape hatch.
See #23495.
- reject mixing formula install hooks in every tap
- autocorrect legacy step methods and keywords
- retain stable serialised API values for compatibility
- document canonical Formula and Cask step authoring
- remove the resolved Cask sandbox deprecation reminder
- Run each complete cask step block in one isolated subprocess and all
generated completions in another phase-scoped sandbox.
- Share sandbox selection, fork fallback, install-hook rules and child
error reporting with formula build, post-install and test processes.
- Restrict home, network and filesystem access while preserving `brew`
and supporting explicit command write paths.
- Keep JSON payloads compact and independent of cask Ruby files.
- Remove the completed official-tap migration plan.
Once homebrew/cask is migrated, the style cops can enforce the intended
order for platform blocks and generated artifact DSLs.
- register platform blocks, system variables and generated artifacts
- keep system variables after versions so interpolation remains valid
- remove the temporary completion-grouping migration allowance
- update affected fixtures, documentation and regression coverage
Formula and cask authors need one current reference while released
aliases remain an implementation-only compatibility bridge.
- document shared names, defaults, guards, tokens and command behaviour
- remove compatibility-only methods and values from the cookbooks
- explain ordered coexistence with legacy hooks during tap migration
- Add a generic Formula helper and serialised install step for changing
one Mach-O dynamic library ID.
- Require complete source and ID paths while allowing callers to resolve
a source symlink explicitly.
- Preserve file permissions and codesign modified libraries on Apple
Silicon.
- Document and audit both public interfaces.
Recent formula and cask DSLs need consistent ordering registrations, but
Cask ordering cannot be enforced until the tap has been migrated.
- register new Cask artifact and conditional stanzas in their intended order
- allow both completion layouts while retaining group boundaries
- leave formula component ordering to `ComponentsOrder`
- document the intended Cask stanza order before enforcing it
The `r` and `wireshark` casks were renamed to `r-app` and
`wireshark-app` in Homebrew/homebrew-cask d20f5f8baba
("Differentiate lesser used casks from formulae"), so the
`on_<system>` example links in this section now 404.
Flight hooks repeatedly stop applications or helpers before mutating
their installed state.
- select processes by exact name or full command line
- serialise attempts, privilege and required-success policies
- preserve fixed user notices and final failure warnings
Many remaining hooks invoke one packaged or system executable and do not
need a Ruby block or shell command string.
- serialise literal arguments, environments, streams and directories
- resolve path bases, templates and guards through shared contexts
- make privilege, output and required-success policies explicit
- migrate GIO callers while retaining the shipped compatibility DSL
Command wrapper callers should declare the command users receive rather
than an implementation-specific staged script filename.
- treat the positional argument as the linked command name
- keep generated wrapper paths internal to the artifact
- reject names containing path components
- document command wrappers as the shim-script replacement
- Avoid false homepage audits when sites block automated requests
- Resume automated checks one year after a human browser check
- Do not suppress audits for future browser-check dates
- Reject browser-check metadata without a homepage URL
- Document the marker in the formula and cask cookbooks
Most command wrappers only execute one binary with optional fixed
arguments or environment variables. Repeating their complete shell
content makes casks harder to audit and maintain.
- generate wrappers from `executable`, `args` and `env` options
- infer the linked target by removing the `.wrapper.sh` suffix
- retain `content` for wrappers which need custom shell logic
Some cask flight hooks only materialise a fixed helper before another
artifact or install step consumes it.
- write literal executable content as a serialisable cask artifact
- restrict generated paths to the staged cask and reject traversal
- order generated scripts before dependent installer artifacts
Many cask flight hooks only write a fixed launcher and link it into the
configured binary directory.
- generate executable wrapper content as a first-class cask artifact
- reuse binary linking, collision and uninstall behaviour
- serialise the stanza so cask JSON preserves its definition
Several tap hooks only substitute install-time paths in generated files
and do not need arbitrary Ruby execution.
- expose the familiar `inreplace` name and option defaults
- serialise literal substitutions, regular expressions and their flags
- accept regexp literals in formula and cask step validators
- expand only fixed install-time template tokens
- share validation and execution between formulae and casks
Tap migrations need declarative removal without giving JSON consumers an
arbitrary shell escape.
- serialise guarded path arrays with automatic glob expansion
- restrict removals by symlink target or owned file content
- route elevated cask removals through the existing permission helper
Tap hooks need a serialisable copy operation before they can move to
literal step blocks.
- add file and recursive directory copies to formula and cask steps
- resolve sources, destinations and globs through shared path handling
- include copies in JSON round trips and literal-block validation
- store deterministic language deltas in public and internal API data
- select URLs, checksums and artifacts without loading cask Ruby
- retain source fallback for older API data and legacy flight blocks
- `set_permissions` and `set_ownership` cover common cask flights
- JSON API casks can keep these operations in structured data
- Ownership keeps the existing App Management and sudo guardrails
- Tests cover restrictive umask and App Management denial paths
- The plan now requires tap conversion checks before finishing
- Let cask uninstall steps remove keychain certificates without loading
Ruby flight blocks from API installs.
- Keep the JSON payload to a certificate common name, with optional
`matching_certificate` fingerprint narrowing for shared names.
- Document formula certificate symlinks as structured `ln_sf` steps and
leave one-off trust store generation in legacy Ruby.
- add a shared `write` install step so formulae and casks can ship
default configuration or data files through structured JSON API data
- skip existing files unless `overwrite: true` so user edits survive
upgrades; the DSL signature requires string content and the runner
raises on blank content so malformed API data fails loudly
- append a trailing newline to `write` content unless it already ends
with one, so written files end in a newline as POSIX expects
- accept non-interpolated heredocs (`dstr`) as step arguments so `write`
content can use heredocs; interpolated content stays rejected
- expand a fixed `{{...}}` token allow-list in `write` content at install
time so paths and versions are not baked into the JSON API; any other
`{{...}}` is left verbatim and dynamic interpolation stays legacy Ruby
- allow `write` in formula and cask step blocks so taps can adopt it
ahead of the enforcing RuboCops, per the per-DSL PR workflow
- remove the FAQ section explaining how to bypass Gatekeeper for
apps from unidentified developers, plus its screenshots
- remove the `pkg allow_untrusted` Cask DSL docs and mark the
`allow_untrusted` definitions `# odeprecated` as they disable
certificate verification
- remove "untar anywhere" and "multiple installations" install
instructions that push users to a non-default prefix and source
builds, dropping them below Tier 1
- avoid Ruby-only `post_install` for common desktop cache rebuilds
- keep API steps structured instead of serialising raw commands
- document the stable runtime surface before lint conversions
- Expose structured steps for cask flight phases and API data.
- Prefer steps over matching Ruby flight blocks with warnings.
- Document cask usage and keep conversion audits separate.
- Avoid unsandboxed upstream code when generating cask completions.
- Keep installer scripts on `SystemCommand` because most run installers.
- Document why cask installers and packages are not sandboxed.
- Note that flight blocks are expected to be sandboxed later.
- Keep `HOMEBREW_NO_SANDBOX_CASK` as a temporary escape hatch.
- Preserve completion output by discarding stderr unless requested.
- Support `depends_on maximum_macos:` in casks.
- Treat maximum macOS requirements as macOS-only.
- Reject non-upper-bound cask maximum macOS values.
- Document matching formula and cask OS semantics.
- Support `depends_on :linux` for casks and formulae.
- Fast-path support checks for Linux-only software.
- Document the Linux-only dependency semantics.
- Cover Linux-only and conflicting OS guard paths.
- Treat top-level macOS requirements as macOS-only.
- Preserve existing `:macos` plus `macos:` formulae for release safety.
- Defer style migration to a later release-aware change.
Mike McQuaid