69 lines
4.6 KiB
Markdown
69 lines
4.6 KiB
Markdown
---
|
|
domain: macos-platform
|
|
last_rule_review_commit: c1c4c41886f44727ad5b9297ec164198d1dd5bd9
|
|
last_rule_updated_at: 2026-06-14
|
|
---
|
|
|
|
# macos-platform
|
|
|
|
## 목적 / 책임
|
|
|
|
macOS desktop target의 bundle metadata, entitlement, URL scheme, runner 설정, bundled ADB resource packaging, certified build/signing/notarization tooling을 담당한다.
|
|
|
|
## 포함 경로
|
|
|
|
- `macos/Runner/Info.plist` — bundle metadata와 `appsok://` URL scheme
|
|
- `macos/Runner/Configs/` — product name, bundle identifier, build config
|
|
- `macos/Runner/AppDelegate.swift`, `macos/Runner/MainFlutterWindow.swift`, `macos/Runner/Base.lproj/` — macOS app/window/menu runner wiring
|
|
- `macos/Runner/*.entitlements` — sandbox/network 권한
|
|
- `macos/Runner/Resources/adb-runtime/` — bundled ADB runtime metadata와 NOTICE
|
|
- `macos/Runner.xcodeproj/`, `macos/Runner.xcworkspace/` — Xcode project/workspace 설정
|
|
- `macos/Flutter/GeneratedPluginRegistrant.swift` — Flutter plugin 등록
|
|
- `scripts/build-certified-macos.sh` — Flutter gate, Developer ID signing, notarization, final zip 생성
|
|
- `scripts/setup-appsok-ci-secrets.sh` — SOPS age key, encrypted CI secret, notary profile setup
|
|
- `.sops.yaml`, `secrets/*.sops.json` — encrypted CI signing/notary input 설정과 암호화 payload
|
|
|
|
## 제외 경로
|
|
|
|
- `lib/src/services/jenkins_client.dart` — network 호출 자체는 `artifact-flow` 책임
|
|
- `lib/src/services/adb_service.dart` — ADB command wrapper는 `device-console` 책임
|
|
- `lib/src/theme/` — 시각 스타일은 `app-shell` 책임
|
|
- `agent-test/` — 검증 명령 라우팅은 테스트 룰 책임
|
|
|
|
## 주요 구성 요소
|
|
|
|
- `AppInfo.xcconfig` — macOS 앱 표시 이름과 bundle id
|
|
- `Info.plist` — URL scheme 등록
|
|
- `DebugProfile.entitlements`, `Release.entitlements` — sandbox와 network client 권한
|
|
- `Runner.xcodeproj` build phase — pinned Android platform-tools `adb`를 app bundle resource로 복사하고 adhoc sign
|
|
- `GeneratedPluginRegistrant.swift` — `app_links`, `flutter_secure_storage_darwin`, `webview_flutter_wkwebview` plugin 등록
|
|
- `build-certified-macos.sh` — release build, bundled `adb` signing, app signing, notarization/staple/assessment packaging
|
|
- `setup-appsok-ci-secrets.sh` — SOPS-encrypted CI input 생성과 `notarytool` profile 저장
|
|
|
|
## 유지할 패턴
|
|
|
|
- 앱 표시 이름은 사용자에게 보이는 이름 `AppSok`을 유지한다.
|
|
- bundle identifier는 `com.tokilabs.appsok` 기준으로 관리한다.
|
|
- URL scheme은 식별자 규칙상 `appsok://`을 유지한다.
|
|
- Jenkins 호출에는 network client entitlement가 필요하다.
|
|
- Release entitlement는 필요 권한만 유지하고, Debug/Profile 권한과 차이가 있으면 목적을 명확히 둔다.
|
|
- bundled ADB는 `source.properties`의 pinned `Pkg.Revision`과 실제 `adb version`을 맞춘 뒤 app resource로 복사한다.
|
|
- app bundle 안의 `adb-runtime/adb`는 app signing/notarization 전에 별도로 codesign 검증한다.
|
|
- CI signing/notary secret은 SOPS-encrypted payload와 macOS Keychain profile로만 다루고 raw password/key를 tracked 문서나 로그에 남기지 않는다.
|
|
- 배포 전에는 sandbox 상태에서 ADB binary 실행과 USB 접근 가능 여부를 macOS host에서 검증한다.
|
|
- macOS build/signing 검증은 local container가 아니라 standard remote Mac runner `toki@toki-labs.com`의 `$HOME/docker/services/code-server/data/volume/workspace/appsok` checkout을 기준으로 한다.
|
|
- certified build script는 `flutter analyze`, `flutter test`, `flutter build macos` gate 이후 signing/notarization/package 순서를 유지한다.
|
|
- 원격에는 valid codesigning identity가 확인되어 있지만, notary credential profile은 profile availability 확인 전까지 미확정으로 둔다.
|
|
|
|
## 다른 도메인과의 경계
|
|
|
|
- **artifact-flow**: deep link payload가 Jenkins job/build/artifact를 가리킬 수 있으나 parsing/권한 확인은 artifact-flow에서 담당한다.
|
|
- **device-console**: bundled ADB resource, sandbox, codesign, packaging 제약은 macos-platform에서 관리하고, runtime 선택과 command semantics는 device-console에서 관리한다.
|
|
- **app-shell**: 앱 이름과 window metadata는 platform 설정에서 관리하고, 화면 layout은 app-shell에서 관리한다.
|
|
|
|
## 금지 사항
|
|
|
|
- entitlement를 넓힐 때 사유 없이 sandbox를 해제하지 않는다.
|
|
- macOS 설정 파일을 Flutter 자동 생성물과 충돌하는 방식으로 수동 대량 편집하지 않는다.
|
|
- notarization, signing, MDM 배포 전제를 확인하지 않고 배포 가능하다고 단정하지 않는다.
|
|
- SOPS key, keychain password, Apple ID password, notary credential 원문을 tracked 파일, task log, 최종 응답에 기록하지 않는다.
|