dsh-app-updater 1.3.1 → 1.3.2

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [1.3.2] — 2026-11-01
+
+### 修复
+
+- **macOS 上「未检测到任何已安装应用」**（用户实测报告）：1.3.0/1.3.1 的 macOS 扫描只执行
+  `brew list --cask --versions`，也就是**只有通过 Homebrew 装过的应用才会出现在列表里**。
+  一台正常使用的 Mac 上绝大多数应用是拖 DMG 装的，于是该命令返回空 → 界面显示「未检测到
+  任何已安装应用」，日志里是「Homebrew 报告 0 个已安装 cask 应用」。这不是「没有应用」，
+  而是**根本没有枚举应用**。现在（`lib/macos.js`）：
+  - 枚举标准应用目录里的 `.app`：`/Applications`、`/Applications/Utilities`、
+    `/System/Applications`（及其 `Utilities`）、`~/Applications`，用 `plutil` 读每个
+    bundle 的 `Info.plist` 取显示名与版本（读不到时退回 `defaults read`）；
+  - 抓取 Homebrew 的 cask 目录（`formulae.brew.sh/api/cask.json`，本地缓存 24 小时）把
+    `.app` 反查到 cask token，从而知道**官网最新版本**；
+  - 只有**确实由 Homebrew 管理**的应用才标记为可一键更新；其余应用如实列出并标注原因
+    （`not-managed` 非 Homebrew 管理 / `store-managed` 由 App Store 管理 /
+    `system-component` 系统组件），绝不假装能更新。
+- **同一个 `.app` 被多个 cask 声明时匹配错乱**：真实目录里 `iterm2` 与 `iterm2@nightly`
+  都声明 `iTerm.app`，旧写法「后写覆盖」会让匹配结果随目录顺序漂移（实测会把同一个应用
+  列出两次）。现在保留全部候选，由 `pickCask` 按「已装 > 非弃用/停用 > 主 token >
+  token 与应用名相等」挑选。
+- **没有 Homebrew 也能扫描**：`capabilitiesFor` 不再把「macOS 无 Homebrew」判成不可扫描 ——
+  应用照样列出来，只是无法判断/驱动更新，提示改为「安装 Homebrew 后可一键升级 cask 应用」。
+- **设置面板按平台显示**：macOS 上不再出现「自动提权安装」「下载失败时回退 winget」
+  「包含应用商店应用」（Windows 概念），改为 macOS 专属的「包含 App Store 应用」与
+  「包含非 Homebrew 应用」（新增设置项 `includeUnmanagedApps`，默认开启）。
+- **空状态文案分平台**：macOS 下列表为空时提示去看运行日志里的「枚举应用目录」记录，
+  而不是干巴巴一句「未检测到任何已安装应用」。
+
+### 新增
+
+- **`lib/macos.js`**：应用目录枚举、`Info.plist` 解析、cask 目录缓存与解析、cask 匹配、
+  列表合并（纯函数 `buildMacosItems` 便于单测）。
+- 日志更细：分别记录「枚举到多少个 .app」「Homebrew 报告多少个 cask」「读取 cask 目录结果」，
+  macOS 上再出现异常时一眼能看出断在哪一步。
+
+### 测试
+
+- `test/unit.mjs` 152 项（新增 macOS 应用枚举 20 项、同名 cask 挑选 6 项、cask 目录解析 6 项）；
+  用**真实** `formulae.brew.sh/api/cask.json`（7824 个 cask）验证过匹配与去重。
+- `test/render.mjs` 44 项（新增 macOS 设置面板 6 项、macOS 空状态文案 2 项）。
+- `test/deny.mjs` 12 项不变。
+
 ## [1.3.1] — 2026-11-01
 
 ### 安全

package/CONTRACT.md

@@ -76,20 +76,25 @@ dsh-app-updater/
 
 ```jsonc
 {
-  "id": "Google.Chrome",            // winget id；注册表项 "reg:<key>"；macOS "brew:<cask token>"
+  "id": "Google.Chrome",            // winget id；注册表项 "reg:<key>"；macOS 由 Homebrew 管理的是 "brew:<cask token>"，其余 "macapp:<bundle id>"
   "name": "Google Chrome",
   "version": "155.0.8059.85",       // 已安装版本，未知时 ""
   "available": "156.0.8078.48",     // 可升级到的版本，无更新时 ""
   "publisher": "Google LLC",
-  "source": "winget",               // winget | msstore | registry | homebrew
+  "source": "winget",               // winget | msstore | registry | homebrew | appstore | app
   "installLocation": "C:\\Program Files\\Google\\Chrome\\Application",
   "hasUpdate": true,
   "updateSupported": true,          // 本插件能否驱动更新
-  "reason": null,                   // null | "not-in-catalog" | "unknown-version" | "pinned" | "store-managed" | "system-component"
-  "kind": "exe"                     // exe | msi | msix | inno | cask | null（未知）
+  "reason": null,                   // null | "not-in-catalog" | "not-managed" | "unknown-version" | "pinned" | "store-managed" | "system-component"
+  "kind": "exe"                     // exe | msi | msix | inno | cask | app | null（未知）
 }
 ```
 
+`reason` 里的 `not-managed` 是 macOS 专用：应用在标准目录里枚举到了，但不是由 Homebrew 管理
+（拖 DMG / 手动安装），所以能列出、不能一键更新。`source` 的 `app` / `appstore` 同理只出现在
+macOS。macOS 的扫描范围是 `/Applications`、`/Applications/Utilities`、`/System/Applications`
+（及其 `Utilities`）与 `~/Applications`；装在别处的应用不在范围内。
+
 ### POST /dsh-app-updater/scan
 
 body `{ "confirm": true, "force": true }` → `{ "ok": true, "started": true }`（异步；结果看 state.json / apps.json）

package/README.en.md

@@ -88,8 +88,9 @@ State file: `%USERPROFILE%\.dsh\dsh-app-updater\state.json`
 
 | Key | Default | Meaning |
 |---|---|---|
-| `includeStoreApps` | `true` | List Store (MSIX) apps too (display only). |
-| `includeRegistryOnly` | `true` | Fill in apps missing from the winget catalog using the registry (display only). |
+| `includeStoreApps` | `true` | List store apps too (MSIX on Windows, App Store on macOS; display only). |
+| `includeRegistryOnly` | `true` | Windows: fill in apps missing from the winget catalog using the registry (display only). |
+| `includeUnmanagedApps` | `true` | macOS: also list apps that Homebrew does not manage (drag-to-Applications installs; display only). |
 | `downloadDir` | empty | Custom download folder; empty = `%USERPROFILE%\Downloads\DSH App Updater`. Must be absolute. |
 | `keepInstallers` | `true` | Keep the installer after a successful update. |
 | `hashFallbackUpgrade` | `true` | Fall back to `winget upgrade` when the download fails. |
@@ -147,8 +148,10 @@ curl -X POST -H "Content-Type: application/json" \
 
 - **Windows**: `winget.exe` (Microsoft App Installer). Without winget the plugin can still
   list registry apps, but cannot tell whether they are up to date.
