feat: prompt plugin users to upgrade the global CLI

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+- Have both plugins check the global CLI against npm's latest stable version at
+  startup and offer an upgrade before continuing. Existing installations change
+  only after the user agrees; offline update checks keep the current CLI usable.
+
 ## 0.10.0 — 2026-10-25
 
 - Make Codex and Claude plugins reuse the global CodeJury CLI, install globally

docs/codex-plugin.md

@@ -16,7 +16,8 @@ In a new Codex chat, select **CodeJury** and ask:
 
 Setup checks prerequisites without starting a review. The plugin uses your global
 CodeJury CLI, or installs it globally with `npm install --global @agentsdance/codejury@latest`
-if missing. Agent installation and login are separate.
+if missing. If a newer stable CLI is available, it asks whether to upgrade or
+keep your current version. Agent installation and login are separate.
 
 ## Review a PR
 
@@ -45,6 +46,11 @@ checks npm's global package directory and reuses CodeJury there. If missing, it
 installs globally; it never creates a separate plugin CLI installation. The plugin
 and CLI have separate versions.
 
+The startup `version` check compares the installed CLI with npm's `latest` stable
+release. The host asks before upgrading an existing CLI; ordinary CLI commands
+do not repeat the lookup. The registry check times out after three seconds, and
+offline or invalid responses leave the installed CLI usable.
+
 Build the submission archive from the repository root:
 
 ```sh

plugin/README.md

@@ -4,7 +4,8 @@ Review and fix pull requests with a Claude reviewer and a separate Claude judge.
 
 You need Node.js 20.10+, npm, Git, and a signed-in Claude Code CLI. GitHub PRs
 also need a signed-in `gh` CLI. The plugin checks your global `jury` installation
-and installs it globally if missing.
+and installs it globally if missing. If a newer stable CLI is available, it asks
+whether to upgrade or keep your current version.
 
 ## Install
 

plugin/scripts/jury.mjs

@@ -18,6 +18,38 @@ function npm(args, capture = false) {
   return capture ? result.stdout.trim() : undefined;
 }
 
+function versionParts(version) {
+  return typeof version === 'string' && /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.exec(version);
+}
+
+function checkForUpdate(currentVersion) {
+  // The host runs `version` once before the operation and presents the choice
+  // in chat. Never wait for terminal input or upgrade an existing CLI here.
+  try {
+    const result = spawnSync(process.platform === 'win32' ? 'npm.cmd' : 'npm', [
+      'view', '@agentsdance/codejury@latest', 'version', '--json', '--prefer-online',
+      '--fetch-retries=0', '--fetch-timeout=2000',
+    ], {
+      encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 3000,
+      maxBuffer: 16 * 1024, shell: process.platform === 'win32',
+    });
+    if (result.error || result.status !== 0) throw new Error('Registry unavailable');
+    const latestVersion = JSON.parse(result.stdout);
+    const current = versionParts(currentVersion);
+    const latest = versionParts(latestVersion);
+    if (!current || !latest || latest[4]) throw new Error('Invalid stable version');
+    const difference = [1, 2, 3].find(index => BigInt(latest[index]) !== BigInt(current[index]));
+    const newer = difference ? BigInt(latest[difference]) > BigInt(current[difference]) : Boolean(current[4]);
+    if (newer) {
+      console.error(`CodeJury update available: ${currentVersion} -> ${latestVersion}`);
+      console.error('Upgrade the global CLI? Ask the user before upgrading; they can keep the current version.');
+      console.error(`To upgrade: npm install --global @agentsdance/codejury@${latestVersion}`);
+    }
+  } catch {
+    console.error(`Update check unavailable; continuing with global CodeJury ${currentVersion}.`);
+  }
+}
+
 const globalRoot = npm(['root', '--global'], true);
 if (!path.isAbsolute(globalRoot)) throw new Error('npm did not return an absolute global package directory.');
 const packageRoot = path.join(globalRoot, '@agentsdance', 'codejury');
@@ -37,6 +69,7 @@ if (!metadata) {
 }
 if (!metadata) throw new Error(`Global CodeJury installation is incomplete at ${packageRoot}. Run npm install --global @agentsdance/codejury@latest and retry.`);
 console.error(`Using global CodeJury ${metadata.version} at ${entry}`);
+if (['version', '--version', '-v'].includes(process.argv[2])) checkForUpdate(metadata.version);
 
 // Import in this process so cancellation reaches the CLI and its agent cleanup.
 process.argv = [process.execPath, entry, ...process.argv.slice(2)];

plugin/skills/codejury/SKILL.md

@@ -23,6 +23,13 @@ checks npm's global CodeJury installation and installs globally if missing; it s
 on errors instead of using npx or a private copy. Use this runner in place of `jury`
 in the examples below. Keep the same `--dir` and `--run` for saved findings.
 
+The `version` check also looks for a newer stable CLI on npm. If an update is
+available, show both versions and ask whether to **upgrade globally** or **keep
+the current version**. Run the printed npm install command only after the user
+agrees, then rerun `version` to verify. If they decline or explicitly chose a
+version, keep it. An unavailable update check does not block the operation.
+Do not repeat this prompt during the same operation.
+
 ## The loop
 
 ```

