Stop assuming CLI stdout is a TTY write stream (#51)

## Motivation for the change, related issues

In WordPress/wordpress-playground, we still assume that the Playground
CLI is running in a TTY context, and the CLI breaks when not in a TTY
context [because `process.stdout.clearLine()` and
`process.stdout.clearLine()` are
missing](#2127).

Here are some lines that fail without a TTY context:

https://github.com/WordPress/wordpress-playground/blob/f5b85399ff8dbabaf122bfa98347ce76d7f59910/packages/playground/cli/src/cli.ts#L232-L233

We have since worked around the bug in the private Playground fork by
using the same functions from the `readline` module, but this is also
incorrect and can lead to some strange behavior. For example, sometimes
two status messages are printed on the same line.

If this fix lands in our private fork, perhaps we could port it to the
public Playground repo so folks are not blocked from using Playground
CLI.

## Implementation details

This PR does a number of things:
- Updates the progress messages to be written in-place over one another
when in TTY contexts
- Updates the progress messages to be written on separate lines when in
non-TTY contexts
- Makes sure that identical progress messages are not repeated across
multiple lines in non-TTY mode
- Ensures that messages following in-place progress updates are written
on the next line (sometimes two messages were appearing on the same line
like "Downloading WordPress 100%... Booted!")
- Makes sure the progress percentage is an integer and doesn't report
100% until truly at 100%.
- Explicitly declares that the nx `run-commands` executor for
`playground-cli:dev` should run in TTY mode.
- It doesn't seem to affect our current version of nx, but when testing
with [my PR to upgrade nx and
vite](Automattic/wordpress-playground-private#35),
`npx nx dev playground-cli` did seem to run in a TTY context.
- Either way [the nx tty
option](https://nx.dev/nx-api/nx/executors/run-commands#tty), doesn't
seem to adversely affect anything, so I'm leaving it explicitly declared
that way for later.


## Testing Instructions (or ideally a Blueprint)

- `cd` into your Playground working dir
- Create a blueprint named `blooprint.json` in that directory
- Test in TTY mode
- Pick a WP version Playground hasn't downloaded or simply run `rm -r
~/.wordpress-playground` to clear the Playground CLI cache.
- Run `npx bun --watch ./packages/playground/cli/src/cli.ts server
--blueprint=blooprint.json`
- Observe that the Download and Blueprint progress messages are updated
on a single line each as they progress to 100%
  - Observe that each message appears on its own line
- Test in non-TTY mode
- Pick a WP version Playground hasn't downloaded or simply run `rm -r
~/.wordpress-playground` to clear the Playground CLI cache.
- Run `npx bun --watch ./packages/playground/cli/src/cli.ts server
--blueprint=blooprint.json | more`
    - Piping output to `more` causes the CLI's stdout to not be a TTY
- Hit the spacebar to proceed through the output (this may be obvious,
but sometimes it took me a second or two to remember :)
- Observe that each Download and Blueprint progress message is printed
on a new line as they progress to 100%.
  - Observe that no progress messages are repeated.

Author: brandonpayton

packages/playground/cli/project.json

@@ -32,7 +32,8 @@
 		"dev": {
 			"executor": "nx:run-commands",
 			"options": {
-				"command": "bun --watch ./packages/playground/cli/src/cli.ts"
+				"command": "bun --watch ./packages/playground/cli/src/cli.ts",
+				"tty": true
 			}
 		},
 		"start": {

packages/playground/cli/src/run-cli.ts

@@ -21,7 +21,6 @@ import {
 import fs from 'fs';
 import { Server } from 'http';
 import path from 'path';
-import readline from 'readline';
 import { rootCertificates } from 'tls';
 import {
 	CACHE_FOLDER,
@@ -127,29 +126,58 @@ export async function runCLI(args: RunCLIArgs): Promise<RunCLIServer> {
 
 		const tracker = new ProgressTracker();
 		let lastCaption = '';
-		let progress100 = false;
+		let progressReached100 = false;
 		tracker.addEventListener('progress', (e: any) => {
-			if (progress100) {
+			if (progressReached100) {
 				return;
-			} else if (e.detail.progress === 100) {
-				progress100 = true;
 			}
+			progressReached100 = e.detail.progress === 100;
+
+			// Use floor() so we don't report 100% until truly there.
+			const progressInteger = Math.floor(e.detail.progress);
 			lastCaption =
 				e.detail.caption || lastCaption || 'Running the Blueprint';
-			readline.clearLine(process.stdout, 0);
-			readline.cursorTo(process.stdout, 0);
-			process.stdout.write(
-				'\r\x1b[K' + `${lastCaption.trim()} – ${e.detail.progress}%`
-			);
-			if (progress100) {
-				process.stdout.write('\n');
+			const message = `${lastCaption.trim()} – ${progressInteger}%`;
+			if (!args.quiet) {
+				writeProgressUpdate(
+					process.stdout,
+					message,
+					progressReached100
+				);
 			}
 		});
 		return compileBlueprint(blueprint as Blueprint, {
 			progress: tracker,
 		});
 	}
 
+	let lastProgressMessage = '';
+	function writeProgressUpdate(
+		writeStream: NodeJS.WriteStream,
+		message: string,
+		finalUpdate: boolean
+	) {
+		if (message === lastProgressMessage) {
+			// Avoid repeating the same message
+			return;
+		}
+		lastProgressMessage = message;
+
+		if (writeStream.isTTY) {
+			// Overwrite previous progress updates in-place for a quieter UX.
+			writeStream.cursorTo(0);
+			writeStream.write(message);
+			writeStream.clearLine(1);
+
+			if (finalUpdate) {
+				writeStream.write('\n');
+			}
+		} else {
+			// Fall back to writing one line per progress update
+			writeStream.write(`${message}\n`);
+		}
+	}
+
 	if (args.quiet) {
 		// @ts-ignore
 		logger.handlers = [];
@@ -169,23 +197,32 @@ export async function runCLI(args: RunCLIArgs): Promise<RunCLIServer> {
 
 			logger.log(`Setting up WordPress ${args.wp}`);
 			let wpDetails: any = undefined;
+			// @TODO: Rename to FetchProgressMonitor. There's nothing Emscripten
+			// about that class anymore.
 			const monitor = new EmscriptenDownloadMonitor();
 			if (!args.skipWordPressSetup) {
-				// @TODO: Rename to FetchProgressMonitor. There's nothing Emscripten
-				// about that class anymore.
+				let progressReached100 = false;
 				monitor.addEventListener('progress', ((
 					e: CustomEvent<ProgressEvent & { finished: boolean }>
 				) => {
-					// @TODO Every progres bar will want percentages. The
+					if (progressReached100) {
+						return;
+					}
+
+					// @TODO Every progress bar will want percentages. The
 					//       download monitor should just provide that.
-					const percentProgress = Math.round(
-						Math.min(100, (100 * e.detail.loaded) / e.detail.total)
+					const { loaded, total } = e.detail;
+					// Use floor() so we don't report 100% until truly there.
+					const percentProgress = Math.floor(
+						Math.min(100, (100 * loaded) / total)
 					);
+					progressReached100 = percentProgress === 100;
+
 					if (!args.quiet) {
-						readline.clearLine(process.stdout, 0);
-						readline.cursorTo(process.stdout, 0);
-						process.stdout.write(
-							`Downloading WordPress ${percentProgress}%...`
+						writeProgressUpdate(
+							process.stdout,
+							`Downloading WordPress ${percentProgress}%...`,
+							progressReached100
 						);
 					}
 				}) as any);