product-spec.md

제품 명세서

목표

Awake는 사용자가 선택한 실행 중 앱/윈도우가 종료될 때까지 macOS 유휴 잠자기를 막는 메뉴바 앱이다. 제품은 신뢰 가능한 전원 assertion, 명확한 상태 표시, 자동 해제, 환경별 한계 안내에 집중한다.

사용자 흐름

보호 세션 시작

1. 사용자가 메뉴바 아이콘을 클릭하거나 전역 단축키를 누른다.
2. Awake가 현재 실행 중인 앱과 감지 가능한 윈도우 목록을 표시한다.
3. 사용자가 하나 이상의 대상을 선택한다.
4. 사용자가 Start를 누른다.
5. Awake가 전원 assertion을 생성하고 세션을 active 상태로 바꾼다.
6. 메뉴바에 active 상태와 선택 대상 수를 표시한다.

보호 세션 유지

• Awake는 선택 대상의 프로세스 생존 여부를 주기적으로 확인한다.
• 선택 대상 중 하나라도 살아 있으면 세션은 유지된다.
• 선택 대상이 모두 종료되면 세션을 자동 종료한다.
• 사용자는 메뉴바에서 언제든 수동 종료할 수 있다.
• 사용자가 전원 관련 설정을 바꾸면 active 세션의 assertion에 즉시 반영한다.

보호 세션 종료

• 자동 종료 조건: 선택한 대상이 모두 종료됨
• 수동 종료 조건: 사용자가 Stop Keeping Awake 선택
• 앱 종료 조건: Awake 종료 시 assertion을 반드시 해제

범위

포함

• macOS 메뉴바 앱
• 실행 중 앱 목록 표시
• 가능한 경우 앱별 윈도우 목록 표시
• 다중 선택
• 전원 assertion 생성/해제
• 선택 대상 종료 감지
• 세션 상태 메뉴바 표시
• 권한 부족 안내
• 기본 설정 저장
• 덮개 닫힘 상태에서 보호 세션을 유지하기 위한 관리자 권한 기반 고급 모드
• 고급 모드 종료 후 macOS sleep 설정 복구

제외

• private API 사용
• 커널 확장 또는 시스템 확장 설치
• 저배터리, 열 보호, MDM 정책, 강제 종료 같은 시스템 보호 동작 우회
• 작업 내용 분석
• 터미널/tmux 세션 내부 프로세스 추적
• 앱별 자동 추천
• iCloud 동기화

덮개 닫힘 정책

Awake는 일반 세션에서 macOS 공개 IOKit assertion을 사용한다. 사용자가 lid-closed 모드를 켜면 최초 1회 관리자 권한을 요청해 LaunchDaemon helper를 설치한다. helper는 세션 신호 파일을 감시하고, 세션 동안 pmset -a disablesleep 1을 적용한 뒤 보호 대상이 종료되거나 사용자가 세션을 멈추거나 앱이 종료될 때 pmset -a disablesleep 0으로 복구한다.

제품이 제공하는 것은 다음이다.

• 선택 대상이 살아 있는 동안 사용자 유휴로 인한 시스템 잠자기를 방지
• 기본 설정으로 사용자 유휴로 인한 디스플레이 잠자기를 방지
• closed-display 환경을 위해 public NetworkClientActive assertion을 best-effort로 함께 사용
• lid-closed 모드에서는 시스템 sleep disabled 설정으로 덮개 닫힘 sleep을 방지
• lid-closed 세션 중 실제 덮개 닫힘 이벤트 또는 clamshell 상태 변경이 확인되면 화면보호기를 실행해 다시 열었을 때 잠금 화면 흐름을 유도
• 메뉴바에서 macOS sleep 설정을 수동 복구할 수 있는 액션 제공

제품이 보장하지 않는 것은 다음이다.

• 사용자가 명시적으로 잠자기를 선택한 상태에서 계속 실행
• 배터리 방전, 저배터리 강제 종료, 열 보호, 회사 관리 정책을 우회한 계속 실행

상태 모델

• idle: 보호 세션 없음
• selecting: 대상 선택 화면 열림
• active: assertion이 켜져 있고 대상 감시 중
• stopping: assertion 해제 중
• error: assertion 생성 실패, 권한 부족, 감시 실패 등 사용자 조치 필요

세션 종료 규칙

선택한 대상 중 하나라도 살아 있으면 보호 세션을 유지한다. 모든 대상이 종료되면 해제한다.

윈도우 단위 선택은 UI에서 제공하되, 현재 종료 감지는 앱 프로세스 단위로 시작한다. 윈도우 단위 자동 종료는 macOS 앱별 윈도우 동작 차이가 크므로 별도 기능으로 정교화한다.

사용자 메시지 원칙

• lid-closed 모드는 관리자 권한으로 시스템 전체 sleep 설정을 바꾸며, 세션 종료 시 복구된다고 안내한다.
• 최초 1회 관리자 권한으로 helper를 설치하면 이후 세션 시작/종료는 반복 비밀번호 없이 처리된다고 안내한다.
• 가방이나 밀폐된 공간에서 사용하지 말라고 안내한다.
• 실패하면 사용자가 다음에 할 행동을 알 수 있게 쓴다.

기본 설정

• 기본 assertion 모드: system sleep 방지 + display sleep 방지 + closed-display best-effort 켬 + lid-closed 모드 켬
• 체크 간격: 5초
• lid-closed 세션 최대 시간: 240분
• lid-closed 배터리 안전 종료 기준: 20%
• 세션 종료 후 알림: 켬
• 메뉴바 active 표시: 켬
• 언어: 시스템 기본 언어를 따름. 설정에서 한국어, 중국어, 일본어, 영어로 변경 가능