plugin/skills/review/SKILL.md

@@ -32,6 +32,13 @@ CLI path, and stops on installation errors. Node.js 20.10+ and npm are required.
 Use this runner in place of `jury` in every command below, including `agents`,
 `runs`, and reopening the console. Never use npx or install a private CLI copy.
 
+The `version` check also looks for a newer stable CLI on npm. If an update is
+available, show both versions and ask whether to **upgrade globally** or **keep
+the current version** before starting the review. Run the printed npm install
+command only after the user agrees, then rerun `version` to verify. If they
+decline or explicitly chose a version, keep it. An unavailable update check does
+not block the review. Do not repeat this prompt during the same operation.
+
 ## 3. Build the command
 
 Start from `node "<plugin-root>/scripts/jury.mjs" review`. Normalize the role flags as
@@ -69,10 +76,11 @@ missing or unauthenticated agent CLI, a missing `gh` login for a GitHub URL), sh
 the fix it names; `jury agents` lists which agent CLIs are installed.
 
 Older CLIs, including 0.8.1, reject a reviewer that is also the judge. If that specific error
-appears, explain that the global CLI is too old. Upgrade it with
-`npm install --global @agentsdance/codejury@latest`, then retry once through the
-same runner with the same normalized arguments. Honor an explicitly requested
-CLI version instead of upgrading it silently. If the upgrade or retry fails,
+appears, explain that the global CLI is too old. Offer
+`npm install --global @agentsdance/codejury@latest`; only after the user agrees,
+upgrade and retry once through the same runner with the same normalized arguments.
+If they already declined the startup offer or explicitly chose the old version,
+explain the incompatibility and stop without asking again. If the upgrade or retry fails,
 report the error and stop. Do not use npx, a private install, or another agent
 as a fallback. Disabled Claude or missing authentication still needs to be fixed.
 

plugins/codejury/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "codejury",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Review pull requests supplied by URL with CodeJury's independent AI reviewers and judge, resume PR reviews, and inspect saved findings.",
   "author": {
     "name": "ZHOU ZHENGXI",
@@ -22,7 +22,7 @@
       "interface": {
         "displayName": "CodeJury",
         "shortDescription": "AI pull request review",
-        "longDescription": "Review pull requests supplied by URL with independent coding agents and a judge that investigates findings, applies fixes, and asks reviewers to check again. Set up the CLI, run or resume a PR review, and inspect saved findings and conversations. A new review requires a PR link; arbitrary local files and folders are not supported plugin review targets. PR reviews use a local checkout. Desktop only: requires Node.js 20.10+, npm, Git, and separately installed and authenticated coding-agent CLIs. GitHub PRs also require GitHub CLI. This plugin reuses your npm-global CodeJury CLI, or installs the latest stable CLI globally if missing. It does not create a private CLI installation. Reviews can edit files, create commits, and push fixes to the PR by default; ask to keep fixes local or use --push=false to disable pushing. Code and prompts are processed by your selected agents and their providers, subject to their terms and usage charges. CodeJury keeps review records locally and operates no hosted review service. The included console screenshot shows a real prior review; results vary by repository and agent.",
+        "longDescription": "Review pull requests supplied by URL with independent coding agents and a judge that investigates findings, applies fixes, and asks reviewers to check again. Set up the CLI, run or resume a PR review, and inspect saved findings and conversations. A new review requires a PR link; arbitrary local files and folders are not supported plugin review targets. PR reviews use a local checkout. Desktop only: requires Node.js 20.10+, npm, Git, and separately installed and authenticated coding-agent CLIs. GitHub PRs also require GitHub CLI. This plugin reuses your npm-global CodeJury CLI, or installs the latest stable CLI globally if missing. It checks for newer stable CLI releases and asks before upgrading an existing installation. It does not create a private CLI installation. Reviews can edit files, create commits, and push fixes to the PR by default; ask to keep fixes local or use --push=false to disable pushing. Code and prompts are processed by your selected agents and their providers, subject to their terms and usage charges. CodeJury keeps review records locally and operates no hosted review service. The included console screenshot shows a real prior review; results vary by repository and agent.",
         "developerName": "ZHOU ZHENGXI",
         "category": "Developer Tools",
         "capabilities": [
@@ -47,7 +47,7 @@
         ]
       },
       "publication": {
-        "release_notes": "Reuse the global CodeJury CLI and install globally when missing. Remove private CLI downloads and stop on installation errors."
+        "release_notes": "Check the global CLI for newer stable releases during setup and ask before upgrading. Keep the installed CLI usable when the update check is unavailable."
       }
     }
   }

plugins/codejury/scripts/jury.mjs

@@ -18,6 +18,38 @@ function npm(args, capture = false) {
   return capture ? result.stdout.trim() : undefined;
 }
 
+function versionParts(version) {
+  return typeof version === 'string' && /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.exec(version);
+}
+
+function checkForUpdate(currentVersion) {
+  // The host runs `version` once before the operation and presents the choice
+  // in chat. Never wait for terminal input or upgrade an existing CLI here.
+  try {
+    const result = spawnSync(process.platform === 'win32' ? 'npm.cmd' : 'npm', [
+      'view', '@agentsdance/codejury@latest', 'version', '--json', '--prefer-online',
+      '--fetch-retries=0', '--fetch-timeout=2000',
+    ], {
+      encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 3000,
+      maxBuffer: 16 * 1024, shell: process.platform === 'win32',
+    });
+    if (result.error || result.status !== 0) throw new Error('Registry unavailable');
+    const latestVersion = JSON.parse(result.stdout);
+    const current = versionParts(currentVersion);
+    const latest = versionParts(latestVersion);
+    if (!current || !latest || latest[4]) throw new Error('Invalid stable version');
+    const difference = [1, 2, 3].find(index => BigInt(latest[index]) !== BigInt(current[index]));
+    const newer = difference ? BigInt(latest[difference]) > BigInt(current[difference]) : Boolean(current[4]);
+    if (newer) {
+      console.error(`CodeJury update available: ${currentVersion} -> ${latestVersion}`);
+      console.error('Upgrade the global CLI? Ask the user before upgrading; they can keep the current version.');
+      console.error(`To upgrade: npm install --global @agentsdance/codejury@${latestVersion}`);
+    }
+  } catch {
+    console.error(`Update check unavailable; continuing with global CodeJury ${currentVersion}.`);
+  }
+}
+
 const globalRoot = npm(['root', '--global'], true);
 if (!path.isAbsolute(globalRoot)) throw new Error('npm did not return an absolute global package directory.');
 const packageRoot = path.join(globalRoot, '@agentsdance', 'codejury');
