@nolit/dsh-notify 0.0.0-stage → 0.0.1-rc.3

package/docs/2026-10-20-final-status.md

@@ -0,0 +1,125 @@
+# DSH Notify — 최종 상태와 알려진 문제
+
+<!-- skeleton:
+version: 1.0
+kind: report
+status: historical
+updated: 2026-10-20
+summary: Final state of the first DSH Notify round and the known problems left open at that point.
+-->
+
+
+> 상태: final · 최종 갱신: 2026-10-20 · git: main @ milestone-3 · 상위: [WORK-PROTOCOL.md](WORK-PROTOCOL.md)
+
+이 문서는 "지금 이 버전을 그대로 두고 멈춘다"는 결정에 따라, 현재 동작·구조·한계를 한곳에 정리한 마감 문서다.
+
+## 인덱스
+
+| § | 섹션 | 한 줄 요약 |
+|---|---|---|
+| 1 | 현재 버전 | 마지막 커밋·태그·실행 방법 |
+| 2 | 동작하는 기능 | 카드·트레이·DSH 팝업·동기화 |
+| 3 | 구조 | 파일 맵과 이벤트 경로 |
+| 4 | 설정 | config.json 키 |
+| 5 | **알려진 문제** | 반드시 읽을 것 — 소리/토스트/SAC |
+| 6 | 진단 로그 | core.log·bridge.log·popup 로그 |
+| 7 | 테스트 | 실행 명령과 현재 결과 |
+| 8 | 다음 후보 (미착수) | 클라이언트 오디오 등 |
+
+---
+
+## 1. 현재 버전
+
+| 항목 | 값 |
+|---|---|
+| 브랜치 | `main` |
+| 태그 | `milestone-3` (문서·팝업 마감) |
+| 실행 | 시작 메뉴 `DSH Notify` 바로가기 또는 `pwsh -NoProfile -File start.ps1` |
+| 종료 | 트레이 고래 아이콘 우클릭 → `종료` |
+| 요구 | PowerShell 7, Windows 10/11, DSH 프로필에 브리지 플러그인 등록됨 |
+
+## 2. 동작하는 기능
+
+- **피크/오프피크 카드**: 제목 `DeepSeek Peak (100%)` / `DeepSeek Off-Peak (50% discount)`. digital-7 타이머 `HH:MM:SS`, 초와 콜론은 배경색(`#2C2C2C`), 본문 색 피크 `#E5534B` / 오프피크 `#4ADE80`, 제목 CI 블루, 투명도 0.6
+- **트레이 메뉴**: 지금 갱신 / 알림(체크) / OLED 보호(체크) / 항상 표시(체크) / 피크일 때만 / 위치 초기화 / 카드 보이기(체크) / 종료
+- **OLED 보호**: 켜면 `oledIntervalSeconds`(기본 60초)마다 카드를 5px씩 네 방향 순환. 저장 기준 위치는 유지
+- **시작 경량화**: 창은 즉시 `00:00:00` 으로 뜨고 5초 뒤 백그라운드 스레드에서 공휴일·지역 동기화
+- **DSH 완료/승인 팝업**: 브리지가 `cache\popup-request.json` 을 남기면 코어가 팝업 표시 (소리 없음)
+- **서브에이전트 완료 필터**: 완료 알림은 루트 세션만. 승인/질문은 서브에이전트 것도 알림
+- **알림 전체 스위치**: 트레이 `알림` 체크 = `config.notifications`. 코어 전환 토스트와 DSH 팝업을 함께 끔
+
+## 3. 구조
+
+```
+DSH host plugin  bridge\index.js (@local/dsh-notify-bridge)
+   ├─ 턴 완료/승인/질문/오류 이벤트 구독 ({global:true})
+   └─ cache\popup-request.json 기록
+            ↓ (1초 tick 폴링)
+core.ps1 (상주 WPF)  ── 카드·트레이·팝업
+   ├─ providers\deepseek-peak.ps1  판정·공휴일 캐시
+   ├─ ui\presenter.ps1             표시 모델
+   ├─ ui\indicator.ps1             카드
+   ├─ ui\tray.ps1                  트레이
+   └─ ui\popup.ps1                 우하단 팝업
+```
+
+- 포트·웹서버·데몬 없음. 파일 큐 + 프로세스 내부 타이머만 사용
+- DSH 프로필 등록: `~\.dsh\profiles\desktop\node_modules\@local\dsh-notify-bridge` junction + `cordis.patch.yml` 의 insert 엔트리 (백업 `cordis.patch.yml.bak`)
+- 브리지는 로더 핫 리로드로 재시작 없이 반영된다. 적용 증거: `cache\bridge.log` 의 `bridge x.y.z applied: ...`
+
+## 4. 설정
+
+`config.json` (프로젝트 루트). 트레이 메뉴가 일부 값을 직접 바꾼다.
+
+| 키 | 기본 | 의미 |
+|---|---|---|
+| `displayMode` | `always` | `peakOnly` 면 피크일 때만 카드 |
+| `opacity` | 0.6 | 카드 불투명도 (0.2–1.0) |
+| `position` | 저장값 | 카드 기준 위치 (OLED 오프셋 제외) |
+| `notifyOnChange` | true | 구간 전환 시 토스트 1회 |
+| `notifications` | true | 전체 알림 스위치 |
+| `oledProtection` | false | OLED 번인 완화 이동 |
+| `oledIntervalSeconds` | 60 | 이동 간격(최소 5초) |
+| `pollSeconds` | 60 | provider 폴링 주기 |
+| `providers.deepseek-peak` | enabled/treatMakeupAsPeak/refreshHours(240) | 공휴일·판정 옵션 |
+
+## 5. 알려진 문제
+
+| 심각도 | 문제 | 원인/현상 | 현재 대응 |
+|---|---|---|---|
+| **높음** | **DSH 팝업 소리 없음** | 이 PC에서 WinMM(`SoundPlayer`/`PlaySound`)은 스피커 앰프까지 도달하지 않고 "뽁"만 났다(피크 0 실측). 5.1 WinRT MediaPlayer 자식도 무음, 미디어 플레이어 경유는 창이 떠서 UX 훼손 | **소리 제거 결정**. 팝업만 표시 |
+| **높음** | 윈도 토스트 배너 미표시 | PushNotification 로그에는 `delivered` 로 찍히지만 배너가 억제됨(집중 지원/알림 설정). 앱은 표시 여부를 알 수 없음 | 토스트는 수동 확인용(`notify\send-toast.ps1`). 정식 알림은 자체 팝업 |
+| **높음** | `DSH-Notify.exe` 실행 차단 | Smart App Control 이 서명 없는 exe 차단 (CodeIntegrity 3073/3077) | 시작 메뉴 바로가기/스크립트 사용. exe 는 서명·SAC 해제 환경용 |
+| 중간 | 완료 팝업은 코어 상주가 전제 | 코어가 꺼져 있으면 요청 파일이 소비되지 않고 남음 | 트레이 앱 실행 상태 유지. 다음 실행 시 첫 tick 에서 소비됨 |
+| 중간 | 로그 무한 증가 | `cache\core.log`, `cache\bridge.log` 로테이션 없음 | 수동 삭제. 필요 시 로테이션 추가 |
+| 낮음 | OLED 이동폭 고정 | 5px 4방향만 지원 | `ui\popup`/`core.ps1` 상수 수정 |
+| 낮음 | digital-7 폰트 라이선스 | 개인용 무료 | 배포 금지. 로컬 사용만 |
+| 낮음 | WMP 11 설치해도 WPF MediaPlayer 실패 | 새 Store 앱은 레거시 WMP 구성 요소가 아님 | 사용 안 함 (소리 제거) |
+
+## 6. 진단 로그
+
+| 파일 | 내용 |
+|---|---|
+| `cache\core.log` | 시작·동기화·UI 반영·팝업 소비·디스패처 예외 |
+| `cache\bridge.log` | 플러그인 적용 버전, 수신 이벤트, 완료 판정 |
+| `cache\popup-sound.log` | 과거 음향 실험 기록(현재 미사용) |
+| `cache\region.json` / `cache\deepseek-peak\holidays.json` | 지역·공휴일 캐시 |
+| `cache\audio-policy-backup.reg` | 실험 중 삭제한 PowerShell 앱 오디오 라우팅 백업 |
+
+## 7. 테스트
+
+```powershell
+pwsh -NoProfile -File tests\run-all.ps1        # 19 files
+pwsh -NoProfile -File tests\docs-contract.ps1   # 헤더/인덱스 검사
+node .\bridge\test.mjs                          # 브리지 단위 테스트
+```
+
+마지막 결과: **19 files, 19 passed / 0 failed**, docs-contract 47 files PASS.
+
+## 8. 다음 후보 (미착수)
+
+- **클라이언트(브라우저) 오디오**: DSH 웹 GUI에서 `<audio>` 로 재생. spawn 프로세스 오디오 문제를 우회하는 유일한 검증된 경로
+- 토스트 AUMID 브랜딩(시작 메뉴 AUMID 등록) — 배너 억제 문제와는 별개
+- 코드 서명으로 SAC 통과
+- 로그 로테이션, OLED 이동폭/패턴 설정화
+- 자동 시작 토글

