MCCCore
Shared core of the MacLustr Command Center Apple apps. Swift 6 language mode, strict concurrency,
macOS 15 / iOS 18. Depends only on swift-openapi-runtime, swift-openapi-urlsession, swift-http-types.
swift build && swift test # unit tests (URLProtocol stub server)
Scripts/integration-test.sh # + integration tests against a real local control-api (throwaway database)
Scripts/generate.sh [--check] # regenerate (or verify) Sources/MCCCore/Generated from the contract + tokens
xcodebuild -scheme MCCCore -destination 'generic/platform=iOS' build # iOS compile checkGenerated code (never edit)
Sources/MCCCore/Generated/ is produced ahead of time by Scripts/generate.sh and committed:
Types*.swift + Client.swift from packages/api-contracts/openapi.yaml with swift-openapi-generator 1.14.4
(pinned in Scripts/generator/Package.swift; config openapi-generator-config.yaml: types + client, public,
idiomatic names), and Tokens.swift copied from packages/ui-tokens/dist. No build plugin runs in Xcode.
API is an alias of Components.Schemas (API.Node, API.Alert…). The generated types are Codable,
Hashable, Sendable, not Identifiable.
Composition root
let config = CoreConfiguration(origin: CoreConfiguration.productionOrigin,
secureStore: KeychainSecureStore(service: "ai.spboucher.clustr.session", accessGroup: group),
passkeys: PlatformPasskeyProvider { window }, // ASAuthorization, RP clustr.spboucher.ai
cacheDirectory: OfflineCache.defaultDirectory(namespace: "clustr.spboucher.ai"))
let session = AppSession(configuration: config) // @MainActor @Observable
await session.start() // restores the Keychain session, starts the watchersAppSession owns everything a navigation shell needs; a platform only adds its windows / tabs:
| Member | Purpose |
|---|---|
phase (starting / signedOut / signedIn), sessionEndError |
which root screen to show |
signIn(), signOut(), sessionOpened() |
identity entry points (auth for the finer flows) |
me, user, permissions, can(_:) |
what the server granted (UI hints only) |
isOffline, offlineSince, canMutate, streamState, lastEventAt |
banners and disabled states |
setActive(_:) |
call from the scene phase: pauses / resumes the event stream |
account, cluster, nodes, services, models, jobs, alerts, maintenance, actions, audit, infrastructure, admin |
repositories |
search(_:), reloadAll(), addEventHandler(_:) |
universal search, manual refresh, typed events (notifications) |
Layers
- Networking —
APIClient(call { try await $0.getMe().ok.body.json },download(path:query:)), middlewares (error mapping →APIError(status, code, message, correlationID, details, retryAfter), GET-only jittered retries, bearer injection + single-flight refresh, offline guard for mutations),TokenManager,Connectivity,IdempotencyTracker,RequestContext(setup-transaction header),JSONValue. - Auth —
AuthService(signIn,stepUp,withStepUp { },exchangeInvitation,setInvitationProfile,completeInvitation,linkInvitation,addPasskey,signOut),PasskeyProviderwithPlatformPasskeyProvider(production) andSoftwareAuthenticator(DEBUG only),WebAuthnJSON. - Session —
SecureStore(KeychainSecureStore,InMemorySecureStore, DEBUGDebugFileSecureStore),SessionStore,DeviceInfo. - Events —
EventStream(SSE onURLSession.bytes,Last-Event-ID, backoff, heartbeat watchdog,pause/resume),ServerEvent,SSEParser. - Store —
Loadable(idle/loading/loaded(value, receivedAt)/failed/unavailable(reason)),Resource<Value>(+snapshot,isShowingStaleData,scheduleReload,update,cancelLoadfor a view that goes away),ResourceMap, the repositories,Gateway(reads, mutations with step-up, pagination). - Cache —
OfflineCache: one versioned JSON file per read model in Application Support (atomic writes, file protection on iOS, excluded from backups). Chosen over SQLite because the read models are whole snapshots that are replaced, never queried across; a schema change is a version bump that ignores older files. - Formatting —
Format(bytes, percent, durations, relative time, UTC, metric values),Localization+tr(_:)(French default, English; String Catalogs; runtime switch;register(bundle:)for the app's catalogs). - Features (view models shared by both platforms) —
ActionFormModel,ActionRunModel,SchemaField,InvitationSetupModel,SetupLink,SearchModel,CalendarMath,LogsTailModel. - UI (platform-neutral SwiftUI) —
mccThemed()+MCCTheme,StatusTone,StatusBadge,StatusLabel,FreshnessLabel,MetricValueView,MetricSupportRow,UsageMeter,Sparkline,TimeSeriesChart(min–max band, gaps, dash patterns, audio graph),ResourceView,UnavailableStateView,ErrorStateView,InlineErrorView,EmptyStateView,StaleDataBanner,InfoBanner,Card,KeyValueRow.
Rules the package enforces
- No business rule client-side: permissions, confirmations, step-up and states are the server's.
501/503/403/ offline are explicitunavailablestates; a missing measurement is never a number.- Mutations are never retried and are refused locally while offline; nothing is queued.
- Tokens never reach UserDefaults or logs; the invitation token and the setup-transaction token stay in memory.
Strings
Sources/MCCCore/Resources/Localizable.xcstrings (French source + English). Scripts/strings.py add|check
merges and verifies catalogs (also used by the apps). Keys built at runtime (enum labels) are listed by
EnumLabelKeys.all and checked by the tests.