@oh-my-pi/pi-utils 16.5.1 → 17.0.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## [Unreleased]
 
+## [17.0.0] - 2026-07-15
+
+### Fixed
+
+- Improved SSE streaming performance by batching complete lines into a single UTF-8 decode per chunk, reducing decoder overhead.
+- Fixed an issue in `parseFrontmatter` where a single malformed YAML line would corrupt sibling values by parsing each line independently.
+
+## [16.5.2] - 2026-07-14
+
+### Fixed
+
+- Improved CLI argument and flag validation error output to display a concise error message and command usage instead of a minified code frame.
+- Corrected required variadic positionals to render as `MODELS...` instead of `[MODELS]` in usage help.
+
 ## [16.5.1] - 2026-07-14
 
 ### Added

package/dist/types/cli.d.ts

@@ -1,3 +1,13 @@
+/**
+ * A user-facing argument/flag validation failure. Thrown by {@link Command.parse}
+ * for missing/invalid positionals and flags. The top-level {@link run} handler
+ * prints its message plus the command usage line to stderr and exits 1, instead
+ * of letting it bubble to the process-level catch — which would dump a minified
+ * `dist/cli.js` code frame over a plain argument mistake (issue #5369).
+ */
+export declare class CliUsageError extends Error {
+    constructor(message: string);
+}
 export interface FlagDescriptor<K extends "string" | "boolean" | "integer" = "string" | "boolean" | "integer"> {
     kind: K;
     description?: string;
@@ -91,6 +101,8 @@ export declare abstract class Command {
 }
 /** Render full root help: header, default command details, subcommand list. */
 export declare function renderRootHelp(config: CliConfig): void;
+/** Build the single USAGE line for a command (without the leading label). */
+export declare function commandUsageLine(bin: string, id: string, Cmd: CommandCtor): string;
 /** Render help for a single command. */
 export declare function renderCommandHelp(bin: string, id: string, Cmd: CommandCtor): void;
 /** A lazily-loaded command: canonical name, loader, and optional aliases. */

package/dist/types/stream.d.ts

@@ -41,9 +41,8 @@ export interface ServerSentEvent {
  * Use `readSseJson` instead when every event is a single `data:` JSON object
  * and you don't need access to the `event:` field.
  *
- * Internally backed by a Buffer-based line reader (`ConcatSink`) so chunk
- * concatenation is O(n) and never triggers per-line string slicing of the
- * accumulated buffer.
+ * Internally backed by a Buffer-based reader (`ConcatSink`) that batches all
+ * complete lines in each source chunk into one UTF-8 decode.
  *
  * @example
  * ```ts

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-utils",
-	"version": "16.5.1",
+	"version": "17.0.0",
 	"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.5.1",
+		"@oh-my-pi/pi-natives": "17.0.0",
 		"handlebars": "^4.7.9",
 		"winston": "^3.19.0",
 		"winston-daily-rotate-file": "^5.0.0"

package/src/cli.ts

@@ -28,6 +28,20 @@ function startupMarker(text: string): void {
 	}
 }
 
+/**
+ * A user-facing argument/flag validation failure. Thrown by {@link Command.parse}
+ * for missing/invalid positionals and flags. The top-level {@link run} handler
+ * prints its message plus the command usage line to stderr and exits 1, instead
+ * of letting it bubble to the process-level catch — which would dump a minified
+ * `dist/cli.js` code frame over a plain argument mistake (issue #5369).
+ */
+export class CliUsageError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "CliUsageError";
+	}
+}
+
 // ---------------------------------------------------------------------------
 // Flag & Arg descriptors
 // ---------------------------------------------------------------------------
@@ -190,12 +204,18 @@ export abstract class Command {
 
 		// strict=false when command declares args (positionals must pass through)
 		// or when the command itself opts out
-		const { values: rawValues, positionals } = nodeParseArgs({
-			args: this.argv,
-			options,
-			allowPositionals: true,
-			strict,
-		});
+		const { values: rawValues, positionals } = (() => {
+			try {
+				return nodeParseArgs({
+					args: this.argv,
+					options,
+					allowPositionals: true,
+					strict,
+				});
+			} catch (error) {
+				throw new CliUsageError(error instanceof Error ? error.message : String(error));
+			}
+		})();
 
 		// Convert raw values to proper types and validate
 		const flags: Record<string, unknown> = {};
@@ -207,7 +227,7 @@ export abstract class Command {
 				} else {
 					const n = Number.parseInt(raw as string, 10);
 					if (Number.isNaN(n)) {
-						throw new Error(`Expected integer for --${name}, got "${raw}"`);
+						throw new CliUsageError(`Expected integer for --${name}, got "${raw}"`);
 					}
 					flags[name] = n;
 				}
@@ -220,14 +240,16 @@ export abstract class Command {
 				// Validate options constraint
 				if (val !== undefined && desc.options && !Array.isArray(val)) {
 					if (!desc.options.includes(val as string)) {
-						throw new Error(`Expected --${name} to be one of: ${[...desc.options].join(", ")}; got "${val}"`);
+						throw new CliUsageError(
+							`Expected --${name} to be one of: ${[...desc.options].join(", ")}; got "${val}"`,
+						);
 					}
 				}
 				flags[name] = val;
 			}
 			// Validate required
 			if (desc.required && flags[name] === undefined) {
-				throw new Error(`Missing required flag: --${name}`);
+				throw new CliUsageError(`Missing required flag: --${name}`);
 			}
 		}
 
@@ -246,13 +268,15 @@ export abstract class Command {
 			}
 			// Validate required
 			if (desc.required && args[argName] === undefined) {
-				throw new Error(`Missing required argument: ${argName}`);
+				throw new CliUsageError(`Missing required argument: ${argName}`);
 			}
 			// Validate options constraint
 			const argVal = args[argName];
 			if (argVal !== undefined && desc.options && typeof argVal === "string") {
 				if (!desc.options.includes(argVal)) {
-					throw new Error(`Expected ${argName} to be one of: ${[...desc.options].join(", ")}; got "${argVal}"`);
+					throw new CliUsageError(
+						`Expected ${argName} to be one of: ${[...desc.options].join(", ")}; got "${argVal}"`,
+					);
 				}
 			}
 		}
@@ -294,15 +318,34 @@ export function renderRootHelp(config: CliConfig): void {
 	process.stdout.write(lines.join("\n"));
 }
 
+/**
+ * Format a command's positional args for a USAGE line. Required args render
+ * bare (`MODELS`), optional args wrapped in brackets (`[MODELS]`), and
+ * `multiple` args get a trailing ellipsis (`MODELS...`) so a required
+ * variadic reads as `MODELS...`, not the misleading optional `[MODELS]`.
+ */
+function formatUsageArgs(Cmd: CommandCtor): string {
+	const entries = Object.entries(Cmd.args ?? {});
+	if (entries.length === 0) return "";
+	const parts = entries.map(([name, desc]) => {
+		const label = `${name.toUpperCase()}${desc.multiple ? "..." : ""}`;
+		return desc.required ? label : `[${label}]`;
+	});
+	return ` ${parts.join(" ")}`;
+}
+
+/** Build the single USAGE line for a command (without the leading label). */
+export function commandUsageLine(bin: string, id: string, Cmd: CommandCtor): string {
+	const hasFlags = Object.keys(Cmd.flags ?? {}).length > 0;
+	return `$ ${bin} ${id}${formatUsageArgs(Cmd)}${hasFlags ? " [FLAGS]" : ""}`;
+}
+
 /** Render help for a single command. */
 export function renderCommandHelp(bin: string, id: string, Cmd: CommandCtor): void {
 	const lines: string[] = [];
 	if (Cmd.description) lines.push(`${Cmd.description}\n`);
 	lines.push("USAGE");
-	const argNames = Object.keys(Cmd.args ?? {});
-	const argStr = argNames.length > 0 ? ` ${argNames.map(n => `[${n.toUpperCase()}]`).join(" ")}` : "";
-	const hasFlags = Object.keys(Cmd.flags ?? {}).length > 0;
-	lines.push(`  $ ${bin} ${id}${argStr}${hasFlags ? " [FLAGS]" : ""}\n`);
+	lines.push(`  ${commandUsageLine(bin, id, Cmd)}\n`);
 	renderCommandBody(lines, Cmd);
 	process.stdout.write(lines.join("\n"));
 }
@@ -435,7 +478,22 @@ export async function run(opts: RunOptions): Promise<void> {
 	const Cmd = await loadEntry(entry);
 	const config: CliConfig = { bin, version, commands: new Map([[entry.name, Cmd]]) };
 	const instance = new Cmd(commandArgv, config);
-	await instance.run();
+	try {
+		await instance.run();
+	} catch (error) {
+		// A usage mistake (missing/invalid arg or flag) is not a crash: print the
+		// message and the command's usage line, then exit 1. Letting it reach the
+		// process-level catch would dump a minified `dist/cli.js` code frame over a
+		// plain argument error (issue #5369).
+		if (error instanceof CliUsageError) {
+			process.stderr.write(`error: ${error.message}\n\n`);
+			process.stderr.write(`USAGE\n  ${commandUsageLine(bin, entry.name, Cmd)}\n`);
+			process.stderr.write(`\nRun \`${bin} ${entry.name} --help\` for details.\n`);
+			process.exitCode = 1;
+			return;
+		}
+		throw error;
+	}
 }
 
 /** Load one command module, leaving streaming markers around the import. */

