SPB Git

Repository Public

README.md 8.0 KB

# 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

text
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.swift
  • 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. One NavigationStack per tab; rows call Navigator.open(route).
  • iPad (regular width): NavigationSplitView with 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 (one Navigator per 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 (NavigationSnapshot in @SceneStorage).
  • Links: https://clustr.spboucher.ai/setup#<token> (invitation; the token is exchanged at once, kept in memory only, never logged) and https://clustr.spboucher.ai/open/<section>[/<uuid>]. The Debug build also registers the scheme mcc-ios-debug:// so that the same handler can be driven by xcrun simctl openurl on 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 / MutationButton or 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 answers 403 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

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

Debug-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:

sh
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.debug

The 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)

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

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

Files main
Menu

Theme