@pmate/cli 0.35.11 → 0.35.13

package/README.md

@@ -270,7 +270,7 @@ Meili's Host may pass `--actor-profile-id` with `PMATE_LOG_DELEGATE_TOKEN` in th
 
 Packaged installers are automatically uploaded to Aliyun OSS (`parrot-static`), using the same credentials as Android APK releases. The completion output and build report include public download URLs, SHA-256 checksums, and a `release.json` URL. Configure `oss.public.region` and `aliyun.ak/sk` in your PMate configuration. Conflicting published versions require an app version bump. `--dir` produces local unpacked output only; `--dry-run` does not upload.
 
-`pmate app build <ns:app> --target electron --config <file>` builds the configured web app, embeds its static output in an Electron ASAR, and produces a macOS DMG and ZIP. It does not require registry login. The first build downloads pinned Electron and electron-builder versions. Current targets: macOS `arm64` and `x64`, built on macOS.
+`pmate app build <ns:app> --target electron --config <file>` builds the configured web app, embeds its static output in an Electron ASAR, and produces a macOS DMG and ZIP. Packaged releases require a CLI login with admin permission in the app namespace; `--dir` and `--dry-run` stay local. The first build downloads pinned Electron and electron-builder versions. Current targets: macOS and Windows, `arm64` and `x64`; macOS packages require a macOS build host.
 
 ```sh
 pmate app build pmate:hello --target electron --config apps/hello/desktop.config.json --platform mac --arch arm64 --out-dir release/desktop
@@ -294,12 +294,22 @@ Config (paths relative to the config file, `web.dist` relative to `web.cwd`):
 
 Use `--dry-run` to inspect the plan, `--dir` for an unpacked `.app`, or `--signed` to require a configured macOS signing identity. Default builds are ad-hoc signed for local use; they are not notarized distribution releases. Signed builds use electron-builder's standard signing/notarization environment variables; verify notarization separately before distributing.
 
-The shell serves the bundled renderer under its existing exact HTTPS origin, preserving authentication callbacks and API CORS. Other origins remain normal network requests. Static resources are hashed and checked at launch; missing assets return 404. The renderer is sandboxed with Node disabled and no privileged preload bridge. Sign-in, chat and inference still require internet. Updates require a new package. Each build prints its artifact directory and a resource/signing report; no build uploads or auto-updates occur.
+The shell serves the bundled renderer under its existing exact HTTPS origin, preserving authentication callbacks and API CORS. Other origins remain normal network requests. Static resources are hashed and checked at launch; missing assets return 404. The renderer is sandboxed with Node disabled and no privileged preload bridge. Sign-in, chat and inference still require internet. The native application menu includes **检查更新…**. It queries apps-api, compares stable versions, and opens the official installer download after confirmation. Installation remains manual. Each build prints its artifact directory and a resource/signing report; packaged releases upload installers and register the version; `--dir` stays local.
 
 ### 日志统计默认口径
 
 请求次数与日均可使用 `pmate logs aggregate pmate:issues-api --metric count --topic application --field event=http.access --interval day --timezone Asia/Shanghai --from <ISO> --to <ISO> --json`。计数由数据库完成，返回 `count`、`durationDays`、`averagePerDay`，时间桶包含零值；不返回 UV 或延迟百分位。JSON 模式失败以非零状态退出并返回固定 `error.code`，区分权限、保留期、查询预算和上游故障，避免泄露上游原始错误。
 
+### Desktop version registry
+
+Desktop clients need a stable way to discover releases without knowing their versioned OSS path. Apps-api owns this index; installer metadata and checksums remain in OSS `release.json`.
+
+`GET https://apps-api.pmate.chat/versions/pmate:hello?platform=mac&arch=arm64` is public and returns `{ success: true, data: { app, version, platform, arch, manifestUrl, publishedAt, publishedBy, id } }`. A missing release returns 404; it does not mean the installed client is current. Supported targets are `mac|win` and `arm64|x64`. Only stable `major.minor.patch` versions are published.
+
+After installers and their immutable manifest upload successfully, the build calls `POST /versions/:appRef` with `{ version, platform, arch, manifestUrl }` using the existing CLI session. Apps-api requires namespace admin permission and validates the official manifest identity and installer metadata. Older releases never supersede a higher version for the same target. `PMATE_APPS_API_BASE_URL` selects the publisher API; distributed clients query the production API.
+
+A registration failure fails the release command, while preserving already uploaded installers. Once API access is repaired, retry the same POST with the manifest URL in the build report; do not rebuild different bytes under that version. Manual registration of an already published release is idempotent. Native checks have a timeout, reject mismatched targets and external download hosts, and never clear user data or restart the app.
+
 ### Android release signing
 
 `pmate service apk release <service> --env prod --variant release` resolves signing credentials from that service's server-side environment (host variables and local signing environment variables are not used). Configure `ANDROID_KEYSTORE_BASE64`, `ANDROID_KEYSTORE_PASSWORD`, `ANDROID_KEY_ALIAS`, and `ANDROID_KEY_PASSWORD` as Service Secrets, plus `ANDROID_SIGNING_CERT_SHA256` as the expected certificate fingerprint. Android SDK `apksigner` must be installed. The CLI signs the Gradle release APK and verifies its certificate before uploading; missing credentials, invalid signatures, or fingerprint mismatches stop publication. Keystore files use restricted temporary storage and are removed after signing. Existing apps must retain their compatible signing key. Debug builds keep their existing Gradle signing behavior.