@zuke/homebrew

`@zuke/homebrew` — ship a prebuilt binary through a

Symbols

BrewAuditSettings

class

class BrewAuditSettings extends BrewCommandSettings

Settings for brew audit. With no formulae named, brew audits every formula it can find.

Member	Signature	Doc
`formulae`	`formulae(...names: string[]): this`	Formulae to audit; repeatable.
`strict`	`strict(): this`	Run the additional, stricter checks (`--strict`).
`online`	`online(): this`	Run the additional checks that need the network (`--online`).
`new`	`new(): this`	Run the checks for a formula new to Homebrew (`--new`), which imply `--strict` and `--online`.
`formula`	`formula(): this`	Treat every name as a formula, not a cask (`--formula`).

BrewCommandSettings

class

class BrewCommandSettings extends BrewSettings

Base for a typed brew subcommand: the verb, then its own flags, then its operands — the order brew's own usage lines print. Anything added through the inherited .command(...)/.flag(...) escape hatches follows.

Operands are refused when they start with -. A formula or tap name never does, and brew would read one that did as an option — so --force passed as a "formula" would change what the command does rather than fail.

BrewFormulaInfo

interface

interface BrewFormulaInfo

One formula, as brew info --json=v2 describes it.

Member	Signature	Doc
`name`	`name: string`	The short name, e.g. `app`.
`fullName`	`fullName: string`	The fully qualified name, e.g. `acme/tap/app`.
`tap`	`tap: string \| null`	The tap it comes from, e.g. `acme/tap`, or `null` for a path formula.
`desc`	`desc: string \| null`	The one-line description, or `null` when it has none.
`homepage`	`homepage: string \| null`	The homepage, or `null` when it has none.
`versions`	`versions: BrewFormulaVersions`	The available versions.
`installed`	`installed: string[]`	The installed versions, oldest first as brew lists them; empty when none.
`linkedKeg`	`linkedKeg: string \| null`	The linked keg's version, or `null` when none is linked.
`outdated`	`outdated: boolean`	Whether an installed version is older than the current one.

BrewFormulaVersions

interface

interface BrewFormulaVersions

A formula's available versions, as brew info reports them.

Member	Signature	Doc
`stable`	`stable: string \| null`	The stable version, or `null` for a HEAD-only formula.
`head`	`head: string \| null`	The HEAD version, or `null` when the formula has no HEAD spec.
`bottle`	`bottle: boolean`	Whether a bottle (a prebuilt package) exists for this platform.

BrewInfo

interface

interface BrewInfo

What brew info --json=v2 reported.

Member	Signature	Doc
`formulae`	`formulae: BrewFormulaInfo[]`	The formulae, in the order brew printed them.

BrewInfoSettings

class

class BrewInfoSettings extends BrewCommandSettings

Settings for brew info, which always runs with --json=v2 — the documented, machine-readable form — so the task can hand back a BrewInfo.

Member	Signature	Doc
`formulae`	`formulae(...names: string[]): this`	Formulae to describe; repeatable.
`formula`	`formula(): this`	Treat every name as a formula, not a cask (`--formula`).
`installed`	`installed(): this`	Describe every installed formula (`--installed`), instead of naming them.

BrewInstallSettings

class

class BrewInstallSettings extends BrewCommandSettings

Settings for brew install. A formula is named by its name, its user/tap/name, or — where Homebrew still allows it — a local .rb path.

Member	Signature	Doc
`formulae`	`formulae(...names: string[]): this`	Formulae to install (required); repeatable.
`formula`	`formula(): this`	Treat every name as a formula, not a cask (`--formula`).
`buildFromSource`	`buildFromSource(): this`	Compile from source even when a bottle exists (`--build-from-source`).
`force`	`force(): this`	Install without checking for keg-only or unmigrated versions (`--force`).
`verbose`	`verbose(): this`	Print the verification and post-install steps (`--verbose`).

BrewLivecheckSettings

class

class BrewLivecheckSettings extends BrewCommandSettings

Settings for brew livecheck, which looks for a newer upstream version.

