@oh-my-pi/pi-utils 13.19.0 → 14.0.3

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-utils",
-	"version": "13.19.0",
+	"version": "14.0.3",
 	"description": "Shared utilities for pi packages",
 	"homepage": "https://github.com/can1357/oh-my-pi",
 	"author": "Can Boluk",
@@ -23,16 +23,22 @@
 	"main": "./src/index.ts",
 	"types": "./src/index.ts",
 	"scripts": {
-		"check": "tsgo -p tsconfig.json",
-		"test": "bun test"
+		"check": "biome check . && bun run check:types",
+		"check:types": "tsgo -p tsconfig.json --noEmit",
+		"lint": "biome lint .",
+		"test": "bun test",
+		"fix": "biome check --write --unsafe .",
+		"fmt": "biome format --write ."
 	},
 	"dependencies": {
 		"beautiful-mermaid": "^1.1",
+		"handlebars": "^4.7.9",
 		"winston": "^3.19",
 		"winston-daily-rotate-file": "^5.0"
 	},
 	"devDependencies": {
-		"@types/bun": "^1.3"
+		"@types/bun": "^1.3",
+		"@oh-my-pi/pi-natives": "14.0.3"
 	},
 	"engines": {
 		"bun": ">=1.3.7"
@@ -48,6 +54,7 @@
 		"./*": {
 			"types": "./src/*.ts",
 			"import": "./src/*.ts"
-		}
+		},
+		"./*.js": "./src/*.ts"
 	}
 }

package/src/frontmatter.ts

