Skip to content

Switch the TUI stack to charm.land v2 (bubbletea, bubbles, lipgloss, huh) - #7742

Draft
pietern wants to merge 2 commits into
pietern/charm-v2/03c-key-changesfrom
pietern/charm-v2/04-swap
Draft

pietern wants to merge 2 commits into
pietern/charm-v2/03c-key-changesfrom
pietern/charm-v2/04-swap

Conversation

@pietern

@pietern pietern commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Changes

Moves the TUI stack to charm.land/bubbletea/v2, bubbles/v2, lipgloss/v2 and huh/v2, and fixes three things the swap would otherwise regress. The last commit of the stack; the earlier PRs carry the rest of the work.

The swap

  • Models handle key events through teainput; tea.HideCursor is gone (bubbletea hides the cursor while a program runs), so the select modes golden loses one ?25 reset.
  • Colour: each program gets its stream's profile (WithColorProfile, floored at ANSI for template helpers). colorDepth still uses termenv, so TERM unset, CI, CLICOLOR=0, TERM=screen and tmux+truecolor keep v1's depth.
  • tableview.RunWithOptions sends its window size with tea.WithWindowSize, so the first frame is drawn at that size (v2 renders before a sent message lands).
  • Dark background: the appkit theme is a huh.ThemeFunc, and huh resolves the background itself.
  • cmd/selftest/tui ports to v2 (keys prints the raw v2 key next to the decoded event; profile and huh read the background through lipgloss.HasDarkBackground).

Fix 1: leftover terminal replies

bubbletea v2 sends queries at startup (DECRQM 2026 and 2027, kitty keyboard flags). A program that quits before the terminal answers left those answers for the shell prompt. cmdio.NewTeaProgram now defers the quit, on a terminal only, until the terminal answers a cursor position request sent at quit time. Terminals answer in order, so the earlier answers have been read by then. The wait is bounded at 2 s, and only applies if the terminal never answers that request.

Fix 2: Shift+Enter

v2 enables the kitty keyboard protocol, so terminals that report Shift+Enter separately (Ghostty, kitty, WezTerm) send it as its own key. teainput.KeyName maps shift+enter to enter, so prompts and selection lists submit on it.

Fix 3: huh forms

Forms go through cmdio.RunHuhField and cmdio.RunHuhForm (19 call sites in libs/apps/prompt, cmd/apps, cmd/aitools, and the selftest probe). They run with the context's input, stderr and the stderr colour profile. huh's WithProgramOptions replaces its defaults, so input and output are passed explicitly. Not covered: the reply guard. It has to inject a message if the terminal never answers, and a huh program does not expose Send, so a missed answer would hang the quit. A huh form can still leave a late reply on the shell prompt after a quick quit; that is open.

Why

v2 changes the key, cursor, colour and program APIs; the swap has to keep v1's visible behaviour except where a change is deliberate and pinned. The three fixes address regressions that the swap would otherwise ship.

Tests

  • go build ./..., golangci-lint (0 issues), gofmt clean.
  • TERM=xterm-256color go test -race -count=3 ./libs/cmdio/... passes.
  • Unit tests for libs/tableview, libs/apps/..., cmd/air, cmd/apps, cmd/fs, cmd/aitools, cmd/selftest/..., internal/build pass.
  • The full acceptance suite (go test ./acceptance/...) passes.
  • GOOS=windows go vet ./libs/cmdio/... and GOOS=darwin go vet ./libs/cmdio/... pass.
  • PTY smoke test of each selftest command built from this branch (keys, profile, colors --lipgloss, pager, table, huh, prompt, select, spinner): all exit 0 with the expected output.

Golden changes (pins), against the previous branch

Fourteen pin groups change, all intended:

  • TestModesPin_{Prompt,Select,Pager}/{enter,ctrl-c}, TestModesPin_Spinner: v2 sets modifyOtherKeys 2 and kitty push 1 and undoes both on exit; the mouse-mode resets are gone (v2 never sets those modes); select no longer toggles ?25 twice.
  • TestKeysPin_{Prompt,Select}ShiftEnter/{kitty,modifyOtherKeys}: Shift+Enter submits (Value: xy, z left unread; the select clears its screen).
  • TestKeysPin_PromptBracketedPasteWithNewline: the screen keeps ✔ Value: a above b█.
  • TestQueriesPin_PromptQuitBeforeReplies and TestQueriesPin_SelectQuitBeforeReplies: pipes never install the guard, so these pins now record v2's queries and the unguarded leftover.
  • TestQueriesPin_PromptTerminalAnswersAtOnce: v2's three startup queries are in the golden.
  • TestQueriesPin_PromptUnsolicitedBackgroundReply: the late OSC 11 reply is consumed; the value is ab, not ab11;rgb:….
  • New: TestQueriesPin_PromptQuitBeforeRepliesTTY (stdin poses as a terminal through the new termtest StdinTTY option). The guard holds the quit for the cursor report; leftover is (none).

Unchanged and passing: the pager's first-page spinner pins (TestPagerPin_SpinnerDuringFirstPage and TestPagerPin_EnterWhileFirstPageLoads still show several frames without the tick patch), the colour pins, and the Alt pins from #03c.

Test-only changes

  • libs/cmdio/teaprogram_test.go: TestNewTeaProgramGuardsTerminalInput runs NewTeaProgram with a faked terminal. It finishes in about 100 ms.
  • Test helpers now strip escape sequences before counting pager rows or comparing row text (v2 writes its queries into the stream).

Known issues

  • Spinner and LogString interleave on v2. LogString writes to the terminal while a spinner's renderer is drawing, so the first frame can land before the log line (*spinner started, or * Workingspinner started). Under eight parallel -race copies of TestColorPin_Spinner with -count=25, v2 failed 13 times across 6 of 8 copies; v1 failed zero times. Fixing it means routing LogString through the active program, which has a message-loss window at teardown. Not in this PR.
  • The huh reply guard (above).

Manual checks on real terminals

