feat(cli): Introduce StaticLine

[BlackAsLight]

Read (#6755) for an overview.

#6756 should be merged before this.

This class uses the scrollable region Ansi code to allow scrolling content to not overwrite lines at the top and bottom of the terminal. It is meant to provide a foundation for anyone looking to easily have a line at the bottom or top of the terminal.

import { delay } from "@std/async/delay";
import { StaticLine } from "@std/cli/unstable-static-line";

const id = setInterval(() => console.log(Math.random()), 1000);

const line = new StaticLine();
await line.write("Hello World!");
await delay(1500);
await line.write("How are you?");
await delay(1500);
await line.write("Doing good?");
await delay(1500);
await line.releaseLine();

No tests as of yet have been written for this class as I am not sure how to write unit tests to test its behaviour.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 94.16%. Comparing base (4db142b) to head (1caadfb).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #6758   +/-   ##
=======================================
  Coverage   94.15%   94.16%           
=======================================
  Files         587      587           
  Lines       42514    42514           
  Branches     6712     6712           
=======================================
+ Hits        40030    40034    +4     
+ Misses       2433     2431    -2     
+ Partials       51       49    -2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[BlackAsLight]

Example

import { delay } from "@std/async/delay";
const id = setInterval(() => console.log(Math.random()), 1000);

for (let i = 0; i < 20; ++i) {
  const line = new StaticLine();
  await line.write(`Line (${i}): Placeholder!`);
  const id = setInterval(
    () => line.write(`Line (${i}): ${Math.random()}`),
    Math.random() * 3000 + 1000,
  );
  setTimeout(() => {
    clearInterval(id);
    line.releaseLine();
  }, Math.random() * 5_000 + 25_000);
  await delay(Math.random() * 1000 + 1000);
}

await delay(30_000);
clearInterval(id);

Screen.Recording.2025-07-11.at.21.14.31.mp4

[kt3k]

Can you provide some real-world example (cli/library/whatever) in which this type of output is used?

Also does this type of abstraction have prior example?

[BlackAsLight]

Can you provide some real-world example (cli/library/whatever) in which this type of output is used?

Also does this type of abstraction have prior example?

I don't know of any real world examples, but as I learn more and more about ANSI escape sequences it is becoming apparent just how unreliable terminals can be.

This type, or some type, of abstraction is needed to "reliably" support multiple spinners and progress bars at once. As request here: #5037. The word reliably is doing a lot of heavy lifting here as any other area that starts inserting sequences can screw this all up.

If we want something truely robust, we'll need to offer some type of complete abstraction away from ansi codes. A framework so to say that isn't merely offering small functions here and there, but that specifies the entire state and keeps track of it all.

Very little of the terminals state can actually be asked or looked up from the terminal itself. Much of these settings and modes must be remembered in code to know if it's enabled or disabled. With the sync functions this isn't really a problem as you can't have random console logs from other areas screwing everything up by sending their own sequences, but with the spinner and progress bar and any other functionality that allows other code to run, allows for the state to be screwed up.