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
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.swiftBuild, run, test
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 launchedThe 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
../../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. A403 step_up_requiredtriggers the passkey ceremony and one retry.outcome_unknownis 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/403are 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 themcc-debug://scheme for local testing.