# 패키지 매니저 배포 (사용자가 해시검증을 안 해도 되게)

> **셋업 단계별 명령은 [SETUP_PACKAGE_MANAGERS.md](SETUP_PACKAGE_MANAGERS.md)** 를 따라 하세요
> (첫 릴리스 → tap/bucket 생성 → 자동 갱신 PAT). 이 문서는 개념·사용자 설치법 위주입니다.

수동 SHA256 검증은 어디까지나 **대체 수단**이다. 패키지 매니저로 설치하면 매니저가
다운로드 해시를 **자동 검증**하므로, 일반 사용자는 해시를 직접 비교할 필요가 없다.

| 경로 | 검증 주체 | 사용자 체감 |
|---|---|---|
| GitHub Release + `SHA256SUMS.txt` | 사용자(수동) | 해시 비교 필요 |
| **Homebrew / winget / Scoop** | 패키지 매니저(자동) | 한 줄 설치, 검증 자동 |
| 코드서명(Win/macOS) | OS(자동) | OS가 게시자/위변조 자동 확인 |

CI(`.github/workflows/agent-build.yml`)는 릴리스마다 `provider-agent/packaging/` 의 템플릿을
실제 `version`·`sha256` 으로 렌더해 릴리스 자산(`nexa-agent.rb`,
`*.yaml`)으로 첨부한다.

## Homebrew (macOS/Linux)

`brew` 는 formula 의 `sha256` 과 실제 다운로드를 대조해 다르면 설치를 거부한다 → 자동 검증.

**1) 한 번만: tap 저장소 만들기**
- GitHub 에 `yeon-intergation-platform/homebrew-tap` 저장소를 만든다(이름 규칙: `homebrew-<탭이름>`).
- `Formula/nexa-agent.rb` 에 릴리스 자산의 렌더된 formula 를 커밋.
  (자동화하려면 tap 저장소에 푸시 권한이 있는 `HOMEBREW_TAP_TOKEN` 시크릿을 만들고,
  릴리스 후 렌더 자산을 그 저장소로 커밋하는 스텝을 추가.)

**2) 사용자 설치**
```bash
# 데스크톱 GUI 앱(맥 .app — winget 과 동일 앱)
brew install --cask yeon-intergation-platform/tap/nexa
# 앱을 열고 ‘디스코드 로그인’ 또는 토큰 붙여넣기로 연결

# (헤드리스/CLI 가 필요하면 formula)
brew install yeon-intergation-platform/tap/nexa-agent
```

## winget (Windows)

winget 은 매니페스트의 `InstallerSha256` 으로 자동 검증한다.

**1) 최초 1회: microsoft/winget-pkgs 에 “New package” 제출**
- 릴리스 자산의 렌더된 `provider-agent/packaging/winget/*.yaml`(version/installer/locale)을
  `microsoft/winget-pkgs` 에 PR 제출(`wingetcreate submit` 또는 수동 PR).
- 통과되면 `winget install --id Nexa.Nexa` 로 전 세계 배포.

**2) 이후 모든 버전: “Update Nexa.Nexa to version X.Y.Z” PR 필요**
- winget 은 버전별 디렉터리(`manifests/n/Nexa/Nexa/<version>/`)에 `InstallerUrl` 과
  `InstallerSha256` 을 고정 저장한다. 따라서 `agent-v*` 릴리스가 새로 나올 때마다
  새 버전 매니페스트 PR 이 필요하다.
- `agent-build.yml` 은 `WINGET_GH_TOKEN` 시크릿이 있으면 릴리스마다 자동으로
  `Hyeonjun0527/winget-pkgs` fork 에 브랜치를 만들고 `microsoft/winget-pkgs` PR 을 생성/갱신한다.
  시크릿이 없으면 릴리스 자산의 `dist/pkg/winget/*.yaml` 을 내려받아 수동 PR 해야 한다.
- **주의:** winget 로컬라이즈 문구의 원본은 `provider-agent/packaging/winget/*.yaml` 템플릿이다.
  여기서 `DefaultLocale: ko-KR`, `Nexa` 표기, `ko-KR/en-US/ja-JP` 설명을 유지해야 다음 릴리스
  자동 PR 에도 같은 문구가 반영된다.

**사용자 설치**
```powershell
winget install --id Nexa.Nexa -e --accept-source-agreements   # 해시 자동 검증, 관리자 불필요
```

## Scoop (Windows, 가장 가벼운 무료 경로)

Scoop 은 `hash` 를 자동 검증하고 포터블 실행파일을 사용자 홈에 설치한다(관리자 불필요).
별도 매니페스트 심사 없이 **자기 bucket** 으로 바로 배포 가능 — winget PR 보다 빠름.

**1) 한 번만: bucket 저장소 만들기**
- GitHub 에 `yeon-intergation-platform/scoop-bucket` 저장소를 만들고, 릴리스 자산의 렌더된
  `nexa.json` 을 `bucket/` 에 커밋(CI 로 자동화 가능).

**2) 사용자 설치**
```powershell
scoop bucket add nexa https://github.com/yeon-intergation-platform/scoop-bucket
scoop install nexa   # 해시 자동 검증
```

## 요약: "사용자가 해시검증 안 하게" 하려면 (전부 $0)
1. **패키지 매니저 등록**(위) — 가장 직접적. 매니저가 sha256 자동 검증.
   - macOS: Homebrew tap. `publish-pkg-managers` 가 cask(`nexa`)와 formula(`nexa-agent`)를
     릴리스마다 자동 커밋한다(`PKG_APP_ID`/`PKG_APP_PRIVATE_KEY` 필요).
     **brew 로 받은 파일은 격리 속성이 안 붙어 Gatekeeper 가 안 막는다**
     → Apple Developer($99) 없이도 경고 없이 실행.
   - Windows: Scoop bucket(자동 커밋, 가장 빠름) 또는 winget(버전마다 PR 필요, `WINGET_GH_TOKEN`
     이 있으면 자동 PR). 둘 다 해시 자동 검증.
2. **무료 코드서명**([RELEASE_SIGNING.md](RELEASE_SIGNING.md)) — Windows 는 **SignPath 무료 OSS**.
3. 결과적으로 사용자는 `brew install` / `scoop install` / `winget install` 한 줄이면 끝이고,
   유료 인증서는 **선택**이다.