Commit 333b8a7a5c68ab8ab1917a6192022b0f96c46823 | sitegen

author	clover caruso <git@paperclover.net> 2026-06-12 18:21:02-07:00
committer	clover caruso <git@paperclover.net> 2026-06-15 12:49:48-07:00
log	333b8a7a5c68ab8ab1917a6192022b0f96c46823
tree	1afbc15d9c3a4264106e327aa0b1951d905b3f11
parent	6f72c75c17126db8f199d81e8e58650a45ed131e
signature	Signed by SSH key SHA256:cOKiuRFOeSRxne6EWgHtdQQSlBxjOXm2hOCFnCdLQbQ

feat(lib/log): writeError will actually write to stderr

closes #93

3 files changed, 176 insertions(+), 48 deletions(-)

lib/log.test.ts+77

...	@@ -758,6 +758,83 @@ describe("log widgets", () => {	...	@@ -758,6 +758,83 @@ describe("log widgets", () => {
758	host.cancel();	758	host.cancel();
759	});	759	});
760		760
		761	test("writeError routes to the interactive stream in order", () => {
		762	const host = new testing.MockScreen();
		763	host.writeOutput("out 1\n");
		764	host.writeError("err 1\n");
		765	host.writeOutput("out 2\n");
		766	host.expectFrame(0, {
		767	stdout: "out 1\nout 2\n",
		768	stderr: "err 1\n",
		769	merged: "out 1\nerr 1\nout 2\n",
		770	});
		771	host.cancel();
		772	});
		773
		774	test("error text moves widgets like output", () => {
		775	const host = new testing.MockScreen();
		776	using _ = host.startWidget({ format: () => "w" });
		777	host.expectFrame(0, { stderr: testing.MockScreen.sync(["w\n"]) });
		778	host.writeError("oops\n");
		779	host.expectFrame(0, {
		780	stdout: "",
		781	stderr: testing.MockScreen.sync([
		782	ansi.cursorUp(1),
		783	ansi.clearFullLine,
		784	"oops\n",
		785	"w\n",
		786	]),
		787	});
		788	host.cancel();
		789	});
		790
		791	test("mixed stream partial lines share cursor math", () => {
		792	const host = new testing.MockScreen();
		793	using _ = host.startWidget({ format: () => "w" });
		794	host.expectFrame(0, { stderr: testing.MockScreen.sync(["w\n"]) });
		795	host.writeOutput("a");
		796	host.writeError("b");
		797	host.expectFrame(0, {
		798	stdout: "a",
		799	merged: testing.MockScreen.sync([
		800	ansi.cursorUp(1),
		801	ansi.clearFullLine,
		802	"a",
		803	"b",
		804	"\n",
		805	"w\n",
		806	]),
		807	});
		808	// the continuation point is column 2, covering both partial chunks
		809	host.writeOutput("c\n");
		810	host.expectFrame(0, {
		811	merged: testing.MockScreen.sync([
		812	ansi.cursorUp(2) + ansi.cursorRight(2),
		813	"c\n",
		814	"w\n",
		815	]),
		816	});
		817	host.cancel();
		818	});
		819
		820	test("error text stays on screen when output is redirected", () => {
		821	const host = new testing.MockScreen({ outputSharesScreen: false });
		822	using _ = host.startWidget({ format: () => "w" });
		823	host.expectFrame(0, { stderr: testing.MockScreen.sync(["w\n"]) });
		824	host.writeOutput("to the file\n");
		825	host.writeError("to the screen\n");
		826	host.expectFrame(0, {
		827	stdout: "to the file\n",
		828	stderr: testing.MockScreen.sync([
		829	ansi.cursorUp(1),
		830	ansi.clearFullLine,
		831	"to the screen\n",
		832	"w\n",
		833	]),
		834	});
		835	host.cancel();
		836	});
		837
761	test("widgets start below a partial line", () => {	838	test("widgets start below a partial line", () => {
762	const host = new testing.MockScreen();	839	const host = new testing.MockScreen();
763	let text = "";	840	let text = "";

lib/log.ts+98-48

 @@ -238,14 +238,14 @@ export function writeOutput(text: string) {
   globalWidgetHost().writeOutput(text);
 }
-// TODO:
+/**
-// /**
+ * like {@linkcode writeOutput}, but the text is written to the error stream
-//  * no built-in prefix, formatting, or newlline. ensures the text does not interweave.
+ * (stderr in node.js). relative ordering between output and error text is
-//  * data will be flushed in the next frame or when drawing is {@link getDrawLock|unlocked}.
+ * preserved through the shared flush buffer.
-//  */
+ */
-// export function writeError(text: string) {
+export function writeError(text: string) {
-//   globalWidgetHost().writeError(text);
+  globalWidgetHost().writeError(text);
-// }
+}
 /** write a {@linkcode Message} object directly. */
 export function writeMessage(m: Message) {
 @@ -390,7 +390,11 @@ export interface TerminalWidgetHostOptions {
  * interface to communicate everything about the terminal state correctly.
  */
 export interface TerminalLock {
-  /** recieves ANSI escape sequences for interactive data (should flush immediately) */
+  /**
+   * recieves ANSI escape sequences for interactive data, as well as error log
+   * content from `writeError` (should flush immediately). the interactive
+   * stream and the error stream are the same: stderr.
+   */
   writeInteractive(text: string): void;
   /** recieves log content from `write` (pre-buffered; should flush immediately) */
   writeOutput(text: string): void;
 @@ -460,7 +464,12 @@ export function createTerminalWidgetHost(
   let locks = 0;
   let redrawTime = 0;
   let lastFlush = 0;
-  let buffer = "";
+  // log text awaiting a flush. error text shares the queue so that relative
+  // write order is preserved, but flushes to the interactive stream (stderr)
+  // and always lands on the widget screen, while plain output rows only
+  // count when `outputSharesScreen`. consecutive same-stream writes merge
+  // into one chunk.
+  let buffer: { text: string; err: boolean }[] = [];
   // visible width of the trailing partial log line (text since the last "\n"
   // written to output). the cursor column is derived as `partialWidth %
   // columns` at draw time, so the value survives resizes and wrapped lines.
 @@ -536,7 +545,7 @@ export function createTerminalWidgetHost(
       }
       // cancel() during this render pass (an exit handler unwinding through
       // a crashed format callback) skips its teardown; finish it here.
-      if (widgets.length === 0 && terminal && !timer && !buffer) {
+      if (widgets.length === 0 && terminal && !timer && !buffer.length) {
         lines = [];
         closeTerminal();
       }
 @@ -550,21 +559,24 @@ export function createTerminalWidgetHost(
     if (!lines.length && !widgets.length) {
       // a redraw can get scheduled with nothing to write (e.g. widgets torn
       // down before the timer fired); it is a no-op, not an error
-      if (!buffer) return;
+      if (!buffer.length) return;
       needsToRestoreCursor = false;
       needsToSaveCursor = false;
-      if (!terminal && writeOutputTemporaryLock) {
+      if (
-        writeOutputTemporaryLock(buffer);
+        !terminal && writeOutputTemporaryLock && !buffer.some((c) => c.err)
+      ) {
+        const text = buffer.map((c) => c.text).join("");
+        buffer = [];
+        writeOutputTemporaryLock(text);
+        if (outputOnScreen) trackPartialWidth(text);
       } else {
-        acquireTerminal().writeOutput(buffer);
+        trackPartialWidth(flushChunks(acquireTerminal()));
       }
       if (hasSyncStart) {
         acquireTerminal().writeInteractive(ansi.syncEnd);
         hasSyncStart = false;
       }
       closeTerminal();
-      trackPartialWidth(buffer);
-      buffer = "";
       return;
     }
 @@ -624,10 +636,8 @@ export function createTerminalWidgetHost(
         needsToRestoreCursor = false;
         lines = [];
       }
-      if (buffer) {
+      if (buffer.length) {
-        term.writeOutput(buffer);
+        trackPartialWidth(flushChunks(term));
-        trackPartialWidth(buffer);
-        buffer = "";
       }
       if (hasSyncStart) {
         term.writeInteractive(ansi.syncEnd);
 @@ -639,15 +649,20 @@ export function createTerminalWidgetHost(
       return;
     }
-    if (buffer && !outputOnScreen) {
+    // concatenation of the buffered text that lands on the widget screen,
+    // which is what the cursor math must account for
+    const screenText = buffer
+      .filter((c) => c.err || outputOnScreen)
+      .map((c) => c.text)
+      .join("");
+    if (buffer.length && screenText === "") {
       // off-screen output (e.g. stdout redirected to a file) does not
       // interact with the widget block; flush it plainly and fall through
       // to a pure widget redraw
-      term.writeOutput(buffer);
+      flushChunks(term);
-      buffer = "";
     }
-    if (buffer) {
+    if (buffer.length) {
       // when writing a buffer alongside widgets, the screen may look like this
       // > [existing log]
       // > [optional partial line]
 @@ -659,7 +674,7 @@ export function createTerminalWidgetHost(
       // first, clear out the space where new lines are going to intersect.
       // `span.rows` measures the cursor descent in physical rows, so log
       // lines wider than the terminal are accounted for correctly.
-      const span = measureTerminalSpan(buffer, pCol, columns);
+      const span = measureTerminalSpan(screenText, pCol, columns);
       // if more rows are buffered than there are widgets, only some are
       // needed. when a partial line exists, the buffer starts on its row
       // (one above the widget block), hence the -1.
 @@ -689,8 +704,8 @@ export function createTerminalWidgetHost(
                 : "")
             : ""),
       );
-      // then write output lines on standard out
+      // then write the buffered log content to its streams
-      term.writeOutput(buffer);
+      flushChunks(term);
       term.writeInteractive(
         // if the buffer leaves a partial line, the widgets have to go on the
         // next line. to avoid breaking stdout, the newline gets emitted on
 @@ -753,17 +768,37 @@ export function createTerminalWidgetHost(
     needsToRestoreCursor ||= needsToSaveCursor;
     needsToSaveCursor = false;
     lines = newWidgetLines;
-    buffer = "";
   }
   /**
-   * update `partialWidth` after writing `text` to the output. rows written
+   * write every buffered chunk to its stream in order, returning the
-   * off-screen never displace the widget block, so they are not tracked.
+   * concatenation of the chunks that landed on the widget screen. error
+   * chunks flush through `writeInteractive` since the interactive stream is
+   * the error stream; plain output rows land on screen only when
+   * `outputSharesScreen`.
    */
-  function trackPartialWidth(text: string) {
+  function flushChunks(term: TerminalLock): string {
-    if (!outputOnScreen) return;
+    let screen = "";
-    const i = text.lastIndexOf("\n");
+    for (const chunk of buffer) {
-    partialWidth = ansi.widthInTerminal(text.slice(i + 1))
+      if (chunk.err) {
+        term.writeInteractive(chunk.text);
+        screen += chunk.text;
+      } else {
+        term.writeOutput(chunk.text);
+        if (outputOnScreen) screen += chunk.text;
+      }
+    }
+    buffer = [];
+    return screen;
+  }
+  /**
+   * update `partialWidth` after `screenText` (already filtered to the chunks
+   * that landed on the widget screen) was written.
+   */
+  function trackPartialWidth(screenText: string) {
+    const i = screenText.lastIndexOf("\n");
+    partialWidth = ansi.widthInTerminal(screenText.slice(i + 1))
       + (i === -1 ? partialWidth : 0);
   }
 @@ -807,24 +842,35 @@ export function createTerminalWidgetHost(
       hasSyncStart = shortTermDrawLock;
     }
     if (buffer.length > 0) {
-      if (widgets.length === 0 && !terminal && writeOutputTemporaryLock) {
+      if (
-        writeOutputTemporaryLock(buffer);
+        widgets.length === 0 && !terminal && writeOutputTemporaryLock
+        && !buffer.some((c) => c.err)
+      ) {
+        const text = buffer.map((c) => c.text).join("");
+        buffer = [];
+        writeOutputTemporaryLock(text);
+        if (outputOnScreen) trackPartialWidth(text);
       } else {
-        acquireTerminal().writeOutput(buffer);
+        trackPartialWidth(flushChunks(acquireTerminal()));
         if (widgets.length === 0) closeTerminal();
       }
-      trackPartialWidth(buffer);
-      buffer = "";
     }
   }
+  /** append a write to the flush buffer, scheduling the flush */
+  function bufferChunk(chunk: string, err: boolean) {
+    const last = buffer[buffer.length - 1];
+    if (last && last.err === err) last.text += chunk;
+    else buffer.push({ text: chunk, err });
+    redrawSoon(0);
+  }
   return {
     writeOutput(chunk) {
-      if (chunk) buffer += chunk, redrawSoon(0);
+      if (chunk) bufferChunk(chunk, false);
     },
     writeError(chunk) {
-      // TODO: write to stderr. when this was introduced it was not a regression from v3
+      if (chunk) bufferChunk(chunk, true);
-      if (chunk) buffer += chunk, redrawSoon(0);
     },
     getDrawLock(mode) {
       if (rendering) ASSERT(locks === 0);
 @@ -1375,11 +1421,15 @@ const globalLog = /* @__PURE__ */ (() =>
     if (global.writeMessage) {
       global.writeMessage(m);
     } else if (node.process) {
-      globalWidgetHost()[
+      // info/debug levels land on stdout, warnings and errors on stderr;
-        (m.level ?? "info") === "info" ? "writeOutput" : "writeError"
+      // colors are keyed off the destination stream
-        // colors keyed off stdout, the destination of host log output;
+      const err = (m.level ?? "info") !== "info" && m.level !== "debug";
-        // `logColors` (used for inspect formatting) matches.
+      globalWidgetHost()[err ? "writeError" : "writeOutput"](
-      ](formatAnsiMessage(m, node.process.stdout.isTTY));
+        formatAnsiMessage(
+          m,
+          (err ? node.process.stderr : node.process.stdout).isTTY,
+        ),
+      );
     } else {
       let { level = "info", [originalLogArgs]: args = [m.text], scope } = m;
       if (scope) {

lib/readme.changes.md+1

...	@@ -17,6 +17,7 @@	...	@@ -17,6 +17,7 @@
17		17
18	- `mime`'s database contains `.eot` for embedded opentype fonts.	18	- `mime`'s database contains `.eot` for embedded opentype fonts.
19	- `async.deferred`	19	- `async.deferred`
		20	- `log.writeError` writes to stderr with proper logic
20		21
21	## v4	22	## v4
22		23