fix(installer): resolve latest stable plugin release (#85)

Resolve the newest stable namespaced Release across all GitHub API pages while retaining explicit version rollback.

Author: gofenix

.github/workflows/deepseek-harness-plugin-release.yml

@@ -46,9 +46,11 @@ jobs:
           const installer = readFileSync('skills/opengui-coremate-install/scripts/install-macos.sh', 'utf8')
           const skill = readFileSync('skills/opengui-coremate-install/SKILL.md', 'utf8')
           const agent = readFileSync('skills/opengui-coremate-install/agents/openai.yaml', 'utf8')
-          if (!installer.includes(`release_version="${pkg.version}"`)) throw new Error('installer version is out of sync')
-          if (!skill.includes(`OpenGUI v${pkg.version} release`)) throw new Error('Skill version is out of sync')
-          if (!agent.includes(`OpenGUI v${pkg.version}`)) throw new Error('Skill agent version is out of sync')
+          if (!installer.includes('/releases?per_page=100') || !installer.includes('--version VERSION')) {
+            throw new Error('installer must resolve the latest stable release and retain an explicit version override')
+          }
+          if (!skill.includes('latest stable OpenGUI release')) throw new Error('Skill latest-release guidance is out of sync')
+          if (!agent.includes('latest stable OpenGUI release')) throw new Error('Skill agent latest-release guidance is out of sync')
           NODE
 
       - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6.0.10
@@ -156,7 +158,7 @@ jobs:
 
           The macOS installer now runs DSH through a per-user LaunchAgent and includes a matching uninstall script. Verified phone-view caches are shared across DSH profiles, including existing \`~/.dsh\` caches.
 
-          Download both the \`.tgz\` package and its \`.sha256\` file. The recommended macOS path is the [Codex installer Skill](https://github.com/Core-Mate/OpenGUI/tree/${GITHUB_REF_NAME}/deepseek-harness-plugin/skills/opengui-coremate-install).
+          Download both the \`.tgz\` package and its \`.sha256\` file. The recommended macOS path is the stable [Codex installer Skill](https://github.com/Core-Mate/OpenGUI/tree/main/deepseek-harness-plugin/skills/opengui-coremate-install), which resolves the latest stable plugin release each time it runs.
 
           The package supports DeepSeek Harness through \`/opengui\` and \`@OpenGUI\`, and Codex through the \`opengui:control\` Skill plus seven local stdio MCP tools. Both hosts share the same bounded Android execution runtime, multi-device locking, cancellation, and read-only device-wall support.
 

README.ja-JP.md

@@ -38,10 +38,10 @@ OpenGUI は実際の Android アプリ UI を読み取り、次のステップ
 
 ## DeepSeek HarnessでOpenGUIを使う
 
-macOSでは、固定バージョンのインストーラーSkillをCodexに実行させる方法が最短です。Node.js 22.19以降または24以降が必要で、互換性のあるDSHバージョンは自動的にインストールされます。次の内容を1つのプロンプトとして送信します：
+macOSでは、`main` ブランチの安定したインストーラーSkillをCodexに実行させる方法が最短です。実行するたびに最新の安定版OpenGUIプラグインを解決してインストールし、ロールバック用に明示的なバージョン指定も利用できます。Node.js 22.19以降または24以降が必要で、互換性のあるDSHバージョンは自動的にインストールされます。次の内容を1つのプロンプトとして送信します：
 
 ```text
-Install and run the OpenGUI installer Skill from https://github.com/Core-Mate/OpenGUI/tree/dsh-coremate-mobile-v0.1.7/deepseek-harness-plugin/skills/opengui-coremate-install for my DSH web profile. Proceed autonomously, and only pause when I need to authorize or select a phone, add or select a DSH workspace, or provide fallback visual-model credentials.
+Install and run the OpenGUI installer Skill from https://github.com/Core-Mate/OpenGUI/tree/main/deepseek-harness-plugin/skills/opengui-coremate-install for my DSH web profile. Install the latest stable release. Proceed autonomously, and only pause when I need to authorize or select a phone, add or select a DSH workspace, or provide fallback visual-model credentials.
 ```
 
 Skillは公開ReleaseのパッケージとチェックサムをダウンロードしてSHA-256を検証し、OpenGUIプラグインだけをインストールします。必要な場合はDSHを起動して開き、既存のプラグインと設定は保持します。DSHがすでに起動していた場合は、一度再起動するとプラグインが読み込まれます。LinuxまたはWindowsでは、[手動パッケージガイド](./deepseek-harness-plugin/README.md#1-download-the-release-package)を使用してください。

README.md

@@ -39,10 +39,10 @@ OpenGUI reads a real Android app UI, plans the next step, takes mobile actions,
 
 ## Use OpenGUI in DeepSeek Harness
 
-The shortest path on macOS is to let Codex run the pinned installer Skill. It requires Node.js 22.19+ or 24+ and installs the compatible DSH version automatically. Paste this as one prompt:
+The shortest path on macOS is to let Codex run the stable installer Skill from `main`. Each run resolves the latest stable OpenGUI plugin release, while an explicit version remains available for rollback. It requires Node.js 22.19+ or 24+ and installs the compatible DSH version automatically. Paste this as one prompt:
 
 ```text
-Install and run the OpenGUI installer Skill from https://github.com/Core-Mate/OpenGUI/tree/dsh-coremate-mobile-v0.1.7/deepseek-harness-plugin/skills/opengui-coremate-install for my DSH web profile. Proceed autonomously, and only pause when I need to authorize or select a phone, add or select a DSH workspace, or provide fallback visual-model credentials.
+Install and run the OpenGUI installer Skill from https://github.com/Core-Mate/OpenGUI/tree/main/deepseek-harness-plugin/skills/opengui-coremate-install for my DSH web profile. Install the latest stable release. Proceed autonomously, and only pause when I need to authorize or select a phone, add or select a DSH workspace, or provide fallback visual-model credentials.
 ```
 
 The Skill downloads the public release package and checksum, verifies SHA-256, installs only the OpenGUI plugin, starts DSH when needed, and opens DSH. It preserves unrelated DSH plugins and settings. If DSH was already running, restart it once to load the plugin. For Linux or Windows, use the [manual package guide](./deepseek-harness-plugin/README.md#1-download-the-release-package).

README.zh-CN.md

@@ -38,10 +38,10 @@ OpenGUI 会读取真实 Android App 界面，规划下一步操作，执行移
 
 ## 在 DeepSeek Harness 中使用 OpenGUI
 
-macOS 上最短的路径，是让 Codex 运行固定版本的安装 Skill。环境需要 Node.js 22.19+ 或 24+，兼容的 DSH 版本会自动安装。把下面整段作为一条消息发给 Codex：
+macOS 上最短的路径，是让 Codex 运行 `main` 分支上的稳定安装 Skill。每次执行时，安装器都会解析并安装最新正式版 OpenGUI 插件，同时保留指定版本参数用于回滚。环境需要 Node.js 22.19+ 或 24+，兼容的 DSH 版本会自动安装。把下面整段作为一条消息发给 Codex：
 
 ```text
-请安装并运行这个 OpenGUI 安装 Skill：https://github.com/Core-Mate/OpenGUI/tree/dsh-coremate-mobile-v0.1.7/deepseek-harness-plugin/skills/opengui-coremate-install，把插件安装到我的 DSH web profile。请自主完成安装，仅在需要我授权或选择手机、添加或选择 DSH workspace，或者提供备用视觉模型凭据时暂停并询问我。
+请安装并运行这个 OpenGUI 安装 Skill：https://github.com/Core-Mate/OpenGUI/tree/main/deepseek-harness-plugin/skills/opengui-coremate-install，把最新正式版插件安装到我的 DSH web profile。请自主完成安装，仅在需要我授权或选择手机、添加或选择 DSH workspace，或者提供备用视觉模型凭据时暂停并询问我。
 ```
 
 Skill 会下载公开 Release 的插件包和校验文件，验证 SHA-256，只安装 OpenGUI 插件，在需要时启动并打开 DSH，同时保留其他 DSH 插件和设置。如果 DSH 原本正在运行，重启一次即可加载插件。Linux 或 Windows 用户可按[手动安装说明](./deepseek-harness-plugin/README.zh.md#1-下载发布包)操作。

deepseek-harness-plugin/README.md

@@ -50,7 +50,7 @@ The examples use the `web` profile and the default `$DSH_HOME=~/.dsh`. Substitut
 
 ### macOS: install with the Codex Skill
 
-Ask Codex to install the repository skill from [`deepseek-harness-plugin/skills/opengui-coremate-install`](./skills/opengui-coremate-install), then invoke `$opengui-coremate-install`. The Skill downloads and verifies the pinned `v0.1.7` package from the public OpenGUI Release, preserves the rest of the `web` profile, and installs a per-user LaunchAgent so DSH returns after a crash or login. GitHub login is not required.
+Ask Codex to install the repository skill from [`deepseek-harness-plugin/skills/opengui-coremate-install`](./skills/opengui-coremate-install), then invoke `$opengui-coremate-install`. The Skill resolves the latest stable namespaced plugin Release, downloads its package and checksum, preserves the rest of the `web` profile, and installs a per-user LaunchAgent so DSH returns after a crash or login. Drafts, prereleases, and unrelated OpenGUI releases are ignored. GitHub login is not required. Use `--version VERSION` only for rollback or a reproducible install.
 
 If port 3080 belongs to an OpenGUI-managed DSH, the installer safely reloads that LaunchAgent. It never terminates an unowned DSH process; in that case the new LaunchAgent takes over after the next login. The manual package flow below remains available on every supported host.
 

deepseek-harness-plugin/README.zh.md

@@ -52,7 +52,7 @@ codex plugin add opengui@opengui-local
 
 ### macOS：通过 Codex Skill 安装
 
-让 Codex 从仓库的 [`deepseek-harness-plugin/skills/opengui-coremate-install`](./skills/opengui-coremate-install) 安装 Skill，然后调用 `$opengui-coremate-install`。Skill 会从 OpenGUI 的公开 Release 下载并校验固定的 `v0.1.7` 安装包，保留 `web` profile 中的其他配置，并安装用户级 LaunchAgent，让 DSH 在异常退出或重新登录后自动恢复；不要求登录 GitHub。
+让 Codex 从仓库的 [`deepseek-harness-plugin/skills/opengui-coremate-install`](./skills/opengui-coremate-install) 安装 Skill，然后调用 `$opengui-coremate-install`。Skill 会解析最新的插件正式版 Release，下载并校验对应的安装包，忽略草稿、预发布版和 OpenGUI 的其他 Release；同时保留 `web` profile 中的其他配置，并安装用户级 LaunchAgent，让 DSH 在异常退出或重新登录后自动恢复。整个过程不要求登录 GitHub。只有回滚或需要可复现安装时才使用 `--version VERSION`。
 
 如果 3080 端口属于 OpenGUI 管理的 DSH，安装器会安全更新并重启对应 LaunchAgent；如果属于其他 DSH 进程，安装器绝不会强制终止它，新 LaunchAgent 会在下次登录后接管。下面的手动安装方式仍适用于所有受支持的系统。
 

deepseek-harness-plugin/skills/opengui-coremate-install/SKILL.md

@@ -1,19 +1,21 @@
 ---
 name: opengui-coremate-install
-description: Install the pinned OpenGUI v0.1.7 release into a DeepSeek Harness web profile on macOS. Use when the user asks to download, install, update, open, or verify OpenGUI for DSH.
+description: Install the latest stable OpenGUI release into a DeepSeek Harness web profile on macOS. Use when the user asks to download, install, update, open, or verify OpenGUI for DSH.
 ---
 
 # Install OpenGUI
 
-Install and verify the signed-off `v0.1.7` release without replacing unrelated DSH plugins or settings.
+Install and verify the latest stable OpenGUI release without replacing unrelated DSH plugins or settings.
 
 ## Run the installer
 
 1. Confirm the host is macOS. Do not improvise a Linux or Windows install.
 2. Run `scripts/install-macos.sh` from this skill directory.
 3. Report the installed package version, profile path, runtime URL, and whether an existing DSH process still needs a manual restart.
 
-The script checks the host Node version, pins DSH to `0.1.0-rc.7`, downloads both the release tarball and checksum from the public GitHub Release, verifies SHA-256, installs only `dsh-coremate-mobile` into the `web` profile, and validates the package, bundle, Client entry, and `/opengui` command. GitHub authentication is not required.
+By default, the script resolves the highest stable `dsh-coremate-mobile-v*` release from the public GitHub Releases API. It ignores drafts, prereleases, and unrelated OpenGUI releases. Use `--version VERSION` only when the user explicitly requests a rollback or reproducible install.
+
+The script checks the host Node version, pins DSH to `0.1.0-rc.7`, downloads both the resolved release tarball and checksum, verifies SHA-256, installs only `dsh-coremate-mobile` into the `web` profile, and validates the package, bundle, Client entry, and `/opengui` command. GitHub authentication is not required.
 
 The script installs a user LaunchAgent with `KeepAlive` so DSH returns after a crash or login. It may safely reload an instance already owned by that exact LaunchAgent. If port 3080 belongs to any other DSH process, preserve it: the installer writes the LaunchAgent but defers takeover until the next login. When DSH is not running, the script starts and verifies `http://127.0.0.1:3080`.
 

deepseek-harness-plugin/skills/opengui-coremate-install/agents/openai.yaml

@@ -1,7 +1,7 @@
 interface:
   display_name: "OpenGUI Installer"
-  short_description: "Install verified OpenGUI v0.1.7 into DSH on macOS"
+  short_description: "Install the latest stable OpenGUI release into DSH on macOS"
   icon_small: "./assets/opengui-mark.svg"
   icon_large: "./assets/opengui-wordmark.svg"
   brand_color: "#F1BF1F"
-  default_prompt: "Use $opengui-coremate-install to download, verify, install, and open OpenGUI v0.1.7 for my DSH web profile."
+  default_prompt: "Use $opengui-coremate-install to download, verify, install, and open the latest stable OpenGUI release for my DSH web profile."

deepseek-harness-plugin/skills/opengui-coremate-install/scripts/install-macos.sh

@@ -1,25 +1,31 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-release_version="0.1.7"
 dsh_version="0.1.0-rc.7"
 profile="web"
 port="${COREMATE_INSTALL_PORT_OVERRIDE:-3080}"
 package_name="dsh-coremate-mobile"
 github_repository="Core-Mate/OpenGUI"
+release_version="${COREMATE_INSTALL_VERSION_OVERRIDE:-}"
 github_release_base="https://github.com/${github_repository}/releases/download"
+github_releases_api="${COREMATE_INSTALL_RELEASES_API_OVERRIDE:-https://api.github.com/repos/${github_repository}/releases?per_page=100}"
 release_base="${COREMATE_INSTALL_RELEASE_BASE:-${github_release_base}}"
 dsh_home="${DSH_HOME:-${HOME}/.dsh}"
 launch_agents_dir="${COREMATE_INSTALL_LAUNCH_AGENTS_DIR_OVERRIDE:-${HOME}/Library/LaunchAgents}"
 start_runtime=true
 open_browser=true
 
 usage() {
-  printf '%s\n' 'Usage: install-macos.sh [--dsh-home PATH] [--release-base URL] [--no-start] [--no-open]'
+  printf '%s\n' 'Usage: install-macos.sh [--version VERSION] [--dsh-home PATH] [--release-base URL] [--no-start] [--no-open]'
 }
 
 while (($# > 0)); do
   case "$1" in
+    --version)
+      [[ $# -ge 2 ]] || { usage >&2; exit 2; }
+      release_version="$2"
+      shift 2
+      ;;
     --dsh-home)
       [[ $# -ge 2 ]] || { usage >&2; exit 2; }
       dsh_home="$2"
@@ -52,7 +58,7 @@ done
 
 platform="${COREMATE_INSTALL_PLATFORM_OVERRIDE:-$(uname -s)}"
 if [[ "$platform" != "Darwin" ]]; then
-  printf 'OpenGUI v%s installer supports macOS only; detected %s.\n' "$release_version" "$platform" >&2
+  printf 'The OpenGUI installer supports macOS only; detected %s.\n' "$platform" >&2
   exit 1
 fi
 
@@ -90,6 +96,79 @@ if [[ "$installed_dsh" != "$dsh_version" ]]; then
   exit 1
 fi
 
+temporary="$(mktemp -d "${TMPDIR:-/tmp}/opengui-coremate-install.XXXXXX")"
+trap 'rm -rf "$temporary"' EXIT
+
+if [[ -z "$release_version" ]]; then
+  printf 'Resolving the latest stable OpenGUI plugin release...\n'
+  api_args=(-fsSL --retry 3 --connect-timeout 15 --max-time 60
+    -H 'Accept: application/vnd.github+json'
+    -H 'X-GitHub-Api-Version: 2022-11-28')
+  if [[ "$github_releases_api" == https://* ]]; then api_args+=(--proto '=https' --tlsv1.2); fi
+  releases_directory="${temporary}/releases"
+  mkdir -p "$releases_directory"
+  releases_url="$github_releases_api"
+  releases_page=1
+  while [[ -n "$releases_url" ]]; do
+    page_body="${releases_directory}/${releases_page}.json"
+    page_headers="${releases_directory}/${releases_page}.headers"
+    if ! curl "${api_args[@]}" --dump-header "$page_headers" --output "$page_body" "$releases_url"; then
+      printf 'Could not read OpenGUI plugin releases from GitHub. Check GitHub access or retry with --version VERSION.\n' >&2
+      exit 1
+    fi
+    if ! node -e '
+      const releases = JSON.parse(require("node:fs").readFileSync(process.argv[1], "utf8"))
+      if (!Array.isArray(releases)) throw new Error("GitHub Releases response is not an array")
+    ' "$page_body"; then
+      printf 'GitHub returned an invalid Releases response. Retry with --version VERSION.\n' >&2
+      exit 1
+    fi
+    releases_url="$(node -e '
+      const headers = require("node:fs").readFileSync(process.argv[1], "utf8")
+      const link = headers.split(/\r?\n/u).find(line => /^link:/iu.test(line)) ?? ""
+      const next = link.replace(/^link:\s*/iu, "").split(",").map(value => value.trim())
+        .map(value => value.match(/^<([^>]+)>;\s*rel="([^"]+)"$/u))
+        .find(match => match?.[2]?.split(/\s+/u).includes("next"))
+      if (next) process.stdout.write(next[1])
+    ' "$page_headers")"
+    releases_page=$((releases_page + 1))
+  done
+
+  if ! release_version="$(
+    node --input-type=module -e '
+        import { readFileSync, readdirSync } from "node:fs"
+        const packageName = process.argv[1]
+        const directory = process.argv[2]
+        const releases = readdirSync(directory)
+          .filter(name => name.endsWith(".json"))
+          .flatMap(name => JSON.parse(readFileSync(`${directory}/${name}`, "utf8")))
+        const pattern = new RegExp(`^${packageName}-v(\\d+)\\.(\\d+)\\.(\\d+)$`)
+        const versions = releases.flatMap(release => {
+          if (release?.draft || release?.prerelease || typeof release?.tag_name !== "string") return []
+          const match = release.tag_name.match(pattern)
+          return match ? [{ version: match.slice(1).join("."), parts: match.slice(1).map(Number) }] : []
+        })
+        versions.sort((left, right) => {
+          for (let index = 0; index < 3; index += 1) {
+            if (left.parts[index] !== right.parts[index]) return right.parts[index] - left.parts[index]
+          }
+          return 0
+        })
+        if (versions.length === 0) throw new Error(`No stable ${packageName} release was found`)
+        process.stdout.write(versions[0].version)
+      ' "$package_name" "$releases_directory"
+  )"; then
+    printf 'Could not resolve the latest stable OpenGUI plugin release. Check GitHub access or retry with --version VERSION.\n' >&2
+    exit 1
+  fi
+fi
+
+if [[ ! "$release_version" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+  printf 'Invalid OpenGUI plugin version: %s. Expected a stable version such as 0.1.7.\n' "$release_version" >&2
+  exit 1
+fi
+printf 'Using OpenGUI plugin v%s.\n' "$release_version"
+
 runtime_running=false
 if lsof -nP -iTCP:"$port" -sTCP:LISTEN >/dev/null 2>&1; then
   page="$(curl -fsS --max-time 3 "http://127.0.0.1:${port}" || true)"
@@ -104,8 +183,6 @@ archive_name="${package_name}-${release_version}.tgz"
 checksum_name="${archive_name}.sha256"
 release_tag="${package_name}-v${release_version}"
 release_url="${release_base%/}/${release_tag}"
-temporary="$(mktemp -d "${TMPDIR:-/tmp}/opengui-coremate-install.XXXXXX")"
-trap 'rm -rf "$temporary"' EXIT
 
 download() {
   local url="$1"