feat(help): add common flags section and cache-age hints (#785)

[BYK]

Summary

Closes the last remaining item from #785 — making --fresh/-f discoverable.

1. "Flags:" section in sentry / sentry help

Adds a new section between commands and environment variables showing the most important cross-command flags:

Flags:
        --json       Output as JSON (with --fields to select)
    -f, --fresh      Bypass cache and fetch fresh data
    -v, --verbose    Enable debug logging
        --help       Show help for a command
        --version    Show version

Also exposed via sentry help --json in a new flags array.

Shown in the branded help (sentry, sentry help) but intentionally not in sentry --help — the Stricli-generated --help stays terse and token-efficient for AI agents.

Note: --fresh is available on most read commands (list, view, whoami) but not on mutation commands (create, delete, resolve, login). This mirrors gh --help which lists flags that apply to "most commands" without enumerating exceptions.

2. Cache-age hint in command footers

When data is served from the HTTP response cache, commands now show a hint like:

cached · 3m ago · use -f to refresh

This is applied automatically in buildCommand (src/lib/command.ts) — individual commands don't need any changes. The mechanism:

1. response-cache.ts sets a module-level lastCacheHitAgeMs on cache hits
2. sentry-client.ts clears it at the start of each authenticatedFetch() call
3. buildCommand calls appendCacheHint(returned?.hint) after the generator completes
4. Bare return; paths (e.g. --web) are skipped since no data was rendered

The hint is suppressed in JSON mode, when --fresh is passed, and when SENTRY_NO_CACHE=1 is set.

[github-actions]

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

[github-actions]

Codecov Results 📊

✅ 6178 passed | Total: 6178 | Pass Rate: 100% | Execution Time: 0ms

📊 Comparison with Base Branch

Metric	Change
Total Tests	📈 +20
Passed Tests	📈 +20
Failed Tests	—
Skipped Tests	—

All tests are passing successfully.

❌ Patch coverage is 79.17%. Project has 12843 uncovered lines.
✅ Project coverage is 75.94%. Comparing base (base) to head (head).

Files with missing lines (1)

File	Patch %	Lines
src/lib/help.ts	66.67%	⚠️ 25 Missing

Coverage diff

@@            Coverage Diff             @@
##          main       #PR       +/-##
==========================================
+ Coverage    75.82%    75.94%    +0.12%
==========================================
  Files          289       290        +1
  Lines        53347     53384       +37
  Branches         0         0         —
==========================================
+ Hits         40451     40541       +90
- Misses       12896     12843       -53
- Partials         0         0         —

---

Generated by Codecov Action

[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 5fe6860. Configure here.}