mirror of
https://github.com/dredx/prole.git
synced 2026-09-24 19:44:33 +00:00
197c72dd7a
- Moved prole-tools-app to prole-app at the project root to make it self-contained for transition to its own repository. - Created prole-tools-app/dist/ directory to host build artifacts. - Generated distribution artifacts (Prole Tools.app and Prole Tools.zip) using prole-app/build.sh package. - Checked in the generated artifacts to prole-tools-app/dist/ (bypassing .gitignore for temporary release process). Changes Summary • Renamed directory prole-tools-app/ to prole-app/. • Populated prole-tools-app/dist/ with the latest build output from prole-app/build.sh. • Staged all changes, including the forced addition of ignored artifacts in prole-tools-app/dist/.
123 lines
6.2 KiB
Markdown
123 lines
6.2 KiB
Markdown
```
|
||
#####################################################
|
||
# ╭───────────────────────────────────────────────╮ #
|
||
# │ _ ___ _ _ │ #
|
||
# │ _ __ _ _ ___| |___/ __| |_ __ _| |_ _ _ ___ │ #
|
||
# │ | '_ \ '_/ _ \ / -_)__ \ _/ _` | _| || (_-< │ #
|
||
# │ | .__/_| \___/_\___|___/\__\__,_|\__|\_,_/__/ │ #
|
||
# │ |_| │ #
|
||
# ╰───────────────────────────────────────────────╯ #
|
||
#####################################################
|
||
```
|
||
|
||
Prole
|
||
— macOS status and control surface for Prole endpoints, with a path to an integrated virtual workstation harness.
|
||
|
||
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.
|
||
- The application will evolve to include a virtual workstation surface to coordinate work across a network of Prole‑linked LLMs. The current scope is operational visibility and control of endpoints.
|
||
|
||
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.
|
||
|
||
Roadmap
|
||
- Integration of a virtual workstation to orchestrate a network of Prole‑linked LLMs from within the Prole surface.
|
||
|
||
License
|
||
- See the repository `LICENSE` file.
|