Member	Signature	Doc
`formulae`	`formulae(...names: string[]): this`	Formulae to check; repeatable.
`json`	`json(): this`	Print the result as JSON (`--json`).
`newerOnly`	`newerOnly(): this`	Report only versions newer than the installed one (`--newer-only`).
`formula`	`formula(): this`	Check only formulae, not casks (`--formula`).

BrewRepositorySettings

class

class BrewRepositorySettings extends BrewCommandSettings

Settings for brew --repository, which prints where Homebrew's repository is — or, given a tap, where that tap's directory is.

Member	Signature	Doc
`tap`	`tap(name: string): this`	The tap whose directory to print, `user/repo`.

BrewSettings

class

class BrewSettings extends SubcommandSettings

Settings for a brew invocation.

BrewStyleSettings

class

class BrewStyleSettings extends BrewCommandSettings

Settings for brew style, Homebrew's RuboCop check. With nothing named it checks Homebrew's own code and every tap.

Member	Signature	Doc
`targets`	`targets(...values: string[]): this`	Files, taps or formulae to check; repeatable.
`fix`	`fix(): this`	Correct what RuboCop can correct (`--fix`).

BrewTapNewSettings

class

class BrewTapNewSettings extends BrewCommandSettings

Settings for brew tap-new, which generates a new, local tap.

Member	Signature	Doc
`name`	`name(tap: string): this`	The tap to create (required), `user/repo`.
`noGit`	`noGit(): this`	Do not initialise a git repository for it (`--no-git`).
`branch`	`branch(name: string): this`	Initialise git on this branch, with its CI workflows (`--branch=`).

BrewTapSettings

class

class BrewTapSettings extends BrewCommandSettings

Settings for brew tap, which adds a formula repository.

Member	Signature	Doc
`name`	`name(tap: string, url?: string): this`	The tap to add (required), `user/repo` — brew clones `github.com/user/homebrew-repo` — and optionally the URL to clone it from instead.
`force`	`force(): this`	Tap a core tap even under API mode (`--force`).

BrewTasks

const

const BrewTasks: BrewTasksApi

Typed task functions for the Homebrew brew CLI.

BrewTasksApi

interface

interface BrewTasksApi

The shape of BrewTasks.

Member	Signature	Doc
`run`	`run(configure?: Configure<BrewSettings>): Promise<CommandOutput>`	Run any `brew` command, built with `.command(...)`/`.flag(...)`.
`install`	`install(configure: Configure<BrewInstallSettings>): Promise<CommandOutput>`	Install formulae (`brew install`).
`uninstall`	`uninstall(configure: Configure<BrewUninstallSettings>): Promise<CommandOutput>`	Uninstall formulae (`brew uninstall`).
`test`	`test(configure: Configure<BrewTestSettings>): Promise<CommandOutput>`	Run installed formulae's `test do` blocks (`brew test`).
`audit`	`audit(configure?: Configure<BrewAuditSettings>): Promise<CommandOutput>`	Audit formulae against Homebrew's rules (`brew audit`).
`style`	`style(configure?: Configure<BrewStyleSettings>): Promise<CommandOutput>`	Check formulae against Homebrew's RuboCop style (`brew style`).
`livecheck`	`livecheck(configure?: Configure<BrewLivecheckSettings>): Promise<CommandOutput>`	Look for newer upstream versions (`brew livecheck`).
`tap`	`tap(configure: Configure<BrewTapSettings>): Promise<CommandOutput>`	Add a tap (`brew tap`).
`untap`	`untap(configure: Configure<BrewUntapSettings>): Promise<CommandOutput>`	Remove taps (`brew untap`).
`tapNew`	`tapNew(configure: Configure<BrewTapNewSettings>): Promise<CommandOutput>`	Generate a new local tap (`brew tap-new`).
`repository`	`repository(configure?: Configure<BrewRepositorySettings>): Promise<string>`	The directory of Homebrew's repository, or of a tap (`brew --repository [tap]`), as a path with the trailing newline removed.
`info`	`info(configure: Configure<BrewInfoSettings>): Promise<BrewInfo>`	Describe formulae (`brew info --json=v2`), parsed into a `BrewInfo`: names, versions and the installed versions.

BrewTestSettings

class

class BrewTestSettings extends BrewCommandSettings

