prole/proleStatus/README.md

ProleStatus — macOS overlay bar

ProleStatus is a native macOS AppKit overlay bar that sits directly beneath the system menu bar on the primary display. It matches the menu bar’s width and thickness and uses the same translucent material. The bar is click‑through for normal interaction, supports hover tooltips, and exposes a context menu via a global hotkey.

Features:

• Three centered “traffic light” indicators:
  1. svc.prole.org:443 — green if reachable, red otherwise.
  2. Aggregate K3s: raspberry.prole.org:6443 and pi.prole.org:6443 — green if both, yellow if only one, red if none.
  3. Local k3d: localhost:6443 — green if reachable, red otherwise.
• Periodic TCP health checks with short timeouts and latency measurement.
• Auto‑hide/reposition to mirror the menu bar’s visibility and the active Space.
• Global hotkey: Command+Option+Shift+P opens a context menu with status text, Refresh Now, and Quit.

Minimum: macOS 12 (Monterey)

Build & run (Xcode)

1. Create a new macOS App project in Xcode (AppKit, Swift). Save/open the project under proleStatus/.
2. Remove the main storyboard entry point if present and include Sources/main.swift.
3. Set deployment target to macOS 12+.
4. Add all files from Sources/ to the app target: main.swift, AppDelegate.swift, OverlayWindow.swift, StatusView.swift, HotKeyManager.swift, ServiceChecker.swift.
5. Build & run on “My Mac”. Use Command+Option+Shift+P to open the context menu.

Notes

• The overlay shows only on the primary display, and hides in full‑screen Spaces where the menu bar is hidden.
• Clicks pass through to underlying apps; hover tooltips still work.
• Health checks run every 30 seconds. A HH:mm:ss timestamp is displayed after the last status light. Use the context menu “Refresh Now” to force an immediate update.

Directory layout

• Sources/ — Swift source files for the overlay app.
• .gitignore — ignores Xcode/SwiftPM build artifacts.

Build without Xcode (CLI)

• Requirements: Xcode Command Line Tools (swiftc, codesign, lipo).
• A convenience script build.sh is provided to compile and package a .app bundle without opening Xcode.

Steps:

cd proleStatus
chmod +x build.sh   # first time only

# Build for your current architecture (arm64 on Apple Silicon, x86_64 on Intel)
./build.sh build

# Optionally, build a universal app (arm64 + x86_64)
./build.sh build-universal

# Run the built app
./build.sh run

# Debug: run in foreground with verbose logs to stdout
./build.sh debug

# Package into a zip
./build.sh package

# Clean artifacts
./build.sh clean

Outputs:

• The app bundle is placed at proleStatus/dist/ProleStatus.app.
• The universal build creates a fat binary using lipo.
• The app is ad‑hoc signed for local running (codesign -s -). For distribution/notarization, replace with your signing identity.

Debug mode notes:

• Use ./build.sh debug to run the app binary directly in the foreground with verbose logs.
• The script sets the environment variable PROLESTATUS_DEBUG=1 which enables detailed lifecycle and network probe logging to stdout.
• You will see messages about window placement, menu bar visibility, timer rounds, and per‑host TCP results.
• Press Ctrl+C in the terminal to terminate, or use the app’s context menu → Quit.