feat(issue): default to recommended sort on Sentry SaaS

[BYK]

Summary

sentry issue list now defaults to the server-side recommended relevance sort on Sentry SaaS (sentry.io), falling back to date on self-hosted instances.

Why SaaS-only

recommended was added to the issue search API on 2026-04-06. The backend raises InvalidSearchQuery → HTTP 400 (Sort key '...' not supported) for instances that lack the sort strategy (sentry/src/sentry/search/snuba/backend.py). Since the CLI supports self-hosted Sentry, an unconditional default would break issue list on older instances — so self-hosted keeps date. If a user explicitly runs --sort recommended against an instance that doesn't support it, the resulting 400 is enriched with a sort-specific hint ("this instance does not support the 'recommended' sort; use --sort date") rather than the generic query/time-range suggestions. The organizations:issue-stream-recommended-sort feature flag is UI-exposure only (api_expose=True); it does not gate the API, so every SaaS org can use it today.

Implementation

• src/lib/sentry-urls.ts — exported the existing private isSaaS() (routing/UX helper; JSDoc points to isSaaSTrustOrigin for trust decisions).
• src/commands/issue/list.ts
  • Added recommended to SortValue / VALID_SORT_VALUES (so parseSort accepts it) and the ListFlags union.
  • New defaultIssueSort() = isSaaS() ? "recommended" : "date".
  • Stricli flag defaults are static, so --sort is now optional and the host-dependent default is resolved at runtime — shadow-resolved at the top of func() (new ListFlagsInput type) so all downstream code keeps a concrete flags.sort.
  • getComparator gains an explicit recommended case.
  • appendIssueFlags omits --sort when it equals the active default (defaultIssueSort() instead of hardcoded "date").
  • The merged-result client re-sort is gated behind isMultiProject so single-project / org-all responses preserve the server's order (fixes the Cursor Bugbot finding where recommended was clobbered by a lastSeen fallback).
  • 400 errors for an unsupported sort get a sort-specific hint (build400Detail).
• No API-layer change — the @sentry/api SDK IssueSort type already includes recommended.

Known limitations (documented)

• Multi-project merges: the recommended relevance score isn't in the issue payload, so when merging results from multiple separately-fetched projects, getComparator falls back to recency (lastSeen). This is identical to the previous date default, so it's not a regression. Single-project and org-all listings (the common case) are fully server-sorted by recommended.
• Pagination cursor reset on upgrade: the pagination context key encodes sort, so on SaaS the default key changes date→recommended after upgrading. Any previously-stored cursor stack is silently orphaned and -c next/-c prev start fresh — self-healing, not corrupting.

Tests

• list.test.ts:
  • End-to-end default wiring (org-all, --sort omitted): asserts the API receives sort: "recommended" on SaaS and sort: "date" on self-hosted — guards the actual feature (verified to fail if the default resolution is reverted).
  • Single-project order preservation: server-ordered recommended results aren't reordered by lastSeen (verified to fail without the isMultiProject guard).
  • defaultIssueSort (SaaS/self-hosted via env), getComparator("recommended"), parseSort("recommended"), appendIssueFlags default-omission, and build400Detail sort-hint cases.
• list.property.test.ts: explicit recommended comparator case (property generators auto-cover it via VALID_SORT_VALUES).
• Docs fragment + regenerated skill reference updated.

Verification

• tsc --noEmit clean
• Issue-list unit + property tests pass (76 in the two files); full CI green on prior revs
• Biome clean; check:fragments passes

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 0a3967f. Configure here.}

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://cli.sentry.dev/_preview/pr-1123/
Built to branch gh-pages at 2026-06-23 10:02 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[github-actions]

Codecov Results 📊

✅ Patch coverage is 100.00%. Project has 5052 uncovered lines.
✅ Project coverage is 81.25%. Comparing base (base) to head (head).

Files with missing lines (1)

File	Patch %	Lines
src/commands/issue/list.ts	100.00%	⚠️ 1 partials

Coverage diff

@@            Coverage Diff             @@
##          main       #PR       +/-##
==========================================
+ Coverage    81.24%    81.25%    +0.01%
==========================================
  Files          388       388         —
  Lines        26936     26947       +11
  Branches     17493     17508       +15
==========================================
+ Hits         21884     21895       +11
- Misses        5052      5052         —
- Partials      1825      1825         —

---

Generated by Codecov Action