Settings for brew test, which runs a formula's test do block.

Member	Signature	Doc
`formulae`	`formulae(...names: string[]): this`	Installed formulae to test (required); repeatable.
`force`	`force(): this`	Test even when the formula is unlinked (`--force`).
`keepTmp`	`keepTmp(): this`	Keep the temporary files the test created (`--keep-tmp`).
`retry`	`retry(): this`	Retry once if the test fails (`--retry`).

BrewUninstallSettings

class

class BrewUninstallSettings extends BrewCommandSettings

Settings for brew uninstall.

Member	Signature	Doc
`formulae`	`formulae(...names: string[]): this`	Formulae to uninstall (required); repeatable.
`formula`	`formula(): this`	Treat every name as a formula, not a cask (`--formula`).
`force`	`force(): this`	Delete every installed version (`--force`).
`ignoreDependencies`	`ignoreDependencies(): this`	Uninstall even when another formula depends on it (`--ignore-dependencies`).

BrewUntapSettings

class

class BrewUntapSettings extends BrewCommandSettings

Settings for brew untap, which removes taps.

Member	Signature	Doc
`taps`	`taps(...names: string[]): this`	Taps to remove (required), `user/repo`; repeatable.
`force`	`force(): this`	Uninstall the tap's formulae first, rather than refusing (`--force`).

FormulaArch

type

type FormulaArch = arm | intel

The CPU families a formula's on_<arch> blocks name.

FormulaBinary

interface

interface FormulaBinary

A validated binary, as the formula renders it.

Member	Signature	Doc
`os`	`os: FormulaOs`	The operating system.
`arch`	`arch: FormulaArch`	The CPU family.
`url`	`url: string`	The `https` download URL.
`sha256`	`sha256: string`	The archive's SHA-256, 64 lowercase hex digits.

FormulaBinarySettings

class

class FormulaBinarySettings

Settings for one prebuilt binary of a formula, rendered as on_<os> do on_<arch> do url "…" sha256 "…" end end.

s.binary((b) =>
  b.os("macos").arch("arm").url("https://…/app-aarch64-apple-darwin.tar.gz")
    .sha256("…")
)

Member	Signature	Doc
`os`	`os(value: FormulaOs): this`	The operating system the archive runs on (required).
`arch`	`arch(value: FormulaArch): this`	The CPU family the archive runs on (required).
`url`	`url(value: string): this`	Where Homebrew downloads the archive (required; must be `https`).
`sha256`	`sha256(value: string): this`	The archive's SHA-256 (required; 64 lowercase hex digits).
`resolve_`	`resolve_(): FormulaBinary`	Validate the settings into a `FormulaBinary`.
`os_?`	`os_?: FormulaOs`	The operating system. Set by `os`.
`arch_?`	`arch_?: FormulaArch`	The CPU family. Set by `arch`.
`url_?`	`url_?: string`	The download URL. Set by `url`.
`sha256_?`	`sha256_?: string`	The archive's SHA-256. Set by `sha256`.

FormulaOs

type

type FormulaOs = macos | linux

The operating systems a formula's on_<os> blocks name.

FormulaSettings

class

class FormulaSettings

Settings for a formula that installs prebuilt binaries.

