Document HTTPS Homebrew tap install and SSH update recovery

[tonythethompson]

Summary

Mirror the homebrew-numan guidance: prefer tapping with an explicit HTTPS remote, and document recovery when brew update fails with SSH host-key verification (leaving a stale formula).

Changes

• README install / quick start Homebrew commands use HTTPS tap URL
• docs/PACKAGING.md and docs/RELEASING.md install commands + recovery note
• packaging/homebrew/README.md install + Troubleshooting section
• Formula render comments / snapshot + unit assertion for the HTTPS tap line

Test plan

• python3 -m unittest scripts.test_render_homebrew_formula -v
• Spot-check README Homebrew sections render as intended

[coderabbitai]

Warning

Review limit reached

@tonythethompson, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 59 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 8625842e-e19f-4013-bac4-0a70bf2fdd7d

📥 Commits

Reviewing files that changed from the base of the PR and between 5ad0d21 and 2e94e9c.

📒 Files selected for processing (7)

• README.md
• docs/PACKAGING.md
• docs/RELEASING.md
• packaging/homebrew/README.md
• packaging/homebrew/numan.rb
• scripts/render_homebrew_formula.py
• scripts/test_render_homebrew_formula.py

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[sourcery-ai]

Sorry @tonythethompson, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[qodo-code-review]

PR Summary by Qodo

Document HTTPS Homebrew tap installs and SSH update recovery

📝 Documentation 🧪 Tests 🕐 20-40 Minutes

AI Description

• Update Homebrew install commands to tap via an explicit HTTPS remote.
• Document recovery steps when brew update fails due to SSH host-key verification.
• Align formula header comments and add a unit test asserting the HTTPS tap line.

Diagram

graph TD
  U["User"] --> D["Install docs"] --> B["Homebrew CLI"] --> R[("GitHub tap repo")]
  T["Renderer tests"] --> S["Formula renderer"] --> F["Formula header"]

Loading

High-Level Assessment

The approach is appropriate: documenting the explicit HTTPS tap URL avoids SSH host-key dependencies, and adding a renderer test keeps the guidance from drifting. Alternatives like only adding troubleshooting notes (without changing the commands) would leave most users on the less-reliable default path.

Files changed (7) +62 / -12

Enhancement (1) +2 / -2

render_homebrew_formula.pyRender HTTPS tap guidance in generated formula comments +2/-2

Render HTTPS tap guidance in generated formula comments

• Updates the rendered header comment template to include the HTTPS tap URL and rationale, keeping generated output consistent with docs.

scripts/render_homebrew_formula.py

Tests (1) +4 / -0

test_render_homebrew_formula.pyAssert rendered formula includes HTTPS tap command +4/-0

Assert rendered formula includes HTTPS tap command

• Adds a unit-test assertion that the rendered formula text contains the HTTPS tap command, preventing regressions in generated guidance.

scripts/test_render_homebrew_formula.py

Documentation (5) +56 / -10

README.mdSwitch Homebrew tap examples to explicit HTTPS remote +3/-3

Switch Homebrew tap examples to explicit HTTPS remote

• Updates install/quick-start commands to tap using the HTTPS GitHub URL. Adds rationale explaining this avoids SSH host-key dependency during 'brew update'.

README.md

PACKAGING.mdUse HTTPS tap in packaging spot-check and add recovery steps +12/-2

Use HTTPS tap in packaging spot-check and add recovery steps

• Updates Homebrew spot-check commands and the install matrix entry to use an explicit HTTPS tap remote. Adds a recovery snippet for cases where 'brew update' fails with SSH host-key verification, including untap/retap and reinstall steps.

docs/PACKAGING.md

RELEASING.mdUpdate release-install matrix to use HTTPS tap URL +1/-1

Update release-install matrix to use HTTPS tap URL

• Adjusts the Homebrew install command in the release docs to tap via the HTTPS GitHub URL, matching packaging guidance.

docs/RELEASING.md

README.mdDocument HTTPS tap preference and SSH host-key troubleshooting +38/-2

Document HTTPS tap preference and SSH host-key troubleshooting

• Updates install instructions to prefer an explicit HTTPS remote and explains why. Adds a troubleshooting section with both untap/retap recovery and an in-place git remote fix, plus guidance for 'insteadOf' URL rewrite rules.

packaging/homebrew/README.md

numan.rbAlign formula header comments with HTTPS tap guidance +2/-2

Align formula header comments with HTTPS tap guidance

• Updates the formula’s header comment to show the HTTPS tap command and briefly notes it avoids SSH host-key update failures.

packaging/homebrew/numan.rb

[Copilot]

Pull request overview

Updates Homebrew installation documentation and formula annotations to prefer an explicit HTTPS tap URL (mirroring homebrew-numan guidance) and documents recovery steps when brew update fails due to an SSH remote/host-key verification issue that can leave the tap stale.

Changes:

• Switch Homebrew tap commands in user-facing docs to brew tap … https://github.com/…/homebrew-numan.
• Add troubleshooting/recovery guidance for SSH host-key verification failures during brew update.
• Update the formula renderer comment and unit test to assert the HTTPS tap guidance is present in rendered output.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
scripts/test_render_homebrew_formula.py	Adds an assertion that rendered formula text includes the HTTPS tap command.
scripts/render_homebrew_formula.py	Updates the generated formula header comment to recommend tapping via HTTPS remote.
README.md	Updates Homebrew install and quick-start snippets to use the explicit HTTPS tap URL and adds a brief rationale.
packaging/homebrew/README.md	Updates install instructions and adds a Troubleshooting section with recovery steps for SSH remote failures.
packaging/homebrew/numan.rb	Updates the checked-in formula snapshot comment to match the renderer’s HTTPS tap guidance.
docs/RELEASING.md	Updates the “Homebrew” install command to use the HTTPS tap URL.
docs/PACKAGING.md	Updates Homebrew spot-check commands and adds recovery instructions for stale SSH-cloned taps.

[greptile-apps]

Greptile Summary

This PR updates Homebrew guidance to prefer the explicit HTTPS tap remote and documents recovery from SSH host-key update failures.

• Updates installation commands across the primary and packaging documentation.
• Adds recovery procedures that uninstall the stale formula before untapping and retapping over HTTPS.
• Keeps generated formula comments and renderer tests aligned with the documented command.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
README.md	Updates the Homebrew installation and quick-start commands to use the explicit HTTPS tap remote.
docs/PACKAGING.md	Adds HTTPS installation guidance and fixes the previously reported recovery sequence by uninstalling the formula before untapping.
docs/RELEASING.md	Aligns release documentation with the preferred HTTPS Homebrew tap command.
packaging/homebrew/README.md	Adds detailed SSH host-key troubleshooting with both retap and in-place remote-repair options.
packaging/homebrew/numan.rb	Updates the generated formula header comment to show the HTTPS tap command.
scripts/render_homebrew_formula.py	Updates generated formula comments without changing renderer behavior.
scripts/test_render_homebrew_formula.py	Verifies that rendered formulas include the preferred HTTPS tap command.

_{Reviews (2): Last reviewed commit: "Fix Homebrew recovery: uninstall stale f..." | Re-trigger Greptile}

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (0)

1. Recovery uses brew install ✓ Resolved 🐞 Bug ≡ Correctness

Description

The new tap-recovery instructions describe a stale already-installed formula but run brew install,
which may not replace an existing install, so users can remain on the old version after “recovery”.
The same doc section says it is “reinstalling”, and elsewhere uses brew reinstall, indicating the
intended action is a reinstall/upgrade.

Code

packaging/homebrew/README.md[R41-44]

+brew untap tonythethompson/numan
+brew tap tonythethompson/numan https://github.com/tonythethompson/homebrew-numan
+brew install tonythethompson/numan/numan
+```

Relevance

●●● Strong

Team commonly accepts doc accuracy/consistency fixes; this aligns recovery steps with stated
“reinstall” behavior.

PR-#24
PR-#72
PR-#60

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The PR adds a recovery flow that says it will "reinstall" after switching to HTTPS, but the command
shown is brew install, which conflicts with the stated goal of replacing a stale already-installed
formula; the same README later uses brew reinstall for the same outcome, showing the
inconsistency.

packaging/homebrew/README.md[34-52]
docs/PACKAGING.md[67-75]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The troubleshooting recovery steps for SSH host-key failures switch the tap back to HTTPS but then run `brew install ...`, which often does not replace an already-installed formula (the exact stale-formula scenario the text calls out). This makes the documented recovery unreliable.

## Issue Context
The docs explicitly say installs can keep an old formula, and the section header says the recovery is “reinstalling”, but the commands use `brew install`. In the same file, the alternate path uses `brew reinstall`, which better matches the intent.

## Fix Focus Areas
- packaging/homebrew/README.md[38-52]
- docs/PACKAGING.md[67-75]

## Suggested change
- Replace `brew install tonythethompson/numan/numan` with `brew reinstall tonythethompson/numan/numan` (or `brew upgrade ...`, optionally with a note to use reinstall if upgrade is a no-op). Consider adding `brew update` after re-tapping if you want the sequence to be explicit.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context used

✅ Compliance rules (platform): 27 rules

✅ REVIEW.md

Review mode: ⚖️ Balanced: The change is mostly documentation but also updates formula-generation runtime code and tests across multiple edit sites; it is not skip-eligible, and the breadth does not justify extended review.

_{To customize comments, go to the Qodo configuration screen, or learn more in the docs.}

[qodo-code-review]

Qodo Fixer

No findings are within the configured fix scope. To change which findings are fixed, adjust the setting on your Qodo configuration page.

[linear-code]

TS-164