package/src/frontmatter.ts

@@ -149,12 +149,25 @@ export function parseFrontmatter(
 			throw err;
 		}
 
-		// Simple YAML parsing - just key: value pairs
+		// Simple key: value fallback. Reparse each value on its own so one
+		// malformed line (e.g. `scope: "text","thinking"`) can't leave sibling
+		// values wrapped in literal quotes; values that don't parse as YAML fall
+		// back to the raw trimmed string (issue #4796).
 		for (const line of metadata.split("\n")) {
 			const match = line.match(/^([\w-]+):\s*(.*)$/);
-			if (match) {
-				frontmatter[match[1]] = match[2].trim();
+			if (!match) continue;
+			const raw = match[2].trim();
+			let value: unknown = raw;
+			if (raw.length > 0) {
+				try {
+					const parsed = YAML.parse(raw);
+					if (parsed !== null && typeof parsed !== "object") value = parsed;
+					else if (Array.isArray(parsed)) value = parsed;
+				} catch {
+					// keep the raw string
+				}
 			}
+			frontmatter[match[1]] = value;
 		}
 
 		return { frontmatter: normalizeKeys(frontmatter) as Record<string, unknown>, body };

package/src/stream.ts

@@ -150,6 +150,29 @@ class ConcatSink {
 			}
 		}
 	}