Member	Signature	Doc
`name`	`name(value: string): this`	The formula name (required), e.g. `app` or `app@2`: a lowercase letter, then lowercase letters, digits, `-`, `_`, `.`, `+` or `@`. The Ruby class name is derived from it exactly as Homebrew does — `app-cli` defines `AppCli`, `app@2` defines `AppAT2`.
`description`	`description(text: string): this`	The one-line description (`desc`, required), held to `brew audit`'s rules: at most 80 characters, starting with a capital letter, not with an article or the formula's name, and with no trailing period.
`homepage`	`homepage(url: string): this`	The project's homepage (required; must be `https`).
`version`	`version(value: string): this`	The version, e.g. `1.2.3` — set it only when Homebrew cannot read it from the archive URLs. Homebrew detects a formula's version from its URL, and `brew audit` rejects a `version` line that repeats what it detected ("version … is redundant with version scanned from URL"). A GitHub release asset such as `…/releases/download/v1.2.3/app-aarch64-apple-darwin.tar.gz` carries it, so leave this unset there; `expectVersion()` in the test still works, against the detected version. Set it for a URL with no version in it, such as a `…/releases/latest/download/…` link or a content-addressed store.
`license`	`license(spdx: string): this`	The SPDX license identifier, e.g. `MIT`.
`binary`	`binary(configure: Configure<FormulaBinarySettings>): this`	Add a prebuilt archive for one OS and CPU family. Call once per platform; at least one is required, and each OS/arch pair at most once.
`install`	`install(...files: string[]): this`	Files from the archive to place in the formula's `bin` (`bin.install`); at least one is required. Plain file names only — no directory part.
`caveats`	`caveats(text: string): this`	Text Homebrew prints after installing (`def caveats`).
`test`	`test(configure: Configure<FormulaTestSettings>): this`	The formula's `test do` block, which `brew test` runs. Without one, `brew test` (and so `HomebrewTasks.verify`) fails.
`name_?`	`name_?: string`	The formula name. Set by `name`.
`description_?`	`description_?: string`	The one-line description. Set by `description`.
`homepage_?`	`homepage_?: string`	The project's homepage. Set by `homepage`.
`version_?`	`version_?: string`	The version. Set by `version`.
`license_?`	`license_?: string`	The SPDX license. Set by `license`.
`binaries_`	`binaries_: FormulaBinarySettings[]`	The binaries, one per platform. Added by `binary`.
`install_`	`install_: string[]`	The files `bin.install` places. Added by `install`.
`caveats_?`	`caveats_?: string`	The caveats text. Set by `caveats`.
`test_?`	`test_?: FormulaTestSettings`	The `test do` block. Set by `test`.

FormulaTestExpectation

type

type FormulaTestExpectation = unknown | unknown

What a formula test checks the command printed: the version, or a text.

FormulaTestSettings

class

class FormulaTestSettings

Settings for the formula's test do block.

s.test((t) => t.command("--version").expectVersion())
// test do
//   assert_match version.to_s, shell_output("#{bin}/app --version")
// end

Without an expectation the command only has to succeed, and is run with system and an argv — no shell at all.

Member	Signature	Doc
`binary`	`binary(name: string): this`	Which installed binary to run. Defaults to the first one the formula installs; it must be one of them.
`command`	`command(...args: string[]): this`	The arguments to run the binary with, e.g. `"--version"`.
`expectVersion`	`expectVersion(): this`	Require the output to contain the formula's version.
`expectOutput`	`expectOutput(text: string): this`	Require the output to contain `text`.
`render_`	`render_(installed: unknown): string[]`	The block's lines (unindented, without `test do`/`end`), for a formula that installs `installed`.
`binary_?`	`binary_?: string`	The installed binary to run. Set by `binary`.
`args_`	`args_: string[]`	The arguments to run it with. Set by `command`.
`expectation_?`	`expectation_?: FormulaTestExpectation`	What the output must contain. Set by `expectVersion`/`expectOutput`.

HomebrewPublishResult

interface

interface HomebrewPublishResult

What became of a HomebrewTasks.publish call.

Member	Signature	Doc
`state`	`state: created \| updated \| unchanged`	`created` for a formula new to the tap, `updated` for a changed one, `unchanged` when the tap already held exactly this formula and nothing was committed.
`repo`	`repo: string`	The tap's GitHub repository, `owner/homebrew-x`.
`path`	`path: string`	The formula's path in the tap, `Formula/<name>.rb`.
`commitSha?`	`commitSha?: string`	The commit that wrote it; absent when the state is `unchanged`.

HomebrewPublishSettings

class

class HomebrewPublishSettings

Settings for publishing a formula to a tap.

