toki/appsok
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
appsok/agent-ops/rules/project/rules.md

4.9 KiB
Raw Blame History

AppSok 프로젝트 규칙

응답 언어

  • 사용자가 다르게 요청하지 않는 한 한국어로 답변한다.
  • 코드 식별자, 명령어, 파일 경로, Jenkins/ADB 용어는 원문 영문을 유지한다.

프로젝트 개요

  • AppSok은 Jenkins Android artifact를 Mac에서 조회/다운로드하고 USB로 연결된 Android 기기에 ADB로 설치하는 Flutter macOS 앱이다.
  • 현재 상태는 초기 scaffold이며, 실제 Jenkins 인증/다운로드/설치 연결 전 UI, 모델, 서비스 골격이 분리되어 있다.
  • 보안 기본 방향은 사용자별 Jenkins API token을 macOS Keychain에 저장하고, 앱 번들에는 공용 secret을 넣지 않는 것이다.

기술 스택

  • Flutter stable / Dart 3.11 계열
  • macOS desktop target
  • http: Jenkins Remote API 호출
  • flutter_secure_storage: macOS Keychain 기반 credential 저장
  • webview_flutter: Jenkins Web Login 후보
  • app_links: appsok:// deep link 후보. URL scheme과 package/bundle id의 소문자 appsok은 식별자용으로 유지하고, 사용자 표시명은 AppSok으로 통일한다.
  • Dart Process: adb devices, adb install, adb logcat 실행

주요 구조

  • lib/main.dart, lib/src/app.dart: 앱 진입점과 MaterialApp 구성
  • lib/src/features/**: 화면 단위 feature
  • lib/src/models/**: Jenkins build, ADB device 등 순수 모델
  • lib/src/services/**: Jenkins, token storage, ADB 외부 연동
  • lib/src/theme/**: 앱 전역 theme
  • macos/Runner/**: macOS 표시 이름, entitlements, URL scheme 등 플랫폼 설정
  • test/**: Flutter widget/unit 테스트

프로젝트 컨벤션

  • UI는 feature별 폴더 아래에 두고, Jenkins/ADB 외부 호출은 services로 분리한다.
  • Jenkins token, LDAP credential, private endpoint 원문은 tracked 파일에 기록하지 않는다.
  • 앱 번들에 Jenkins 공용 API token이나 service account credential을 넣지 않는다.
  • Jenkins API 호출은 사용자별 credential과 Jenkins 권한 모델을 기본 전제로 한다.
  • ADB 명령은 AdbService를 통해 실행하고, 화면 코드에서 Process를 직접 호출하지 않는다.
  • macOS entitlement, URL scheme, sandbox 변경은 macos-platform domain rule을 먼저 확인한다.
  • split APK/APKS/AAB 지원은 아직 구현 범위가 아니므로 단일 APK 흐름과 분리해 설계한다.

검증 기준

  • Dart/Flutter 코드 변경 후 기본 검증은 flutter analyze와 flutter test로 한다.
  • macOS platform 파일 변경은 macOS host에서 flutter run -d macos 또는 flutter build macos 확인이 필요하다.
  • local 테스트 환경의 기본 evidence는 standard remote Mac runner toki@toki-labs.com 기준으로 판단한다. 기본 checkout은 $HOME/docker/services/code-server/data/volume/workspace/appsok이다.
  • Flutter web preview가 필요한 경우 workspace project-owned slot 13050을 사용한다. 일반 Flutter unit/analyze/macOS build 검증은 public port를 사용하지 않는다.
  • 현재 Linux/container checkout에서의 git diff --check, flutter analyze, flutter test는 편집 직후 preflight로 사용할 수 있지만, Flutter/macOS/ADB/runtime evidence가 필요한 완료 검증은 remote runner에서 수행한다.
  • 2026-06-08 조회 기준 remote runner에는 Flutter, Xcode 26.0.1, Android SDK/ADB, macOS desktop device, Android emulator, valid codesigning identity가 있다. Notary credential profile은 확인되지 않았으므로 notarization 가능으로 단정하지 않는다.
  • SSH password, Jenkins credential, signing key, notary credential 원문은 tracked 파일, task log, 최종 응답에 기록하지 않는다.

도메인 매핑

경로 패턴 도메인 rules.md
lib/main.dart, lib/src/app.dart, lib/src/features/app_shell.dart, lib/src/models/pending_install.dart, lib/src/theme/** app-shell agent-ops/rules/project/domain/app-shell/rules.md
lib/src/features/builds/**, lib/src/features/settings/**, lib/src/models/jenkins_build.dart, lib/src/services/jenkins_client.dart, lib/src/services/jenkins_artifact_session.dart, lib/src/services/artifact_staging_service.dart, lib/src/services/token_store.dart artifact-flow agent-ops/rules/project/domain/artifact-flow/rules.md
lib/src/features/devices/**, lib/src/features/console/**, lib/src/models/adb_device.dart, lib/src/services/adb_service.dart device-console agent-ops/rules/project/domain/device-console/rules.md
macos/** macos-platform agent-ops/rules/project/domain/macos-platform/rules.md
scripts/build-certified-macos.sh, scripts/setup-appsok-ci-secrets.sh, .sops.yaml, secrets/*.sops.json macos-platform agent-ops/rules/project/domain/macos-platform/rules.md

스킬 라우팅

현재 프로젝트 전용 skill은 없다. 반복되는 Jenkins/ADB 구현 절차가 안정화되면 agent-ops/skills/project/ 아래에 추가한다.