# Package Manager Distribution

Pier-X publishes installable desktop bundles to GitHub Releases. Each GitHub
release also generates package-manager metadata from those exact assets:

- Homebrew cask: `pier-x-homebrew-cask-v<version>.rb`
- Homebrew formula: `pier-x-homebrew-formula-v<version>.rb`
- WinGet manifests: `pier-x-winget-manifests-v<version>.tar.gz`
- Checksums: `pier-x-release-sha256-v<version>.txt`

The metadata is generated by:

```bash
npm run release:package-managers -- \
  --version 0.3.0 \
  --repo chenqi92/Pier-X \
  --assets-dir release-assets \
  --out-dir dist-package-managers
```

`release-assets` must contain:

- `Pier-X_<version>_universal.dmg`
- `Pier-X_<version>_amd64.AppImage`
- `Pier-X_<version>_x64-setup.exe`
- `Pier-X_<version>_arm64-setup.exe`

The script computes SHA256 checksums from those files and writes the cask and
WinGet manifests under `dist-package-managers/`.

## Release automation

The GitHub release workflow publishes three things after Tauri uploads the
release bundles:

1. It uploads the generated package-manager metadata back to the Pier-X GitHub
   Release.
2. If `HOMEBREW_TAP_TOKEN` is configured, it pushes the generated cask and
   formula to `chenqi92/homebrew-tap`.
3. If `WINGET_PKGS_TOKEN` is configured, it pushes the generated WinGet
   manifests to `chenqi92/winget-pkgs` and opens a pull request against
   `microsoft/winget-pkgs`.

The Homebrew tap is directly user-facing after the workflow pushes it. The
WinGet package is user-facing only after the pull request is accepted by
`microsoft/winget-pkgs`.

## GitHub secrets

Add these secrets in the Pier-X repository:

```text
Settings -> Secrets and variables -> Actions -> New repository secret
```

### `HOMEBREW_TAP_TOKEN`

Recommended token type: fine-grained personal access token.

Required access:

- Resource owner: `chenqi92`
- Repository access: only `chenqi92/homebrew-tap`
- Repository permissions:
  - Contents: Read and write

The workflow uses this token only to checkout, commit, and push generated files
to the tap repository.

### `WINGET_PKGS_TOKEN`

Recommended token type: classic personal access token with `public_repo`, or a
token that can push to `chenqi92/winget-pkgs` and create pull requests from that
fork to `microsoft/winget-pkgs`.

Required access:

- Push branches to `chenqi92/winget-pkgs`
- Create pull requests against `microsoft/winget-pkgs`

The workflow creates a branch named `pier-x-v<version>` in the fork, then opens
or reuses a pull request with head `chenqi92:pier-x-v<version>`.

## Homebrew

The generated cask is intended for a dedicated tap such as
`chenqi92/homebrew-tap`:

```text
homebrew-tap/
├── Formula/
│   └── pier-x.rb
└── Casks/
    └── pier-x.rb
```

After copying the generated cask and formula into that tap, macOS users can
install the cask with:

```bash
brew install --cask chenqi92/tap/pier-x
```

Linuxbrew users can install the AppImage-backed formula with:

```bash
brew install chenqi92/tap/pier-x
```

Do not claim official Homebrew/homebrew-cask distribution until Pier-X is
accepted there. The custom tap is the supported path first.

The release workflow updates this tap automatically when `HOMEBREW_TAP_TOKEN`
is configured.

## WinGet

The generated manifests use package identifier `Chenqi92.PierX` and NSIS
installer assets from the GitHub release:

```text
winget/manifests/c/Chenqi92/PierX/<version>/
├── Chenqi92.PierX.yaml
├── Chenqi92.PierX.installer.yaml
├── Chenqi92.PierX.locale.en-US.yaml
└── Chenqi92.PierX.locale.zh-CN.yaml
```

To publish to the community source, copy that version directory into a fork of
`microsoft/winget-pkgs`, validate with `winget validate`, then open a pull
request to `microsoft/winget-pkgs`.

Once accepted, users can install with:

```powershell
winget install Chenqi92.PierX
```

Until then, the release-attached manifests are a prepared submission artifact,
not proof that the package is already available from WinGet.

The release workflow opens this pull request automatically when
`WINGET_PKGS_TOKEN` is configured.