@oh-my-pi/pi-utils 16.2.5 → 16.2.7

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [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
+
+- Added `stripWindowsExtendedLengthPathPrefix()` utility to normalize `\\?\` and native Win32 path prefixes before Bun import or spawn calls.
+
 ## [16.2.3] - 2026-06-28
 
 ### 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";
@@ -14,6 +15,7 @@ export * as logger from "./logger";
 export * from "./loop-phase";
 export * from "./mermaid-ascii";
 export * from "./mime";
+export * from "./path";
 export * from "./path-tree";
 export * from "./peek-file";
 export * as postmortem from "./postmortem";

package/dist/types/path.d.ts

@@ -0,0 +1,2 @@
+/** Removes Win32 extended-length prefixes before passing paths to Bun APIs. */
+export declare function stripWindowsExtendedLengthPathPrefix(filePath: string, platform?: NodeJS.Platform): string;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-utils",
-	"version": "16.2.5",
+	"version": "16.2.7",
 	"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.5",
+		"@oh-my-pi/pi-natives": "16.2.7",
 		"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";
@@ -14,6 +15,7 @@ export * as logger from "./logger";
 export * from "./loop-phase";
 export * from "./mermaid-ascii";
 export * from "./mime";
+export * from "./path";
 export * from "./path-tree";
 export * from "./peek-file";
 export * as postmortem from "./postmortem";

package/src/path.ts

@@ -0,0 +1,28 @@
+const WINDOWS_DRIVE_EXTENDED_PREFIX = /^\\\\[?]\\([A-Za-z]:[\\/].*)$/;
+const WINDOWS_UNC_EXTENDED_PREFIX = /^\\\\[?]\\UNC[\\/]([^\\/]+)[\\/](.+)$/i;
+const WINDOWS_DRIVE_EXTENDED_FORWARD_PREFIX = /^\/\/[?]\/([A-Za-z]:\/.*)$/;
+const WINDOWS_UNC_EXTENDED_FORWARD_PREFIX = /^\/\/[?]\/UNC\/([^/]+)\/(.+)$/i;
+const WINDOWS_DRIVE_NT_PREFIX = /^\\\\[?][?]\\([A-Za-z]:[\\/].*)$/;
+const WINDOWS_UNC_NT_PREFIX = /^\\\\[?][?]\\UNC[\\/]([^\\/]+)[\\/](.+)$/i;
+
+/** Removes Win32 extended-length prefixes before passing paths to Bun APIs. */
+export function stripWindowsExtendedLengthPathPrefix(
+	filePath: string,
+	platform: NodeJS.Platform = process.platform,
+): string {
+	if (platform !== "win32") return filePath;
+
+	const uncMatch = WINDOWS_UNC_EXTENDED_PREFIX.exec(filePath) ?? WINDOWS_UNC_NT_PREFIX.exec(filePath);
+	if (uncMatch) return `\\\\${uncMatch[1]}\\${uncMatch[2]}`;
+
+	const driveMatch = WINDOWS_DRIVE_EXTENDED_PREFIX.exec(filePath) ?? WINDOWS_DRIVE_NT_PREFIX.exec(filePath);
+	if (driveMatch) return driveMatch[1];
+
+	const forwardUncMatch = WINDOWS_UNC_EXTENDED_FORWARD_PREFIX.exec(filePath);
+	if (forwardUncMatch) return `//${forwardUncMatch[1]}/${forwardUncMatch[2]}`;
+
+	const forwardDriveMatch = WINDOWS_DRIVE_EXTENDED_FORWARD_PREFIX.exec(filePath);
+	if (forwardDriveMatch) return forwardDriveMatch[1];
+
+	return filePath;
+}

package/src/worker-host.ts

@@ -1,3 +1,5 @@
+import { stripWindowsExtendedLengthPathPrefix } from "./path";
+
 /**
  * Main-module path declared by self-dispatching CLI entrypoints — entries
  * whose top-level argv handling routes hidden `__omp_*` worker selectors.
@@ -10,7 +12,7 @@ let workerHostMain: string | null = null;
 
 /** Called by CLI entrypoints whose main module dispatches worker argv selectors. */
 export function declareWorkerHostEntry(): void {
-	workerHostMain = Bun.main;
+	workerHostMain = stripWindowsExtendedLengthPathPrefix(Bun.main);
 }
 
 /** Main-module path of the self-dispatching CLI host, or null outside it. */