@@ -37,6 +69,7 @@ if (!metadata) {
 }
 if (!metadata) throw new Error(`Global CodeJury installation is incomplete at ${packageRoot}. Run npm install --global @agentsdance/codejury@latest and retry.`);
 console.error(`Using global CodeJury ${metadata.version} at ${entry}`);
+if (['version', '--version', '-v'].includes(process.argv[2])) checkForUpdate(metadata.version);
 
 // Import in this process so cancellation reaches the CLI and its agent cleanup.
 process.argv = [process.execPath, entry, ...process.argv.slice(2)];

plugins/codejury/skills/codejury-results/SKILL.md

@@ -12,6 +12,13 @@ Installation errors stop the operation; do not use npx or a private CLI copy.
 Respect an explicitly requested CLI version, install it globally if needed,
 and check its help for supported flags.
 
+Run `version` once before inspecting results. It checks npm for a newer stable
+CLI. If an update is available, show both versions and ask whether to **upgrade
+globally** or **keep the current version**. Run the printed npm install command
+only after the user agrees, then rerun `version` to verify. If they decline or
+explicitly chose a version, keep it. An unavailable update check does not block
+reading saved results. Do not repeat this prompt during the same operation.
+
 1. Identify the original state root. URL reviews default to `~/.jury`; use
    `--dir ""` to select it explicitly. A local-checkout review stores `runs/`
    under that checkout. Do not assume the current repository owns a URL run.

plugins/codejury/skills/codejury-review/SKILL.md

@@ -29,6 +29,13 @@ version and absolute path. Installation errors stop the run; do not use npx or a
 private CLI copy. If the user requests a different version, install that version
 globally and inspect its help.
 
+Run `version` once before starting or resuming a review. It also checks npm for a
+newer stable CLI. If an update is available, show both versions and ask whether
+to **upgrade globally** or **keep the current version**. Run the printed npm
+install command only after the user agrees, then rerun `version` to verify.
+If they decline or explicitly chose a version, keep it. An unavailable update
+check does not block the review. Do not repeat this prompt during the same operation.
+
 Check Node.js 20.10+, npm, Git, and the requested agent CLIs. For GitHub PRs,
 check GitHub CLI authentication. Run `jury agents` to discover executables;
 this does not verify provider login or quota. Fix missing prerequisites before

plugins/codejury/skills/codejury-setup/SKILL.md

@@ -21,16 +21,19 @@ selected, without starting a review.
 
    ```sh
    node "<plugin-root>/scripts/jury.mjs" version
-   node "<plugin-root>/scripts/jury.mjs" agents
    ```
 
    The launcher checks `npm root --global` for CodeJury and reuses that global
    installation. If missing, it runs `npm install --global @agentsdance/codejury@latest`.
    It reports the version and absolute CLI path. Installation errors stop setup;
    never use npx, a custom prefix, or a plugin-private CLI copy as a fallback.
-   Existing versions are not upgraded automatically. For a requested version,
-   install that version globally and check its help before using its options.
-3. `jury agents` checks executable availability, not authentication or quota.
+   `version` also checks npm for a newer stable CLI. If it reports an update,
+   show both versions and ask whether to **upgrade globally** or **keep the current
+   version** before continuing. Run the printed npm install command only after
+   the user agrees, then rerun `version` to verify. If they decline or explicitly
+   chose a version, keep it. An unavailable update check does not block setup.
+3. Run `node "<plugin-root>/scripts/jury.mjs" agents`. This checks executable
+   availability, not authentication or quota.
    Report these separately. Consult the CLI's built-in install hints for missing
    agents. Let the user complete provider sign-in; do not collect credentials
    into the plugin or copy credentials between providers.