SPB Git

Repository Public

README.md 5.9 KB

# MacLustr Command Center — macOS

Native macOS application (SwiftUI; AppKit only for the passkey anchor window, save panels, the pasteboard and the application delegate). No web view, no Catalyst. All data, permissions, confirmations and states come from the server through the contract (packages/api-contracts/openapi.yaml) and the shared package MCCCore. Details on bundles, entitlements, signing, notarization, the test matrix and what is not verified yet: docs/APPLE-APPS.md.

Product name MacLustr Command Center
Bundle id ai.spboucher.clustr (Release), ai.spboucher.clustr.debug (Debug)
Team 3YM54G49SN
Deployment target macOS 15.0 (built with Xcode 27.2, Swift 6 language mode, strict concurrency)
Server https://clustr.spboucher.ai in Release; overridable in Debug only (MCC_BASE_URL)

# Layout

text
project.yml                 XcodeGen spec (the .xcodeproj is generated, never committed)
Support/                    Info.plist (Release), Info-Debug.plist (ATS local networking, mcc-debug:// scheme), entitlements
Sources/App/                scenes, AppModel, navigation, commands, menu bar extra, notifications, lock, palette
Sources/Shared/             page scaffold, error presentation, mutation guard, schema-driven form
Sources/Features/<area>/    one folder per sidebar section (+ Auth, Actions)
Resources/*.xcstrings       String Catalogs, French (source) + English, one per area
Tests/                      XCTest (logic and view models, hosted by the Debug app)
UITests/                    XCUITest against a real local control-api
Scripts/                    build.sh  test.sh  release.sh  notarize.sh  verify-release.sh  make-icon.swift

# Build, run, test

sh
Scripts/build.sh                 # Debug build → /tmp/mcc-swift/DerivedData/Build/Products/Debug/MacLustr Command Center.app
Scripts/test.sh unit             # logic / view-model tests
Scripts/test.sh ui               # XCUITest: builds control-api, creates a throwaway database, runs the app against it
Scripts/build.sh Release         # needs the Developer ID provisioning profile (infra/apple/provision.py)
Scripts/release.sh               # archive, sign, dmg, notarize, staple, verify → dist/macos/
Scripts/verify-release.sh <dmg>  # codesign / spctl / stapler / entitlements / no Debug code — nothing is launched

The generated project and the derived data live under /tmp/mcc-swift (override with MCC_DERIVED_DATA): a build running from under ~/Desktop cannot present the system passkey sheet (the system daemon cannot read it, error 1004).

# Running the Debug build against a local backend

sh
../../packages/swift-core/Scripts/local-backend.sh build
../../packages/swift-core/Scripts/local-backend.sh start mcc_swift_dev        # control-api on 127.0.0.1:8760
TOKEN="$(../../packages/swift-core/Scripts/local-backend.sh owner mcc_swift_dev owner "Owner")"   # first owner only
MCC_BASE_URL=http://localhost:8760 MCC_PASSKEY=software MCC_SECURE_STORE=file MCC_SETUP_TOKEN="$TOKEN" \
  "/tmp/mcc-swift/DerivedData/Build/Products/Debug/MacLustr Command Center.app/Contents/MacOS/MacLustr Command Center"

Debug-only launch environment (compiled out of Release, checked by verify-release.sh):

Variable Effect
MCC_BASE_URL server origin (http://localhost:8760)
MCC_PASSKEY=software software WebAuthn authenticator instead of system passkeys (needed for localhost)
MCC_SECURE_STORE=file|memory|keychain where the session tokens go (file = plain file in the app container, tests only)
MCC_SETUP_TOKEN invitation token exchanged at launch (never logged, never stored)
MCC_LANGUAGE=fr|en force the interface language
MCC_RESET=1 wipe this build's local state at launch
MCC_UITEST=1 no notification prompt, app lock disabled

# Keyboard shortcuts

Keys Action
⌘1 … ⌘9, ⌘0 Overview, Nodes, Services, AI Models, Jobs, Network, Storage, Alerts, Maintenance, Activity
⌥⌘A / ⌘, Audit / Settings
⌘K Command palette (sections, commands, universal search)
⌘F Search field (universal search, GET /search)
⌘R Reload what is on screen
⇧⌘O Operations-centre presentation of the overview
⇧⌘N New maintenance note
⌘N New main window
⌘[ / ⌘T / ⌘] Maintenance calendar: previous / today / next
⌃⌘L Lock (when the local lock is enabled)
⌘↩ / ⎋ Confirm / cancel a form
⌘/ This list (Help menu)

# Behaviour worth knowing

  • Authorization is the server's. The UI hides or disables with the permissions returned by GET /me; every refusal still comes from the server and is shown with its correlation id.
  • Actions are forms generated from GET /action-types (parameters from the JSON Schema, criticality, justification, typed confirmation, approval). The typed confirmation is sent as typed: the server compares it. A 403 step_up_required triggers the passkey ceremony and one retry. outcome_unknown is shown as such.
  • Offline: the last loaded read models are shown read-only from the on-disk cache, with "offline since" and "data from" timestamps; controls that change something are disabled and nothing is queued.
  • Not available: 501 / 503 / 403 are explicit states; no placeholder data is ever displayed.
  • Local lock (Touch ID / password) is a convenience for an unattended Mac. It never replaces the server's authentication or the passkey step-up.
  • Notifications announce firing and resolved alerts received over the event stream. Clicking opens the alert; it never performs an action.
  • Deep links: https://clustr.spboucher.ai/setup#<token> (invitation setup in the app) and /open/<section>, /open/{nodes|actions|alerts|incidents|services|jobs|models|maintenance}/<uuid>. Debug builds also accept the mcc-debug:// scheme for local testing.
Files main
Menu

Theme