-- **macOS**: `brew` ([Homebrew](https://brew.sh)). Without Homebrew the plugin reports the engine
-  as unavailable instead of pretending it can update anything.
+- **macOS**: no extra dependency is needed to **list** apps (the plugin reads `.app` bundles from
+  `/Applications` and friends); judging and applying updates needs `brew` ([Homebrew](https://brew.sh)).
+  Without Homebrew the apps are still listed, with a note that installing Homebrew enables one-click
+  cask upgrades.
 - No third-party npm dependencies: the host half uses Node built-ins only, the browser half
   only the host-provided `react`.
 
@@ -159,7 +162,7 @@ The plugin detects its own environment at startup and picks the installer that m
 | System | Architecture | Engine | Notes |
 |---|---|---|---|
 | Windows 10 / 11 | x64 / ARM64 / x86 | **winget** | the detected architecture is passed as `winget --architecture`; if the manifest has no installer for it, the plugin falls back to automatic matching and says so in the log |
-| macOS 11+ | Apple Silicon / Intel | **Homebrew casks** | Homebrew itself resolves the right cask for the machine; without Homebrew the engine is reported unavailable |
+| macOS 11+ | Apple Silicon / Intel | **Homebrew casks** | apps are enumerated from `/Applications` and friends, then matched against the cask catalog; Homebrew resolves the right cask for the machine. Without Homebrew the apps are still listed, they just cannot be upgraded in one click |
 | anything else | — | none | the scan/update routes answer 400 with the reason |
 
 The result is shown in the status line and in the settings panel's “运行环境 / Environment” row, e.g.
@@ -169,9 +172,13 @@ The result is shown in the status line and in the settings panel's “运行环
 The “按本机架构安装包 / match system architecture” switch (on by default) can be turned off to hand
 the choice back to winget; Homebrew always resolves for the local architecture.
 
-> The macOS/Homebrew path follows Homebrew's documented CLI behaviour and its detection and parsing
-> logic are covered by unit tests, but it has not been verified on a real Mac — this plugin is
-> developed on Windows. Please open an issue if something misbehaves there.
+> The macOS app enumeration (`/Applications` + `Info.plist`) and cask matching are covered by unit
+> tests and were validated against the real `formulae.brew.sh` catalog (7,800+ casks), but the
+> macOS **install/update execution** has not been verified on a real Mac — this plugin is developed
+> on Windows. Please open an issue if something misbehaves there.
+>
+> Only the standard application directories are enumerated. Apps installed elsewhere (a custom
+> folder, the Desktop, an external volume) are outside the scan scope by design.
 
 ## HTTP API (host half)
 
@@ -208,8 +215,9 @@ Then add `dsh-app-updater` to `dsh.profile.bundles` in the profile's `package.js
 ## Tests
 
 ```bash
-node test/unit.mjs     # 66 checks: table parsing, version compare, manifest & switches, OS/arch detection, Homebrew parsing
-node test/render.mjs   # 32 checks: settings panel, rehearsal banner, column drag, request bodies
+node test/unit.mjs     # 152 checks: table parsing, version compare, manifest & switches, OS/arch detection, Homebrew parsing, macOS app enumeration & cask matching
+node test/render.mjs   # 44 checks: settings panel (per platform), rehearsal banner, column drag, request bodies
+node test/deny.mjs     # 12 checks: deny-by-default per route when the host has no connection service
 node test/harness.mjs --scan   # boots the host half against a fake cordis ctx + real HTTP
 ```
 

package/README.md

@@ -93,9 +93,10 @@ dsh plugin --profile web add https://github.com/19952730389/dsh-app-updater/rele
 
 | 键 | 默认 | 说明 |
 |---|---|---|
-| `includeStoreApps` | `true` | 是否把商店（MSIX）应用列进来（只展示，不会被更新）。 |
-| `includeRegistryOnly` | `true` | 是否用注册表补齐 winget 未收录的应用（只展示，不能更新）。 |
-| `downloadDir` | 空 | 自定义安装包下载目录；空 = `%USERPROFILE%\Downloads\DSH App Updater`。 |
+| `includeStoreApps` | `true` | 是否把商店应用列进来（Windows 是 MSIX、macOS 是 App Store 应用；只展示，不会被更新）。 |
+| `includeRegistryOnly` | `true` | Windows：是否用注册表补齐 winget 未收录的应用（只展示，不能更新）。 |
+| `includeUnmanagedApps` | `true` | macOS：是否把非 Homebrew 管理（拖 DMG / 手动装）的应用也列出来（只展示，不能更新）。 |
+| `downloadDir` | 空 | 自定义安装包下载目录；空 = `%USERPROFILE%\Downloads\DSH App Updater`（macOS 为 `~/Downloads/DSH App Updater`）。 |
 | `keepInstallers` | `true` | 更新后保留安装包；`false` 则在安装完成后删掉该应用刚下载的包。 |
 | `hashFallbackUpgrade` | `true` | 下载失败时退回 `winget upgrade` 兜底。 |
 | `dryRun` | `false` | **演练模式**：只下载官网全量安装包、不执行安装。用来先看会装什么。 |
@@ -154,7 +155,7 @@ curl -X POST -H "Content-Type: application/json" \
 ## 依赖
 
 - **Windows**：`winget.exe`（Microsoft「应用安装程序 / App Installer」）。没装 winget 时插件仍能列出注册表里的应用，但无法判断是否有新版本。
-- **macOS**：`brew`（[Homebrew](https://brew.sh)）。没装 Homebrew 时明确报告引擎不可用，不会假装能更新。
+- **macOS**：无需额外依赖即可**列出**应用（直接读 `/Applications` 等目录里的 `.app`）；要判断并执行更新需要 `brew`（[Homebrew](https://brew.sh)）。没装 Homebrew 时会照常列出应用，并说明「安装 Homebrew 后可一键升级 cask 应用」。
 - 不需要任何第三方 npm 依赖；宿主半身只用 Node 内置模块，浏览器半身只用宿主提供的 `react`。
 
 ## 接口（宿主半身）
@@ -189,8 +190,9 @@ dsh plugin --profile <profile> add link:/path/to/dsh-app-updater
 ## 测试
 
 ```bash
-node test/unit.mjs              # 66 项：定宽表格解析、版本比较、清单与静默参数、系统/架构识别、Homebrew 解析
-node test/render.mjs            # 32 项：设置面板、演练提示、列宽拖拽、请求体
+node test/unit.mjs              # 152 项：定宽表格解析、版本比较、清单与静默参数、系统/架构识别、Homebrew 解析、macOS 应用枚举与 cask 匹配
+node test/render.mjs            # 44 项：设置面板（按平台）、演练提示、列宽拖拽、请求体
+node test/deny.mjs              # 12 项：无 connection 服务时逐路由验证默认拒绝
 node test/harness.mjs --scan    # 用假 cordis ctx + 真 HTTP 把宿主半身跑起来
 ```
 
@@ -201,7 +203,7 @@ node test/harness.mjs --scan    # 用假 cordis ctx + 真 HTTP 把宿主半身
 | 系统 | 架构 | 更新引擎 | 说明 |
 |---|---|---|---|
 | Windows 10 / 11 | x64 / ARM64 / x86 | **winget** | 把识别到的架构传给 `winget --architecture`；清单没有该架构的包时自动退回自动匹配并记录日志 |
-| macOS 11+ | Apple Silicon / Intel | **Homebrew cask** | Homebrew 自己按本机架构取 cask；没有 Homebrew 时明确报告引擎不可用 |
+| macOS 11+ | Apple Silicon / Intel | **Homebrew cask** | 应用从 `/Applications` 等目录枚举，再按 cask 目录匹配；Homebrew 自己按本机架构取 cask。没装 Homebrew 时仍能列出应用，只是不能一键更新 |
 | 其它 | — | 无 | 扫描/更新接口返回 400 并说明原因 |
 
 识别结果会显示在状态行与设置面板的「运行环境」里，例如
@@ -219,8 +221,12 @@ UAC 为「始终通知」时每次安装会弹一次确认；把 DSH 本身以
 Edge 走它自带的更新服务：winget 目录里的 `Microsoft.Edge` 是企业版 MSI，与本机消费版的
 安装技术不匹配（`0x8A15008E`），winget 会直接拒绝。
 
-> macOS 的 Homebrew 路径是按 Homebrew 官方 CLI 行为实现的，识别与解析逻辑有单测覆盖；
-> 但本插件主要在 Windows 上开发，macOS 上的安装/更新没有真机验证过，遇到问题请开 Issue。
+> macOS 的应用枚举（`/Applications` 等目录 + `Info.plist`）与 cask 匹配逻辑有单测覆盖，
+> 并用真实的 `formulae.brew.sh` 目录（7800+ cask）验证过匹配与去重；
+> 但本插件主要在 Windows 上开发，macOS 上的**安装/更新执行**没有真机验证过，遇到问题请开 Issue。
+>
+> macOS 上只枚举标准应用目录。应用如果装在别处（例如 `~/Desktop` 或自定义目录），
+> 本插件看不到它 —— 这不是漏扫，是扫描范围之外。
 
 ## 卸载
 

package/lib/client.js

@@ -34,7 +34,9 @@ window.__ModuleLoader__.load({
     const MIN_COL_PX = 48;
     const MAX_COL_PX = 640;
 
-    /* 设置项 → 中文标签与说明 */
+    /* 设置项 → 中文标签与说明。
+       `only` 限定平台：跨平台的开关不写，平台专属的开关只有对应系统才显示，
+       避免 macOS 上出现「自动提权安装」这种 Windows 概念。 */
     const TOGGLES = [
       {
         key: "keepInstallers",
@@ -56,26 +58,49 @@ window.__ModuleLoader__.load({
         key: "autoElevate",
         label: "自动提权安装",
         hint: "需要管理员的安装包（MSI、写入 Program Files）改由管理员上下文执行；UAC 开启时每次安装会弹一次确认",
+        only: "windows",
       },
       {
         key: "hashFallbackUpgrade",
         label: "下载失败时回退 winget",
         hint: "官网包哈希与目录记录不一致时，改用 winget 安装同源全量包",
+        only: "windows",
       },
       {
         key: "includeStoreApps",
         label: "包含应用商店应用",
         hint: "商店 / MSIX 应用只列出，更新仍由 Microsoft Store 负责",
+        only: "windows",
       },
       {
         key: "includeRegistryOnly",
         label: "包含目录未收录应用",
         hint: "用注册表补齐 winget 目录未收录的软件（只列出，无法自动更新）",
+        only: "windows",
+      },
+      {
+        key: "includeStoreApps",
+        label: "包含 App Store 应用",
+        hint: "App Store 应用只列出，升级仍由 App Store 负责",
+        only: "macos",
+      },
+      {
+        key: "includeUnmanagedApps",
+        label: "包含非 Homebrew 应用",
+        hint: "把拖 DMG / 手动安装的应用也列出来（只列出，无法自动更新）",
+        only: "macos",
       },
     ];
 
+    /** 当前平台该显示的开关（未知平台按 Windows 显示，保持兼容）。 */
+    function togglesFor(family) {
+      const fam = family === "macos" ? "macos" : "windows";
+      return TOGGLES.filter((t) => !t.only || t.only === fam);
+    }
+
     const REASON_TEXT = {
       "not-in-catalog": "软件目录未收录",
+      "not-managed": "非 Homebrew 管理",
       "unknown-version": "版本未知",
       "system-component": "系统组件",
       pinned: "版本被固定",
@@ -87,6 +112,8 @@ window.__ModuleLoader__.load({
       msstore: "msstore",
       registry: "registry",
       homebrew: "homebrew",
+      appstore: "App Store",
+      app: "应用",
     };
 
     /** 引擎显示名 */
@@ -170,6 +197,8 @@ window.__ModuleLoader__.load({
       ".appupd-badge-msstore{border-color:rgba(52,211,153,.55);color:#34d399;}",
       ".appupd-badge-registry{border-color:rgba(148,163,184,.5);}",
       ".appupd-badge-homebrew{border-color:rgba(251,191,36,.55);color:#fbbf24;}",
+      ".appupd-badge-appstore{border-color:rgba(52,211,153,.55);color:#34d399;}",
+      ".appupd-badge-app{border-color:rgba(148,163,184,.5);}",
       ".appupd-envline{font-size:12px;color:var(--dsw-alias-label-primary,#f3f4f6);word-break:break-word;}",
       ".appupd-state-new{font-weight:600;color:var(--dsw-alias-brand-primary,#4f8cff);white-space:nowrap;}",
       ".appupd-state-ok{color:#34d399;white-space:nowrap;}",
@@ -634,6 +663,8 @@ window.__ModuleLoader__.load({
         (state && state.envSummary) ||
         (env ? [env.osName || env.platform, env.archLabel].filter(Boolean).join(" · ") : "环境未知");
       const engineText = !state ? "" : engineTextOf(engine);
+      /* 平台族：设置面板与空状态文案都要用，必须在下面的组件定义之前算出来 */
+      const family = (env && env.family) || (platform === "darwin" ? "macos" : "windows");
 
       const filtered = react.useMemo(() => {
         if (!items) return [];
@@ -909,7 +940,17 @@ window.__ModuleLoader__.load({
             "还没有检测过，点右上角『刷新检测』开始"
           );
         }
-        if (!items.length) return h("div", { className: "appupd-empty" }, "未检测到任何已安装应用");
+        if (!items.length) {
+          // 分平台给出可执行的下一步，而不是一句「未检测到任何已安装应用」
+          return h(
+            "div",
+            { className: "appupd-empty" },
+            family === "macos"
+              ? "未在应用目录里找到应用。若确认本机有应用，请看看下面的运行日志里「枚举应用目录」的记录；" +
+                "应用装在非标准位置时本插件看不到它。"
+              : "未检测到任何已安装应用"
+          );
+        }
         return h("div", { className: "appupd-empty" }, "没有匹配的应用");
       };
 
@@ -919,7 +960,10 @@ window.__ModuleLoader__.load({
 
       const settings = (state && state.settings) || {};
       const dryRunOn = Boolean(settings.dryRun);
-      const effectiveDir = (state && state.downloadDir) || "%USERPROFILE%\\Downloads\\DSH App Updater";
+      const visibleToggles = togglesFor(family);
+      const effectiveDir =
+        (state && state.downloadDir) ||
+        (family === "macos" ? "~/Downloads/DSH App Updater" : "%USERPROFILE%\\Downloads\\DSH App Updater");
 
       const dryRunBanner = dryRunOn
         ? h(
@@ -1043,7 +1087,7 @@ window.__ModuleLoader__.load({
                   )
                 )
               ),
-              ...TOGGLES.map((t) =>
+              ...visibleToggles.map((t) =>
                 h(
                   "div",
                   { className: "appupd-field", key: t.key },

package/lib/engine.js

@@ -27,6 +27,7 @@ import {
 import { readRegistryApps, normalizeName } from "./registry.js";
 import { compareVersions, isNewer, looksLikeVersion } from "./version.js";
 import { detectEnvironment, describeEnvironment, engineFor, ENGINE_BREW, ENGINE_WINGET } from "./platform.js";
+import { scanAppBundles, fetchCaskCatalog, parseCaskCatalog, buildMacosItems } from "./macos.js";
 
 const INSTALLER_EXT = /\.(exe|msi|msix|appx|msixbundle|pkg|dmg)$/i;
 
@@ -1113,88 +1114,70 @@ export function parseBrewOutdated(text) {
 
 async function scanMacos({ settings, log, signal, env, startedAt, warnings }) {
   const brewPath = findBrew();
-  const items = [];
 
-  if (!brewPath) {
-    warnings.push("未找到 Homebrew，macOS 上无法检测/更新应用（安装 Homebrew 后重新检测即可）");
+  /* ---------------------------------------------------------------- *
+   * 1. 先枚举「本机到底装了哪些应用」——这一步不依赖 Homebrew。
+   *    旧实现只读 `brew list --cask`，没走 Homebrew 装的应用一个都看不到，
+   *    于是正常 Mac 上就是「未检测到任何已安装应用」。
+   * ---------------------------------------------------------------- */
+  log("info", "正在枚举应用目录（/Applications 等）…");
+  const apps = await scanAppBundles({ log });
+
+  /* ---------------------------------------------------------------- *
+   * 2. Homebrew：哪些 cask 已装、哪些有新版（没装 Homebrew 也继续）。
+   * ---------------------------------------------------------------- */
+  let brewVersion = "";
+  const brews = new Map();
+  const outdated = new Map();
+
+  if (brewPath) {
+    const verRes = await runBrew(brewPath, ["--version"], { timeoutMs: 30000 });
+    brewVersion = firstLine(outputText(verRes)).replace(/^Homebrew\s+/i, "");
+    log("info", `Homebrew ${brewVersion}（${brewPath}）· ${env.archLabel}`);
+
+    const listRes = await runBrew(brewPath, ["list", "--cask", "--versions"], { signal });
+    for (const [token, version] of parseBrewCaskVersions(listRes.stdout)) brews.set(token, version);
+    log("info", `Homebrew 报告 ${brews.size} 个已安装 cask`);
+
+    const outRes = await runBrew(brewPath, ["outdated", "--json=v2", "--cask", "--greedy"], { signal });
+    for (const [token, version] of parseBrewOutdated(outRes.stdout)) outdated.set(token, version);
+    log("info", `其中 ${outdated.size} 个有新版本`);
+  } else {
+    warnings.push("未找到 Homebrew：可以列出已安装应用，但无法判断/驱动更新（安装 Homebrew 后可一键升级 cask 应用）");
     log("warn", warnings[warnings.length - 1]);
-    return {
-      env,
-      engine: { id: ENGINE_BREW, available: false, version: "", path: "" },
-      scannedAt: Date.now(),
-      startedAt,
-      stats: { total: 0, upgradable: 0, unsupported: 0 },
-      items,
-      warnings,
-    };
-  }
-
-  const verRes = await runBrew(brewPath, ["--version"], { timeoutMs: 30000 });
-  const brewVersion = firstLine(outputText(verRes)).replace(/^Homebrew\s+/i, "");
-  log("info", `Homebrew ${brewVersion}（${brewPath}）· ${env.archLabel}`);
-
-  const listRes = await runBrew(brewPath, ["list", "--cask", "--versions"], { signal });
-  const installed = parseBrewCaskVersions(listRes.stdout);
-  log("info", `Homebrew 报告 ${installed.size} 个已安装 cask 应用`);
-
-  const outRes = await runBrew(brewPath, ["outdated", "--json=v2", "--cask", "--greedy"], { signal });
-  const outdated = parseBrewOutdated(outRes.stdout);
-  log("info", `其中 ${outdated.size} 个有新版本`);
-
-  for (const [token, version] of installed) {
-    const available = outdated.get(token) || "";
-    const hasUpdate = Boolean(available) && (!version || isNewer(available, version));
-    items.push({
-      id: `brew:${token}`,
-      name: token,
-      version: version || "",
-      available: hasUpdate ? available : "",
-      publisher: "Homebrew cask",
-      source: "homebrew",
-      installLocation: "",
-      hasUpdate,
-      updateSupported: hasUpdate,
-      reason: hasUpdate ? null : null,
-      kind: "cask",
-    });
   }
 
-  // 有更新但没在「已安装」列表里露出的（例如 --greedy 强制升级项）也补进来
-  for (const [token, available] of outdated) {
-    if (installed.has(token)) continue;
-    items.push({
-      id: `brew:${token}`,
-      name: token,
-      version: "",
-      available,
-      publisher: "Homebrew cask",
-      source: "homebrew",
-      installLocation: "",
-      hasUpdate: true,
-      updateSupported: true,
-      reason: null,
-      kind: "cask",
-    });
+  /* ---------------------------------------------------------------- *
+   * 3. cask 目录：把 .app 反查到 cask token，才能知道官网最新版本。
+   *    抓不到就降级（只显示 Homebrew 自己报告的信息），不中断扫描。
+   * ---------------------------------------------------------------- */
+  let catalog = null;
+  if (brewPath) {
+    const list = await fetchCaskCatalog({ log, warnings });
+    if (list) catalog = parseCaskCatalog(list);
   }
 
-  items.sort((a, b) => {
-    if (a.hasUpdate !== b.hasUpdate) return a.hasUpdate ? -1 : 1;
-    return String(a.name).localeCompare(String(b.name));
-  });
+  /* ---------------------------------------------------------------- *
+   * 4. 合并：已装应用 + Homebrew 管理状态 → 最终列表
+   * ---------------------------------------------------------------- */
+  const built = buildMacosItems({ apps, brews, outdated, catalog, settings });
+  const items = built.items;
+  for (const w of built.warnings) if (!warnings.includes(w)) warnings.push(w);
 
   const stats = {
     total: items.length,
     upgradable: items.filter((i) => i.hasUpdate).length,
-    unsupported: 0,
+    unsupported: items.filter((i) => !i.updateSupported).length,
   };
   log("success", `扫描完成：${stats.total} 个应用，${stats.upgradable} 个可更新`);
+
   if (settings.includeStoreApps) {
-    warnings.push("macOS 的应用商店（App Store）应用不在 Homebrew 覆盖范围内，本插件不会更新它们");
+    warnings.push("App Store 应用只列出、不由本插件更新（由 App Store 自己负责升级）");
   }
 
   return {
     env,
-    engine: { id: ENGINE_BREW, available: true, version: brewVersion, path: brewPath },
+    engine: { id: ENGINE_BREW, available: Boolean(brewPath), version: brewVersion, path: brewPath || "" },
     scannedAt: Date.now(),
     startedAt,
     stats,
@@ -1227,6 +1210,19 @@ async function runMacosUpdates({ ids, settings, log, onProgress, signal, env })
       log("warn", `已取消：${rawId}`);
       break;
     }
+    // 非 Homebrew 管理的应用（macapp:…）没有可交给 brew 的 token：
+    // 明确报「不由本插件更新」，而不是把一个 bundle id 当 cask 名去执行。
+    if (!String(rawId).startsWith("brew:")) {
+      index += 1;
+      results.push({
+        id: rawId,
+        ok: false,
+        error: "该应用不由 Homebrew 管理（拖 DMG / 手动安装），本插件只能列出、不能更新它；请在应用内或官网升级",
+      });
+      log("warn", `${rawId} 跳过：非 Homebrew 管理的应用`);
+      onProgress({ running: true, total: queue.length, done: index, current: null, results });
+      continue;
+    }
     index += 1;
     const token = String(rawId).replace(/^brew:/, "");
     onProgress({ running: true, total: queue.length, done: index - 1, current: token });

package/lib/macos.js

@@ -0,0 +1,409 @@
+/**
+ * macOS 应用清单：把「本机装了哪些应用」真正列出来。
+ *
+ * 为什么需要这个模块：1.3.x 的 macOS 扫描只读了 `brew list --cask`，也就是
+ * **只有通过 Homebrew 装过的应用才会出现在列表里**。一台正常使用的 Mac 上，
+ * 绝大多数应用是拖 DMG 装的，于是 `brew list --cask` 返回空 → 界面显示
+ * 「未检测到任何已安装应用」。这不是「没有应用」，而是**没有枚举应用**。
+ *
+ * 现在的做法：
+ *  1. 枚举标准应用目录里的 `.app`（/Applications、/System/Applications 及其
+ *     Utilities 子目录、~/Applications），从每个 bundle 的 Info.plist 读版本；
+ *  2. 用 Homebrew 的 cask 目录（formulae.brew.sh，缓存一天）把 `.app` 反向匹配到
+ *     cask token，从而知道**官网最新版本**；
+ *  3. 只有「确实由 Homebrew 管理」的应用才标记为可一键更新 —— 其余应用如实列出，
+ *     但标注为不可由本插件更新，绝不假装能更新。
+ *
+ * 这里只做「读」，不改动任何东西；所有命令都是绝对路径 + 参数数组，不经 shell。
+ */
+
+import { readdir, readFile, writeFile, mkdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+import { runProcess } from "./proc.js";
+import { dataDir } from "./state.js";
+import { isNewer, looksLikeVersion } from "./version.js";
+
+/** macOS 放应用的标准目录（约定：这些目录第一层就是 `.app`）。 */
+export function applicationDirs(home = homedir()) {
+  // 这些是 macOS 的 POSIX 路径，用字符串拼接而不是 path.join：
+  // join 在 Windows 上会产出反斜杠，跨平台跑单测时就对不上了。
+  const h = String(home || "").replace(/\/+$/, "");
+  return [
+    "/Applications",
+    "/Applications/Utilities",
+    "/System/Applications",
+    "/System/Applications/Utilities",
+    `${h}/Applications`,
+  ];
+}
+
+/** cask 目录的缓存文件（放插件自己的数据目录，不碰宿主配置）。 */
+export function catalogCachePath(dir) {
+  return join(dir || dataDir(), "cask-catalog.json");
+}
+
+const CATALOG_URL = "https://formulae.brew.sh/api/cask.json";
+const CATALOG_TTL_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * 从 cask 目录 JSON 建索引：
+ *  - byApp：`.app` 文件名（小写）→ 条目**数组**，用来「从已装应用反查 cask」；
+ *  - byToken：cask token → 条目，用来「从已装 cask 正查最新版本」。
+ *
+ * 一个 .app 可能被多个 cask 声明（例如 `iterm2` 与 `iterm2@nightly` 都装
+ * `iTerm.app`），只留最后一个会让匹配随目录顺序漂移 —— 所以这里保留全部候选，
+ * 由 pickCask 按「已装 > 非 nightly/非弃用 > token 精确匹配」挑选。
+ *
+ * @param {any} list formulae.brew.sh/api/cask.json 的内容
+ */
+export function parseCaskCatalog(list) {
+  const byApp = new Map();
+  const byToken = new Map();
+  const addCandidate = (appName, entry) => {
+    const key = String(appName).toLowerCase();
+    const bucket = byApp.get(key);
+    if (bucket) bucket.push(entry);
+    else byApp.set(key, [entry]);
+  };
+  for (const c of Array.isArray(list) ? list : []) {
+    if (!c || typeof c !== "object" || !c.token) continue;
+    const appNames = [];
+    for (const art of Array.isArray(c.artifacts) ? c.artifacts : []) {
+      if (!art || typeof art !== "object") continue;
+      for (const raw of Array.isArray(art.app) ? art.app : []) {
+        // 形如 "$APPDIR/Foo.app" 或 "Foo.app"，只取最后一段
+        const base = String(raw).split("/").pop();
+        if (base && /\.app$/i.test(base)) appNames.push(base);
+      }
+    }
+    const entry = {
+      token: String(c.token),
+      version: String(c.version == null ? "" : c.version).trim(),
+      name: Array.isArray(c.name) && c.name.length ? String(c.name[0]) : String(c.token),
+      appNames,
+      deprecated: Boolean(c.deprecated),
+      disabled: Boolean(c.disabled),
+      autoUpdates: Boolean(c.auto_updates),
+    };
+    byToken.set(entry.token, entry);
+    for (const appName of appNames) addCandidate(appName, entry);
+  }
+  return { byApp, byToken };
+}
+
+/** token 里的变体后缀（iterm2@nightly → iterm2），用于排序时优先主 cask。 */
+function baseToken(token) {
+  return String(token || "").split("@")[0];
+}
+
+/**
+ * 在多个候选 cask 里挑出最可能是「这个 .app 对应的那个 cask」。
+ *
+ * 优先级（越靠前越优先）：
+ *  1. 已安装（token 出现在 brews 里）—— 已装的就是用户实际在用的那个；
+ *  2. 非 deprecated / disabled；
+ *  3. 主 token（不带 @nightly 这类变体后缀）；
+ *  4. token 与应用名/应用文件名归一化后相等。
+ */
+export function pickCask(candidates, { appName, bundleName, brews = new Map() } = {}) {
+  if (!Array.isArray(candidates) || !candidates.length) return null;
+  const keys = new Set([normalizeAppKey(appName), normalizeAppKey(bundleName)].filter(Boolean));
+  const score = (entry) => {
+    let s = 0;
+    if (brews.has(entry.token)) s += 100;
+    if (!entry.deprecated && !entry.disabled) s += 10;
+    if (entry.token === baseToken(entry.token)) s += 5;
+    if (keys.has(normalizeAppKey(entry.token))) s += 3;
+    for (const n of entry.appNames) if (keys.has(normalizeAppKey(n))) s += 1;
+    return s;
+  };
+  let best = candidates[0];
+  let bestScore = score(best);
+  for (const candidate of candidates.slice(1)) {
+    const s = score(candidate);
+    if (s > bestScore) {
+      best = candidate;
+      bestScore = s;
+    }
+  }
+  return best;
+}
+
+/** 名字归一化：去掉 .app、空格与标点，只留字母数字，用于 token ↔ 应用名兜底匹配。 */
+export function normalizeAppKey(name) {
+  return String(name || "")
+    .replace(/\.app$/i, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "");
+}
+
+/**
+ * 在标准应用目录里找 `.app`（不进入 bundle 内部，避免把框架当应用）。
+ * @returns {Promise<string[]>} 绝对路径，已去重
+ */
+export async function listAppBundles(dirs, depth = 1) {
+  const found = [];
+  const seen = new Set();
+  const walk = async (dir, level) => {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return; // 目录不存在 / 无权限：跳过，不影响其它目录
+    }
+    for (const entry of entries) {
+      const full = join(dir, entry.name);
+      if (/\.app$/i.test(entry.name)) {
+        if (!seen.has(full)) {
+          seen.add(full);
+          found.push(full);
+        }
+        continue;
+      }
+      if (level > 0 && (entry.isDirectory() || entry.isSymbolicLink())) {
+        await walk(full, level - 1);
+      }
+    }
+  };
+  for (const dir of dirs) await walk(dir, depth);
+  return found;
+}
+
+/** 用 plutil 读 Info.plist（macOS 自带，binary plist 也能转 JSON）。 */
+async function readInfoPlist(appPath) {
+  const plist = join(appPath, "Contents", "Info.plist");
+  const res = await runProcess("/usr/bin/plutil", ["-convert", "json", "-o", "-", plist], { timeoutMs: 15000 });
+  if (!res.ok) return null;
+  try {
+    return JSON.parse(res.stdout);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 读一个 `.app` 的元信息。
+ * @returns {Promise<{path:string,bundleName:string,name:string,version:string,bundleId:string,appStore:boolean,system:boolean}>}
+ */
+export async function readAppBundle(appPath) {
+  // macOS 上路径一定用 /，但单测在 Windows 上跑，两种分隔符都要能取到最后一段
+  const bundleName = String(appPath).split(/[\\/]/).filter(Boolean).pop() || String(appPath);
+  const info = {
+    path: appPath,
+    bundleName,
+    name: bundleName.replace(/\.app$/i, ""),
+    version: "",
+    bundleId: "",
+    appStore: existsSync(join(appPath, "Contents", "_MASReceipt", "receipt")),
+    system: appPath.startsWith("/System/"),
+  };
+  const plist = await readInfoPlist(appPath);
+  if (plist) {
+    const short = plist.CFBundleShortVersionString;
+    const bundle = plist.CFBundleVersion;
+    info.version = String(short || bundle || "").trim();
+    info.bundleId = String(plist.CFBundleIdentifier || "").trim();
+    const display = plist.CFBundleDisplayName || plist.CFBundleName;
+    if (display) info.name = String(display).trim();
+  }
+  if (!info.version) {
+    // plutil 失败时的兜底：defaults 直接读单个键
+    const res = await runProcess(
+      "/usr/bin/defaults",
+      ["read", join(appPath, "Contents", "Info"), "CFBundleShortVersionString"],
+      { timeoutMs: 15000 }
+    );
+    if (res.ok) info.version = res.stdout.trim();
+  }
+  return info;
+}
+
+/** 枚举并读取全部已安装应用（并发有限，避免一次开几百个进程）。 */
+export async function scanAppBundles({ dirs, log, concurrency = 8 } = {}) {
+  const paths = await listAppBundles(dirs || applicationDirs());
+  const out = [];
+  let index = 0;
+  const worker = async () => {
+    while (index < paths.length) {
+      const current = paths[index];
+      index += 1;
+      try {
+        out.push(await readAppBundle(current));
+      } catch {
+        /* 单个 bundle 读不出来不影响其它应用 */
+      }
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(concurrency, paths.length || 1) }, worker));
+  if (log) log("info", `在应用目录里找到 ${out.length} 个 .app`);
+  return out;
+}
+
+/** 读缓存的 cask 目录（超过 TTL 视为没有缓存）。 */
+export async function readCatalogCache(file, now = Date.now()) {
+  try {
+    const raw = JSON.parse(await readFile(file, "utf8"));
+    if (!raw || typeof raw.fetchedAt !== "number") return null;
+    if (now - raw.fetchedAt > CATALOG_TTL_MS) return null;
+    return raw.list || null;
+  } catch {
+    return null;
+  }
+}
+
+/** 抓取 cask 目录并写缓存；失败返回 null（调用方降级，不中断扫描）。 */
+export async function fetchCaskCatalog({ file, log, warnings, fetchImpl } = {}) {
+  const cacheFile = file || catalogCachePath();
+  const cached = await readCatalogCache(cacheFile);
+  if (cached) return cached;
+
+  const run = fetchImpl || (async () => {
+    const res = await runProcess("/usr/bin/curl", ["-fsSL", "--max-time", "120", CATALOG_URL], { timeoutMs: 180000 });
+    if (!res.ok) {
+      throw new Error(String(res.stderr || "").trim().split("\n")[0] || `curl 退出码 ${res.code}`);
+    }
+    return JSON.parse(res.stdout);
+  });
+
+  try {
+    const list = await run();
+    if (!Array.isArray(list)) throw new Error("cask 目录格式不符合预期");
+    try {
+      await mkdir(dataDir(), { recursive: true });
+      await writeFile(cacheFile, JSON.stringify({ fetchedAt: Date.now(), list }), "utf8");
+    } catch {
+      /* 缓存写不进去不影响本次扫描 */
+    }
+    if (log) log("info", `已读取 Homebrew cask 目录（${list.length} 个 cask）`);
+    return list;
+  } catch (err) {
+    const message = String((err && err.message) || err);
+    if (warnings) warnings.push(`读取 Homebrew cask 目录失败（不影响列出应用，但无法判断是否有新版本）：${message}`);
+    if (log) log("warn", `读取 Homebrew cask 目录失败：${message}`);
+    return null;
+  }
+}
+
+/**
+ * 组装 macOS 应用列表（纯函数，便于单测）。
+ *
+ * @param {object} input
+ * @param {Array} input.apps        已安装的 .app（scanAppBundles 的结果）
+ * @param {Map<string,string>} input.brews   已装 cask：token → 已装版本
+ * @param {Map<string,string>} input.outdated 可升级 cask：token → 可用版本
+ * @param {{byApp:Map,byToken:Map}|null} input.catalog cask 目录索引
+ * @param {object} input.settings
+ * @returns {{items:Array, warnings:string[]}}
+ */
+export function buildMacosItems({ apps = [], brews = new Map(), outdated = new Map(), catalog = null, settings = {} }) {
+  const warnings = [];
+  const items = [];
+  const byApp = catalog ? catalog.byApp : new Map();
+  const byToken = catalog ? catalog.byToken : new Map();
+  /** 已被某个 .app 认领的 cask token，避免重复列出 */
+  const claimed = new Set();
+
+  // 没有 cask 目录时也能把「已装 cask」和 .app 对上：用 token 名归一化匹配，
+  // 否则同一个应用会既作为 .app 出现、又作为 brew 条目再出现一次。
+  const brewByName = new Map();
+  for (const token of brews.keys()) brewByName.set(normalizeAppKey(token), token);
+
+  const matchCask = (app) => {
+    const direct = byApp.get(String(app.bundleName || "").toLowerCase());
+    if (direct && direct.length) {
+      return pickCask(direct, { appName: app.name, bundleName: app.bundleName, brews });
+    }
+    const key = normalizeAppKey(app.name || app.bundleName);
+    for (const entry of byToken.values()) {
+      if (normalizeAppKey(entry.token) === key) return entry;
+      for (const appName of entry.appNames) {
+        if (normalizeAppKey(appName) === key) return entry;
+      }
+    }
+    const token = brewByName.get(key);
+    if (token) return { token, version: "", name: token, appNames: [] };
+    return null;
+  };
+
+  for (const app of apps) {
+    // 注意：只有**显式**设为 false 才过滤。settings 缺字段时按默认「包含」处理，
+    // 否则单测/老状态文件里缺字段会把应用整批吞掉。
+    if (settings.includeStoreApps === false && app.appStore) continue;
+    const cask = matchCask(app);
+    const managed = Boolean(cask && brews.has(cask.token));
+    // 非 Homebrew 管理的应用：默认列出（includeUnmanagedApps），关掉后只看 Homebrew 应用
+    if (!managed && settings.includeUnmanagedApps === false) continue;
+    if (cask && managed) claimed.add(cask.token);
+
+    const latest = cask && looksLikeVersion(cask.version) ? cask.version : "";
+    const forced = managed && outdated.get(cask.token) ? String(outdated.get(cask.token)) : "";
+
+    let available = "";
+    if (managed) {
+      if (forced) available = forced;
+      else if (latest && looksLikeVersion(app.version) && isNewer(latest, app.version)) available = latest;
+    }
+
+    let reason = null;
+    if (app.system && !managed) reason = "system-component";
+    else if (app.appStore && !managed) reason = "store-managed";
+    else if (!managed) reason = "not-managed";
+
+    const hasUpdate = Boolean(managed && available);
+    items.push({
+      id: managed ? `brew:${cask.token}` : `macapp:${app.bundleId || app.bundleName}`,
+      name: app.name || app.bundleName,
+      version: app.version || "",
+      available,
+      publisher: cask ? `Homebrew cask · ${cask.token}` : app.bundleId || "",
+      source: managed ? "homebrew" : app.appStore ? "appstore" : "app",
+      installLocation: app.path,
+      hasUpdate,
+      updateSupported: hasUpdate,
+      reason: hasUpdate ? null : reason,
+      kind: managed ? "cask" : "app",
+    });
+  }
+
+  // 通过 Homebrew 装的、但标准目录里没找到 .app 的（字体、命令行 cask 等）也要列出来。
+  // 它们本来就由 Homebrew 管理，不受「包含非 Homebrew 应用」开关影响。
+  for (const [token, version] of brews) {
+    if (claimed.has(token)) continue;
+    const entry = byToken.get(token);
+    const forced = outdated.get(token) ? String(outdated.get(token)) : "";
+    const latest = entry && looksLikeVersion(entry.version) ? entry.version : "";
+    let available = "";
+    if (forced) available = forced;
+    else if (latest && looksLikeVersion(version) && isNewer(latest, version)) available = latest;
+    const hasUpdate = Boolean(available);
+    items.push({
+      id: `brew:${token}`,
+      name: entry ? entry.name : token,
+      version: version || "",
+      available,
+      publisher: `Homebrew cask · ${token}`,
+      source: "homebrew",
+      installLocation: "",
+      hasUpdate,
+      updateSupported: hasUpdate,
+      reason: hasUpdate ? null : null,
+      kind: "cask",
+    });
+  }
+
+  if (!catalog) {
+    warnings.push("没有可用的 Homebrew cask 目录：只显示 Homebrew 报告的更新，非 Homebrew 应用无法判断是否有新版本");
+  }
+  if (settings.includeUnmanagedApps === false) {
+    warnings.push("「包含非 Homebrew 应用」已关闭：只显示由 Homebrew 管理的应用");
+  }
+
+  items.sort((a, b) => {
+    if (a.hasUpdate !== b.hasUpdate) return a.hasUpdate ? -1 : 1;
+    return String(a.name).localeCompare(String(b.name));
+  });
+  return { items, warnings };
+}

package/lib/platform.js

@@ -178,12 +178,14 @@ export function engineFor(family) {
 /** 该 环境+引擎 组合下能做什么。 */
 export function capabilitiesFor(env, engineAvailable) {
   const family = env ? env.family : "other";
-  const scan = family === "windows" || (family === "macos" && engineAvailable);
+  // macOS 即使没有 Homebrew 也能枚举 .app（列出已装应用），只是无法判断/驱动更新
+  const scan = family === "windows" || family === "macos";
+  const canUpdate = family === "windows" ? Boolean(engineAvailable) : Boolean(engineAvailable);
   return {
     scan: Boolean(scan),
-    update: Boolean(scan),
-    checkVersions: Boolean(scan),
-    storeAppsIncluded: family === "windows",
+    update: Boolean(canUpdate),
+    checkVersions: Boolean(canUpdate),
+    storeAppsIncluded: family === "windows" || family === "macos",
     note:
       family === "windows"
         ? engineAvailable
@@ -192,7 +194,7 @@ export function capabilitiesFor(env, engineAvailable) {
         : family === "macos"
           ? engineAvailable
             ? ""
-            : "未找到 Homebrew，macOS 上无法检测/更新应用；请安装 Homebrew 后重试"
+            : "未找到 Homebrew：可以列出已安装应用，但无法判断/驱动更新；安装 Homebrew 后可一键升级 cask 应用"
           : "当前系统没有可用的更新引擎（本插件支持 Windows 与 macOS）",
   };
 }

package/lib/state.js

@@ -25,6 +25,8 @@ export function defaultSettings() {
   return {
     includeStoreApps: true,
     includeRegistryOnly: true,
+    // macOS：把非 Homebrew 管理（拖 DMG / 手动装）的应用也列出来（只列出，不更新）
+    includeUnmanagedApps: true,
     downloadDir: "",
     keepInstallers: true,
     useWingetDownload: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-app-updater",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "type": "module",
   "description": "App Updater for DeepSeek Harness: detect every installed app that has a newer version and update it with one click by downloading the vendor's full installer from its official website and installing it silently — without launching the app. Windows (winget) and macOS (Homebrew), architecture-aware (ARM64 / x64). · 检测本机所有已安装应用是否有新版本，并从各自官网下载全量安装包一键静默更新（不需要打开被检测的软件）；自动识别 Windows / macOS 与 ARM64 / x64 架构，按架构下载对应安装包。",
   "license": "MIT",

package/test/render.mjs

@@ -359,7 +359,61 @@ tree = rt.render();
 group("设置面板与列宽手柄");
 ok(byClass(tree, "appupd-panel").length === 1, "渲染出插件设置面板");
 const switches = byClass(tree, "appupd-switch");
-ok(switches.length === 7, "渲染出 7 个设置开关（新增自动提权）", switches.length);
+ok(switches.length === 7, "渲染出 7 个设置开关（Windows：不含 macOS 专属项）", switches.length);
+
+group("设置面板按平台显示开关");
+{
+  const macState = baseState({
+    platform: "darwin",
+    env: { family: "macos", platform: "darwin", osName: "macOS 15（Sequoia）", archLabel: "Apple Silicon（ARM64）" },
+    envSummary: "macOS 15（Sequoia） · Apple Silicon（ARM64）",
+    engine: { id: "homebrew", available: true, version: "4.5.0" },
+  });
+  statePayload = macState;
+  rt.reset();
+  await tick();
+  tree = rt.render();
+  await tick();
+  tree = rt.render();
+  const macSwitches = byClass(tree, "appupd-switch");
+  ok(macSwitches.length === 5, "macOS 显示 5 个开关（跨平台 3 + macOS 专属 2）", macSwitches.length);
+  const labels = byClass(tree, "appupd-field-label").map(textOf);
+  ok(!labels.includes("自动提权安装"), "macOS 不显示「自动提权安装」", labels);
+  ok(!labels.includes("下载失败时回退 winget"), "macOS 不显示「下载失败时回退 winget」", labels);
+  ok(labels.includes("包含非 Homebrew 应用"), "macOS 显示「包含非 Homebrew 应用」", labels);
+  ok(labels.includes("包含 App Store 应用"), "macOS 显示「包含 App Store 应用」", labels);
+  ok(labels.includes("演练模式") && labels.includes("保留安装包"), "跨平台开关仍然显示", labels);
+}
+statePayload = baseState();
+rt.reset();
+await tick();
+tree = rt.render();
+await tick();
+tree = rt.render();
+
+group("macOS 空状态文案");
+{
+  const emptyMac = baseState({
+    platform: "darwin",
+    env: { family: "macos", platform: "darwin" },
+    apps: { scannedAt: Date.now(), stats: { total: 0, upgradable: 0, unsupported: 0 }, items: [] },
+  });
+  statePayload = emptyMac;
+  rt.reset();
+  await tick();
+  tree = rt.render();
+  await tick();
+  tree = rt.render();
+  const emptyText = textOf(byClass(tree, "appupd-empty")[0] || tree);
+  ok(emptyText.includes("应用目录") || emptyText.includes("运行日志"), "macOS 空列表给出可执行的下一步，而不是只说「未检测到」", emptyText.slice(0, 120));
+  ok(!emptyText.includes("未检测到任何已安装应用"), "macOS 不再显示会产生误解的那句话");
+}
+statePayload = baseState();
+rt.reset();
+await tick();
+tree = rt.render();
+await tick();
+tree = rt.render();
 ok(byClass(tree, "appupd-grip").length === 4, "渲染出 4 个列宽拖拽手柄", byClass(tree, "appupd-grip").length);
 const ths = walk(tree).filter((n) => n.type === "th");
 ok(ths.length === 6, "表头 6 列", ths.length);

package/test/unit.mjs

@@ -20,6 +20,13 @@ import {
 import { compareVersions, isNewer, looksLikeVersion, splitVersion } from "../lib/version.js";
 import { parseInstallerManifest, splitSwitchArgs, defaultSilentArgs, resolveInstallArgs, parseBrewCaskVersions, parseBrewOutdated, findBrew, isArchNotFoundError, explainInstallerExitCode, evaluateUpdateResult, findEdgeUpdate, updateHintFor } from "../lib/engine.js";
 import { psQuote, ELEVATION_CANCELLED } from "../lib/elevate.js";
+import {
+  applicationDirs,
+  parseCaskCatalog,
+  pickCask,
+  normalizeAppKey,
+  buildMacosItems,
+} from "../lib/macos.js";
 import { admissionGate, hasConnectionCredentials, resolveLegacyLoopbackOptIn, LEGACY_LOOPBACK_ENV } from "../lib/index.js";
 import {
   detectEnvironment,
@@ -232,8 +239,11 @@ ok(envMac.family === "macos" && envMac.osName.includes("Sequoia") && envMac.arch
 
 ok(capabilitiesFor(envWinArm, false).scan === true, "有 winget 时 Windows 可扫描");
 ok(capabilitiesFor(envWinArm, false).note.includes("winget"), "缺 winget 时给出提示", capabilitiesFor(envWinArm, false).note);
-ok(capabilitiesFor(envMac, false).scan === false, "macOS 缺 Homebrew 时不可扫描");
+ok(capabilitiesFor(envMac, false).update === false, "macOS 缺 Homebrew 时不可更新");
+ok(capabilitiesFor(envMac, false).note.includes("Homebrew"), "macOS 缺 Homebrew 时提示装 Homebrew", capabilitiesFor(envMac, false).note);
 ok(capabilitiesFor(envMac, true).scan === true, "macOS 有 Homebrew 时可扫描");
+ok(capabilitiesFor(envMac, false).scan === true, "macOS 没有 Homebrew 也能扫描（只是不能更新）——「0 个应用」的真正原因不是没 Homebrew");
+ok(capabilitiesFor(envMac, false).update === false, "macOS 没有 Homebrew 时不可更新");
 ok(capabilitiesFor({ family: "other" }, false).scan === false, "其它系统不可扫描");
 
 /* ---------------- Homebrew 解析 ---------------- */
@@ -246,6 +256,124 @@ ok(outdated.get("visual-studio-code") === "1.95.0" && outdated.get("iterm2") ===
 ok(parseBrewOutdated("not json").size === 0, "坏 JSON 不抛错");
 ok(findBrew({ HOMEBREW_PREFIX: "/nonexistent-prefix-for-test" }) === null, "找不到 brew 时返回 null");
 
+/* ---------------- macOS 应用枚举（本次修复的核心） ---------------- */
+group("macOS 应用枚举");
+ok(applicationDirs("/Users/x").includes("/Applications"), "枚举 /Applications");
+ok(applicationDirs("/Users/x").includes("/Users/x/Applications"), "枚举 ~/Applications");
+ok(applicationDirs("/Users/x").includes("/System/Applications/Utilities"), "枚举系统工具目录");
+
+const catalogList = [
+  {
+    token: "visual-studio-code",
+    version: "1.144.0",
+    name: ["Microsoft Visual Studio Code"],
+    artifacts: [{ app: ["Visual Studio Code.app"], target: "/Applications/Visual Studio Code.app" }],
+  },
+  {
+    token: "iterm2",
+    version: "3.5.14",
+    name: ["iTerm2"],
+    artifacts: [{ app: ["iTerm.app"] }],
+  },
+  {
+    token: "raycast",
+    version: "1.99.0",
+    name: ["Raycast"],
+    artifacts: [{ app: ["Raycast.app"] }],
+  },
+];
+const catalog = parseCaskCatalog(catalogList);
+ok(catalog.byToken.get("iterm2").version === "3.5.14", "目录按 token 建索引");
+ok(catalog.byApp.get("iterm.app")[0].token === "iterm2", "目录按 .app 文件名建索引（大小写无关）");
+
+const macApps = [
+  // 通过 Homebrew 装、且有新版
+  { path: "/Applications/Visual Studio Code.app", bundleName: "Visual Studio Code.app", name: "Visual Studio Code", version: "1.140.0", bundleId: "com.microsoft.VSCode", appStore: false, system: false },
+  // 通过 Homebrew 装、已是最新
+  { path: "/Applications/iTerm.app", bundleName: "iTerm.app", name: "iTerm2", version: "3.5.14", bundleId: "com.googlecode.iterm2", appStore: false, system: false },
+  // 拖 DMG 装的，Homebrew 不管
+  { path: "/Applications/Raycast.app", bundleName: "Raycast.app", name: "Raycast", version: "1.99.0", bundleId: "com.raycast.macos", appStore: false, system: false },
+  // App Store 装的
+  { path: "/Applications/Xcode.app", bundleName: "Xcode.app", name: "Xcode", version: "16.0", bundleId: "com.apple.dt.Xcode", appStore: true, system: false },
+];
+const brews = new Map([["visual-studio-code", "1.140.0"], ["iterm2", "3.5.14"]]);
+const macBuilt = buildMacosItems({ apps: macApps, brews, outdated: new Map(), catalog, settings: { includeStoreApps: true, includeUnmanagedApps: true } });
+
+ok(macBuilt.items.length === 4, "4 个 .app 全部列出（旧实现只会有 2 个）", macBuilt.items.map((i) => i.name));
+const vsc = macBuilt.items.find((i) => i.name === "Visual Studio Code");
+ok(vsc && vsc.hasUpdate && vsc.available === "1.144.0", "Homebrew 管理 + 有新版本 → 可更新并给出目标版本", vsc);
+ok(vsc && vsc.updateSupported === true && vsc.id === "brew:visual-studio-code", "可更新的应用带上 brew: token", vsc && vsc.id);
+const iterm = macBuilt.items.find((i) => i.name === "iTerm2");
+ok(iterm && iterm.hasUpdate === false && iterm.reason === null, "Homebrew 管理且已最新 → 不可更新但没有「不支持」理由", iterm);
+const ray = macBuilt.items.find((i) => i.name === "Raycast");
+ok(ray && ray.hasUpdate === false && ray.reason === "not-managed", "非 Homebrew 应用：列出但标注「非 Homebrew 管理」", ray);
+ok(ray && ray.updateSupported === false, "非 Homebrew 应用不会被标成可更新");
+const xcode = macBuilt.items.find((i) => i.name === "Xcode");
+ok(xcode && xcode.reason === "store-managed" && xcode.source === "appstore", "App Store 应用标注由商店管理", xcode);
+ok(macBuilt.items.filter((i) => i.hasUpdate).length === 1, "只有 1 个可更新");
+
+// --greedy 能强制升级的 cask（自更新应用）也要露出可用版本
+const greedy = buildMacosItems({ apps: macApps, brews, outdated: new Map([["iterm2", "3.5.15"]]), catalog, settings: {} });
+ok(greedy.items.find((i) => i.name === "iTerm2").available === "3.5.15", "brew outdated --greedy 报告的版本优先", greedy.items.find((i) => i.name === "iTerm2"));
+
+// 关掉「包含非 Homebrew 应用」后只剩 Homebrew 管理的
+const onlyBrew = buildMacosItems({ apps: macApps, brews, outdated: new Map(), catalog, settings: { includeUnmanagedApps: false } });
+ok(onlyBrew.items.length === 2 && onlyBrew.items.every((i) => i.source === "homebrew"), "关闭开关后只显示 Homebrew 应用", onlyBrew.items.map((i) => i.name));
+
+// 关掉「包含 App Store 应用」
+const noStore = buildMacosItems({ apps: macApps, brews, outdated: new Map(), catalog, settings: { includeStoreApps: false } });
+ok(!noStore.items.some((i) => i.name === "Xcode"), "关闭 App Store 开关后不显示 Xcode");
+
+// 没有 cask 目录时降级：仍然列出应用，只是都不认为可更新
+const noCatalog = buildMacosItems({ apps: macApps, brews, outdated: new Map(), catalog: null, settings: {} });
+ok(noCatalog.items.length === 4 && noCatalog.items.every((i) => !i.hasUpdate), "没有 cask 目录也照样列出应用", noCatalog.items.length);
+ok(noCatalog.warnings.some((w) => w.includes("cask 目录")), "没有 cask 目录时给出警告");
+
+// Homebrew 装了但 .app 不在标准目录（字体 / 命令行 cask）
+const brewOnly = buildMacosItems({
+  apps: [],
+  brews: new Map([["font-jetbrains-mono", "2.304"]]),
+  outdated: new Map(),
+  catalog: parseCaskCatalog([{ token: "font-jetbrains-mono", version: "2.304", name: ["JetBrains Mono"], artifacts: [] }]),
+  settings: {},
+});
+ok(brewOnly.items.length === 1 && brewOnly.items[0].id === "brew:font-jetbrains-mono", "没有 .app 的 cask 也能列出", brewOnly.items);
+
+/* ---------------- macOS 目录解析 ---------------- */
+group("cask 目录解析");
+const parsedCatalog = parseCaskCatalog([
+  { token: "raycast", version: "1.99.0", name: ["Raycast"], artifacts: [{ app: ["Raycast.app"] }] },
+  { token: "bad-no-artifacts", version: "1.0" },
+  null,
+  { version: "9.9" },
+]);
+ok(parsedCatalog.byToken.size === 2, "跳过没有 token 的条目", parsedCatalog.byToken.size);
+ok(!parsedCatalog.byApp.has("bad-no-artifacts"), "artifacts 里没有 app 的不建 byApp 索引");
+ok(normalizeAppKey("Visual Studio Code.app") === "visualstudiocode", "应用名归一化去掉 .app 与空格");
+ok(normalizeAppKey("VS Code") === "vscode", "应用名归一化保留字母数字");
+
+group("同名 .app 的多个 cask：挑对那一个");
+// 真实目录里 iterm2 与 iterm2@nightly 都声明 iTerm.app
+const dupCatalog = parseCaskCatalog([
+  { token: "iterm2@nightly", version: "3.6.0", name: ["iTerm2 Nightly"], artifacts: [{ app: ["iTerm.app"] }] },
+  { token: "iterm2", version: "3.7.6", name: ["iTerm2"], artifacts: [{ app: ["iTerm.app"] }] },
+]);
+ok(dupCatalog.byApp.get("iterm.app").length === 2, "两个 cask 都留在候选里", dupCatalog.byApp.get("iterm.app").length);
+ok(
+  pickCask(dupCatalog.byApp.get("iterm.app"), { appName: "iTerm2", bundleName: "iTerm.app", brews: new Map() }).token === "iterm2",
+  "没有安装记录时优先主 token（不是 @nightly）"
+);
+ok(
+  pickCask(dupCatalog.byApp.get("iterm.app"), { appName: "iTerm2", bundleName: "iTerm.app", brews: new Map([["iterm2@nightly", "3.6.0"]]) }).token === "iterm2@nightly",
+  "已装的是 nightly 时优先已装的那个"
+);
+// 弃用 / 停用的 cask 排在后面
+const depCatalog = parseCaskCatalog([
+  { token: "foo-old", version: "1.0", deprecated: true, artifacts: [{ app: ["Foo.app"] }] },
+  { token: "foo", version: "2.0", artifacts: [{ app: ["Foo.app"] }] },
+]);
+ok(pickCask(depCatalog.byApp.get("foo.app"), { appName: "Foo", bundleName: "Foo.app", brews: new Map() }).token === "foo", "弃用的 cask 不会被选中");
+
 /* ---------------- 提权与安装复核 ---------------- */
 group("提权执行（PowerShell 助手）");
 ok(psQuote("C:\\Program Files\\a.exe") === "'C:\\Program Files\\a.exe'", "psQuote 保留 Windows 路径");