SPB Git

Repository Public

README.md 8.0 KB 114 lines markdown

1# MacLustr CC — iOS / iPadOS app23Native SwiftUI client of MacLustr Command Center for iPhone and iPad. Product name `MacLustr`, display name4`MacLustr CC`, bundle id `ai.spboucher.clustr.ios` (Debug: `ai.spboucher.clustr.ios.debug`), team `3YM54G49SN`,5iOS 18.0+, Swift 6 language mode with complete concurrency checking. No WebView, no Catalyst, no UIKit screen: UIKit6is used only for the application delegate (APNs token), the passkey presentation anchor and the hardware-specific7bits SwiftUI does not expose. Everything that is not navigation or layout comes from the shared package8`packages/swift-core` (`MCCCore`): API client, passkeys, session store, event stream, offline cache, repositories,9feature models, formatting, localization, design tokens and the shared SwiftUI components.1011Reference: `docs/APPLE-APPS.md` §11 (entitlements, universal links, push, signing, TestFlight, test matrix, what12remains to be validated on a real device).1314## Layout1516```17project.yml                 XcodeGen spec (the .xcodeproj is generated next to the derived data, never committed)18Support/                    Info.plist / Info-Debug.plist, MCC.entitlements / MCC-Debug.entitlements19Resources/                  Assets (icon, accent colour), String Catalogs (French source + English), one per area20Sources/App/                MCCApp (scenes, commands), AppModel, AppEnvironment, Navigation (sections, routes,21                            Navigator, deep links, state restoration), RootView (phone / pad shells, lock screen),22                            Routes, AppLock, Push23Sources/Shared/             Scaffolding: screen chrome, RouteRow, MutationRunner / MutationButton, DataStamp,24                            ConnectionBanner, InfoRow, TileGrid, RangePicker25Sources/Features/<Area>/    Auth, Overview, Search, Nodes, Alerts, Actions, Services, Models, Jobs, Maintenance,26                            Network, Storage, Activity, Audit, Settings — views + `*Logic.swift` (pure, unit-tested)27Tests/                      unit tests (Swift Testing, hosted by the Debug app)28UITests/                    XCUITest scenarios against a real local backend29Scripts/                    build.sh, test.sh, release.sh, local-backend.sh, seed.sql, ui-test-control.py, make-icon.swift30```3132## Navigation3334- **iPhone** (and an iPad window of compact width): `TabView` — Overview, Nodes, Alerts, Actions, More. "More"35  lists Services, AI Models, Jobs, Maintenance, Network, Storage, Activity, Audit, Settings. One36  `NavigationStack` per tab; rows call `Navigator.open(route)`.37- **iPad** (regular width): `NavigationSplitView` with a sidebar of all sections. Sections that are a list of items38  (Nodes, Alerts, Actions, Services, AI Models, Jobs) show the list and the selected item side by side; the others39  use the whole detail column. ⌘1…⌘9 switch sections, ⌘R refreshes, ⌘F opens the universal search, ⇧⌘N a quick40  maintenance note. Rows have pointer hover effects. Several windows are supported (one `Navigator` per scene).41- The shell is chosen from the horizontal size class: an iPad window narrowed by multitasking switches to the42  tabs and back, keeping the current section.43- State restoration: selected tab / section and the open item (`NavigationSnapshot` in `@SceneStorage`).44- Links: `https://clustr.spboucher.ai/setup#<token>` (invitation; the token is exchanged at once, kept in memory45  only, never logged) and `https://clustr.spboucher.ai/open/<section>[/<uuid>]`. The Debug build also registers the46  scheme `mcc-ios-debug://` so that the same handler can be driven by `xcrun simctl openurl` on a simulator.4748## Rules the app follows4950- Every block of data shows when it was received (`DataStamp`) or how fresh the telemetry is (`FreshnessLabel`);51  `unsupported` / `permission_denied` / `unavailable` / "not reported" are rendered as such, never as 0.52- Mutations go through `MutationRunner` / `MutationButton` or the core form models: disabled while offline (nothing53  is queued), hidden or disabled without the permission, errors shown with the server's message, status and54  correlation id. Confirmation text, justification, approval and step-up are enforced by the server; the app only55  collects and sends them. Step-up is the passkey ceremony run by the core when the server answers56  `403 step_up_required`.57- The app lock (Face ID / Touch ID / passcode) is local: it hides the UI at launch and after backgrounding and58  never replaces sign-in or step-up.59- A notification can only open a screen (alert or action). No action is executed from a notification; the only60  notification action is "Open".61- Design tokens only (`Tokens`, `MCCTheme`, `StatusTone`); state always has an icon and a text; system text styles62  for Dynamic Type, with rows that stack vertically at accessibility sizes; 44 pt minimum targets.63- No reordering between size classes: DOM order = visual order on iPhone and iPad.6465## Build, run, test6667```sh68Scripts/build.sh                       # Debug build for the simulator → /tmp/mcc-ios/DerivedData/…/MacLustr.app69Scripts/local-backend.sh build         # control-api, action-orchestrator, mccctl, mcc-devlogin → /tmp/mcc-ios/70Scripts/local-backend.sh start mcc_ios_test_dev   # control-api on 127.0.0.1:8780, orchestrator health on :878271psql -d mcc_ios_test_dev -f Scripts/seed.sql      # synthetic nodes ios-test-node-01…04 (test databases only)72Scripts/local-backend.sh owner mcc_ios_test_dev owner "Owner"   # prints a one-time setup token7374Scripts/test.sh unit                   # catalogs + unit tests on the iPhone simulator75Scripts/test.sh ui iphone|ipad|both    # XCUITest, real backend + throwaway database (dropped at the end)76MCC_UI_SCREENSHOTS=$PWD/../../docs/screenshots/ios Scripts/test.sh ui both   # also saves the screenshots77```7879Debug-only launch environment (ignored by Release builds, absent from the Release binary): `MCC_BASE_URL`,80`MCC_PASSKEY=software` (software authenticator — real passkeys cannot target `localhost`), `MCC_SECURE_STORE=keychain|file|memory`,81`MCC_LANGUAGE`, `MCC_APPEARANCE`, `MCC_RESET=1`, `MCC_OPEN_URL` (a link handled at launch), `MCC_UITEST=1`82(no notification prompt), `MCC_STATE_DIR`. Example on a booted simulator:8384```sh85SIMCTL_CHILD_MCC_BASE_URL=http://localhost:8780 SIMCTL_CHILD_MCC_PASSKEY=software SIMCTL_CHILD_MCC_SECURE_STORE=file \86SIMCTL_CHILD_MCC_OPEN_URL="mcc-ios-debug://setup#<token>" xcrun simctl launch booted ai.spboucher.clustr.ios.debug87```8889The test scripts create and reuse two dedicated simulators ("MCC iPhone 17 Pro", "MCC iPad Pro 13") so that they90never disturb a simulator another project is using. Derived data and the generated project live under91`/tmp/mcc-ios` (keep them outside `~/Desktop`).9293## Strings9495French is the source language, English the second. One String Catalog per area in `Resources/`; keys are looked up96with `tr("key")` (literal keys, checked statically by `packages/swift-core/Scripts/strings.py check`) or97`trDynamic(key)` (keys built at runtime, listed in `DynamicKeys` / the per-area lists and checked by unit tests).98Add or change entries with `python3 ../../packages/swift-core/Scripts/strings.py add Resources/<Area>.xcstrings`99(TSV on stdin: `key<TAB>français<TAB>English`). The language can be switched at runtime (Settings → Profile).100101## Release (TestFlight)102103```sh104ASC_KEY_ID=L379BDKR69 ASC_ISSUER_ID=<issuer> python3 ../../infra/apple/provision.py --ios   # bundle ids + capabilities105ASC_ISSUER_ID=<issuer> Scripts/release.sh archive    # Release archive + IPA (App Store signature) → dist/ios/106Scripts/release.sh verify                            # signature, profile, entitlements, no Debug code, no ATS exception107ASC_ISSUER_ID=<issuer> Scripts/release.sh upload     # refuses when the App Store Connect record does not exist108```109110Signing is Xcode automatic signing authenticated by the App Store Connect API key (cloud-managed Apple Distribution111certificate, profile "iOS Team Store Provisioning Profile: ai.spboucher.clustr.ios"). The icon is drawn by112`Scripts/make-icon.swift` (1024 px, opaque). `ITSAppUsesNonExemptEncryption` is `NO`: the app only uses HTTPS and113the system's cryptography.114
Files main
Menu

Theme