@@ -0,0 +1,118 @@
+import { YAML } from "bun";
+import { truncate } from "./format";
+import * as logger from "./logger";
+
+function stripHtmlComments(content: string): string {
+	return content.replace(/<!--[\s\S]*?-->/g, "");
+}
+
+/** Convert kebab-case to camelCase (e.g. "thinking-level" -> "thinkingLevel") */
+function kebabToCamel(key: string): string {
+	return key.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+/** Recursively normalize object keys from kebab-case to camelCase */
+function normalizeKeys<T>(obj: T): T {
+	if (obj === null || typeof obj !== "object") {
+		return obj;
+	}
+	if (Array.isArray(obj)) {
+		return obj.map(normalizeKeys) as T;
+	}
+	const result: Record<string, unknown> = {};
+	for (const [key, value] of Object.entries(obj as Record<string, unknown>)) {
+		const normalizedKey = kebabToCamel(key);
+		result[normalizedKey] = normalizeKeys(value);
+	}
+	return result as T;
+}
+
+export class FrontmatterError extends Error {
+	constructor(
+		error: Error,
+		readonly source?: unknown,
+	) {
+		super(`Failed to parse YAML frontmatter (${source}): ${error.message}`, { cause: error });
+		this.name = "FrontmatterError";
+	}
+
+	toString(): string {
+		// Format the error with stack and detail, including the error message, stack, and source if present
+		const details: string[] = [this.message];
+		if (this.source !== undefined) {
+			details.push(`Source: ${JSON.stringify(this.source)}`);
+		}
+		if (this.cause && typeof this.cause === "object" && "stack" in this.cause && this.cause.stack) {
+			details.push(`Stack:\n${this.cause.stack}`);
+		} else if (this.stack) {
+			details.push(`Stack:\n${this.stack}`);
+		}
+		return details.join("\n\n");
+	}
+}
+
+export interface FrontmatterOptions {
+	/** Source of the content (alias: source) */
+	location?: unknown;
+	/** Source of the content (alias for location) */
+	source?: unknown;
+	/** Fallback frontmatter values */
+	fallback?: Record<string, unknown>;
+	/** Normalize the content */
+	normalize?: boolean;
+	/** Level of error handling */
+	level?: "off" | "warn" | "fatal";
+}
+
+/**
+ * Parse YAML frontmatter from markdown content
+ * Returns { frontmatter, body } where body has frontmatter stripped
+ */
+export function parseFrontmatter(
+	content: string,
+	options?: FrontmatterOptions,
+): { frontmatter: Record<string, unknown>; body: string } {
+	const { location, source, fallback, normalize = true, level = "warn" } = options ?? {};
+	const loc = location ?? source;
+	const frontmatter: Record<string, unknown> = { ...fallback };
+
+	const normalized = normalize ? stripHtmlComments(content.replace(/\r\n/g, "\n").replace(/\r/g, "\n")) : content;
+	if (!normalized.startsWith("---")) {
+		return { frontmatter, body: normalized };
+	}
+
+	const endIndex = normalized.indexOf("\n---", 3);
+	if (endIndex === -1) {
+		return { frontmatter, body: normalized };
+	}
+
+	const metadata = normalized.slice(4, endIndex);
+	const body = normalized.slice(endIndex + 4).trim();
+
+	try {
+		// Replace tabs with spaces for YAML compatibility, use failsafe mode for robustness
+		const loaded = YAML.parse(metadata.replaceAll("\t", "  ")) as Record<string, unknown> | null;
+		return { frontmatter: normalizeKeys({ ...frontmatter, ...loaded }), body };
+	} catch (error) {
+		const err = new FrontmatterError(
+			error instanceof Error ? error : new Error(`YAML: ${error}`),
+			loc ?? `Inline '${truncate(content, 64)}'`,
+		);
+		if (level === "warn" || level === "fatal") {
+			logger.warn("Failed to parse YAML frontmatter", { err: err.toString() });
+		}
+		if (level === "fatal") {
+			throw err;
+		}
+
+		// Simple YAML parsing - just key: value pairs
+		for (const line of metadata.split("\n")) {
+			const match = line.match(/^([\w-]+):\s*(.*)$/);
+			if (match) {
+				frontmatter[match[1]] = match[2].trim();
+			}
+		}
+
+		return { frontmatter: normalizeKeys(frontmatter) as Record<string, unknown>, body };
+	}
+}

package/src/index.ts

@@ -4,19 +4,44 @@ export * from "./color";
 export * from "./dirs";
 export * from "./env";
 export * from "./format";
+export * from "./frontmatter";
 export * from "./fs-error";
 export * from "./glob";
 export * from "./hook-fetch";
-export * from "./indent";
 export * from "./json";
 export * as logger from "./logger";
 export * from "./mermaid-ascii";
+export * from "./mime";
+export * from "./peek-file";
 export * as postmortem from "./postmortem";
 export * as procmgr from "./procmgr";
 export { setNativeKillTree } from "./procmgr";
+export * as prompt from "./prompt";
 export * as ptree from "./ptree";
 export { AbortError, ChildProcess, Exception, NonZeroExitError } from "./ptree";
 export * from "./snowflake";
 export * from "./stream";
 export * from "./temp";
 export * from "./type-guards";
+export * from "./which";
+
+function isPlainObject(val: object): val is Record<string, unknown> {
+	return Object.getPrototypeOf(val) === Object.prototype || Array.isArray(val);
+}
+
+export function structuredCloneJSON<T>(value: T): T {
+	// primitives|null|undefined, copy
+	if (!value || typeof value !== "object") {
+		return value;
+	}
+
+	// deep clone
+	if (isPlainObject(value)) {
+		try {
+			return structuredClone(value);
+		} catch {
+			// might still fail due to nested structures
+		}
+	}
+	return JSON.parse(JSON.stringify(value)) as T;
+}

package/src/logger.ts

@@ -5,7 +5,6 @@
  * Each log entry includes process.pid for traceability.
  */
 import * as fs from "node:fs";
-import { RingBuffer } from "@oh-my-pi/pi-utils/ring";
 import winston from "winston";
 import DailyRotateFile from "winston-daily-rotate-file";
 import { getLogsDir } from "./dirs";
@@ -58,29 +57,6 @@ const winstonLogger = winston.createLogger({
 	exitOnError: false,
 });
 
-/**
- * Centralized logger for omp.
- *
- * Logs to ~/.omp/logs/omp.YYYY-MM-DD.log with size-based rotation.
- * Safe for concurrent access from multiple omp instances.
- *
- * @example
- * ```typescript
- * import { logger } from "@oh-my-pi/pi-utils";
- *
- * logger.error("MCP request failed", { url, method });
- * logger.warn("Theme file invalid, using fallback", { path });
- * logger.debug("LSP fallback triggered", { reason });
- * ```
- */
-export interface Logger {
-	error(message: string, context?: Record<string, unknown>): void;
-	warn(message: string, context?: Record<string, unknown>): void;
-	debug(message: string, context?: Record<string, unknown>): void;
-	time<T>(op: string, fn: () => T): T;
-	timeAsync<T>(op: string, fn: () => PromiseLike<T>): Promise<T>;
-}
-
 /**
  * Log an error message.
  * @param message - The message to log.
@@ -122,85 +98,107 @@ export function debug(message: string, context?: Record<string, unknown>): void
 
 const LOGGED_TIMING_THRESHOLD_MS = 5;
 
-const longOpBuffer = new RingBuffer<[op: string, duration: number]>(1000);
-let longOpRecord = false;
+/** Sequential wall-clock markers (next marker closes the previous segment). */
+let gTimings: [op: string, ts: number][] = [];
 
-function logTiming(op: string, duration: number): void {
-	duration = Math.round(duration * 100) / 100;
-	if (duration > LOGGED_TIMING_THRESHOLD_MS) {
-		warn(`${op} done`, { duration, op });
-		if (longOpRecord) {
-			longOpBuffer.push([op, duration]);
-		}
-	} else {
-		debug(`${op} done`, { duration, op });
-	}
-}
+/** Await-accurate durations (safe for parallel work; sums can overlap). */
+let gAsyncSpans: [op: string, durationMs: number][] = [];
+
+/** Whether to record timings. */
+let gRecordTimings = false;
 
 /**
- * Print all collected long operation timings to stderr.
- * To be called at the end of a startup or timing window.
+ * Print collected timings to stderr.
+ * Wall segments are gaps between consecutive {@link time} markers only; they are wrong when
+ * concurrent code also calls {@link time} (e.g. parallel capability loads). Use {@link timeAsync}
+ * for those awaits instead.
  */
 export function printTimings(): void {
-	// Use stderr for timings output, do not use logger (see AGENTS.md).
-	console.error("\n--- Startup Timings ---");
-	let totalDuration = 0;
-	for (const [op, duration] of longOpBuffer) {
-		console.error(`  ${op}: ${duration}ms`);
-		totalDuration += duration;
+	if (!gRecordTimings || gTimings.length === 0) {
+		console.error("\n--- Startup Timings ---\n(no markers)\n");
+		return;
 	}
-	console.error(`  TOTAL: ${totalDuration}ms`);
+
+	const endTs = performance.now();
+	gTimings.push(["(end)", endTs]);
+
+	console.error("\n--- Startup timings (wall segments between time() markers) ---");
+	const firstTs = gTimings[0][1];
+	for (let i = 0; i < gTimings.length - 1; i++) {
+		const [op, ts] = gTimings[i];
+		const [, nextTs] = gTimings[i + 1];
+		const dur = nextTs - ts;
+		if (dur > LOGGED_TIMING_THRESHOLD_MS) {
+			console.error(`  ${op}: ${dur}ms`);
+		}
+	}
+	console.error(`  span (first marker → end): ${endTs - firstTs}ms`);
+
+	if (gAsyncSpans.length > 0) {
+		console.error("\n--- Async (await-accurate; parallel spans may overlap) ---");
+		for (const [op, dur] of gAsyncSpans) {
+			if (dur > LOGGED_TIMING_THRESHOLD_MS) {
+				console.error(`  ${op}: ${dur}ms`);
+			}
+		}
+	}
+
 	console.error("------------------------\n");
+
+	gTimings.pop();
 }
 
 /**
- * Begin recording long operation timings.
- * Typically called at the beginning of startup.
+ * Begin recording startup timings. Seeds the timeline so the first segment is meaningful.
  */
 export function startTiming(): void {
-	longOpBuffer.clear();
-	longOpRecord = true;
+	gTimings = [["(startup)", performance.now()]];
+	gAsyncSpans = [];
+	gRecordTimings = true;
 }
 
 /**
- * End timing window and print all timings.
- * Disables further buffering until next startTiming().
+ * End timing window and clear buffers.
  */
 export function endTiming(): void {
-	longOpBuffer.clear();
-	longOpRecord = false;
+	gTimings = [];
+	gAsyncSpans = [];
+	gRecordTimings = false;
 }
 
-/**
- * Time a synchronous operation and log the duration.
- * @param op - The operation name.
- * @param fn - The function to time.
- * @returns The result of the function.
- */
-export function time<T, A extends unknown[]>(op: string, fn: (...args: A) => T, ...args: A): T {
-	const start = performance.now();
-	try {
-		return fn(...args);
-	} finally {
-		logTiming(op, performance.now() - start);
+function recordAsyncSpan(op: string, start: number): void {
+	const dur = performance.now() - start;
+	if (dur > LOGGED_TIMING_THRESHOLD_MS) {
+		gAsyncSpans.push([op, dur]);
 	}
 }
 
 /**
- * Time an asynchronous operation and log the duration.
- * @param op - The operation name.
- * @param fn - The function to time.
- * @returns The result of the function.
+ * Wall-clock segment boundary: duration for this label runs until the next {@link time} call.
+ * Do not use across `await` when other tasks may call {@link time}; use {@link timeAsync} for the awaited work.
  */
-export async function timeAsync<R, A extends unknown[]>(
-	op: string,
-	fn: (...args: A) => R,
-	...args: A
-): Promise<Awaited<R>> {
-	const start = performance.now();
-	try {
-		return await fn(...args);
-	} finally {
-		logTiming(op, performance.now() - start);
+export function time(op: string): void;
+export function time<T, A extends unknown[]>(op: string, fn: (...args: A) => T, ...args: A): T;
+export function time<T, A extends unknown[]>(op: string, fn?: (...args: A) => T, ...args: A): T | undefined {
+	if (fn === undefined) {
+		if (gRecordTimings) {
+			gTimings.push([op, performance.now()]);
+		}
+		return undefined as T;
+	} else if (gRecordTimings) {
+		const start = performance.now();
+		try {
+			const result = fn(...args);
+			if (result instanceof Promise) {
+				return result.finally(recordAsyncSpan.bind(null, op, start)) as T;
+			}
+			recordAsyncSpan(op, start);
+			return result;
+		} catch (error) {
+			recordAsyncSpan(op, start);
+			throw error;
+		}
+	} else {
+		return fn(...args);
 	}
 }

package/src/mime.ts

@@ -0,0 +1,159 @@
+import { peekFile, peekFileSync } from "./peek-file";
+
+const DEFAULT_IMAGE_METADATA_HEADER_BYTES = 256 * 1024;
+
+const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const JPEG_MAGIC = Buffer.from([0xff, 0xd8, 0xff]);
+const WEBP_RIFF_MAGIC = Buffer.from([0x52, 0x49, 0x46, 0x46]);
+const WEBP_MAGIC = Buffer.from([0x57, 0x45, 0x42, 0x50]);
+const PNG_IHDR = Buffer.from("IHDR");
+const GIF87A = Buffer.from("GIF87a");
+const GIF89A = Buffer.from("GIF89a");
+const WEBP_VP8X = Buffer.from("VP8X");
+const WEBP_VP8L = Buffer.from("VP8L");
+const WEBP_VP8 = Buffer.from("VP8 ");
+
+export const SUPPORTED_IMAGE_MIME_TYPES = new Set(["image/png", "image/jpeg", "image/gif", "image/webp"]);
+
+export type ImageMetadata =
+	| { mimeType: "image/png"; width?: number; height?: number; channels?: number; hasAlpha?: boolean }
+	| { mimeType: "image/jpeg"; width?: number; height?: number; channels?: number; hasAlpha?: false }
+	| { mimeType: "image/gif"; width?: number; height?: number; channels?: 3; hasAlpha?: never }
+	| { mimeType: "image/webp"; width?: number; height?: number; channels?: number; hasAlpha?: boolean };
+
+function magicEquals(header: Uint8Array, offset: number, magic: Buffer): boolean {
+	if (header.length < offset + magic.length) {
+		return false;
+	}
+	return magic.equals(header.subarray(offset, offset + magic.length));
+}
+
+function parsePngMetadata(header: Uint8Array): ImageMetadata | null {
+	if (!magicEquals(header, 0, PNG_MAGIC)) return null;
+	if (!magicEquals(header, 12, PNG_IHDR)) return { mimeType: "image/png" };
+	if (header.length < 26) return { mimeType: "image/png" };
+
+	const view = new DataView(header.buffer, header.byteOffset, header.byteLength);
+	const width = view.getUint32(16, false);
+	const height = view.getUint32(20, false);
+	const colorType = view.getUint8(25);
+	if (colorType === 0) return { mimeType: "image/png", width, height, channels: 1, hasAlpha: false };
+	if (colorType === 2) return { mimeType: "image/png", width, height, channels: 3, hasAlpha: false };
+	if (colorType === 3) return { mimeType: "image/png", width, height, channels: 3 };
+	if (colorType === 4) return { mimeType: "image/png", width, height, channels: 2, hasAlpha: true };
+	if (colorType === 6) return { mimeType: "image/png", width, height, channels: 4, hasAlpha: true };
+	return { mimeType: "image/png", width, height };
+}
+
+function parseJpegMetadata(header: Uint8Array): ImageMetadata | null {
+	if (!magicEquals(header, 0, JPEG_MAGIC)) return null;
+	if (header.length < 4) return { mimeType: "image/jpeg" };
+
+	const view = new DataView(header.buffer, header.byteOffset, header.byteLength);
+	let offset = 2;
+	while (offset + 9 < header.length) {
+		if (header[offset] !== 0xff) {
+			offset += 1;
+			continue;
+		}
+
+		let markerOffset = offset + 1;
+		while (markerOffset < header.length && header[markerOffset] === 0xff) {
+			markerOffset += 1;
+		}
+		if (markerOffset >= header.length) break;
+
+		const marker = header[markerOffset];
+		const segmentOffset = markerOffset + 1;
+		if (marker === 0xd8 || marker === 0xd9 || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) {
+			offset = segmentOffset;
+			continue;
+		}
+		if (segmentOffset + 1 >= header.length) break;
+
+		const segmentLength = view.getUint16(segmentOffset, false);
+		if (segmentLength < 2) break;
+
+		const isStartOfFrame = marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc;
+		if (isStartOfFrame) {
+			if (segmentOffset + 7 >= header.length) break;
+			const height = view.getUint16(segmentOffset + 3, false);
+			const width = view.getUint16(segmentOffset + 5, false);
+			const channels = header[segmentOffset + 7];
+			return {
+				mimeType: "image/jpeg",
+				width,
+				height,
+				channels: Number.isFinite(channels) ? channels : undefined,
+				hasAlpha: false,
+			};
+		}
+
+		offset = segmentOffset + segmentLength;
+	}
+
+	return { mimeType: "image/jpeg" };
+}
+
+function parseGifMetadata(header: Uint8Array): ImageMetadata | null {
+	if (!magicEquals(header, 0, GIF87A) && !magicEquals(header, 0, GIF89A)) return null;
+	if (header.length < 10) return { mimeType: "image/gif" };
+	const view = new DataView(header.buffer, header.byteOffset, header.byteLength);
+	return {
+		mimeType: "image/gif",
+		width: view.getUint16(6, true),
+		height: view.getUint16(8, true),
+		channels: 3,
+	};
+}
+
+function parseWebpMetadata(header: Uint8Array): ImageMetadata | null {
+	if (!magicEquals(header, 0, WEBP_RIFF_MAGIC)) return null;
+	if (!magicEquals(header, 8, WEBP_MAGIC)) return null;
+	if (header.length < 30) return { mimeType: "image/webp" };
+
+	if (magicEquals(header, 12, WEBP_VP8X)) {
+		const hasAlpha = (header[20] & 0x10) !== 0;
+		const width = (header[24] | (header[25] << 8) | (header[26] << 16)) + 1;
+		const height = (header[27] | (header[28] << 8) | (header[29] << 16)) + 1;
+		return { mimeType: "image/webp", width, height, channels: hasAlpha ? 4 : 3, hasAlpha };
+	}
+
+	const view = new DataView(header.buffer, header.byteOffset, header.byteLength);
+	if (magicEquals(header, 12, WEBP_VP8L)) {
+		if (header.length < 25) return { mimeType: "image/webp" };
+		const bits = view.getUint32(21, true);
+		const width = (bits & 0x3fff) + 1;
+		const height = ((bits >> 14) & 0x3fff) + 1;
+		const hasAlpha = ((bits >> 28) & 0x1) === 1;
+		return { mimeType: "image/webp", width, height, channels: hasAlpha ? 4 : 3, hasAlpha };
+	}
+
+	if (magicEquals(header, 12, WEBP_VP8)) {
+		const width = view.getUint16(26, true) & 0x3fff;
+		const height = view.getUint16(28, true) & 0x3fff;
+		return { mimeType: "image/webp", width, height, channels: 3, hasAlpha: false };
+	}
+
+	return { mimeType: "image/webp" };
+}
+
+export function parseImageMetadata(header: Uint8Array): ImageMetadata | null {
+	return (
+		parsePngMetadata(header) ?? parseJpegMetadata(header) ?? parseGifMetadata(header) ?? parseWebpMetadata(header)
+	);
+}
+
+export function readImageMetadataSync(
+	filePath: string,
+	maxBytes = DEFAULT_IMAGE_METADATA_HEADER_BYTES,
+): ImageMetadata | null {
+	return peekFileSync(filePath, maxBytes, parseImageMetadata);
+}
+
+export function readImageMetadata(
+	filePath: string,
+	maxBytes = DEFAULT_IMAGE_METADATA_HEADER_BYTES,
+): Promise<ImageMetadata | null> {
+	return peekFile(filePath, maxBytes, parseImageMetadata);
+}

package/src/peek-file.ts

@@ -0,0 +1,114 @@
+/**
+ * Read the first `maxBytes` of a file (offset 0) and pass that slice to `op`.
+ *
+ * Buffers are reused to avoid allocating on every peek: sync uses one growable
+ * `Uint8Array`; async uses a small fixed pool of `Buffer`s with a bounded wait
+ * queue, falling back to a fresh allocation when the pool and queue are saturated
+ * or when `maxBytes` exceeds the pool slot size.
+ */
+import * as fs from "node:fs";
+
+/** Async pool slot size; larger peeks allocate ad hoc. */
+const POOLED_BUFFER_SIZE = 512;
+const ASYNC_POOL_SIZE = 10;
+/** Cap waiter queue so heavy concurrency does not queue unbounded; overflow uses alloc. */
+const MAX_ASYNC_WAITERS = 4;
+const INITIAL_SYNC_BUFFER_SIZE = 1024;
+const EMPTY_BUFFER = Buffer.alloc(0);
+
+const asyncPool = Array.from({ length: ASYNC_POOL_SIZE }, () => Buffer.allocUnsafe(POOLED_BUFFER_SIZE));
+const availableAsyncPoolIndexes = Array.from({ length: ASYNC_POOL_SIZE }, (_, index) => index);
+const asyncPoolWaiters: Array<(index: number) => void> = [];
+let syncPool = new Uint8Array(INITIAL_SYNC_BUFFER_SIZE);
+
+/** Returns a pool slot index, or `-1` when the caller should use a standalone buffer. */
+function acquireAsyncPoolIndex(): Promise<number> | number {
+	const index = availableAsyncPoolIndexes.pop();
+	if (index !== undefined) {
+		return index;
+	}
+	if (asyncPoolWaiters.length >= MAX_ASYNC_WAITERS) {
+		return -1;
+	}
+	const { promise, resolve } = Promise.withResolvers<number>();
+	asyncPoolWaiters.push(resolve);
+	return promise;
+}
+
+function releaseAsyncPoolIndex(index: number): void {
+	if (index < 0) {
+		return;
+	}
+	const waiter = asyncPoolWaiters.shift();
+	if (waiter) {
+		waiter(index);
+		return;
+	}
+	availableAsyncPoolIndexes.push(index);
+}
+
+async function withAsyncPoolBuffer<T>(maxBytes: number, op: (buffer: Buffer) => Promise<T>): Promise<T> {
+	if (maxBytes <= 0) {
+		return op(EMPTY_BUFFER);
+	}
+	if (maxBytes > POOLED_BUFFER_SIZE) {
+		return op(Buffer.allocUnsafe(maxBytes));
+	}
+
+	const poolIndex = await acquireAsyncPoolIndex();
+	const buffer = poolIndex >= 0 ? asyncPool[poolIndex] : Buffer.allocUnsafe(maxBytes);
+	try {
+		return await op(buffer.subarray(0, maxBytes));
+	} finally {
+		releaseAsyncPoolIndex(poolIndex);
+	}
+}
+
+function withSyncPoolBuffer<T>(maxBytes: number, op: (buffer: Uint8Array) => T): T {
+	if (maxBytes <= 0) {
+		return op(EMPTY_BUFFER);
+	}
+	if (maxBytes > syncPool.byteLength) {
+		syncPool = new Uint8Array(maxBytes + (maxBytes >> 1));
+	}
+	return op(syncPool.subarray(0, maxBytes));
+}
+
+/**
+ * Synchronously reads up to `maxBytes` from the start of `filePath` and returns `op(header)`.
+ * If the file is shorter, `header` is only the bytes actually read.
+ */
+export function peekFileSync<T>(filePath: string, maxBytes: number, op: (header: Uint8Array) => T): T {
+	if (maxBytes <= 0) {
+		return op(EMPTY_BUFFER);
+	}
+
+	const fileHandle = fs.openSync(filePath, "r");
+	try {
+		return withSyncPoolBuffer(maxBytes, buffer => {
+			const bytesRead = fs.readSync(fileHandle, buffer, 0, buffer.byteLength, 0);
+			return op(buffer.subarray(0, bytesRead));
+		});
+	} finally {
+		fs.closeSync(fileHandle);
+	}
+}
+
+/**
+ * Like {@link peekFileSync} but uses async I/O.
+ */
+export async function peekFile<T>(filePath: string, maxBytes: number, op: (header: Uint8Array) => T): Promise<T> {
+	if (maxBytes <= 0) {
+		return op(EMPTY_BUFFER);
+	}
+
+	const fileHandle = await fs.promises.open(filePath, "r");
+	try {
+		return await withAsyncPoolBuffer(maxBytes, async buffer => {
+			const { bytesRead } = await fileHandle.read(buffer, 0, buffer.byteLength, 0);
+			return op(buffer.subarray(0, bytesRead));
+		});
+	} finally {
+		await fileHandle.close();
+	}
+}