Skip to content
This repository was archived by the owner on Oct 23, 2026. It is now read-only.

feat(banner): sixel image banner on capable terminals - #1187

Merged
BYK merged 5 commits into
mainfrom
feat/banner-sixel
Jul 3, 2026
Merged

BYK merged 5 commits into
mainfrom
feat/banner-sixel

Conversation

@BYK

@BYK BYK commented Jul 3, 2026

Copy link
Copy Markdown
Member

On terminals that support sixel graphics, sentry help now renders the Sentry arch + SENTRY wordmark as a real image (brand gradient, transparent background so it floats on the terminal bg like the block-art) instead of the Unicode block-art. Everything degrades gracefully to the existing block-art banner (and to plain text on narrow terminals).

Follow-up to the banner block-art work (#1169).

How it works

  • Baked at build, no runtime image deps. assets/banner-mask.png (white-on-transparent arch+SENTRY mask) is encoded by script/generate-banner-sixel.ts into a transparent sixel string (P2=1) with the brand gradient, written to src/generated/banner-sixel.ts (gitignored, like skill-content.ts). The generator runs first in the generate:docs chain. The runtime just prints the baked string — ~4.2 KB.
  • Detection (src/lib/sixel.ts): a best-effort, cached, unix-only probe. It queries Primary DA (ESC[c → attribute 4 = sixel) + cell size (ESC[16t), reading the reply from a blocking /dev/tty fd (Node keeps stdin non-blocking, which otherwise both defeats detection and leaks the reply onto the prompt). Gated behind an interactive TTY and honoring NO_COLOR / SENTRY_PLAIN_OUTPUT / SENTRY_NO_SIXEL / TERM.
  • Fit check. The fixed-pixel image is only shown when it isn't wider than the terminal (bannerWidth ≤ columns × cellWidth); otherwise block-art.
  • Opt-out. SENTRY_NO_SIXEL=1 forces the block-art banner (registered in the env registry).

Scope / limitations (by design)

  • Unix only for now (the probe uses stty + /dev/tty); Windows falls back to block-art. Kitty/Ghostty/iTerm2 (non-sixel graphics protocols) and the init wizard are out of scope — possible phase 2.
  • The image is a single baked size; narrow terminals fall back to block-art rather than scaling.

Tests

test/lib/sixel.test.ts covers DA1/cell-size reply parsing (incl. not matching 4 as a substring), fit selection, the safe non-TTY default, and the generated payload shape. Existing help tests still pass. Verified live: renders correctly with a transparent background, and the terminal reply no longer leaks.

…nals

On terminals that advertise sixel support, `sentry help` now renders the Sentry
arch + SENTRY wordmark as a real image — brand gradient, transparent background
(floats on the terminal bg like the block-art) — instead of Unicode block art.
Everything degrades gracefully to the existing block-art banner.

- assets/banner-mask.png: white-on-transparent arch+SENTRY source mask
- script/generate-banner-sixel.ts: bakes the mask into a transparent sixel
  (P2=1) with the brand gradient -> src/generated/banner-sixel.ts. Runs first in
  the generate:docs chain; no runtime image deps (the string is baked in).
- src/lib/sixel.ts: best-effort, cached, unix-only probe — DA1 (attribute 4) +
  cell-size (CSI 16 t) read from a blocking /dev/tty fd, TTY-gated, honoring
  NO_COLOR / SENTRY_PLAIN_OUTPUT / SENTRY_NO_SIXEL / TERM. Fit check ensures the
  fixed-pixel image isn't wider than the terminal.
- src/lib/help.ts: prefer the sixel banner, else block art.
- SENTRY_NO_SIXEL env var (registered) to force the block-art banner.

Tests cover DA1/cell-size parsing, fit selection, the safe non-TTY default, and
the generated payload shape.
@github-actions

github-actions Bot commented Jul 3, 2026 •

Copy link
Copy Markdown
Contributor
PR Preview Action v1.8.1

QR code for preview link

🚀 View preview at
https://cli.sentry.dev/_preview/pr-1187/

Built to branch gh-pages at 2026-07-03 11:11 UTC.
Preview will be ready when the GitHub Pages deployment is complete.

Comment thread src/lib/sixel.ts Resolved
Comment thread src/lib/sixel.ts Resolved
Comment thread src/lib/sixel.ts Resolved
@github-actions

github-actions Bot commented Jul 3, 2026 •

Copy link
Copy Markdown
Contributor

Codecov Results 📊

❌ Patch coverage is 73.33%. Project has 5240 uncovered lines.
✅ Project coverage is 81.74%. Comparing base (base) to head (head).

Files with missing lines (1)
File Patch % Lines
src/lib/sixel.ts 70.37% ⚠️ 16 Missing and 2 partials
Coverage diff
@@            Coverage Diff             @@
##          main       #PR       +/-##
==========================================
+ Coverage    81.71%    81.74%    +0.03%
==========================================
  Files          413       415        +2
  Lines        28657     28698       +41
  Branches     18599     18627       +28
==========================================
+ Hits         23415     23458       +43
- Misses        5242      5240        -2
- Partials      1917      1919        +2

Generated by Codecov Action

…ommit baked file, tests

- readReply: order queries so Primary DA ('c', universally answered) arrives
  LAST after the optional cell-size reply; read until 'c'. Guarantees the full
  reply is drained even if the cell-size report lags, so nothing leaks onto the
  shell prompt (Cursor Bugbot MEDIUM).
- SENTRY_NO_SIXEL now uses the shared isTruthyEnv (exported from plain-detect),
  so '0'/'false' don't disable sixel — consistent with other display toggles
  (Cursor Bugbot LOW).
- Commit the deterministic baked src/generated/banner-sixel.ts via a .gitignore
  exception so the statically-imported module exists on fresh checkouts before
  any build step (Seer MEDIUM).
- Tests: cover optedOut branches, readReply drain (incl. empty), detectSixelCaps
  caching, and the help TTY banner branch. Patch coverage 46% -> ~78% (the
  remaining lines are the terminal-syscall probe, untestable without a PTY).
Comment thread src/lib/sixel.ts Resolved
Comment thread src/lib/sixel.ts Resolved
- optedOut reads TERM/SENTRY_NO_SIXEL via getEnv() (like isPlainOutput), so
  library/test runs using setEnv() see consistent values (Cursor Bugbot MEDIUM).
- readReply now stops only on a complete Primary DA reply (DA1_RE) instead of
  any 'c', so a stray 'c' (e.g. a keypress on /dev/tty during the probe) can't
  end the drain early and leak trailing bytes (Cursor Bugbot MEDIUM). Added
  tests proving it keeps reading past a stray 'c'.
Comment thread src/lib/sixel.ts Resolved
detectSixelCaps caches the probe, so sixelBanner could still emit the image if
opt-out state changed after caps were cached (NO_COLOR, SENTRY_PLAIN_OUTPUT,
SENTRY_NO_SIXEL, or a non-TTY stream). Guard the emit path with optedOut() —
cheap and I/O-free — so those gates are always honored (Cursor Bugbot LOW).
Added a test asserting suppression with a TTY + SENTRY_NO_SIXEL.

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Fix All in Cursor

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

Reviewed by Cursor Bugbot for commit b9fc65d. Configure here.

Comment thread src/lib/help.ts Resolved
Comment thread src/lib/sixel.ts
* didn't report one we can't guarantee the image won't overflow, so we decline.
*/
export function sixelFits(
caps: SixelCaps,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bug: The savedStty variable, containing output from stty -g, is directly interpolated into an execSync command string, creating a theoretical shell injection risk and violating security best practices.
Severity: LOW

Suggested Fix

To prevent potential shell injection, replace the execSync call that uses string interpolation with execFileSync. The command should be execFileSync("stty", [savedStty, "<", "/dev/tty"]), passing the savedStty content as a distinct argument to prevent shell interpretation. This aligns with safer practices used elsewhere in the project.

Prompt for AI Agent
Review the code at the location below. A potential bug has been identified by an AI
agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's
not valid.

Location: src/lib/sixel.ts#L78

Potential issue: The code saves terminal settings using `execSync("stty -g < /dev/tty")`
and stores the output in the `savedStty` variable. This variable is later used to
restore the settings via string interpolation in another `execSync` call:
`execSync(\`stty ${savedStty} < /dev/tty\`)`. While the output of `stty -g` on standard
systems is typically safe and does not contain shell metacharacters, this pattern
creates a theoretical shell injection vulnerability. An exploit would require a
non-standard or compromised `stty` implementation. This violates the established
security practice of using `execFileSync` with an array of arguments for executing
commands with variable data.

… probe

The root help path built the branded banner eagerly in the command func and put
it in _banner (stripped from JSON). On an interactive TTY, 'sentry help --json'
therefore still ran printCustomHelp -> sixelBanner -> the synchronous /dev/tty
probe + stty changes for a banner JSON consumers never receive (Cursor Bugbot
MEDIUM).

The func now yields only the introspection tree; formatHelpHuman renders the
branded banner via printCustomHelp for the full tree. Since the wrapper only
calls the human formatter in human mode, --json never triggers the probe or any
terminal I/O. Removed the now-unused _banner field, jsonExclude, and dead
formatFullTreeHuman fallback.
@BYK
BYK merged commit ff2a3a9 into main Jul 3, 2026
32 checks passed
@BYK
BYK deleted the feat/banner-sixel branch July 3, 2026 11:22
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant