Skip to content

feat: add debug-only FORGE_RUNTIME_BINARY runtime override - #44

Merged
ssddOnTop merged 1 commit into
mainfrom
feat/dev-runtime-binary-override
Aug 4, 2026
Merged

ssddOnTop merged 1 commit into
mainfrom
feat/dev-runtime-binary-override

Conversation

@ssddOnTop

Copy link
Copy Markdown
Collaborator

Summary

Add a debug-only escape hatch (FORGE_RUNTIME_BINARY) so developers can point the macOS menu bar app at a locally built forge3 instead of the managed runtime store, and make the app runnable unbundled by skipping Sparkle when there is no .app bundle.

Changes

  • Add DeveloperRuntimeOverride, which resolves FORGE_RUNTIME_BINARY into an InstalledRuntime in DEBUG builds only
  • Add DeveloperOverrideRuntimeInstaller, a RuntimeInstalling wrapper that short-circuits download, staging, and store validation when an override is active
  • Wire the wrapper into AppDelegate runtime setup via wrapIfOverridden
  • Make the Sparkle updater controller optional and only construct it when running from a .app bundle that declares SUFeedURL; hide the "Check for Updates" menu item and log a warning on manual checks otherwise
  • Document the override, its constraints, and the GUI-launch environment caveat in macos/README.md

Key Implementation Details

  • resolve is guarded by #if DEBUG and returns nil unconditionally in release builds, so a shipped app cannot be redirected to an arbitrary binary through the environment.
  • An unset or blank variable is ignored; a value that is relative, missing, a directory, or a non-executable file throws ForgeCoreError.missingExecutable so typos fail loudly instead of silently falling back to the downloaded runtime. wrapIfOverridden logs that error and returns the base installer.
  • The override reports version 0.0.0 so it never sorts as an upgrade, and the existing launch-boundary checks in RuntimePinnedExecutable still apply to the overridden path.
  • Skipping Sparkle unbundled avoids the crash path where Sparkle's configuration failure NSAlert faults inside ImageIO; packaged builds keep the previous behaviour.

Testing

Run the tests added in macos/Tests/ForgeMenuCoreTests/CoreBehaviorTests.swift, which cover override resolution under DEBUG, the release-build nil result, empty/unset variables, and rejection of relative, missing, directory, and non-executable paths. Manually verify with FORGE_RUNTIME_BINARY=/path/to/forge3 .build/debug/ForgeMenuBar and confirm the unbundled debug binary launches without an updater menu item.

@ssddOnTop
ssddOnTop marked this pull request as ready for review August 4, 2026 19:00
@ssddOnTop
ssddOnTop merged commit 9d9aa44 into main Aug 4, 2026
7 checks passed
@ssddOnTop
ssddOnTop deleted the feat/dev-runtime-binary-override branch August 4, 2026 19:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant