# CLAUDE.md — Nexa Coffee 프로젝트 컨텍스트 (이식용 메모리) > 다른 PC에서 clone 시 즉시 컨텍스트를 복원하기 위한 휴대용 메모리. **먼저 읽기:** [docs/STATUS.md](docs/STATUS.md) → [docs/10-decision-record.md](docs/10-decision-record.md). ## 0. 응답 언어 — 🔴 항상 한글 - **사용자에게 보이는 모든 글은 한글로 쓴다** — 최종 보고 · 중간 진행 안내 · 질문 · 표 · 요약 전부(사용자 요청 09-26 · 두 번 요청됨). - 코드 · 명령 · 파일 경로 · 식별자 · 로그/오류 원문만 그대로 둔다. 커밋 메시지·문서도 기존대로 한글. - 긴 작업 끝의 보고에서 영어로 돌아가는 일이 있었다 — 보내기 전에 언어를 확인한다. ## 1. 이 프로젝트는 **Nexa Coffee** = 트레이/메뉴바 절전 방지 타이머(Windows · macOS · Linux). **순수 C · 프레임워크 0 · 외부 라이브러리 0 · 극단적 최소화**. - 조직: SosomLab · 개발자: Sangyong Bae · kiros33@gmail.com · 저장소: - 라이선스: **MIT**(누구나 무료 — nexa-shortcut과 동일. beep/clip/dir2의 PolyForm NC와 **다르다**). - 현 단계: **v0.1.5 배포됨(11-07 · release run 42373565671 전부 success · 자산 8종)** — ① **macOS 잠금 중 30초마다 화면 깨움 → loginwindow 창 수천 개 누적·마우스 지연 수정**(DR-17 · T-23 · 사용자 보고 11-05·11-07 · `mac.m screenLockedOrDark`) ② **보안 결함 10건 수정 + 관리 원장 [docs/19](docs/19-security-hardening.md)**(T-24 · 설정 파서 경계 밖 읽기 · 정수 포화 · D-Bus 수신 파서 랩어라운드/NUL/재귀/길이 상한 · `make test-san` ASan+UBSan · test_dbus 퍼징 · CI 단계) ③ 임시 파일 정리 `scripts/tmp-clean.sh`(T-25) · CLAUDE.md §4 규칙 3건(보안·임시 파일·크로스 플랫폼 — nexa-dir3 이식). 두 세션(개발 `개발` · 협업 `협업`) 분담은 nexa-dir3 10-25 합의 기준. 채널: brew cask·formula 0.1.5 ✓ · pkg.sosomlab.com APT 0.1.5 ✓ · **choco `nexa-coffee`·`nexa-coffee-portable` 0.1.5 제출 ✓(이전 버전 승인돼 있었음)** · winget `SosomLab.NexaCoffee`는 #436346 대기로 건너뜀 · Portable 0.1.5 [#474187](https://github.com/microsoft/winget-pkgs/pull/474187)(0.1.4 #454127 대기 중 가드 누락 → `e75c44c` 수정). 남은 사람 손: 맥 실기 [18 ④](docs/18-build-and-test.md#사람이-해야-하는-실기-점검macos). - 0.1.4(10-17) = Windows 배포를 **설치본/포터블로 분리**한 첫 릴리스(앱 코드는 0.1.3과 같음 · DR-16). 자산 `windows-setup.exe` · `windows-{x64,x86}-portable.zip` · brew 0.1.4 ✓ · pkg.sosomlab.com 0.1.4 ✓ · 새 winget `SosomLab.NexaCoffee.Portable` [PR #454127](https://github.com/microsoft/winget-pkgs/pull/454127) · 새 choco `nexa-coffee-portable` 0.1.4 제출 · 기존 `SosomLab.NexaCoffee`([#436346](https://github.com/microsoft/winget-pkgs/pull/436346) 0.1.1)·`nexa-coffee`(0.1.3 검수)는 대기라 건너뜀. - 0.1.3(10-17) = 트레이 메뉴 **"로그인 시 실행"**(3-OS · DR-15 · 진실 원천 = OS 상태) · **Windows 설치본**(NSIS · DR-16 · "로그인 시 실행" 체크박스 기본 해제 · `/S` · `/AUTOSTART=1`) · 언어 ▸ **"시스템 (OS 언어)"**(DR-13 보강). 두 세션(개발·협업) 분담으로 진행(journal 10-16). - 0.1.2(09-26) = **T-19**(Linux 늦게 뜬 트레이 워처 SIGSEGV) 수정 · 16px · Windows 배율 · install.sh. choco 0.1.2 승인 ✓(10-09). - **Windows 실기 사실상 완료**(09-13·09-17): 트레이·툴팁·메뉴 라디오·열린 메뉴 1초 갱신·`powercfg`·i18n(CJK·언어 메뉴·입력 창 라벨 폭)·T-13 메모리·**DR-14 파이프 끝단**. 남은 둘(아이콘 DPI·TaskbarCreated)은 화면 배율·셸을 건드려야 해 [18 실기 점검표](docs/18-build-and-test.md#사람이-해야-하는-실기-점검windows)로 넘겼다. - **v1은 코드 서명이 없다** — SmartScreen·Gatekeeper 경고의 원인이자, 0.1.0 x86이 Defender 오탐(`Trojan:Win32/Tecabans.STV!cl`)으로 격리된 근본 원인. 0.1.1에서 **PE 버전 리소스**를 넣어 완화했다(09-17 실측: 0.1.0 x86 격리 / 0.1.1 x86 통과). ### 참조 원천(재발명 금지) | 원천 | 경로 | 무엇을 가져왔나 | | --- | --- | --- | | **nexa-shortcut** | `../kiros33/nexa-shortcut` | ★ 초경량 원칙 — CRT 미링크 · `-nostdlib` · 진입점 `start` · Makefile/build.bat · 크기 예산 CI · winget/choco 포터블 | | **nexa-clip** | `../kiros33/nexa-clip` | 트레이 계약 — SNI 속성 · dbusmenu 레이아웃(`nclip-plat/src/tray.rs::sni`) · macOS NSStatusItem · 패키징/릴리스 워크플로 · 문서 규약(docs/16) | | **nexa-sql · linux-repo** | `../kiros33/nexa-sql` · `../kiros33/linux-repo` | pkg.sosomlab.com(APT·RPM) — 등록 `apps/nexa-coffee.toml` · deb/rpm 포장(`packaging/linux/build-pkgs.sh`) · 발행 신호(`linux-packages.yml`) | | **nexa-beep / nexa-dir2** | `../kiros33/…` | 브랜딩 계열 규칙(라운드 스퀘어 rx 232 · 세로 그라디언트) · 문서 4층 체계 | ## 2. 확정 결정(요약 — 전문 [docs/10](docs/10-decision-record.md)) | # | 결정 | | --- | --- | | DR-1 | **C**로 쓴다(맥은 .m 한 파일). Rust std만으로도 수백 KB라 "극단적 최소화"에 안 맞는다 | | DR-2 | 코어(`src/core`)는 **libc·부동소수점·힙 금지** — 정수 래스터라이저 · 3-OS 동일 픽셀 · Windows CRT 미링크 가능 | | DR-3 | Linux는 **libdbus 없이 D-Bus를 직접 구현**(`src/plat/dbus.c`) → musl 정적 · libc 하나 | | DR-4′ | UI = 메뉴 + **입력 창 1개**(일·시·분 숫자 + 시작/저장) + About. 서브메뉴 방식은 사용자 QA로 폐기(09-12) | | DR-5 | 대기 아이콘(`icon_idle.c`)과 동작 아이콘(`icon_active.c`)은 **별도 모듈** · 대기 = 앱 아이콘 모티프 단색 | | DR-6 | 메뉴 트리는 코어(`app.c`)에 한 번만 두고 각 OS가 그대로 네이티브 메뉴로 옮긴다 | | DR-7 | 작업 종료 시 메모리 회수 — 아이콘 버퍼 free + OS별 반납(`SetProcessWorkingSetSize` / `malloc_zone_pressure_relief` / `malloc_trim`) | | DR-14 | **창은 자식 프로세스**(입력 창·About) — 자기 자신 `--dialog`/`--about` 재실행 · stdout 파이프. 프레임워크 텍스트 캐시가 프로세스 안에선 안 돌아와서(09-13 실측) | | DR-8 | 덮개 닫힘은 Windows·macOS에선 관리자 정책 영역 — 앱이 손대지 않고 문서에 명시. Linux만 logind로 막는다 | | DR-13 | i18n = 코어 문구 블록(언어당 NUL 구분 문자열 1개 · 포인터 테이블 없음). "언어 ▸" 메뉴에서 고른 뒤에만 `lang=` 저장, 아니면 OS 로케일 자동. **10-16 보강**: 서브메뉴 맨 위 "시스템 (OS 언어)"(id 29) — 고르면 `lang=` 제거 · OS 언어 변경을 Win/mac은 즉시 반영(Linux는 시작 시 고정) | | DR-15 | **로그인 시 실행** = 앱 메뉴 체크 토글(3-OS) + Windows 설치본 옵션. 설정에 저장하지 않고 **OS 상태**를 읽는다 — Win HKCU Run 값 `Nexa Coffee` · mac `~/Library/LaunchAgents/com.sosomlab.nexa-coffee.plist` · Linux `~/.config/autostart/nexa-coffee.desktop`(install.sh --autostart와 같은 파일) | | DR-17 | **macOS 사용자 활동 선언은 화면이 잠겼거나 꺼져 있으면 건너뛴다**(`CGDisplayIsAsleep` ‖ `CGSSessionScreenIsLocked` ‖ 콘솔 아님 · 사전 없음도 건너뜀) — `IOPMAssertionDeclareUserActivity`는 꺼진 화면을 켜므로 잠금 뒤 30초마다 loginwindow가 다시 그려져 창이 쌓였다. 어설션 둘은 유지 · 활동 어설션 id 재사용 · Win/Linux는 주기 호출이 없어 해당 없음 | | DR-16 | **Windows 설치본 = NSIS**(`packaging/windows/installer.nsi` · nexa-clip 이식) — 사용자 단위(HKCU · `%LOCALAPPDATA%\Programs\NexaCoffee`) · x64/x86 한 파일 · 실행 중 인스턴스는 WM_CLOSE로 종료. **10-17 분리**: winget `SosomLab.NexaCoffee`·choco `nexa-coffee` = 설치본 / `SosomLab.NexaCoffee.Portable`·`nexa-coffee-portable` = 포터블 zip(`-portable.zip`) · 검수 대기 판정은 패키지별 | ## 3. 구조 ``` src/core/ coffee.h · util.c · timer.c · font.c · draw.c · icon_idle.c · icon_active.c · app.c ← 플랫폼 비종속 src/plat/ win.c(Win32 · CRT 없음) · mac.m(AppKit+IOKit) · linux.c(SNI·dbusmenu·억제) · dbus.c/h(미니 D-Bus) test/ test_core.c(단위) · test_dbus.c(수신 파서 보안·퍼징) · icon_dump.c(PAM 덤프) scripts/ linux-smoke.sh(D-Bus 계약) · dbus-test.conf · linux-docker.sh · tmp-clean.sh(임시 파일 정리) packaging/ branding(SVG SSOT = tools/gen-icon.py) · macos · linux(tar.gz 설치 스크립트 · build-pkgs.sh = deb/rpm) · windows(NSIS installer.nsi) · homebrew · winget · choco ``` ## 4. 작업 규약 - 문서·커밋/푸시 규약 SSOT = [docs/16](docs/16-doc-git-conventions.md). 기록: journal 상세 → DEVLOG 요약 → STATUS/TODO. - **큰 단위 = 브랜치, 세부 = 커밋. push·태그는 사용자 명시 요청 시에만.** `git add <파일>`만(`-A`·`.` 금지). - 🔴 push 전: `make test` · `make win` · `sh scripts/linux-smoke.sh`(brew dbus) · macOS `make app` 실행 확인. Linux PC에는 mingw/musl이 없어 `make win`·`make app`은 CI(`gh run watch`)로 대신한다. 크기 예산(CI): Windows ≤ 64KB · Linux 정적 ≤ 128KB · macOS 유니버설 ≤ 256KB. - 코어에 libc 호출·float·malloc을 넣지 않는다(Windows 링크가 깨진다). 플랫폼 파일만 OS API를 만진다. - 아이콘을 바꾸면 `make test` 후 `build/icons/*.pam`을 눈으로 확인(magick으로 PNG 변환) — 16px 두 자리 숫자 선명도 기준. - 🔒 **보안([docs/19](docs/19-security-hardening.md) · 사용자 11-07)**: 외부 입력(설정 파일 · 자식 stdout · 명령줄 · D-Bus 와이어 · 환경 변수)은 **길이 경계로 파싱**(`cf_atoi_n(s, end, &e)` · NUL 종단 가정 금지) · 정수는 **포화 + clamp**(`atoi` · 부호 있는 `v*10` 누적 금지) · 표 인덱스는 `(unsigned)x < COUNT` · 와이어 길이는 `n > end - pos`(랩어라운드 금지) + NUL 검증 · 재귀는 깊이 상한. **push 전 `make test-san`**(ASan+UBSan · CI ubuntu도 돈다). 결함은 docs/19 §4에 `V-n` 행 + **수정 전 코드에서 실패하는 시험**을 먼저. - 🧹 **임시 파일(사용자 11-07)**: 프로젝트 밖 임시 폴더/파일은 접두사 **`nexa-coffee-*`** + 만든 쪽이 `trap`으로 삭제. **회차 마감 때 `sh scripts/tmp-clean.sh --trim`**(스크립트 고정물 24h · Claude 세션 스크래치 7일 나이 가드 · 접두사 화이트리스트). 새 접두사는 스크립트 `PATTERNS`와 [docs/18 "임시 파일 정리"](docs/18-build-and-test.md#임시-파일-정리사용자-11-07)에 함께. 실기 백업(`%TEMP%\nc-config.bak`)은 마무리 단계에서 사람이. - 🌐 **크로스 플랫폼(nexa-dir3 docs/15 §2-3 이식 · 11-07)**: OS API·`#ifdef`는 `src/plat`에만(코어 0) · 미지원은 **조용히 넘기지 않고** 알림/문서(Linux "대화창 도구 없음" 알림처럼) · 시험·스모크 인스턴스는 **사용자 포커스·실제 세션 버스·실제 설정을 건드리지 않음**(전용 버스 · HOME 격리 · mac Accessory 정책) · 한 OS에서 고친 결함은 **다른 두 OS의 같은 자리**를 함께 확인하고 journal에 "해당 없음" 근거를 적는다(11-07: 주기 활동 선언은 mac만) · 개발 PC에 없는 툴체인(musl·mingw·맥)은 **CI 3-OS 결과로 판정**한 뒤 push 판정 · 실기 전 사용자 설치본 유무 확인(10-17 사고). ## 5. 다음 단계 0. **v0.1.5 사후(11-07)** — 배포·채널 확인 ✅(RPM 색인은 repodata 경로를 못 찾아 직접 미확인 · T-20 dnf 실기로 대신) → 남은 것: winget 3 PR(#436346 · #454127 · #474187) 머지 · choco 0.1.5 두 패키지 검수 · 원격 브랜치 `fix/mac-wake-when-locked` 삭제(권한 분류에 막혀 보류 · 사용자 판단) · **맥 실기 [18 ④](docs/18-build-and-test.md#사람이-해야-하는-실기-점검macos)**(잠금 → 화면 꺼진 뒤 `pmset -g log` "Display is turned on" 증가 0 · UserIsActive 누적 없음) · T-24 남음(Windows 런타임 시험 = MSVC `/fsanitize=address` 검토 · Windows PC) · 회차 마감 `sh scripts/tmp-clean.sh --trim`. 0-1. **채널 마무리(T-6)** — 검수 대기: winget #436346(0.1.1)·#454127(Portable 0.1.4) · choco `nexa-coffee` 0.1.3·`nexa-coffee-portable` 0.1.4. 기존 ID가 풀리면 `publish-windows-packages` dispatch(`tag=v0.1.4`)로 설치본 제출 — choco 사이트 `nexa-coffee` 제목 "(Portable)"도 이 설치본 0.1.4가 승인돼야 "Nexa Coffee"로 바뀐다(버전별 nuspec 제목). ⚠️ 설치본 실기 전엔 사용자 설치본(`%LOCALAPPDATA%\Programs\NexaCoffee`) 유무를 먼저 확인(10-17 사고). 남은 사람 손: pkg.sosomlab.com apt/dnf 설치 실기(T-20). 1. **실기 확인(사람)** — Windows: [18 점검표](docs/18-build-and-test.md#사람이-해야-하는-실기-점검windows) ③ 설치본(마법사 언어별 문구 · 체크 → 재로그인 트레이) · ① 배율(T-18) · ② TaskbarCreated. macOS·Linux: 메뉴 "로그인 시 실행" 토글 + 재로그인 · Linux GNOME 16px · T-19 트레이 복귀. 2. macOS — 언어 메뉴(시스템 항목 포함) 실기(T-11) · 화면보호기 실측(T-4). Linux — KDE Plasma · 입력 창 실제 클릭(T-3). 3. 결정 대기 — linux-repo 등록 확인 단계(T-21) · 툴팁 종료 시각(T-8) · cask DSL(T-15). ja/zh 원어민 검토(T-12). > 자동 검증: `make test` · `scripts/linux-smoke.sh`(가짜 워처·logind) · `scripts/test-install.sh` — 모두 CI linux. 릴리스 절차는 [packaging/README](packaging/README.md#릴리스-절차)(노트 → VERSION → 태그).