---
domain: macos-platform
last_rule_review_commit: fea3860d011f006a058506cb1f054407a5975a87
last_rule_updated_at: 2026-06-24
---

# macos-platform

## 목적 / 책임

macOS desktop target의 bundle metadata, entitlement, URL scheme, runner 설정, bundled ADB resource packaging, certified build/signing/notarization tooling, certified Jenkins job provisioning을 담당한다.

## 포함 경로

- `macos/Runner/Info.plist` — bundle metadata와 `appsok://` URL scheme
- `macos/Runner/Configs/` — product name, bundle identifier, build config
- `macos/Runner/Assets.xcassets/` — macOS app icon asset catalog
- `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/RunnerTests/` — macOS Runner XCTest scaffold
- `macos/Flutter/` — Flutter generated xcconfig와 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
- `scripts/upsert-jenkins-certified-job.sh` — certified macOS artifact Jenkins job XML dry-run/create/update
- `.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, SHA-256 sidecar 생성
- `setup-appsok-ci-secrets.sh` — SOPS-encrypted CI input 생성, Jenkins credential input 암호화, `notarytool` profile 저장
- `upsert-jenkins-certified-job.sh` — credential-free SCM URL 기반 `appsok-macos-certified` Jenkins job XML 생성/갱신

## 유지할 패턴

- 앱 표시 이름은 사용자에게 보이는 이름 `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 문서나 로그에 남기지 않는다.
- Jenkins certified job upsert는 dry-run을 기본값으로 두고, SCM URL userinfo를 거부하며, Jenkins credential은 SOPS payload에서 읽어 임시 curl config로만 전달한다.
- certified build 산출물은 `AppSok-certified.zip`과 같은 경로의 `.sha256` sidecar를 함께 생성한다.
- 배포 전에는 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에서 담당한다. certified Jenkins job provisioning은 배포 CI 설정으로 macos-platform 책임이다.
- **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 배포 전제를 확인하지 않고 배포 가능하다고 단정하지 않는다.
- Jenkins job XML이나 SCM URL에 username/password/token을 직접 포함하지 않는다.
- SOPS key, keychain password, Apple ID password, notary credential 원문을 tracked 파일, task log, 최종 응답에 기록하지 않는다.