package/docs/2026-10-23-asset-policy.md

@@ -0,0 +1,170 @@
+# 에셋·상표 라이선스 정책 — BYO(Bring Your Own) 방식
+
+<!-- skeleton:
+version: 1.0
+kind: policy
+status: reference
+updated: 2026-10-23
+summary: Asset and trademark licence policy: bring-your-own assets, what may ship, and what must never be redistributed.
+-->
+
+
+> 상태: active · 최종 갱신: 2026-10-23 · git: main @ 8129b54 · 상위: [README.md](../README.md)
+
+- 목적: 오픈소스 재배포 시 폰트·로고·사운드 라이선스 분쟁을 원천 차단한다.
+- 원칙: **패키지는 에셋을 배포하지 않는다.** 사용자가 직접 주입한 에셋만 로컬에서 사용한다.
+- 적용 대상: `@nolit/dsh-notify`(웹 플러그인), 윈도우 오프피크 위젯(포터블 패키지).
+- 코드 라이선스: MIT ([LICENSE](../LICENSE)).
+
+## 인덱스
+
+| § | 섹션 | 한 줄 요약 |
+|---|---|---|
+| 1 | 기본 원칙 | 기본은 시스템 폰트/중립 아이콘/합성음, 에셋 번들 없음 |
+| 2 | 폰트 | 시스템 폰트 기본, `fonts/digital-7.ttf` 사용자 주입 시 우선 |
+| 3 | 아이콘·상표 | DeepSeek 로고 제외, 중립 시계 아이콘, `icons/custom.ico` 지원 |
+| 4 | 사운드 | `ding.wav` 제거, Web Audio 합성/시스템 소리 |
+| 5 | 라이선스·면책 | MIT + 사용자 주입 에셋 책임은 사용자 |
+| 6 | 패키징 검사 | 배포물에 금지 에셋이 없어야 함 |
+| 7 | 사용자 안내 | 다운로드/배치/적용/제거 방법 |
+
+---
+
+## 1. 기본 원칙
+
+1. **기본값은 라이선스가 명확한 시스템 자산**을 쓴다.
+2. ** Digital-7, DeepSeek 로고, `ding.wav`는 저장소/배포물에서 제외**한다. 로컬 개발 편의를 위해 남아 있더라도 공개 아티팩트에는 포함하지 않는다.
+3. 사용자 주입 에셋은 앱이 **감지하면 우선 적용**하고, 없으면 기본값으로 조용히 폴백한다.
+4. 사용자 주입 에셋의 라이선스/재배포 권리는 **사용자 책임**이며, 프로젝트는 이를 배포하지 않는다.
+5. 기본 아이콘/코드 외에 제3자 에셋을 포함할 경우 `THIRD-PARTY-NOTICES.md`에 출처/라이선스를 기록한다.
+
+---
+
+## 2. 폰트
+
+### 2.1 기본값
+
+- 타이머: `Consolas, "Cascadia Mono", "Segoe UI", monospace` 순서의 시스템 폰트.
+- 일반 UI: `"Segoe UI", system-ui, sans-serif`.
+- 별도 TTF/OTF를 패키지에 넣지 않는다. OS 기본 폰트로 렌더링한다.
+
+### 2.2 사용자 주입(BYO)
+
+- 경로: `<widget-data>\fonts\digital-7.ttf` (권장) 또는 `fonts\*.ttf`.
+- 앱은 시작 시 `fonts\digital-7.ttf` 존재 여부를 확인하고, 로드에 성공하면 타이머 폰트로 우선 사용한다.
+- 파일이 없거나 로드에 실패하면 시스템 폰트로 폴백한다. 오류를 띄우지 않는다.
+- README에는 폰트 배포 페이지 링크만 안내한다. 패키지에 폰트 파일을 포함하지 않는다.
+  - Digital-7 제작사: <https://www.styleseven.com/>
+- 사용자는 다운로드한 폰트의 라이선스를 직접 확인해야 한다. Digital-7은 제작사 EULA상 가정용/프리웨어 조건이므로, 상업적 사용자는 별도 라이선스를 구매해야 한다.
+
+### 2.3 웹 플러그인
+
+- 웹 플러그인은 폰트를 번들하지 않으며, DSH/브라우저의 시스템 폰트를 그대로 쓴다.
+- 웹 알림에는 커스텀 폰트를 적용하지 않는다.
+
+---
+
+## 3. 아이콘·상표
+
+### 3.1 기본 아이콘
+
+- 웹 플러그인: `plugin/icon.svg` — 자체 제작한 중립 알람시계 SVG(MIT).
+- 윈도우 위젯: 동일 계열의 중립 시계/타이머 `.ico`. 기본 배포물에 DeepSeek 로고를 넣지 않는다.
+- 트레이/창 아이콘은 중립 아이콘을 기본으로 하고, 사용자가 교체할 수 있다.
+
+### 3.2 DeepSeek 로고
+
+- DeepSeek 공식 로고/워드마크/브랜드 자산은 **배포 패키지에서 완전히 제외**한다.
+- 저장소에 남아 있는 로컬 개발용 로고 파일은 공개 아티팩트 빌드에서 제외한다.
+- 사용자가 로컬에서 직접 넣는 경우에도 상표 사용 권한은 사용자 책임이다.
+
+### 3.3 사용자 커스텀 아이콘
+
+- 경로: `<widget-data>\icons\custom.ico` (트레이/앱 아이콘), 선택적으로 `icons\custom.png`.
+- 앱은 `custom.ico`가 있으면 우선 사용하고, 없으면 중립 기본 아이콘을 쓴다.
+- 잘못된 ICO/크기 불일치는 무시하고 기본 아이콘으로 폴백한다.
+- 웹 플러그인은 알림 아이콘을 지정하지 않는다(브라우저 기본 표시). 커스텀 아이콘 주입은 위젯 전용이다.
+
+---
+
+## 4. 사운드
+
+### 4.1 웹 플러그인
+
+- `ding.wav`를 번들하지 않는다.
+- Web Audio API로 짧은 2음 차임을 합성한다(예: 880Hz/1175Hz, 120ms).
+- 사용자 제스처 전에는 `AudioContext`가 잠겨 있을 수 있으며, 패널의 “소리 켜기”로 활성화한다.
+
+### 4.2 윈도우 위젯
+
+- `notify/ding.wav`를 배포물에서 제거한다.
+- 시스템 기본 알림음(`[System.Media.SystemSounds]::Asterisk` 등) 또는 무음 정책을 사용한다.
+- 별도 오디오 파일을 패키지에 넣지 않는다.
+
+---
+
+## 5. 라이선스·면책
+
+- 코드는 MIT 라이선스다. [LICENSE](../LICENSE) 참조.
+- **사용자 주입 에셋 면책:** 사용자가 `fonts/`, `icons/`, 사운드 등으로 주입한 제3자 자산의 저작권/상표권/라이선스 준수 책임은 전적으로 사용자에게 있다. 프로젝트 저자와 기여자는 이에 대해 책임지지 않는다.
+- 프로젝트는 사용자 주입 에셋을 수집·배포·호스팅하지 않는다.
+- 소프트웨어는 “있는 그대로(AS IS)” 제공되며, 상품성/특정 목적 적합성/비침해에 대한 보증을 하지 않는다.
+- 기본 패키지에 포함된 자체 제작 아이콘/SVG는 MIT로 배포한다.
+- 향후 OFL 폰트를 기본 포함할 경우, 해당 폰트의 OFL 고지와 저작권을 `THIRD-PARTY-NOTICES.md`에 포함한다.
+
+---
+
+## 6. 패키징 검사
+
+공개 아티팩트(`npm pack`, 위젯 zip)에 다음이 없어야 한다.
+
+- [ ] `digital-7.ttf`, 기타 Digital-7 폰트 파일
+- [ ] `deepseek-logo*.png`, `deepseek-*.ico` 등 DeepSeek 브랜드 자산
+- [ ] `ding.wav`, 기타 출처 불명 오디오 파일
+- [ ] `DSH-Notify.exe`, `start.vbs` (SAC/VBScript 문제)
+- [ ] 사용자 `config.json`, 로그, 캐시, 개인 경로
+
+검사 예:
+
+```powershell
+# 저장소에서 금지 에셋이 있는지 확인
+Get-ChildItem -Recurse -File |
+  Where-Object { $_.Name -match 'digital-7|deepseek-logo|ding\.wav|DSH-Notify\.exe|start\.vbs' } |
+  Select-Object FullName
+
+# npm 패키지 내용 확인
+npm pack --dry-run --json
+```
+
+> 로컬 개발용 `ui/assets`에 기존 에셋이 남아 있을 수 있다. 이는 공개 빌드 입력에서 제외하며, 위젯 패키징 단계에서 정리한다.
+
+---
+
+## 7. 사용자 안내(README용)
+
+### 폰트
+
+1. <https://www.styleseven.com/>에서 Digital-7 폰트를 내려받는다.
+2. 앱 데이터 폴더에 `fonts\digital-7.ttf`로 저장한다.
+3. 앱을 재시작하면 타이머에 적용된다. 파일이 없으면 Consolas/Segoe UI로 표시된다.
+4. 폰트 라이선스는 사용자가 직접 확인한다.
+
+### 아이콘
+
+1. 사용할 `.ico` 파일을 준비한다.
+2. 앱 데이터 폴더에 `icons\custom.ico`로 저장한다.
+3. 앱을 재시작하면 트레이/창 아이콘에 적용된다.
+4. 없으면 중립 기본 아이콘이 사용된다.
+
+### 사운드
+
+- 웹 플러그인: 패널에서 “소리 켜기” 후 Web Audio 차임 사용.
+- 윈도우 위젯: 시스템 기본 알림음 사용. 별도 파일 없음.
+
+---
+
+## 8. 관련 문서
+
+- 웹 플러그인 사양: [2026-10-23-web-notify-plugin-spec.md](2026-10-23-web-notify-plugin-spec.md)
+- 배포 전략 검증: [2026-10-23-deployment-strategy-review.md](2026-10-23-deployment-strategy-review.md)
+- 코드 라이선스: [LICENSE](../LICENSE)