Distribute via Homebrew (jdwit/tap)

[jdwit]

Goal

Let users install the CLI with a one-liner:

brew install jdwit/tap/ytstudio-cli

Approach: custom tap (not homebrew-core)

homebrew-core has notability requirements (roughly 75+ stars/forks, 30+ days, stable releases). At v0.3.1 / alpha / 10 stars we don't qualify yet, and core also forbids apps that mostly wrap a single web API. A personal tap (jdwit/homebrew-tap) is the standard route and gives us full control. Revisit homebrew-core later once the project is more notable.

We already package cleanly for this: ytstudio-cli is on PyPI (sdist + sha256 published), single project.scripts entry points (ytstudio / yts), requires-python >=3.12. A Homebrew Python formula builds an isolated virtualenv and vendors every dependency as a pinned resource, so this is a good fit.

Plan

1. Create the tap repo

• New public repo jdwit/homebrew-tap (Homebrew auto-resolves jdwit/tap to homebrew-tap).
• Layout: Formula/ytstudio-cli.rb, plus a short README with the install command.

2. Author the formula

• Skeleton via brew create --python --tap jdwit/homebrew-tap https://files.pythonhosted.org/.../ytstudio_cli-0.3.1.tar.gz.
• Class YtstudioCli < Formula, include Language::Python::Virtualenv.
• url -> PyPI sdist, sha256 -> 0.3.1 sdist digest (2f3acd080872031552a1e32d2ea9361bc92fff49c911a0311ff7f1a6aabddc5f).
• depends_on "python@3.13" (or @3.12; both are in our classifiers).
• def install; virtualenv_install_with_resources; end.

3. Generate dependency resources

• Run brew update-python-resources Formula/ytstudio-cli.rb to auto-emit pinned resource stanzas for the full transitive tree (typer, rich, google-auth, google-auth-oauthlib, google-api-python-client, packaging, pydantic, ruamel.yaml + their deps - google-api-python-client pulls in a sizeable subtree, so do this with the tool, not by hand).
• Sanity check that no resource resolves to a yanked/incompatible version.

4. Smoke test block

test do
  assert_match "ytstudio", shell_output("#{bin}/ytstudio --help")
  assert_match version.to_s, shell_output("#{bin}/ytstudio --version")
end

(Confirm a --version flag exists; if not, add one or assert on --help only.)

5. Local validation (must pass before tagging)

brew install --build-from-source jdwit/tap/ytstudio-cli
brew test jdwit/tap/ytstudio-cli
brew audit --strict --new --formula jdwit/tap/ytstudio-cli
brew style jdwit/tap/ytstudio-cli

Verify both ytstudio and yts shims land on PATH and run.

6. Automate version bumps on release

• Add a GitHub Actions workflow (in this repo, triggered on published release/tag) that runs brew bump-formula-pr against jdwit/homebrew-tap, updating url + sha256 from the new PyPI sdist. Needs a PAT with access to the tap repo stored as a secret.
• Keeps the formula from going stale on every release.

7. Docs

• README: add a Homebrew section (brew install jdwit/tap/ytstudio-cli) above/alongside the existing install instructions.
• mkdocs install page: same.

Open questions / decisions

• Pin to python@3.13 or python@3.12? (Default to 3.13; revisit if a dep lags.)
• Does a --version flag exist for the test block? Confirm or add.
• Tap README minimal vs. listing all formulae - minimal for now.

Out of scope

• homebrew-core submission (later, once notable enough).
• Bottling/prebuilt binaries (tap formulae build from source; fine for a Python CLI).