Proposal for `@std/cli/tty` package

[thesmart]

Is your feature request related to a problem? Please describe.

It is difficult to write robust, cross-platform terminal applications on any platforms. There is too much arcana in dealing with various terminals. The portability of compiled Deno apps is amazing.

Lately I have been diving into the deep-end of VT100/VT220/XTerm/ANSI/ECMA-84/kitty. I stopped active development of my own project once I discovered ticket #6755. After briefly reviewing the PRs, I wanted to share a few ideas/suggestions/proposals for a new @std/cli/tty package.

Describe the solution you'd like

A package focused on providing a stable terminal driver w/ compatibility for common Linux, MacOS, and Windows terminals. This solution should make it easy to patch bugs that fix issues across the ecosystem in support of semver.

Describe alternatives you've considered

• Ink smooths over A LOT. That's a huge package for simple terminal apps.
• Python has Textual, much to the same effect.
• ncurses at [terminfo])(https://en.wikipedia.org/wiki/Terminfo) are insane, but it exists for a reason
• I started writing a thin layer for style text, positioning, and handling raw input processing. It quickly turned into a bigger project that I had thought possible.

[thesmart]

Here I'll include a much longer winded version of the concise proposal above. I'm not sure if I'll commit to working on this, but I might. I figured the first step is an analysis, proposal, and discussion.

1. Purpose of @std/cli/tty

Why might a Tty module be useful for? Most users are probably looking for:

1. simple components for accomplishing cli applications quickly (see the unstable- components already in @std/cli)
2. a stable terminal driver w/ compatibility for common Linux, MacOS, and Windows terminals
3. patching of bugs that can propagate across the ecosystem in support of semver

I suppose that Deno doesn't have #⁠2 or #⁠3 solved yet. And it seems that #⁠1 depends on #⁠2 and #⁠3 being solved. Those last two also don't require much opinion, whereas #⁠1 requires forecasting what users' objectives might be and defining presentation constraints. For example, the proposed StaticLine has opinions about composition a static region at the top or bottom. Those terms are arbitrary, especially if the window is ever resized. The implications of regions will ultimately beget complex layout strategies, flow geometries and compositing.

These are very hard problems with a very broad scope.

Check out how complex Textual is. It is amazing, includes an entire compositing system with geometry, themes, etc. It has been under active development for 4+ years, and reached reaching production v1.0.0 less than a year ago. Since then, it has had six major versions due to breaking changes.

Ink leverages React. This is really smart, because component compositing is such a hard problem. JSX and flexbox (Yoga) provide well explored and understood solutions.

But IMO, both of these projects demonstrate a complexity that is wildly out of scope, even for a batteries-included standard library. It would be great to enable projects like them a cross-platform foundation to exist upon.

2. What to include?

I think the project should start with broadly compatible, extensible, and simple terminal drivers with support for popular terminals. I'll take a stab at a requirements list:

Requirement A) Output that is Easy, Safe, FIFO

1. Deno should have a canonical set of escape sequences
2. Deno should try to sniff which terminal it runs in and offer compatibility layers
3. Deno should escaping / unescaping text, support escape nesting
4. Deno should automatically encode textual output
5. Deno should support NO_COLOR
6. Deno should buffer atomic write operations
7. Deno should automatically restore the terminal window when done

// example of an API
import { Tty } from '@std/cli/tty';
Tty
  .cursorTo(1, 50)
  .bold.green.text('Task complete! ')
  .dim.gray.text('Press enter to exit...')
  .cursorHide()
  .write();

Not proposing this to be the actual API (similar to Chalk) but just as an example.

By having an API, the actual ANSI and TextEncoder encoding sent can be abstracted away. An API like this would be automatically safe from exceptions thrown because the writes are atomic and synchronous. It could optionally support theming, e.g. redefining what .green means or how intense .bold is, and what foreground/background to unescape back. An output API makes it easily extensible to add features and support plugins.

Synchronized output might also be important. This might be solvable at the driver level rather than relying on terminal features. For example, writing screens on a run-loop so that writes finish atomically before subsequent writes.

Requirement B) Compatibility w/ Console Tracing

• Deno should support console
• Deno should not trash console
• Deno should support the developer experience

The current implementation uses console.log but I would recommend against this. Many libraries log trace via console.*, so the terminal presentation layer shouldn't also write on top of stdout unless console is redirected.

To solve, I propose:

1. terminal output should default to /dev/tty or the CON console device on Windows
   • apps can redirect stdout to not interfere with tty operation
   • alternatively, apps can redirect console to not interfere with stdout
   • @std/cli could have a developer console facility for tracing
   • Deno currently has a permission issue when opening /dev/tty
2. terminal apps could automatically check if running piped or as a terminal process
   • Node has process.stdout.isTTY , not sure about Deno
   • support an optional fallback strategy or else throw?

Requirement C) Canonical Raw Input Processing

Raw mode input processing is tricky. Different terminals support different escape sequences for keyboard input. It would be super helpful if there were a compatibility layer built-in to Deno, similar to ncurses but wayyyy more simplified.

• Ink actually has a pretty janky keypress parser
• Textual has a super well documented set of keypress sequences and keyboard protocol
  • Defines a parser for XTerm, and I assume could be extended for different terminals. It currently uses the XTerm parser for both Windows and posix.

Deno could have a keypress/keyup KeyboardEvent interface similar to browsers:

Tty.addEventListener("keydown", function(event) { 
	const keyName = event.key;
	console.log(`Key pressed: ${keyName}`); 
	if (event.ctrl && keyName === 'c') {
		Deno.exit(1);
	}
});

It could also support window resizing similar to browser:

Tty.addEventListener('resize', function(event) {
	// can use this to re-draw positioned components
	// this should probably be reasonably debounced
});

Deno could also handle secure paste, such as automatic file encoding and Bracketed-paste support.

Requirement D) Testing

• Deno should automate unit-testing of its tty package against the popular terminals and on different platforms
• Deno should provide testing tools for verifying apps written on @std/cli/tty

3. Conclusions

So to close, it would be awesome to have a compatibility layer to make it trivial to write simple console applications. It would be even more awesome to have a plethora of third-party compositing system exist on top of Deno's @std/cli.

How do we make it easy, fun, and safe to do this?