prole/prole-app

#####################################################
# ╭───────────────────────────────────────────────╮ #
# │               _     ___ _        _            │ #
# │  _ __ _ _ ___| |___/ __| |_ __ _| |_ _  _ ___ │ #
# │ | '_ \ '_/ _ \ / -_)__ \  _/ _` |  _| || (_-< │ #
# │ | .__/_| \___/_\___|___/\__\__,_|\__|\_,_/__/ │ #
# │ |_|                                           │ #
# ╰───────────────────────────────────────────────╯ #
#####################################################

Prole — macOS status and control surface for Prole endpoints.

Overview

• Prole provides live reachability and latency signals for Prole service endpoints. It operates in two modes: a regular application window for situational awareness and a minimalist status‑bar overlay for persistent at‑a‑glance status.

Supported platform

• macOS 12.0+ (Monterey or newer) on Apple Silicon (arm64) and Intel (x86_64). Universal builds are supported by the build script.

Execution environment requirements (runtime)

• No external daemons or brew packages are required to run the built app bundle.
• Network access to the configured endpoints.

Build environment requirements

• Xcode Command Line Tools (swiftc, xcrun). Install if needed:

  xcode-select --install
  

• System tools used by the build:
  • iconutil and sips (for .icns generation)
  • codesign (ad‑hoc signing)
  • plutil (plist formatting, via xcrun if needed)

Repository layout (subset)

• prole-app/ — macOS app sources and build system
  • Sources/ — Swift sources (AppKit)
  • build.sh — hermetic CLI build producing a .app bundle
  • prole.properties — default endpoint configuration (bundled into Resources)
  • dist/Prole.app — build output

Build script

• The build is driven by prole-app/build.sh. Typical usage:

  cd prole-app
  ./build.sh build             # build for host arch
  ./build.sh run               # build (if needed) and open the app
  ./build.sh build-universal   # produce a universal (arm64+x86_64) binary
  ./build.sh debug             # run in foreground with verbose logs
  ./build.sh clean             # remove build artifacts
  ./build.sh package           # zip dist/Prole.app into dist/Prole.zip
  

What the script does

• Compiles all Swift sources with swiftc (AppKit, Carbon, Network frameworks).
• Generates Contents/Info.plist with LSUIElement=false so the app can present a standard menu when in Application Window mode.
• Generates an application icon (Prole.icns) and a template status glyph as needed.
• Copies resources:
  • www/images/prole-type.gif → Contents/Resources/prole-type.gif (for the startup tip splash)
  • prole-app/prole.properties → Contents/Resources/prole.properties
• Performs ad‑hoc code signing of the .app bundle.

Alternate build path (installer UI)

• The repository includes install.py, a Tkinter helper that can orchestrate the build. From the repository root:

  python3 install.py
  

• Use the “Build Prole macOS app” step. The installer will produce prole-app/dist/Prole.app and can optionally copy it to /Applications.

Run modes and controls

• Modes:
  • Application Window mode (default): resizable window with three vertical status rows (svc, k3s aggregate, local) and a timestamp in the top‑right. A small control bar bottom‑left exposes Refresh (⟳) and Minimize to Status Bar (_).
  • Status Bar mode: thin overlay aligned with the macOS menu bar; shows a scrolling summary and a 'maximize' button (□) to return to the main window.
• Toggle between modes with the global shortcut:
  • Cmd+Option+Shift+P
• Menus:
  • Application menu “Prole” (next to the Apple menu): Show Status Bar / Show Main Window (same toggle as the hotkey), Refresh Now, Quit.
  • Status‑bar “P” icon (right‑click): Show/Hide Status Bar Icon, Show/Hide Application Window, Refresh Now, Quit.

Configuration

• Endpoint configuration is provided via Java‑style key=value properties. Two locations are read at startup; the user override has precedence:
  1. Bundled defaults: Prole.app/Contents/Resources/prole.properties
  2. User override (optional): ~/Library/Application Support/Prole/prole.properties
• Default keys:
  • svc.host, svc.port
  • k3s.retropie.host, k3s.retropie.port
  • k3s.pi.host, k3s.pi.port
  • k3d.local.host, k3d.local.port
• Example user override:

  # Override core service endpoint
  svc.host=svc.my-domain.tld
  svc.port=443
  
  # Local k3d on a custom port
  k3d.local.port=6445
  

Operational notes

• Status checks are TCP connect probes executed on a background timer (default: 30s). Latency is the connection time in milliseconds; failures record a short diagnostic for tooltips.
• The splash screen is transient (~ 5s) and can be dismissed with a click. It loads prole-type.gif if present in Resources.

Diagnostics & troubleshooting

• Ensure Xcode CLT is installed if the build fails:

  xcode-select --install
  

• If the app launches without a standard menu/window, verify Info.plist has LSUIElement=false (the build script sets this). Rebuild using build.sh.
• If the hotkey appears inactive, bring the app to the foreground or use the Prole menu item (it triggers the same toggle).
• If status indicators stay red, validate network reachability and adjust prole.properties to endpoints reachable from your host.
• For ad‑hoc logging, search the sources for dlog("…") and run via ./build.sh debug to watch stdout.

Security & signing

• The .app bundle is ad‑hoc signed by default. For distribution, replace with a Developer ID signature and notarize as appropriate for your environment.

License

• See the repository LICENSE file.