@oh-my-pi/pi-utils 16.0.1 → 16.0.3

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+## [16.0.3] - 2026-06-16
+
+### Added
+
+- Added `escapeXmlText` utility to escape XML-significant characters `&`, `<`, and `>` in element body text
+- Added `isTerminalHeadless()` / `setTerminalHeadless()` to centrally suppress real-terminal side effects (stdout escape/frame writes, stdin raw mode, CSI/OSC capability probes, SIGWINCH, window-title changes, emergency restore) under the test runtime. Defaults on when `bun test` sets `NODE_ENV=test`; terminal-contract tests opt out via `setTerminalHeadless(false)`
+
 ## [15.13.3] - 2026-06-15
 
 ### Added

package/dist/types/env.d.ts

@@ -45,6 +45,23 @@ export declare function $pickenv(...keys: string[]): string | undefined;
 export declare function $envpos(name: string, defaultValue: number): number;
 /** True when `BUN_ENV` or `NODE_ENV` is the string `test`. */
 export declare function isBunTestRuntime(): boolean;
+/**
+ * True when real-terminal side effects must be suppressed: stdout escape/frame
+ * writes, stdin raw-mode + resume, CSI/OSC capability probes, SIGWINCH, window
+ * title changes, and emergency restore. Defaults to {@link isBunTestRuntime} so
+ * `bun test` launched inside a real TTY never paints the TUI, leaks probe
+ * queries, or hijacks the developer's stdin; production runtimes stay
+ * interactive.
+ *
+ * Terminal-contract tests that must exercise the real I/O path opt out with
+ * `setTerminalHeadless(false)` and restore it afterwards.
+ */
+export declare function isTerminalHeadless(): boolean;
+/**
+ * Override the {@link isTerminalHeadless} default and return the previous value
+ * so callers can restore exact prior state (`const prev = setTerminalHeadless(false); … setTerminalHeadless(prev);`).
+ */
+export declare function setTerminalHeadless(headless: boolean): boolean;
 /**
  * True when this code is running inside a `bun build --compile` standalone
  * binary. Detects via the embedded virtual-filesystem path markers

package/dist/types/sanitize-text.d.ts

@@ -12,3 +12,10 @@
  * string after the control probe.
  */
 export declare function sanitizeText(text: string): string;
+/**
+ * Escape the three XML-significant characters (`&`, `<`, `>`) in text destined
+ * for an XML/markup element body. Allocation-conscious: returns the input
+ * unchanged (same reference) when nothing needs escaping. Quotes are left as-is
+ * — use it for element text, not attribute values.
+ */
+export declare function escapeXmlText(input: string): string;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-utils",
-	"version": "16.0.1",
+	"version": "16.0.3",
 	"description": "Shared utilities for pi packages",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -31,7 +31,7 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "16.0.1",
+		"@oh-my-pi/pi-natives": "16.0.3",
 		"beautiful-mermaid": "^1.1.3",
 		"handlebars": "^4.7.9",
 		"winston": "^3.19.0",

package/src/env.ts

@@ -167,6 +167,33 @@ export function isBunTestRuntime(): boolean {
 	return Bun.env.BUN_ENV === "test" || Bun.env.NODE_ENV === "test";
 }
 
+let terminalHeadless = isBunTestRuntime();
+
+/**
+ * True when real-terminal side effects must be suppressed: stdout escape/frame
+ * writes, stdin raw-mode + resume, CSI/OSC capability probes, SIGWINCH, window
+ * title changes, and emergency restore. Defaults to {@link isBunTestRuntime} so
+ * `bun test` launched inside a real TTY never paints the TUI, leaks probe
+ * queries, or hijacks the developer's stdin; production runtimes stay
+ * interactive.
+ *
+ * Terminal-contract tests that must exercise the real I/O path opt out with
+ * `setTerminalHeadless(false)` and restore it afterwards.
+ */
+export function isTerminalHeadless(): boolean {
+	return terminalHeadless;
+}
+
+/**
+ * Override the {@link isTerminalHeadless} default and return the previous value
+ * so callers can restore exact prior state (`const prev = setTerminalHeadless(false); … setTerminalHeadless(prev);`).
+ */
+export function setTerminalHeadless(headless: boolean): boolean {
+	const previous = terminalHeadless;
+	terminalHeadless = headless;
+	return previous;
+}
+
 /**
  * True when this code is running inside a `bun build --compile` standalone
  * binary. Detects via the embedded virtual-filesystem path markers

package/src/sanitize-text.ts

@@ -36,3 +36,31 @@ function sanitizeWellFormedText(text: string): string {
 	CONTROL_RE.lastIndex = 0;
 	return stripped.replace(CONTROL_RE, "");
 }
+
+/**
+ * Escape the three XML-significant characters (`&`, `<`, `>`) in text destined
+ * for an XML/markup element body. Allocation-conscious: returns the input
+ * unchanged (same reference) when nothing needs escaping. Quotes are left as-is
+ * — use it for element text, not attribute values.
+ */
+export function escapeXmlText(input: string): string {
+	let firstEscapable = -1;
+	for (let index = 0; index < input.length; index++) {
+		const char = input.charCodeAt(index);
+		if (char === 38 || char === 60 || char === 62) {
+			firstEscapable = index;
+			break;
+		}
+	}
+	if (firstEscapable === -1) return input;
+
+	let output = input.slice(0, firstEscapable);
+	for (let index = firstEscapable; index < input.length; index++) {
+		const char = input[index];
+		if (char === "&") output += "&amp;";
+		else if (char === "<") output += "&lt;";
+		else if (char === ">") output += "&gt;";
+		else output += char;
+	}
+	return output;
+}