MacLustr CC — iOS / iPadOS app
Native SwiftUI client of MacLustr Command Center for iPhone and iPad. Product name MacLustr, display name
MacLustr CC, bundle id ai.spboucher.clustr.ios (Debug: ai.spboucher.clustr.ios.debug), team 3YM54G49SN,
iOS 18.0+, Swift 6 language mode with complete concurrency checking. No WebView, no Catalyst, no UIKit screen: UIKit
is used only for the application delegate (APNs token), the passkey presentation anchor and the hardware-specific
bits SwiftUI does not expose. Everything that is not navigation or layout comes from the shared package
packages/swift-core (MCCCore): API client, passkeys, session store, event stream, offline cache, repositories,
feature models, formatting, localization, design tokens and the shared SwiftUI components.
Reference: docs/APPLE-APPS.md §11 (entitlements, universal links, push, signing, TestFlight, test matrix, what
remains to be validated on a real device).
Layout
project.yml XcodeGen spec (the .xcodeproj is generated next to the derived data, never committed)
Support/ Info.plist / Info-Debug.plist, MCC.entitlements / MCC-Debug.entitlements
Resources/ Assets (icon, accent colour), String Catalogs (French source + English), one per area
Sources/App/ MCCApp (scenes, commands), AppModel, AppEnvironment, Navigation (sections, routes,
Navigator, deep links, state restoration), RootView (phone / pad shells, lock screen),
Routes, AppLock, Push
Sources/Shared/ Scaffolding: screen chrome, RouteRow, MutationRunner / MutationButton, DataStamp,
ConnectionBanner, InfoRow, TileGrid, RangePicker
Sources/Features/<Area>/ Auth, Overview, Search, Nodes, Alerts, Actions, Services, Models, Jobs, Maintenance,
Network, Storage, Activity, Audit, Settings — views + `*Logic.swift` (pure, unit-tested)
Tests/ unit tests (Swift Testing, hosted by the Debug app)
UITests/ XCUITest scenarios against a real local backend
Scripts/ build.sh, test.sh, release.sh, local-backend.sh, seed.sql, ui-test-control.py, make-icon.swiftNavigation
- iPhone (and an iPad window of compact width):
TabView— Overview, Nodes, Alerts, Actions, More. "More" lists Services, AI Models, Jobs, Maintenance, Network, Storage, Activity, Audit, Settings. OneNavigationStackper tab; rows callNavigator.open(route). - iPad (regular width):
NavigationSplitViewwith a sidebar of all sections. Sections that are a list of items (Nodes, Alerts, Actions, Services, AI Models, Jobs) show the list and the selected item side by side; the others use the whole detail column. ⌘1…⌘9 switch sections, ⌘R refreshes, ⌘F opens the universal search, ⇧⌘N a quick maintenance note. Rows have pointer hover effects. Several windows are supported (oneNavigatorper scene). - The shell is chosen from the horizontal size class: an iPad window narrowed by multitasking switches to the tabs and back, keeping the current section.
- State restoration: selected tab / section and the open item (
NavigationSnapshotin@SceneStorage). - Links:
https://clustr.spboucher.ai/setup#<token>(invitation; the token is exchanged at once, kept in memory only, never logged) andhttps://clustr.spboucher.ai/open/<section>[/<uuid>]. The Debug build also registers the schememcc-ios-debug://so that the same handler can be driven byxcrun simctl openurlon a simulator.
Rules the app follows
- Every block of data shows when it was received (
DataStamp) or how fresh the telemetry is (FreshnessLabel);unsupported/permission_denied/unavailable/ "not reported" are rendered as such, never as 0. - Mutations go through
MutationRunner/MutationButtonor the core form models: disabled while offline (nothing is queued), hidden or disabled without the permission, errors shown with the server's message, status and correlation id. Confirmation text, justification, approval and step-up are enforced by the server; the app only collects and sends them. Step-up is the passkey ceremony run by the core when the server answers403 step_up_required. - The app lock (Face ID / Touch ID / passcode) is local: it hides the UI at launch and after backgrounding and never replaces sign-in or step-up.
- A notification can only open a screen (alert or action). No action is executed from a notification; the only notification action is "Open".
- Design tokens only (
Tokens,MCCTheme,StatusTone); state always has an icon and a text; system text styles for Dynamic Type, with rows that stack vertically at accessibility sizes; 44 pt minimum targets. - No reordering between size classes: DOM order = visual order on iPhone and iPad.
Build, run, test
Scripts/build.sh # Debug build for the simulator → /tmp/mcc-ios/DerivedData/…/MacLustr.app
Scripts/local-backend.sh build # control-api, action-orchestrator, mccctl, mcc-devlogin → /tmp/mcc-ios/
Scripts/local-backend.sh start mcc_ios_test_dev # control-api on 127.0.0.1:8780, orchestrator health on :8782
psql -d mcc_ios_test_dev -f Scripts/seed.sql # synthetic nodes ios-test-node-01…04 (test databases only)
Scripts/local-backend.sh owner mcc_ios_test_dev owner "Owner" # prints a one-time setup token
Scripts/test.sh unit # catalogs + unit tests on the iPhone simulator
Scripts/test.sh ui iphone|ipad|both # XCUITest, real backend + throwaway database (dropped at the end)
MCC_UI_SCREENSHOTS=$PWD/../../docs/screenshots/ios Scripts/test.sh ui both # also saves the screenshotsDebug-only launch environment (ignored by Release builds, absent from the Release binary): MCC_BASE_URL,
MCC_PASSKEY=software (software authenticator — real passkeys cannot target localhost), MCC_SECURE_STORE=keychain|file|memory,
MCC_LANGUAGE, MCC_APPEARANCE, MCC_RESET=1, MCC_OPEN_URL (a link handled at launch), MCC_UITEST=1
(no notification prompt), MCC_STATE_DIR. Example on a booted simulator:
SIMCTL_CHILD_MCC_BASE_URL=http://localhost:8780 SIMCTL_CHILD_MCC_PASSKEY=software SIMCTL_CHILD_MCC_SECURE_STORE=file \
SIMCTL_CHILD_MCC_OPEN_URL="mcc-ios-debug://setup#<token>" xcrun simctl launch booted ai.spboucher.clustr.ios.debugThe test scripts create and reuse two dedicated simulators ("MCC iPhone 17 Pro", "MCC iPad Pro 13") so that they
never disturb a simulator another project is using. Derived data and the generated project live under
/tmp/mcc-ios (keep them outside ~/Desktop).
Strings
French is the source language, English the second. One String Catalog per area in Resources/; keys are looked up
with tr("key") (literal keys, checked statically by packages/swift-core/Scripts/strings.py check) or
trDynamic(key) (keys built at runtime, listed in DynamicKeys / the per-area lists and checked by unit tests).
Add or change entries with python3 ../../packages/swift-core/Scripts/strings.py add Resources/<Area>.xcstrings
(TSV on stdin: key<TAB>français<TAB>English). The language can be switched at runtime (Settings → Profile).
Release (TestFlight)
ASC_KEY_ID=L379BDKR69 ASC_ISSUER_ID=<issuer> python3 ../../infra/apple/provision.py --ios # bundle ids + capabilities
ASC_ISSUER_ID=<issuer> Scripts/release.sh archive # Release archive + IPA (App Store signature) → dist/ios/
Scripts/release.sh verify # signature, profile, entitlements, no Debug code, no ATS exception
ASC_ISSUER_ID=<issuer> Scripts/release.sh upload # refuses when the App Store Connect record does not existSigning is Xcode automatic signing authenticated by the App Store Connect API key (cloud-managed Apple Distribution
certificate, profile "iOS Team Store Provisioning Profile: ai.spboucher.clustr.ios"). The icon is drawn by
Scripts/make-icon.swift (1024 px, opaque). ITSAppUsesNonExemptEncryption is NO: the app only uses HTTPS and
the system's cryptography.