Repository Public
1# MacLustr Command Center — macOS23Native macOS application (SwiftUI; AppKit only for the passkey anchor window, save panels, the pasteboard and the4application delegate). No web view, no Catalyst. All data, permissions, confirmations and states come from the5server through the contract (`packages/api-contracts/openapi.yaml`) and the shared package6[`MCCCore`](../../packages/swift-core). Details on bundles, entitlements, signing, notarization, the test matrix7and what is not verified yet: [`docs/APPLE-APPS.md`](../../docs/APPLE-APPS.md).89| | |10|---|---|11| Product name | MacLustr Command Center |12| Bundle id | `ai.spboucher.clustr` (Release), `ai.spboucher.clustr.debug` (Debug) |13| Team | `3YM54G49SN` |14| Deployment target | macOS 15.0 (built with Xcode 27.2, Swift 6 language mode, strict concurrency) |15| Server | `https://clustr.spboucher.ai` in Release; overridable in Debug only (`MCC_BASE_URL`) |1617## Layout1819```20project.yml XcodeGen spec (the .xcodeproj is generated, never committed)21Support/ Info.plist (Release), Info-Debug.plist (ATS local networking, mcc-debug:// scheme), entitlements22Sources/App/ scenes, AppModel, navigation, commands, menu bar extra, notifications, lock, palette23Sources/Shared/ page scaffold, error presentation, mutation guard, schema-driven form24Sources/Features/<area>/ one folder per sidebar section (+ Auth, Actions)25Resources/*.xcstrings String Catalogs, French (source) + English, one per area26Tests/ XCTest (logic and view models, hosted by the Debug app)27UITests/ XCUITest against a real local control-api28Scripts/ build.sh test.sh release.sh notarize.sh verify-release.sh make-icon.swift29```3031## Build, run, test3233```sh34Scripts/build.sh # Debug build → /tmp/mcc-swift/DerivedData/Build/Products/Debug/MacLustr Command Center.app35Scripts/test.sh unit # logic / view-model tests36Scripts/test.sh ui # XCUITest: builds control-api, creates a throwaway database, runs the app against it37Scripts/build.sh Release # needs the Developer ID provisioning profile (infra/apple/provision.py)38Scripts/release.sh # archive, sign, dmg, notarize, staple, verify → dist/macos/39Scripts/verify-release.sh <dmg> # codesign / spctl / stapler / entitlements / no Debug code — nothing is launched40```4142The generated project and the derived data live under `/tmp/mcc-swift` (override with `MCC_DERIVED_DATA`): a build43running from under `~/Desktop` cannot present the system passkey sheet (the system daemon cannot read it, error 1004).4445### Running the Debug build against a local backend4647```sh48../../packages/swift-core/Scripts/local-backend.sh build49../../packages/swift-core/Scripts/local-backend.sh start mcc_swift_dev # control-api on 127.0.0.1:876050TOKEN="$(../../packages/swift-core/Scripts/local-backend.sh owner mcc_swift_dev owner "Owner")" # first owner only51MCC_BASE_URL=http://localhost:8760 MCC_PASSKEY=software MCC_SECURE_STORE=file MCC_SETUP_TOKEN="$TOKEN" \52 "/tmp/mcc-swift/DerivedData/Build/Products/Debug/MacLustr Command Center.app/Contents/MacOS/MacLustr Command Center"53```5455Debug-only launch environment (compiled out of Release, checked by `verify-release.sh`):5657| Variable | Effect |58|---|---|59| `MCC_BASE_URL` | server origin (`http://localhost:8760`) |60| `MCC_PASSKEY=software` | software WebAuthn authenticator instead of system passkeys (needed for `localhost`) |61| `MCC_SECURE_STORE=file\|memory\|keychain` | where the session tokens go (`file` = plain file in the app container, tests only) |62| `MCC_SETUP_TOKEN` | invitation token exchanged at launch (never logged, never stored) |63| `MCC_LANGUAGE=fr\|en` | force the interface language |64| `MCC_RESET=1` | wipe this build's local state at launch |65| `MCC_UITEST=1` | no notification prompt, app lock disabled |6667## Keyboard shortcuts6869| Keys | Action |70|---|---|71| ⌘1 … ⌘9, ⌘0 | Overview, Nodes, Services, AI Models, Jobs, Network, Storage, Alerts, Maintenance, Activity |72| ⌥⌘A / ⌘, | Audit / Settings |73| ⌘K | Command palette (sections, commands, universal search) |74| ⌘F | Search field (universal search, `GET /search`) |75| ⌘R | Reload what is on screen |76| ⇧⌘O | Operations-centre presentation of the overview |77| ⇧⌘N | New maintenance note |78| ⌘N | New main window |79| ⌘[ / ⌘T / ⌘] | Maintenance calendar: previous / today / next |80| ⌃⌘L | Lock (when the local lock is enabled) |81| ⌘↩ / ⎋ | Confirm / cancel a form |82| ⌘/ | This list (Help menu) |8384## Behaviour worth knowing8586- **Authorization is the server's.** The UI hides or disables with the permissions returned by `GET /me`; every87 refusal still comes from the server and is shown with its correlation id.88- **Actions** are forms generated from `GET /action-types` (parameters from the JSON Schema, criticality,89 justification, typed confirmation, approval). The typed confirmation is sent as typed: the server compares it.90 A `403 step_up_required` triggers the passkey ceremony and one retry. `outcome_unknown` is shown as such.91- **Offline**: the last loaded read models are shown read-only from the on-disk cache, with "offline since" and92 "data from" timestamps; controls that change something are disabled and nothing is queued.93- **Not available**: `501` / `503` / `403` are explicit states; no placeholder data is ever displayed.94- **Local lock** (Touch ID / password) is a convenience for an unattended Mac. It never replaces the server's95 authentication or the passkey step-up.96- **Notifications** announce firing and resolved alerts received over the event stream. Clicking opens the alert;97 it never performs an action.98- **Deep links**: `https://clustr.spboucher.ai/setup#<token>` (invitation setup in the app) and `/open/<section>`,99 `/open/{nodes|actions|alerts|incidents|services|jobs|models|maintenance}/<uuid>`. Debug builds also accept the100 `mcc-debug://` scheme for local testing.101