Member	Signature	Doc
`tap`	`tap(value: string): this`	The tap (required): its GitHub repository `owner/homebrew-x`, or brew's short form `owner/x`, which names the same repository.
`formula`	`formula(name: string, source: string): this`	The formula to publish (required): its name, which becomes the file `Formula/<name>.rb`, and its Ruby source — typically what `HomebrewTasks.formula` rendered.
`token`	`token(value: string): this`	The token to write with — needs `contents: write` on the tap repository. Defaults to `GITHUB_TOKEN`, which only works when the tap is the repository the job runs in; a separate tap needs its own token.
`branch`	`branch(name: string): this`	The branch to commit on. Defaults to the tap's default branch.
`message`	`message(text: string): this`	The commit message. Defaults to `<name>: update formula`.
`baseUrl`	`baseUrl(url: string): this`	The API root, for GitHub Enterprise.
`fetch`	`fetch(fn: fetch): this`	Override the `fetch` implementation (a test seam).
`tap_?`	`tap_?: string`	The tap, as given. Set by `tap`.
`name_?`	`name_?: string`	The formula name. Set by `formula`.
`source_?`	`source_?: string`	The formula's Ruby source. Set by `formula`.
`token_?`	`token_?: string`	The token. Set by `token`.
`branch_?`	`branch_?: string`	The branch to commit on. Set by `branch`.
`message_?`	`message_?: string`	The commit message. Set by `message`.
`baseUrl_?`	`baseUrl_?: string`	The API root. Set by `baseUrl`.
`fetch_?`	`fetch_?: fetch`	The `fetch` implementation. Set by `fetch`.

HomebrewTasks

const

const HomebrewTasks: HomebrewTasksApi

Tasks for shipping a prebuilt binary through a Homebrew tap.

HomebrewTasksApi

interface

interface HomebrewTasksApi

The shape of HomebrewTasks.

Member	Signature	Doc
`formula`	`formula(configure: Configure<FormulaSettings>): string`	The Ruby source of a formula that installs prebuilt binaries — one archive per OS and CPU family. Pure: nothing is read or written.
`publish`	`publish(configure: Configure<HomebrewPublishSettings>): Promise<HomebrewPublishResult>`	Write `Formula/<name>.rb` into a tap repository on GitHub, or leave it alone — reporting `unchanged` — when the tap already holds exactly that source.
`verify`	`verify(configure: Configure<HomebrewVerifySettings>): Promise<void>`	Install a formula file through a throwaway local tap, run its test, then uninstall it and remove the tap — the cleanup runs whether or not the install and test succeeded.
`verifyJob`	`verifyJob(configure: Configure<HomebrewVerifyJobSettings>): CiInvocation`	The CI job that runs a verifying target across macOS and Linux runners, ready to list in `cicd({ invokes: [...] })`.

HomebrewVerifyJobSettings

class

class HomebrewVerifyJobSettings

Settings for the formula-verification CI job.

Member	Signature	Doc
`target`	`target(value: TargetBuilder): this`	The target to run (required) — one that calls `HomebrewTasks.verify`, or otherwise installs, tests and uninstalls the formula.
`runners`	`runners(...labels: string[]): this`	The runner labels to verify on, replacing the default `macos-latest` and `ubuntu-latest` — e.g. `"macos-15", "macos-15-intel", "ubuntu-latest"` to cover both Mac CPU families. GitHub's ARM Linux runners (`ubuntu-24.04-arm`) ship without Homebrew, so they cannot verify a formula without installing it first.
`target_?`	`target_?: TargetBuilder`	The target the job runs. Set by `target`.
`runners_`	`runners_: string[]`	The runner labels the job fans out over. Set by `runners`.

HomebrewVerifySettings

class

class HomebrewVerifySettings

Settings for verifying a formula file.

Member	Signature	Doc
`formulaFile`	`formulaFile(path: PathLike): this`	The formula's Ruby source on disk (required), e.g. `dist/app.rb`.
`name`	`name(value: string): this`	The formula's name (required) — the class the file defines is derived from it, and it is installed and tested under it.
`toolPath`	`toolPath(path: PathLike): this`	The `brew` to run, when it is not on `PATH` — on a GitHub Linux runner Homebrew is installed but not on `PATH`: `/home/linuxbrew/.linuxbrew/bin/brew`.
`formulaFile_?`	`formulaFile_?: string`	The formula file to verify. Set by `formulaFile`.
`name_?`	`name_?: string`	The formula's name. Set by `name`.
`toolPath_?`	`toolPath_?: string`	The `brew` binary to run. Set by `toolPath`.