@sayknow-cli/utils 0.2.2

package/src/logger.ts

@@ -0,0 +1,392 @@
+/**
+ * Centralized logger for sayknow-cli.
+ *
+ * Default: rotating `~/.skc/logs/skc.<DATE>.log`, no console output (writing
+ * to stdout/stderr would corrupt the TUI). Long-running headless services
+ * (the auth broker, etc.) call {@link setTransports} to swap in a console
+ * transport so a process supervisor (pm2, journald, k8s) captures the logs.
+ *
+ * Each entry includes `process.pid` so concurrent skc instances stay
+ * traceable.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import * as fs from "node:fs";
+import winston from "winston";
+import DailyRotateFile from "winston-daily-rotate-file";
+import { getLogsDir } from "./dirs";
+
+/** Ensure a logs directory exists; return the resolved path. */
+function ensureDir(dir: string): string {
+	if (!fs.existsSync(dir)) {
+		fs.mkdirSync(dir, { recursive: true });
+	}
+	return dir;
+}
+
+/** Custom format that includes pid and flattens metadata */
+const logFormat = winston.format.combine(
+	winston.format.timestamp({ format: "YYYY-MM-DDTHH:mm:ss.SSSZ" }),
+	winston.format.printf(({ timestamp, level, message, ...meta }) => {
+		const entry: Record<string, unknown> = {
+			timestamp,
+			level,
+			pid: process.pid,
+			message,
+		};
+		// Flatten metadata into entry
+		for (const [key, value] of Object.entries(meta)) {
+			if (key !== "level" && key !== "timestamp" && key !== "message") {
+				entry[key] = value;
+			}
+		}
+		return JSON.stringify(entry);
+	}),
+);
+
+/** Build a rotating file transport, materializing the target directory lazily. */
+function makeFileTransport(dir?: string): winston.transport {
+	return new DailyRotateFile({
+		dirname: ensureDir(dir ?? getLogsDir()),
+		filename: "skc.%DATE%.log",
+		datePattern: "YYYY-MM-DD",
+		maxSize: "10m",
+		maxFiles: 5,
+		zippedArchive: true,
+	});
+}
+
+function makeConsoleTransport(): winston.transport {
+	return new winston.transports.Console({ format: logFormat });
+}
+
+/** The winston logger instance. Default: file ON (TUI-safe), console OFF. */
+const winstonLogger = winston.createLogger({
+	level: "debug",
+	format: logFormat,
+	transports: [makeFileTransport()],
+	// Don't exit on error - logging failures shouldn't crash the app
+	exitOnError: false,
+});
+
+/**
+ * Replace the active log transports. Pass `console: true, file: false` for
+ * long-running services (the auth broker, etc.) that want their structured
+ * logs piped into a process supervisor instead of the rotating file.
+ */
+export function setTransports(opts: { console?: boolean; file?: boolean | string }): void {
+	winstonLogger.clear();
+	if (opts.file) {
+		winstonLogger.add(makeFileTransport(typeof opts.file === "string" ? opts.file : undefined));
+	}
+	if (opts.console) winstonLogger.add(makeConsoleTransport());
+}
+
+/**
+ * Log an error message.
+ * @param message - The message to log.
+ * @param context - The context to log.
+ */
+export function error(message: string, context?: Record<string, unknown>): void {
+	try {
+		winstonLogger.error(message, context);
+	} catch {
+		// Silently ignore logging failures
+	}
+}
+
+/**
+ * Log a warning message.
+ * @param message - The message to log.
+ * @param context - The context to log.
+ */
+export function warn(message: string, context?: Record<string, unknown>): void {
+	try {
+		winstonLogger.warn(message, context);
+	} catch {
+		// Silently ignore logging failures
+	}
+}
+
+/**
+ * Log an informational message.
+ * @param message - The message to log.
+ * @param context - The context to log.
+ */
+export function info(message: string, context?: Record<string, unknown>): void {
+	try {
+		winstonLogger.info(message, context);
+	} catch {
+		// Silently ignore logging failures
+	}
+}
+
+/**
+ * Log a debug message.
+ * @param message - The message to log.
+ * @param context - The context to log.
+ */
+export function debug(message: string, context?: Record<string, unknown>): void {
+	try {
+		winstonLogger.debug(message, context);
+	} catch {
+		// Silently ignore logging failures
+	}
+}
+
+const LOGGED_TIMING_THRESHOLD_MS = 0.5;
+
+interface Span {
+	op: string;
+	start: number;
+	end?: number;
+	parent?: Span;
+	children: Span[];
+	/** Marker / point event without a duration. */
+	point?: boolean;
+}
+
+const spanStorage = new AsyncLocalStorage<Span>();
+let gRootSpan: Span | undefined;
+let gRecordTimings = false;
+
+/**
+ * Print collected timings as an indented tree.
+ * Each span shows wall duration; parents with children also show "(self)" for unattributed time.
+ * Sibling spans are sorted by start time. Spans whose intervals overlap with siblings ran in parallel.
+ */
+export function printTimings(): void {
+	if (!gRecordTimings || !gRootSpan) {
+		console.error("\n--- Startup Timings ---\n(no markers)\n");
+		return;
+	}
+
+	gRootSpan.end = performance.now();
+	const lines: string[] = [];
+	lines.push("");
+	lines.push("--- Startup timings (hierarchical) ---");
+	const work: Span[] = [];
+	const loads: Span[] = [];
+	for (const child of gRootSpan.children) {
+		if (isModuleLoadSpan(child)) loads.push(child);
+		else work.push(child);
+	}
+	for (const child of work.sort((a, b) => a.start - b.start)) {
+		printSpan(child, 0, lines);
+	}
+	if (loads.length > 0) {
+		printModuleLoadSummary(loads, 0, lines);
+	}
+	const totalMs = (gRootSpan.end - gRootSpan.start).toFixed(1);
+	lines.push(`Total: ${totalMs}ms`);
+	lines.push("--------------------------------------");
+	lines.push("");
+	console.error(lines.join("\n"));
+	gRootSpan.end = undefined;
+}
+
+/**
+ * Begin recording startup timings under a new root span.
+ * Idempotent: a second call while already recording is a no-op so that side-effect
+ * starters (see module-timer.ts) and explicit starters (main.ts) can coexist.
+ */
+export function startTiming(): void {
+	if (gRecordTimings) return;
+	gRootSpan = {
+		op: "(root)",
+		start: performance.now(),
+		parent: undefined,
+		children: [],
+	};
+	gRecordTimings = true;
+}
+
+/**
+ * Record an externally-measured span as a leaf child of the active span (or root
+ * when no span is active). Used by the module-load timing plugin to splice load
+ * events into the tree retroactively.
+ */
+export function recordModuleLoadSpan(path: string, start: number, durationMs: number): void {
+	if (!gRecordTimings || !gRootSpan) return;
+	const parent = spanStorage.getStore() ?? gRootSpan;
+	const span: Span = {
+		op: `load:${shortenLoadPath(path)}`,
+		start,
+		end: start + durationMs,
+		parent,
+		children: [],
+	};
+	parent.children.push(span);
+}
+
+function shortenLoadPath(p: string): string {
+	const cwd = process.cwd();
+	if (p.startsWith(`${cwd}/`)) return p.slice(cwd.length + 1);
+	const home = process.env.HOME;
+	if (home && p.startsWith(`${home}/`)) return `~/${p.slice(home.length + 1)}`;
+	return p;
+}
+
+/**
+ * End timing window and clear buffers.
+ */
+export function endTiming(): void {
+	gRootSpan = undefined;
+	gRecordTimings = false;
+}
+
+function durationOf(span: Span): number {
+	if (span.point || span.end === undefined) return 0;
+	return span.end - span.start;
+}
+
+/** Self time = total - union of child intervals (handles parallel children correctly). */
+function selfTimeOf(span: Span): number {
+	const dur = durationOf(span);
+	if (span.children.length === 0 || span.point) return dur;
+	const intervals = span.children
+		.filter(c => !c.point && c.end !== undefined)
+		.map(c => [c.start, c.end as number] as const)
+		.sort((a, b) => a[0] - b[0]);
+	if (intervals.length === 0) return dur;
+	let union = 0;
+	let curStart = intervals[0][0];
+	let curEnd = intervals[0][1];
+	for (let i = 1; i < intervals.length; i++) {
+		const [s, e] = intervals[i];
+		if (s > curEnd) {
+			union += curEnd - curStart;
+			curStart = s;
+			curEnd = e;
+		} else if (e > curEnd) {
+			curEnd = e;
+		}
+	}
+	union += curEnd - curStart;
+	return Math.max(0, dur - union);
+}
+
+function fmtMs(ms: number): string {
+	if (ms < 1) return `${ms.toFixed(2)}ms`;
+	if (ms < 100) return `${ms.toFixed(1)}ms`;
+	return `${ms.toFixed(0)}ms`;
+}
+
+const MODULE_LOAD_PREFIX = "load:";
+const MODULE_LOAD_VERBOSE_TOP = 10;
+
+function isModuleLoadSpan(span: Span): boolean {
+	return span.op.startsWith(MODULE_LOAD_PREFIX);
+}
+
+function printSpan(span: Span, depth: number, lines: string[]): void {
+	const indent = "  ".repeat(depth);
+	if (span.point) {
+		lines.push(`${indent}• ${span.op}`);
+		return;
+	}
+	const dur = durationOf(span);
+	if (dur < LOGGED_TIMING_THRESHOLD_MS && span.children.length === 0) return;
+	const parallel = isParallel(span);
+	const tag = parallel ? " [parallel]" : "";
+	const self = selfTimeOf(span);
+	const selfStr = span.children.length > 0 && self > LOGGED_TIMING_THRESHOLD_MS ? ` (self ${fmtMs(self)})` : "";
+	lines.push(`${indent}${span.op}: ${fmtMs(dur)}${selfStr}${tag}`);
+
+	// Split children into work spans and module-load spans for summarization.
+	const work: Span[] = [];
+	const loads: Span[] = [];
+	for (const child of span.children) {
+		if (isModuleLoadSpan(child)) loads.push(child);
+		else work.push(child);
+	}
+	for (const child of work.sort((a, b) => a.start - b.start)) {
+		printSpan(child, depth + 1, lines);
+	}
+	if (loads.length > 0) {
+		printModuleLoadSummary(loads, depth + 1, lines);
+	}
+}
+
+/** Collapse the (typically hundreds of) module-load spans into one summary line. */
+function printModuleLoadSummary(loads: Span[], depth: number, lines: string[]): void {
+	const childIndent = "  ".repeat(depth);
+	const grandIndent = "  ".repeat(depth + 1);
+	let unionStart = Number.POSITIVE_INFINITY;
+	let unionEnd = 0;
+	let totalSelf = 0;
+	for (const span of loads) {
+		if (span.end === undefined) continue;
+		if (span.start < unionStart) unionStart = span.start;
+		if (span.end > unionEnd) unionEnd = span.end;
+		totalSelf += span.end - span.start;
+	}
+	const wall = unionEnd > unionStart ? unionEnd - unionStart : 0;
+	lines.push(`${childIndent}(modules): ${loads.length} loaded, wall ${fmtMs(wall)}, sum ${fmtMs(totalSelf)}`);
+	const showAll = process.env.PI_TIMING === "full";
+	const sorted = [...loads].sort((a, b) => durationOf(b) - durationOf(a));
+	const visible = showAll ? sorted : sorted.slice(0, MODULE_LOAD_VERBOSE_TOP);
+	for (const span of visible) {
+		const dur = durationOf(span);
+		if (dur < LOGGED_TIMING_THRESHOLD_MS) break;
+		const tag = isParallel(span) ? " [parallel]" : "";
+		lines.push(`${grandIndent}${span.op}: ${fmtMs(dur)}${tag}`);
+	}
+	if (!showAll && sorted.length > MODULE_LOAD_VERBOSE_TOP) {
+		lines.push(`${grandIndent}… ${sorted.length - MODULE_LOAD_VERBOSE_TOP} more (PI_TIMING=full to show all)`);
+	}
+}
+
+/** A span is parallel if it overlaps a sibling that started before it. */
+function isParallel(span: Span): boolean {
+	const parent = span.parent;
+	if (!parent || span.end === undefined) return false;
+	for (const sibling of parent.children) {
+		if (sibling === span || sibling.end === undefined || sibling.point) continue;
+		// Overlap test: A overlaps B iff A.start < B.end && B.start < A.end
+		if (sibling.start < span.end && span.start < sibling.end) return true;
+	}
+	return false;
+}
+
+/**
+ * Time a span. Three forms:
+ *   time(op)                    — point event (zero-duration breadcrumb)
+ *   time(op, fn, ...args)        — wrap fn in a span; returns fn's return value (sync or Promise)
+ *
+ * Spans nest hierarchically via AsyncLocalStorage: a child started inside another span's fn
+ * (even across awaits) becomes that span's child. Parallel children are recorded as siblings
+ * with overlapping intervals.
+ */
+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 (!gRecordTimings || !gRootSpan) {
+		if (fn === undefined) return undefined as T;
+		return fn(...args);
+	}
+
+	const parent = spanStorage.getStore() ?? gRootSpan;
+	const span: Span = { op, start: performance.now(), parent, children: [] };
+	parent.children.push(span);
+
+	if (fn === undefined) {
+		span.end = span.start;
+		span.point = true;
+		return undefined as T;
+	}
+
+	const finish = (): void => {
+		span.end = performance.now();
+	};
+	try {
+		const result = spanStorage.run(span, () => fn(...args));
+		if (result instanceof Promise) {
+			return result.finally(finish) as T;
+		}
+		finish();
+		return result;
+	} catch (error) {
+		finish();
+		throw error;
+	}
+}

package/src/mermaid-ascii.ts

@@ -0,0 +1,31 @@
+import { type AsciiRenderOptions, renderMermaidASCII } from "beautiful-mermaid";
+
+export type { AsciiRenderOptions as MermaidAsciiRenderOptions };
+
+export function renderMermaidAscii(source: string, options?: AsciiRenderOptions): string {
+	return renderMermaidASCII(source, options);
+}
+
+export function renderMermaidAsciiSafe(source: string, options?: AsciiRenderOptions): string | null {
+	try {
+		return renderMermaidASCII(source, options);
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Extract mermaid code blocks from markdown text.
+ */
+export function extractMermaidBlocks(markdown: string): { source: string; hash: bigint | number }[] {
+	const blocks: { source: string; hash: bigint | number }[] = [];
+	const regex = /```mermaid\s*\n([\s\S]*?)```/g;
+
+	for (let match = regex.exec(markdown); match !== null; match = regex.exec(markdown)) {
+		const source = match[1].trim();
+		const hash = Bun.hash(source);
+		blocks.push({ source, hash });
+	}
+
+	return blocks;
+}

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();
+	}
+}