fix(core): add actionable warnings for terminal fallbacks (#14426)

[spencer426]

Summary

This PR introduces actionable terminal compatibility warnings for problematic environments such as tmux, GNU screen, JetBrains IDE terminals, and "dumb" terminal setups. Instead of forcefully restricting functionality (like disabling alternate screen buffers), it preserves power-user configurations while alerting the user to potential issues and providing specific configuration fixes.

Details

• Added comprehensive terminal heuristics (isTmux, isGnuScreen, isDumbTerminal, isJetBrainsTerminal, and isLowColorTmux) to packages/core/src/utils/compatibility.ts.
• Updated getCompatibilityWarnings to natively surface warnings based on these precise terminal detections.
• Removed unused legacy terminal functions (e.g., getTerminalNameFromEnv) and their associated tests.
• Captured JETBRAINS_IDE in isJetBrainsTerminal detection.
• Expanded unit test coverage in compatibility.test.ts, ensuring robust tests that isolate environment variables to prevent leakage across the test suite.

Related Issues

Fixes #14426

How to Validate

1. Run the CLI in a tmux session with TERM=screen.
2. Observe the startup warning recommending set -g default-terminal "tmux-256color".
3. Run the CLI with TERM=dumb.
4. Observe the basic terminal startup warning.
5. Run the CLI inside a JetBrains IDE (IntelliJ / WebStorm).
6. Verify the warnings are displayed correctly and no core functionality is abruptly blocked.
7. Verify all tests pass by running npm run preflight.

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any)
• Validated on required platforms/methods:
  • MacOS
    • npm run
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows
    • npm run
    • npx
    • Docker
  • Linux
    • npm run
    • npx
    • Docker

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly improves the CLI's terminal compatibility by shifting from forceful feature restrictions to providing informative and actionable warnings. It introduces robust detection for various terminal environments like tmux, GNU screen, and basic terminals, offering users clear guidance and configuration tips to optimize their experience. This change ensures better usability and preserves power-user configurations across diverse terminal setups.

Highlights

• Actionable Terminal Warnings: Introduced specific, actionable warnings for tmux, GNU screen, and dumb terminal environments, guiding users to improve their setup rather than restricting functionality.
• Enhanced Terminal Detection: Added new utility functions (isTmux, isGnuScreen, isLowColorTmux, isDumbTerminal, getTerminalNameFromEnv) to accurately identify various terminal types and their configurations.
• Improved JetBrains Integration: Updated isJetBrainsTerminal to also recognize the JETBRAINS_IDE environment variable, enhancing detection within JetBrains products.

Changelog

• packages/core/src/utils/compatibility.test.ts
  • Imported new compatibility utility functions.
  • Expanded test cases for isJetBrainsTerminal to include JETBRAINS_IDE detection.
  • Added comprehensive test suites for isTmux, isGnuScreen, isLowColorTmux, isDumbTerminal, and getTerminalNameFromEnv.
  • Introduced new tests for getCompatibilityWarnings to validate the new terminal-specific warnings.
• packages/core/src/utils/compatibility.ts
  • Added isTmux function to detect tmux sessions.
  • Added isGnuScreen function to detect GNU screen sessions.
  • Added isLowColorTmux function to identify low-color tmux environments.
  • Added isDumbTerminal function to detect basic terminal types.
  • Added getTerminalNameFromEnv function to determine the terminal name from environment variables.
  • Updated isJetBrainsTerminal to check for JETBRAINS_IDE environment variable.
  • Modified getCompatibilityWarnings to issue new warnings for tmux, low-color tmux, GNU screen, and dumb terminals, and refined the JetBrains warning message.

Activity

• spencer426 opened the pull request to add actionable warnings for terminal fallbacks.
• spencer426 added new terminal detection heuristics and updated getCompatibilityWarnings.
• spencer426 expanded unit test coverage for terminal compatibility.
• spencer426 validated the changes on MacOS.
• spencer426 confirmed that tests were added/updated.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces valuable, actionable warnings for various terminal environments, which will significantly improve the user experience for those on non-standard terminals. The new compatibility checks for tmux, GNU screen, and dumb terminals are well-implemented.

I've identified a minor bug in the warning message for "dumb" terminals where the TERM value is hardcoded, leading to incorrect output. I've also suggested an improvement to the corresponding test to make it more robust and prevent similar issues in the future. Once these points are addressed, this will be a great addition.

[github-actions]

Size Change: +1.88 kB (+0.01%)

Total Size: 26.2 MB

Filename	Size	Change
./bundle/chunk-WRB2UCR6.js	0 B	-13.5 MB (removed)	🏆
./bundle/chunk-YAPQBGOM.js	0 B	-3.63 MB (removed)	🏆
./bundle/core-TBM5EK6C.js	0 B	-41.1 kB (removed)	🏆
./bundle/devtoolsService-EAYU3FFL.js	0 B	-27.7 kB (removed)	🏆
./bundle/interactiveCli-LG2V6ACJ.js	0 B	-1.6 MB (removed)	🏆
./bundle/oauth2-provider-2GAZHFSQ.js	0 B	-9.19 kB (removed)	🏆
./bundle/chunk-A6J36GXW.js	3.63 MB	+3.63 MB (new file)	🆕
./bundle/chunk-WPFA4VRG.js	13.5 MB	+13.5 MB (new file)	🆕
./bundle/core-XUZGWY4E.js	41.3 kB	+41.3 kB (new file)	🆕
./bundle/devtoolsService-ROHCSZTU.js	27.7 kB	+27.7 kB (new file)	🆕
./bundle/interactiveCli-TWD3Y4SL.js	1.6 MB	+1.6 MB (new file)	🆕
./bundle/oauth2-provider-2X7TVC3O.js	9.19 kB	+9.19 kB (new file)	🆕

ℹ️ View Unchanged

Filename	Size
./bundle/chunk-34MYV7JD.js	2.45 kB
./bundle/chunk-37ZTTFQF.js	966 kB
./bundle/chunk-5AUYMPVF.js	858 B
./bundle/chunk-664ZODQF.js	124 kB
./bundle/chunk-DAHVX5MI.js	206 kB
./bundle/chunk-IUUIT4SU.js	56.5 kB
./bundle/chunk-OIY7FXRG.js	1.95 MB
./bundle/chunk-RJTRUG2J.js	39.8 kB
./bundle/devtools-36NN55EP.js	696 kB
./bundle/dist-T73EYRDX.js	356 B
./bundle/gemini.js	695 kB
./bundle/getMachineId-bsd-TXG52NKR.js	1.55 kB
./bundle/getMachineId-darwin-7OE4DDZ6.js	1.55 kB
./bundle/getMachineId-linux-SHIFKOOX.js	1.34 kB
./bundle/getMachineId-unsupported-5U5DOEYY.js	1.06 kB
./bundle/getMachineId-win-6KLLGOI4.js	1.72 kB
./bundle/memoryDiscovery-7QMQUGPE.js	922 B
./bundle/multipart-parser-KPBZEGQU.js	11.7 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/client/main.js	221 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/_client-assets.js	227 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/index.js	11.5 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/types.js	132 B
./bundle/sandbox-macos-permissive-open.sb	890 B
./bundle/sandbox-macos-permissive-proxied.sb	1.31 kB
./bundle/sandbox-macos-restrictive-open.sb	3.36 kB
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB
./bundle/sandbox-macos-strict-open.sb	4.82 kB
./bundle/sandbox-macos-strict-proxied.sb	5.02 kB
./bundle/src-QVCVGIUX.js	47 kB
./bundle/tree-sitter-7U6MW5PS.js	274 kB
./bundle/tree-sitter-bash-34ZGLXVX.js	1.84 MB
./bundle/undici-4X2YZID5.js	360 B

_{compressed-size-action}