Run each with the v1 build (main, or #7688 for the selftest tui commands) and with this build.

  • Shift+Enter (Ghostty, kitty, WezTerm): databricks selftest tui prompt, type xy, Shift+Enter, z, Enter. v2: Entered: xy (Shift+Enter submits). Record what v1 prints: without the kitty keyboard protocol these terminals usually send a plain Enter.
  • Quick quit leftovers (SSH with about 150 ms RTT, or nested tmux): databricks selftest tui prompt, type ab and Enter at once, then look at the shell prompt. Both: nothing left over, such as ^[[?2026;2$y. v1 sends no such queries; v2 waits for the answers before it exits.
  • Terminal signal: databricks selftest tui prompt &, kill -TERM %1, then stty -a in the shell. Open issue: v2 leaves kitty keyboard and modifyOtherKeys on until reset, as v1 leaves raw mode.
  • Colour: databricks selftest tui profile and databricks selftest tui colors --lipgloss, with TERM unset, CI=1, CLICOLOR=0, TERM=screen, and tmux with COLORTERM=truecolor. The depth must match v1's.
  • Startup: databricks selftest tui prompt under a terminal that does not answer OSC 11 (for example script): the prompt should appear at once, and typed keys are kept.
  • Pager: databricks selftest tui pager --items 30 --delay-first 4s: the spinner animates during the first fetch, then the first page and the prompt.
  • Table: databricks selftest tui table --rows 50, /, type text, Alt+F, paste, Enter, q: no alt+f or pasted [text] in the search.
  • huh: databricks selftest tui huh --field confirm, on a dark and a light background: dark_background and the blurred-button colour match the background.

This pull request and its description were written by Isaac.

@pietern
pietern force-pushed the pietern/charm-v2/04-swap branch from e70fa46 to 93defd8 Compare November 17, 2026 22:30
@eng-dev-ecosystem-bot

eng-dev-ecosystem-bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

✅ Integration test report

Commit: 60a6b63

Run: 44310902884

Env 💚​RECOVERED ✅​pass 🙈​skip Time
💚​ aws linux-2core-8gb 1 272 19 19:27
💚​ aws-windows-latest-4core-16gb 1 274 17 19:26
💚​ azure linux-2core-8gb 1 271 19 20:03
💚​ azure-windows-latest-4core-16gb 1 273 17 12:41
💚​ gcp linux-2core-8gb 1 272 19 15:38
💚​ gcp-windows-latest-4core-16gb 1 274 17 13:23
Test Name aws linux-2core-8gb aws-windows-latest-4core-16gb azure linux-2core-8gb azure-windows-latest-4core-16gb gcp linux-2core-8gb gcp-windows-latest-4core-16gb
💚​ TestAccept 💚​R 💚​R 💚​R 💚​R 💚​R 💚​R
Top 45 slowest tests (at least 2 minutes):
duration env testname
8:24 aws-windows-latest-4core-16gb TestFilerWorkspaceFilesExtensionsReadDir
7:44 azure-windows-latest-4core-16gb TestAccept
7:34 gcp-windows-latest-4core-16gb TestAccept
7:15 aws-windows-latest-4core-16gb TestAccept
6:05 aws linux-2core-8gb TestFilerWorkspaceFilesExtensionsReadDir
5:17 gcp-windows-latest-4core-16gb TestFilerWorkspaceFilesExtensionsReadDir
5:05 azure linux-2core-8gb TestFilerWorkspaceFilesExtensionsReadDir
4:57 aws linux-2core-8gb TestFilerRecursiveDelete/workspace_files
4:33 aws-windows-latest-4core-16gb TestFilerWorkspaceFilesExtensionsDelete
4:06 aws-windows-latest-4core-16gb TestFilerReadWrite/workspace_files
4:04 azure linux-2core-8gb TestAccept
4:00 gcp-windows-latest-4core-16gb TestImportDir
3:59 aws linux-2core-8gb TestAccept
3:56 gcp linux-2core-8gb TestAccept
3:53 aws-windows-latest-4core-16gb TestFilerWorkspaceFilesExtensionsRead
3:21 azure linux-2core-8gb TestFilerRecursiveDelete/workspace_files_extensions
3:01 gcp-windows-latest-4core-16gb TestImportDirDoesNotOverwrite
3:00 aws linux-2core-8gb TestFilerReadDir/workspace_files
2:57 azure-windows-latest-4core-16gb TestFilerRecursiveDelete/workspace_files
2:51 gcp linux-2core-8gb TestFilerWorkspaceFilesExtensionsReadDir
2:48 azure-windows-latest-4core-16gb TestFilerWorkspaceFilesExtensionsReadDir
2:46 azure linux-2core-8gb TestImportDirDoesNotOverwrite
2:46 azure-windows-latest-4core-16gb TestFilerRecursiveDelete/workspace_files_extensions
2:41 gcp linux-2core-8gb TestFilerWorkspaceNotebook/sqlNb.sql
2:41 gcp linux-2core-8gb TestFilerReadWrite/workspace_files_extensions
2:35 azure linux-2core-8gb TestWorkspaceFilesExtensionsNotebooksAreNotReadAsFiles
2:33 aws-windows-latest-4core-16gb TestFilerReadDir/workspace_files
2:32 aws-windows-latest-4core-16gb TestFilerWorkspaceFilesExtensionsStat
2:31 aws linux-2core-8gb TestSyncFullFileSync
2:28 gcp-windows-latest-4core-16gb TestFilerWorkspaceFilesExtensionsStat
2:27 aws linux-2core-8gb TestWorkspaceFilesExtensions_ExportFormatIsPreserved/jupyter_sql
2:27 gcp linux-2core-8gb TestLock
2:27 aws linux-2core-8gb TestFilerWorkspaceFilesExtensionsDelete
2:26 azure linux-2core-8gb TestFilerRecursiveDelete/workspace_files
2:24 gcp-windows-latest-4core-16gb TestImportDirWithOverwriteFlag
2:22 gcp-windows-latest-4core-16gb TestFilerWorkspaceFilesExtensionsDelete
2:19 aws-windows-latest-4core-16gb TestFilerRecursiveDelete/workspace_files
2:18 azure-windows-latest-4core-16gb TestFilerWorkspaceFilesExtensionsRead
2:10 aws linux-2core-8gb TestImportDirDoesNotOverwrite
2:10 azure linux-2core-8gb TestFilerWorkspaceFilesExtensionsStat
2:09 aws linux-2core-8gb TestImportDirWithOverwriteFlag
2:08 azure-windows-latest-4core-16gb TestExportDir
2:08 aws-windows-latest-4core-16gb TestExportDir
2:02 aws-windows-latest-4core-16gb TestTelemetryEndpoint
2:01 gcp-windows-latest-4core-16gb TestFilerWorkspaceFilesExtensionsRead

@pietern
pietern added this pull request to stack #7754 November 18, 2026 08:35
@pietern

pietern commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

/review

Comment thread libs/cmdio/teaprogram.go
g.waiting = true
g.quit = msg
go g.send(tea.RequestCursorPosition())
time.AfterFunc(g.wait, func() { g.send(replyGuardTimeout{}) })

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

The time.AfterFunc timer is not stopped when the cursor report arrives and releases the guard at line 81. After the program exits, the timer fires and calls p.Send(replyGuardTimeout{}) on a completed program. Saving the *time.Timer on the struct and calling Stop() in the release branch would avoid the stale callback. Can we add a timer field and stop it at line 81?

@pietern
pietern force-pushed the pietern/charm-v2/04-swap branch from 93defd8 to 60a6b63 Compare November 18, 2026 13:07
@github-actions github-actions Bot added Dependencies Pull requests that update a dependency file AIR Databricks AI Runtime CLI aitools AI tools (databricks aitools) related changes labels Nov 18, 2026
@pietern
pietern force-pushed the pietern/charm-v2/04-swap branch from 60a6b63 to 4b39c09 Compare November 18, 2026 15:55
pietern and others added 2 commits November 18, 2026 16:06
…huh)

Moves the CLI's TUI code to charm.land/bubbletea/v2, bubbles/v2,
lipgloss/v2 and huh/v2, with the behaviour that v1 gave callers kept or
deliberately changed and pinned.

Swap
- Models handle key events through teainput; tea.HideCursor is gone
  (Bubble Tea hides the cursor while a program runs), so the select
  modes golden loses one "?25 reset".
- Color: the program's profile comes from the stream's cmdio.Renderer
  (WithColorProfile), floored at ANSI for template helpers, so
  TERM unset, CI and CLICOLOR=0 keep v1's depth.
- tableview.RunWithOptions sends its window size with tea.WithWindowSize,
  so the first frame is drawn at that size.
- cmd/selftest/tui ports to v2: keys prints the message and the decoded
  event side by side; profile and huh read the background through
  lipgloss.HasDarkBackground.

Quit guard
- cmdio.NewTeaProgram defers quitting, on a terminal, until the terminal
  answers the cursor position request sent at quit time. Terminals answer
  in order, so the answers to the startup queries are read before the
  program exits, and nothing is left at the shell prompt. The wait is
  bounded at 2 s.

Shift+Enter
- teainput.KeyName reports shift+enter as enter, for terminals that
  enable the kitty keyboard protocol.

huh
- Forms go through cmdio.RunHuhField or RunHuhForm, which run with the
  context's input, stderr, and the stderr color profile. huh's
  WithProgramOptions replaces its defaults, so the input and output are
  passed explicitly. The reply guard is not installed for huh: it needs
  to inject a message when the terminal does not answer, and a huh
  program does not expose Send.

Golden changes are listed in the stack PR body, one per behaviour.
Pins that need a terminal have a TTY variant (TestQueriesPin_PromptQuitBeforeRepliesTTY,
termtest StdinTTY), and TestNewTeaProgramGuardsTerminalInput covers the
constructor with a faked terminal.

Co-authored-by: Isaac <no-reply@databricks.com>
Co-authored-by: Isaac <no-reply@databricks.com>
@pietern
pietern force-pushed the pietern/charm-v2/04-swap branch from 4b39c09 to 2c519b9 Compare November 18, 2026 16:08

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

AIR Databricks AI Runtime CLI aitools AI tools (databricks aitools) related changes Dependencies Pull requests that update a dependency file

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants