appsok/agent-ops/rules/project/domain/macos-platform/rules.md

domain	last_rule_review_commit	last_rule_updated_at
macos-platform	no-commit	2026-06-08

macos-platform

목적 / 책임

macOS desktop target의 bundle metadata, entitlement, URL scheme, runner 설정을 담당한다.

포함 경로

• macos/Runner/Info.plist — bundle metadata와 appsok:// URL scheme
• macos/Runner/Configs/ — product name, bundle identifier, build config
• macos/Runner/*.entitlements — sandbox/network 권한
• macos/Runner.xcodeproj/, macos/Runner.xcworkspace/ — Xcode project/workspace 설정
• macos/Flutter/GeneratedPluginRegistrant.swift — Flutter plugin 등록

제외 경로

• 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 책임

주요 구성 요소

• AppInfo.xcconfig — macOS 앱 표시 이름과 bundle id
• Info.plist — URL scheme 등록
• DebugProfile.entitlements, Release.entitlements — sandbox와 network client 권한

유지할 패턴

• 앱 표시 이름은 사용자에게 보이는 이름 AppSok을 유지한다.
• bundle identifier는 com.tokilabs.appsok 기준으로 관리한다.
• URL scheme은 식별자 규칙상 appsok://을 유지한다.
• Jenkins 호출에는 network client entitlement가 필요하다.
• 배포 전에는 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을 기준으로 한다.
• 원격에는 valid codesigning identity가 확인되어 있지만, notary credential profile은 별도 확인 전까지 미확정으로 둔다.

다른 도메인과의 경계

• artifact-flow: deep link payload가 Jenkins job/build/artifact를 가리킬 수 있으나 parsing/권한 확인은 artifact-flow에서 담당한다.
• device-console: ADB 실행 권한과 packaging 제약은 macos-platform에서 관리하고, command semantics는 device-console에서 관리한다.
• app-shell: 앱 이름과 window metadata는 platform 설정에서 관리하고, 화면 layout은 app-shell에서 관리한다.

금지 사항

• entitlement를 넓힐 때 사유 없이 sandbox를 해제하지 않는다.
• macOS 설정 파일을 Flutter 자동 생성물과 충돌하는 방식으로 수동 대량 편집하지 않는다.
• notarization, signing, MDM 배포 전제를 확인하지 않고 배포 가능하다고 단정하지 않는다.