SPB Git

Repository Public

README.md 5.9 KB

# 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.

sh
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 check

# Generated 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

swift
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 watchers

AppSession 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), PasskeyProvider with PlatformPasskeyProvider (production) and SoftwareAuthenticator (DEBUG only), WebAuthnJSON.
  • Session — SecureStore (KeychainSecureStore, InMemorySecureStore, DEBUG DebugFileSecureStore), SessionStore, DeviceInfo.
  • Events — EventStream (SSE on URLSession.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, cancelLoad for 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 explicit unavailable states; 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.

Files main
Menu

Theme