toki/appsok
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
appsok/agent-ops/rules/project/domain/macos-platform/rules.md
toki 8308e60a6e docs(roadmap): 로드맵과 도메인 규칙을 갱신한다 
security-distribution 및 workflow-integration 마일스톤과 관련 도메인 규칙을 최신화한다.
2026-06-25 11:01:53 +09:00

5.6 KiB
Raw Blame History

domain last_rule_review_commit last_rule_updated_at
macos-platform fea3860d01 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, 최종 응답에 기록하지 않는다.