# Homebrew Upgrade Manager

`brew-upgrade-manager.sh` 是一个 macOS Homebrew 升级脚本，用来按固定流程更新仓库、检查环境、升级命令行工具和 GUI 应用，并清理旧缓存。

## 功能

- 执行 `brew update -v` 更新 Homebrew 仓库。
- 执行 `brew doctor` 做健康检查，发现问题时给出警告但不中断后续流程。
- 自动检查并安装 `buo/cask-upgrade`，用于提供 `brew cu`。
- 使用 `brew upgrade --formula` 升级命令行 Formula。
- 使用 `brew cu -yaq` 升级 Cask GUI 应用。
- 使用 Python PTY 包装 `brew cu`，用于处理交互输入转发和终端尺寸问题。
- 执行 `brew cleanup --prune=all` 清理旧版本与缓存。

## 依赖

- macOS
- Homebrew
- Bash
- Python 3
- 可访问 Homebrew tap 的网络环境

可先检查：

```bash
brew --version
python3 --version
```

## 使用方法

进入目录并赋予执行权限：

```bash
cd homebrew
chmod +x brew-upgrade-manager.sh
```

运行：

```bash
./brew-upgrade-manager.sh
```

默认会动态读取当前终端宽度；运行过程中缩放窗口时，`brew cu` 的 PTY 尺寸也会跟随更新。如果遇到非交互环境或某些表格渲染异常，可以指定固定终端宽度：

```bash
./brew-upgrade-manager.sh --width 130
./brew-upgrade-manager.sh --width=130
```

也可以通过环境变量指定：

```bash
HB_TERMINAL_WIDTH=130 ./brew-upgrade-manager.sh
```

优先级为：命令行 `--width` 高于 `HB_TERMINAL_WIDTH`。两者都不设置时使用动态终端宽度。

## sudo 认证

脚本不会保存、传递或自动注入 sudo 密码。如果你的 `brew cu` 流程会触发 sudo，建议在运行脚本前先刷新 sudo 凭据：

```bash
sudo -v
./brew-upgrade-manager.sh
```

如果 sudo 凭据过期，脚本内的 PTY 逻辑只会把你的键盘输入转发给子进程，不会嗅探 `Password:` 提示，也不会替你填写密码。

## 执行流程

1. 打印分隔线并更新 Homebrew 仓库。
2. 执行 `brew doctor`。
3. 检查 `buo/cask-upgrade` tap。
4. 升级 Formula。
5. 升级 Cask。
6. 清理 Homebrew 缓存。

## 常见问题

### `brew cu` 不存在

脚本会自动执行：

```bash
brew tap buo/cask-upgrade
```

如果失败，通常是网络、Homebrew tap 或权限问题。

### 表格渲染或 Ruby 报终端宽度错误

默认会跟随终端窗口变化；如果某些环境无法正确报告窗口尺寸，可以使用固定宽度运行：

```bash
./brew-upgrade-manager.sh --width 130
```

### sudo 卡住

先在交互终端运行 `sudo -v`，确认 sudo 凭据有效后再执行脚本。非交互环境中请避免依赖脚本内输入密码。

## 注意事项

- 脚本启用了 `set -e` 和 `set -o pipefail`，关键命令失败会终止流程。
- 升级 GUI 应用可能关闭或替换已安装应用，建议在重要工作保存后执行。
- 如果你使用公司设备或受管 macOS，先确认 Homebrew、Cask 和 sudo 策略是否允许自动升级。