[alexandre-vl]

Human comments

What was wrong

A plugin installed from git or npm records a semver range, and update checks only look inside it (satisfyingGitSemverTags). Most marketplace entries declare ^0.y.z, and on 0.x a caret range stops before the next minor: ^0.1.0 is >=0.1.0 <0.2.0-0. A plugin installed at 0.1.x therefore reports current when 0.2.0 exists, and the plugin page draws no Update control, because it only renders when an in-range release exists (PluginUpdatesCard.tsx#L61). Users read this as the plugin being pinned (#5570).

Reproducing it turned up three neighbouring defects in the same path:

• Apply installs a release nobody reviewed. applyUpdate resolves again when it runs (plugin-updates.ts#L582) and takes no arguments (pluginApplyUpdateRequestSchema). If a release is tagged between the check and the click, the CLI, UI and API install it, not the one shown.
• One bad source fails every check. The update sweep has no per-plugin error boundary (checkRows). One unreachable repository (HTTP 422: git ls-remote failed (exit 128)) fails bb plugin outdated and the background check for all plugins.
• An "update" can be a downgrade. Neither resolver checks that the candidate is newer than the installed release (git, npm). On npm this already happens today: a plugin that follows a dist-tag is "updated" back to an older version when its maintainer moves the tag back (allowedNpmVersions). On git it becomes reachable once the recorded range can change, which is the follow-up PR.

What changed

Server (apps/server/src/services/plugins/)

• update-resolver.ts:
  • Each check now also reports outsideRange: the newest stable release that is newer than the installed one and than every release the range admits. A release in a gap of the range is skipped once a newer admitted release exists. For example, ^0.1.0||>=0.2.1 does not name the excluded 0.2.0 while it offers 0.2.5. It is computed from the tag list or packument the check already fetched, so it costs no extra request.
  • breaking follows caret semantics: a new major; a new minor while the major is 0; a new patch while both major and minor are 0.
  • Downgrade guard for git ranges, npm ranges and default specs, and npm dist-tags. A dist-tag that points below the installed version answers current with a "bb does not downgrade" detail.
• plugin-updates.ts:
  • A failure while checking one plugin is stored as unavailable with the error as its detail; the rest of the sweep continues.
  • Apply takes an optional expectedVersion and refuses before staging anything when the fresh candidate differs from it (HTTP 422, naming both releases).
  • After an apply, an outsideRange that is still newer is carried over with breaking recomputed.
• plugin-service.ts: updateState gains availableDisplay, availableBreaking and outsideRange, and forwards the detail of a current check.
• plugin-update-jobs.ts: job deduplication includes expectedVersion.

Contract (packages/server-contract/src/api/plugins.ts): additive only.

• outsideRange {version, display, breaking, range} and candidateBreaking on check entries.
• expectedVersion on the apply request.
• The new updateState fields.

SDK (packages/sdk/src/areas/plugins.ts)

• applyUpdate and experimental_startUpdate take PluginApplyUpdateArgs { expectedVersion? }.
• A server that predates the field raises the typed PluginUpdateExpectedVersionUnsupportedError.
• docs/api_to_audit.md and the plugin SDK bundled declarations are updated.

CLI (apps/cli/src/commands/plugin.ts)

• bb plugin outdated adds an "Outside range" column. Under the table, it prints each plugin's detail line, such as the reason a source is unavailable.
• bb plugin update:
  • prints <id>: current within ^0.1.0; 0.2.0 (may break) is outside the range (compatibility not checked).;
  • warns before confirming a breaking candidate;
  • always sends expectedVersion;
  • tells the user to upgrade a server that predates expectedVersion.

UI (apps/app/src/components/plugin/management/)

• Plugin details show the outside-range release when there is no in-range update, plus a breaking-change note and the check's detail.
• Installed-plugin rows show a muted "0.2.0 outside range" hint.
• The update dialog names a git release by its tag (v0.1.3) instead of a short SHA.
• Update and Retry send expectedVersion.

Docs: bb guide plugins (template bb-guide-plugins.md) explains the outside-range report, the 0.x caret rule and reviewed-release updates.

No daemon wire change, so HOST_DAEMON_PROTOCOL_VERSION is unchanged. Changing the recorded range is the follow-up PR (bb plugin track); this PR only reports what the range excludes.

How you verified

Tests added (they fail without the fix):

• apps/server/test/services/plugins/update-resolver.test.ts: outsideRange for git and npm, gapped and || ranges (a gap release below a newer admitted release is not named), a range tracked above the installed release, prereleases, tag prefixes, the caret breaking rule including 0.0.x, and the downgrade guard (git range, npm range or default, npm dist-tag).
• plugin-update.test.ts: per-plugin isolation in the sweep, the expectedVersion refusal before staging, and the outsideRange carry-over after an apply.
• plugin-update-jobs.test.ts: deduplication by expectedVersion.
• SDK, CLI output, app (details, dialog, row hint, queries) and the plugin SDK bundled declarations.
• To prove the tests bite, 12 fixes were reverted one at a time, and each revert failed its test: 5 server (including the gap rule: expected '0.2.0' to be null), 2 app, 4 CLI, 1 SDK.

Suites, on this branch before its rebase onto 9fad6b625 (pnpm exec turbo run …):

Filter	Result
lint typecheck --filter=...@bb/server-contract --filter=...@bb/sdk --filter=...@get-bb/plugin-sdk --filter=...@bb/templates (every dependent package)	Tasks: 120 successful, 120 total
test --filter=@get-bb/plugin-sdk	Tests 385 passed (385)
test --filter=@bb/sdk	Tests 128 passed (128)
test --filter=@bb/server-contract	Tests 78 passed (78)
test --filter=@bb/cli	Tests 886 passed | 1 skipped (887)
test --filter=@bb/templates	Tests 46 passed (46)
test --filter=@bb/server	Tests 3635 passed | 1 skipped (3636)
test --filter=@bb/app	Tests 6239 passed | 4 skipped (6243)

Rebase. The branch is rebased onto 9fad6b625, plus one commit that bumps @get-bb/plugin-sdk to 0.6.66: this PR changes the SDK's bundled declarations, and CI's npm version guard refuses a changed package under a published version. git range-diff shows the other 14 commits unchanged, and the guard prints PASS — @get-bb/plugin-sdk@0.6.66 is not on npm yet.

End to end, with an isolated dev instance (its own data dir and ports) driven through the CLI, the HTTP API and the browser. Fixtures: a local marketplace and HTTPS git repositories tagged v0.1.0…v0.2.0:

Journey	Before (main)	After
Catalog install with ^0.1.0 while v0.2.0 exists	current, nothing shown	rangefix: current within ^0.1.0; 0.2.0 (may break) is outside the range (compatibility not checked). The detail and row hints say the same. 8/8 checks
A newer release tagged between review and apply	The CLI and UI install the newer release, not the reviewed one; the API cannot name the reviewed release (expectedVersion → HTTP 400)	update refused: expected 1b38c744…, but the current candidate is …@v0.1.2 (460860148a20); check for updates again and review it. HTTP 422 from the API; nothing changes. 20/20 checks
One plugin's repository unreachable	The whole check fails: HTTP 422: git ls-remote failed (exit 128)	That plugin is unavailable with the git error; the others are still checked. 8/8 checks

Part of #5570

AGENT GENERATED