feat: shpool tui

[GeoffChurch]

Issue Link

#341 (a "discussion")

AI Policy Ack

ack

Claude Opus 4.7 generated the initial implementation, and then I painstakingly reviewed/edited it line-by-line.

Description

Adds a TUI to shpool, invoked via shpool tui. The TUI shows the list of shpool sessions, their attached status, and their relative created and active times. You can create, attach to, and kill sessions.

The primary use case is a workflow where you spin up the TUI, attach to a session, and then automatically return to the TUI upon detaching. This allows easy switching between sessions.

The TUI looks like:

 shpool sessions (2)                                                  
  name   created  active                                              
* main   2m       2m                                                  
 >build  3h       3h                                                  
                                                                      
 [j] down  [k] up  [spc] attach  [n] new  [d] kill  [q] quit

where * denotes an attached session and > denotes the current selection (which is also rendered with reverse highlighting in the TUI).

I used ratatui, backed by crossterm for the UI. The architecture is Elm-based (model.rs, view.rs, update.rs).

One caveat is that it only refreshes the list upon keypress and when the terminal gains focus, so the view can remain stale indefinitely until interacted with. If the daemon could be subscribed to for events this could be avoided.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[ethanpailes]

I know I said I thought this would be a reasonable feature in the discussion we had, but now actually looking at the code I'm realizing just how far outside shpool's core functionality this feels. If we bake this into shpool, we'll have to own and support it forever, and since it already can be implemented as a wrapper, that gets harder to justify. Also, merging this would bless a single tui implementation when it seems like there is lots of room in the design space.

Also, the fact that this requires two new dependencies that are not core to shpool's purpose worries me. Dependencies are quite annoying to deal with, and as much as possible I would like to avoid adding new ones.

I feel pretty bad because I said I was open to the feature and now I'm reversing course. Maybe instead putting a TUI implementation in-tree there are things we could do that would make implementing TUI wrappers easier? Also, we can update the README and wiki to link to various tui options.

[GeoffChurch]

That makes sense. It's elegant to keep it separate since shelling out already suffices.

The dependencies can technically be avoided (shpool-table just uses raw ANSI sequences), but the separation argument still stands.

One improvement that would improve UI wrappers is having the daemon publish events, so that UIs can refresh as-needed without hacky workarounds like timers or waiting for focus/keypresses.

[ethanpailes]

One improvement that would improve UI wrappers is having the daemon publish events, so that UIs can refresh as-needed without hacky workarounds like timers or waiting for focus/keypresses.

That seems like a much more focused feature that definitely belongs in core shpool. Shpool actually already has a push-event system that is only compiled in for testing purposes. We probably don't want to just expose that because it is rather hacky (events are just a single identifier written on a line), but we could do something along those lines.

We would probably want to avoid relying on shpool-protocol since then it would be hard for non-rust clients to make use of the protocol. Maybe we could do something JSON-rpc-like (though obviously not rpcs since we want to push events from shpool to the client). We'll probably want a seperate unix socket that hangs out next to the main socket because otherwise we would have to fit the new push mechanism into shpool-protocol.