+
+	appendAndFlushText(chunk: Uint8Array, decoder: TextDecoder): string | undefined {
+		const lastNewline = chunk.lastIndexOf(LF);
+		if (lastNewline === -1) {
+			this.append(chunk);
+			return undefined;
+		}
+
+		const completeEnd = lastNewline + 1;
+		let text: string;
+		if (this.isEmpty) {
+			const complete = completeEnd === chunk.length ? chunk : chunk.subarray(0, completeEnd);
+			text = decoder.decode(complete);
+		} else {
+			this.append(completeEnd === chunk.length ? chunk : chunk.subarray(0, completeEnd));
+			text = decoder.decode(this.flush());
+			this.clear();
+		}
+		if (completeEnd < chunk.length) {
+			this.append(chunk.subarray(completeEnd));
+		}
+		return text;
+	}
 	*pullJSONL<T>(chunk: Uint8Array, beg: number, end: number) {
 		if (this.isEmpty) {
 			const { values, error, read, done } = parseJsonlChunkCompat(chunk, beg, end);
@@ -275,14 +298,9 @@ interface SseEventState {
 	raw: string[];
 }
 
-// Single decoder reused for all line decodes. Safe because lines are split on
-// LF (0x0a) which is always a single-byte ASCII char in UTF-8 and never appears
-// inside a multi-byte sequence — so each line is itself a complete UTF-8 run.
-const SSE_LINE_DECODER = new TextDecoder("utf-8");
-
-function decodeSseLineBytes(line: Uint8Array, end: number): string {
-	return end === line.length ? SSE_LINE_DECODER.decode(line) : SSE_LINE_DECODER.decode(line.subarray(0, end));
-}
+// Complete lines are decoded in one batch per source chunk. Each batch ends on
+// LF, which cannot split a multi-byte UTF-8 sequence.
+const SSE_DECODER = new TextDecoder("utf-8");
 
 function flushSseEvent(state: SseEventState): ServerSentEvent | null {
 	if (state.event === null && state.data === null) {
@@ -300,25 +318,25 @@ function flushSseEvent(state: SseEventState): ServerSentEvent | null {
 	return event;
 }
 
-function pushSseLine(line: Uint8Array, state: SseEventState): ServerSentEvent | null {
-	// `appendAndFlushLines` splits on LF only; strip a trailing CR so CRLF sources
+function pushSseLine(line: string, state: SseEventState): ServerSentEvent | null {
+	// Complete-line batches split on LF only; strip a trailing CR so CRLF sources
 	// don't leak `\r` into field values.
-	let end = line.length;
-	if (end > 0 && line[end - 1] === 0x0d /* '\r' */) end--;
-	if (end === 0) return flushSseEvent(state);
+	if (line.charCodeAt(line.length - 1) === 0x0d /* '\r' */) {
+		line = line.slice(0, -1);
+	}
+	if (line.length === 0) return flushSseEvent(state);
 
 	// Comment line: keep in `raw` for diagnostic context, skip parsing.
-	if (line[0] === 0x3a /* ':' */) {
-		state.raw.push(decodeSseLineBytes(line, end));
+	if (line.charCodeAt(0) === 0x3a /* ':' */) {
+		state.raw.push(line);
 		return null;
 	}
 
-	const text = decodeSseLineBytes(line, end);
-	state.raw.push(text);
+	state.raw.push(line);
 
-	const colon = text.indexOf(":");
-	const fieldName = colon === -1 ? text : text.slice(0, colon);
-	let value = colon === -1 ? "" : text.slice(colon + 1);
+	const colon = line.indexOf(":");
+	const fieldName = colon === -1 ? line : line.slice(0, colon);
+	let value = colon === -1 ? "" : line.slice(colon + 1);
 	if (value.charCodeAt(0) === 0x20 /* ' ' */) value = value.slice(1);
 
 	if (fieldName === "event") {
@@ -344,9 +362,8 @@ function pushSseLine(line: Uint8Array, state: SseEventState): ServerSentEvent |
  * Use `readSseJson` instead when every event is a single `data:` JSON object
  * and you don't need access to the `event:` field.
  *
- * Internally backed by a Buffer-based line reader (`ConcatSink`) so chunk
- * concatenation is O(n) and never triggers per-line string slicing of the
- * accumulated buffer.
+ * Internally backed by a Buffer-based reader (`ConcatSink`) that batches all
+ * complete lines in each source chunk into one UTF-8 decode.
  *
  * @example
  * ```ts
@@ -365,9 +382,14 @@ export async function* readSseEvents(
 	const source = abortableSource(stream, signal);
 	try {
 		for await (const chunk of source) {
-			for (const line of lineBuffer.appendAndFlushLines(chunk)) {
-				const event = pushSseLine(line, state);
+			const text = lineBuffer.appendAndFlushText(chunk, SSE_DECODER);
+			if (text === undefined) continue;
+			let start = 0;
+			while (start < text.length) {
+				const newline = text.indexOf("\n", start);
+				const event = pushSseLine(text.slice(start, newline), state);
 				if (event) yield event;
+				start = newline + 1;
 			}
 		}
 		// Treat any trailing partial line (no terminating LF) as a complete line.
@@ -375,7 +397,7 @@ export async function* readSseEvents(
 			const tail = lineBuffer.flush();
 			if (tail) {
 				lineBuffer.clear();
-				const event = pushSseLine(tail, state);
+				const event = pushSseLine(SSE_DECODER.decode(tail), state);
 				if (event) {
 					trailingEvents.add(event);
 					yield event;