@oh-my-pi/pi-utils 16.2.6 → 16.2.8

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [16.2.7] - 2026-06-30
+
+### Added
+
+- Added a utility to detect binary files based on content sniffing.
+
 ## [16.2.6] - 2026-06-29
 
 ### Added

package/dist/types/binary.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Classify an in-memory byte header as binary (non-UTF-8-text).
+ *
+ * Binary when the header contains a NUL byte (true binary, plus UTF-16/UTF-32
+ * text whose ASCII range is NUL-padded) or when it is not valid UTF-8. The
+ * decode runs in streaming mode so a multibyte sequence truncated at the header
+ * boundary is tolerated, while any genuinely invalid byte still fails — matching
+ * the strict `fatal` decode the `local://`/`ssh://` read paths already use.
+ */
+export declare function isProbablyBinaryHeader(header: Uint8Array): boolean;
+/**
+ * Sniff the first {@link BINARY_SNIFF_BYTES} of `filePath` and report whether it
+ * is binary (non-UTF-8-text). See {@link isProbablyBinaryHeader} for the rule.
+ */
+export declare function isProbablyBinary(filePath: string, maxBytes?: number): Promise<boolean>;
+/** Synchronous {@link isProbablyBinary}. */
+export declare function isProbablyBinarySync(filePath: string, maxBytes?: number): boolean;

package/dist/types/index.d.ts

@@ -1,5 +1,6 @@
 export { once, untilAborted } from "./abortable";
 export * from "./async";
+export * from "./binary";
 export * from "./color";
 export * from "./dirs";
 export * from "./env";

package/package.json

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

package/src/binary.ts

@@ -0,0 +1,50 @@
+/**
+ * Content-based binary/text classification for files that are about to be
+ * decoded as UTF-8 text and shown to a model or user.
+ *
+ * The read tool and `@file` auto-read both materialize file bytes as UTF-8
+ * strings. For a binary file (font, object, archive, packed blob) that decode
+ * is lossy: NUL bytes and invalid sequences survive as control characters and
+ * U+FFFD replacements, which corrupt terminal rendering and waste the context
+ * window with mojibake. Sniff the header first and refuse instead.
+ *
+ * @example
+ * if (await isProbablyBinary(path)) return "[binary file omitted]";
+ * const text = await Bun.file(path).text();
+ */
+import { peekFile, peekFileSync } from "./peek-file";
+
+/** Header window sniffed for the binary heuristic; mirrors git's 8000-byte scan. */
+const BINARY_SNIFF_BYTES = 8192;
+
+/**
+ * Classify an in-memory byte header as binary (non-UTF-8-text).
+ *
+ * Binary when the header contains a NUL byte (true binary, plus UTF-16/UTF-32
+ * text whose ASCII range is NUL-padded) or when it is not valid UTF-8. The
+ * decode runs in streaming mode so a multibyte sequence truncated at the header
+ * boundary is tolerated, while any genuinely invalid byte still fails — matching
+ * the strict `fatal` decode the `local://`/`ssh://` read paths already use.
+ */
+export function isProbablyBinaryHeader(header: Uint8Array): boolean {
+	if (header.indexOf(0) !== -1) return true;
+	try {
+		new TextDecoder("utf-8", { fatal: true }).decode(header, { stream: true });
+		return false;
+	} catch {
+		return true;
+	}
+}
+
+/**
+ * Sniff the first {@link BINARY_SNIFF_BYTES} of `filePath` and report whether it
+ * is binary (non-UTF-8-text). See {@link isProbablyBinaryHeader} for the rule.
+ */
+export function isProbablyBinary(filePath: string, maxBytes = BINARY_SNIFF_BYTES): Promise<boolean> {
+	return peekFile(filePath, maxBytes, isProbablyBinaryHeader);
+}
+
+/** Synchronous {@link isProbablyBinary}. */
+export function isProbablyBinarySync(filePath: string, maxBytes = BINARY_SNIFF_BYTES): boolean {
+	return peekFileSync(filePath, maxBytes, isProbablyBinaryHeader);
+}

package/src/index.ts

@@ -1,5 +1,6 @@
 export { once, untilAborted } from "./abortable";
 export * from "./async";
+export * from "./binary";
 export * from "./color";
 export * from "./dirs";
 export * from "./env";