Fix macOS installer when release artifact is missing

[manuschillerdev]

Summary

• make the macOS full installer select the latest release, then fall back to building that release from source when the darwin server archive is missing
• share the source-build path with BRANCH installs instead of duplicating it
• stop requiring Docker CLI during macOS preflight; Docker remains optional for build workloads
• publish hypeman_<version>_darwin_arm64.tar.gz from the release workflow on a macOS arm64 runner and update checksums.txt
• keep tag releases as drafts until the macOS artifact and merged checksum file are uploaded, so users do not see partially-published releases
• add workflow_dispatch to backfill the macOS artifact for an existing release tag
• document the macOS source-build fallback prerequisites

Closes #273.

Validation

• bash -n scripts/install.sh scripts/install-cli.sh
• git diff --check
• actionlint -ignore 'label "kvm" is unknown' .github/workflows/release.yml
• make sign-darwin
• confirmed https://get.hypeman.sh/cli currently redirects to scripts/install-cli.sh
• confirmed latest release v0.1.0 only has Linux server archives

---

Note

Medium Risk
Installer behavior changes for all macOS release installs (version selection and automatic source builds), which affects first-run reliability and install time but not runtime server logic.

Overview
Fixes macOS full-server installs when GitHub releases lack a darwin server archive (e.g. Linux-only tags).

scripts/install.sh now resolves the latest release tag on macOS (instead of scanning for an artifact like Linux). It tries the prebuilt hypeman_*_darwin_arm64.tar.gz; on 404 or a bad extract, it warns and builds that tag from source via a shared build_server_from_source path (also used for BRANCH). Preflight drops the Docker CLI requirement on macOS; Docker stays optional for the builder image step. VERSION=latest is normalized early; source builds need git/go/make through require_source_build_tools.

README documents the prebuilt-vs-source behavior and that Xcode CLT, Go, and Make are needed for source fallback.

^{Reviewed by Cursor Bugbot for commit 0fe1e42. Bugbot is set up for automated code reviews on this repo. Configure here.}

[firetiger-agent]

Created a monitoring plan for this PR.

What this PR does: Makes the Hypeman macOS full installer work when the latest release doesn't include a pre-built macOS server binary — it now falls back to building from source instead of failing with an error. Docker is no longer required at install time on macOS.

Intended effect:

• macOS install success rate: baseline = 0% (full installer hard-fails when no Darwin artifact exists, as with current v0.1.0); confirmed if macOS users can complete installation using the source-build fallback path without a Docker requirement.
• No production server telemetry exists for installer execution — this is a curl | bash script running on user machines. Confirmation is manual (macOS test run) or inferred from absence of new GitHub Issues reporting macOS install failures.

Risks:

• Missing source-build prerequisites — require_source_build_tools check, alert if users report "git/go/make is required to build from source but not installed" errors (GitHub Issues or user feedback within 48h of merge).
• find_latest_release_tag selects a partially-uploaded release — installer falls back to source build even though the artifact will be available shortly; self-resolving, alert if sustained reports of unexpected source builds appear.
• make sign-darwin fails without signing identity — codesign error during macOS source build; alert if any report of "Build/signing failed" from the new source-build fallback path.

Status updates will be posted automatically on this PR as monitoring progresses.

View monitor

[manuschillerdev]

Added the release-side fix as well: the release workflow now builds and uploads hypeman_<version>_darwin_arm64.tar.gz from a macOS arm64 runner, updates checksums.txt, and supports workflow_dispatch so maintainers can backfill an existing tag such as v0.1.0.

[manuschillerdev]

Addressed the remaining caveats from the monitoring plan: future tag releases are now created as drafts and only published after the macOS artifact plus merged checksums are uploaded, so installers will not see a partially-published latest release. I also validated the macOS source build/signing path with make sign-darwin on darwin/arm64, confirming ad-hoc signing works without a Developer ID identity.

[jarugupj]

Hi @manuschillerdev, thanks for the PR and the quick turnaround on the bugbot findings.

Heads up that parts of #273 were handled in parallel while this was in flight, which is why the issue is closed:

• #282 publishes hypeman_<version>_darwin_arm64.tar.gz via a release-darwin CI job — the latest release (v0.1.1) ships it.
• #281 added scripts/install-cli.sh, and get.hypeman.sh/cli redirects to it.

What's not on main yet and I'd like to land from this PR:

• the source-build fallback in install.sh when the darwin artifact is missing
• dropping the hard Docker CLI requirement in the macOS preflight
• the README note on source-build prerequisites

Could you drop the .github/workflows/release.yml and .goreleaser.yaml changes? The release side is already covered on our end — the macos-14 job produces the artifact (ad-hoc signing works without a Developer ID, per your own validation), v0.1.1 already ships it so there's nothing to backfill, and the source-build fallback covers the partial-publish window anyway.

Once it's trimmed to install.sh + README it should be quick to land.

[manuschillerdev]

hey @jarugupj - thanks for taking the time to review the PR.

I addressed the review feedback: removed the release workflow and GoReleaser changes, leaving only the installer fallback, optional Docker preflight, and README prerequisites updates.

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit d3e5816. Configure here.}