@oh-my-pi/pi-utils 15.8.3 → 15.9.1

package/dist/types/color.d.ts

@@ -5,9 +5,7 @@
  * ```ts
  * import { hexToHsv, hsvToHex } from "@oh-my-pi/pi-utils";
  *
- * // Work with HSV directly
- *
- * // Or work with HSV directly
+ * // Rotate the hue by 90°
  * const hsv = hexToHsv("#4ade80");
  * hsv.h = (hsv.h + 90) % 360;
  * const newHex = hsvToHex(hsv);
@@ -80,3 +78,25 @@ export interface HSVAdjustment {
  * ```
  */
 export declare function adjustHsv(hex: string, adj: HSVAdjustment): string;
+/**
+ * Convert HSL (h: 0-360, s: 0-1, l: 0-1) to a CSS hex string.
+ */
+export declare function hslToHex(h: number, s: number, l: number): string;
+/**
+ * Perceptual luma (gamma-encoded BT.709 weights over raw sRGB), normalized to 0..1.
+ *
+ * Accepts a hex string (`#rgb` / `#rrggbb`) or a 256-color palette index; returns
+ * `undefined` for var refs, empty strings, or anything unparseable.
+ *
+ * Cheap and good enough for a light/dark *classification* threshold. NOT suitable
+ * for contrast ratios — use {@link relativeLuminance} for those.
+ */
+export declare function colorLuma(value: string | number): number | undefined;
+/**
+ * WCAG 2.x relative luminance (BT.709 weights over linearized sRGB), normalized to
+ * 0..1. This is the value the WCAG contrast-ratio formula expects.
+ *
+ * Accepts a hex string (`#rgb` / `#rrggbb`) or a 256-color palette index; returns
+ * `undefined` for var refs, empty strings, or anything unparseable.
+ */
+export declare function relativeLuminance(value: string | number): number | undefined;

package/dist/types/peek-file.d.ts

@@ -7,3 +7,23 @@ export declare function peekFileSync<T>(filePath: string, maxBytes: number, op:
  * Like {@link peekFileSync} but uses async I/O.
  */
 export declare function peekFile<T>(filePath: string, maxBytes: number, op: (header: Uint8Array) => T): Promise<T>;
+/**
+ * Read up to the last `maxBytes` of `filePath` and pass that slice to `op`.
+ *
+ * The tail mirror of {@link peekFile}: same pooled-buffer strategy (no per-call
+ * allocation for small reads), but the read is positioned at `size - len` so the
+ * window ends at EOF. When the file is shorter than `maxBytes`, the whole file is
+ * returned. A multi-byte codepoint straddling the leading cut decodes to a
+ * replacement char — callers that parse line-oriented tails drop the partial
+ * leading line anyway.
+ */
+export declare function peekFileTail<T>(filePath: string, maxBytes: number, op: (tail: Uint8Array) => T): Promise<T>;
+/**
+ * Read up to the first `prefixBytes` and last `suffixBytes` of `filePath`, then
+ * pass both slices to `op`.
+ *
+ * Uses a single open/stat sequence. When the whole file fits in the head window,
+ * the tail is sliced from the already-read head bytes instead of issuing a
+ * second read.
+ */
+export declare function peekFileEnds<T>(filePath: string, prefixBytes: number, suffixBytes: number, op: (head: Uint8Array, tail: Uint8Array) => T): Promise<T>;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-utils",
-	"version": "15.8.3",
+	"version": "15.9.1",
 	"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": "15.8.3",
+		"@oh-my-pi/pi-natives": "15.9.1",
 		"beautiful-mermaid": "^1.1.3",
 		"handlebars": "^4.7.9",
 		"winston": "^3.19.0",

package/src/color.ts

@@ -5,9 +5,7 @@
  * ```ts
  * import { hexToHsv, hsvToHex } from "@oh-my-pi/pi-utils";
  *
- * // Work with HSV directly
- *
- * // Or work with HSV directly
+ * // Rotate the hue by 90°
  * const hsv = hexToHsv("#4ade80");
  * hsv.h = (hsv.h + 90) % 360;
  * const newHex = hsvToHex(hsv);
@@ -202,3 +200,103 @@ export function adjustHsv(hex: string, adj: HSVAdjustment): string {
 	}
 	return hsvToHex(hsv);
 }
+
+/**
+ * Convert HSL (h: 0-360, s: 0-1, l: 0-1) to a CSS hex string.
+ */
+export function hslToHex(h: number, s: number, l: number): string {
+	const a = s * Math.min(l, 1 - l);
+	const f = (n: number) => {
+		const k = (n + h / 30) % 12;
+		const color = l - a * Math.max(Math.min(k - 3, 9 - k, 1), -1);
+		return Math.round(255 * color)
+			.toString(16)
+			.padStart(2, "0");
+	};
+	return `#${f(0)}${f(8)}${f(4)}`;
+}
+
+// Conventional xterm RGB for the 16 base ANSI colors. Terminals may remap these,
+// so they're a best-effort approximation for light/dark classification.
+const ANSI_16: readonly (readonly [number, number, number])[] = [
+	[0, 0, 0],
+	[128, 0, 0],
+	[0, 128, 0],
+	[128, 128, 0],
+	[0, 0, 128],
+	[128, 0, 128],
+	[0, 128, 128],
+	[192, 192, 192],
+	[128, 128, 128],
+	[255, 0, 0],
+	[0, 255, 0],
+	[255, 255, 0],
+	[0, 0, 255],
+	[255, 0, 255],
+	[0, 255, 255],
+	[255, 255, 255],
+];
+const CUBE_STEPS = [0, 95, 135, 175, 215, 255] as const;
+
+/** Parse a 256-color palette index (0–255) to RGB (0..255). */
+function paletteToRgb(index: number): RGB | undefined {
+	if (!Number.isInteger(index) || index < 0 || index > 255) return undefined;
+	if (index < 16) {
+		const rgb = ANSI_16[index];
+		return rgb ? { r: rgb[0], g: rgb[1], b: rgb[2] } : undefined;
+	}
+	if (index < 232) {
+		const n = index - 16;
+		return {
+			r: CUBE_STEPS[Math.floor(n / 36) % 6] ?? 0,
+			g: CUBE_STEPS[Math.floor(n / 6) % 6] ?? 0,
+			b: CUBE_STEPS[n % 6] ?? 0,
+		};
+	}
+	const gray = 8 + (index - 232) * 10;
+	return { r: gray, g: gray, b: gray };
+}
+
+/** Parse a theme color value — `#rgb`/`#rrggbb` hex or 256-color palette index — to RGB (0..255). */
+function toRgb(value: string | number): RGB | undefined {
+	if (typeof value === "number") return paletteToRgb(value);
+	if (typeof value !== "string" || value[0] !== "#") return undefined;
+	if (value.length !== 4 && value.length !== 7) return undefined;
+	const rgb = hexToRgb(value);
+	if (Number.isNaN(rgb.r) || Number.isNaN(rgb.g) || Number.isNaN(rgb.b)) return undefined;
+	return rgb;
+}
+
+/** Gamma-decode a single 0..255 sRGB channel to linear 0..1. */
+function linearizeChannel(channel: number): number {
+	const c = channel / 255;
+	return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+
+/**
+ * Perceptual luma (gamma-encoded BT.709 weights over raw sRGB), normalized to 0..1.
+ *
+ * Accepts a hex string (`#rgb` / `#rrggbb`) or a 256-color palette index; returns
+ * `undefined` for var refs, empty strings, or anything unparseable.
+ *
+ * Cheap and good enough for a light/dark *classification* threshold. NOT suitable
+ * for contrast ratios — use {@link relativeLuminance} for those.
+ */
+export function colorLuma(value: string | number): number | undefined {
+	const rgb = toRgb(value);
+	if (!rgb) return undefined;
+	return (0.2126 * rgb.r + 0.7152 * rgb.g + 0.0722 * rgb.b) / 255;
+}
+
+/**
+ * WCAG 2.x relative luminance (BT.709 weights over linearized sRGB), normalized to
+ * 0..1. This is the value the WCAG contrast-ratio formula expects.
+ *
+ * Accepts a hex string (`#rgb` / `#rrggbb`) or a 256-color palette index; returns
+ * `undefined` for var refs, empty strings, or anything unparseable.
+ */
+export function relativeLuminance(value: string | number): number | undefined {
+	const rgb = toRgb(value);
+	if (!rgb) return undefined;
+	return 0.2126 * linearizeChannel(rgb.r) + 0.7152 * linearizeChannel(rgb.g) + 0.0722 * linearizeChannel(rgb.b);
+}

package/src/peek-file.ts

@@ -112,3 +112,77 @@ export async function peekFile<T>(filePath: string, maxBytes: number, op: (heade
 		await fileHandle.close();
 	}
 }
+
+/**
+ * Read up to the last `maxBytes` of `filePath` and pass that slice to `op`.
+ *
+ * The tail mirror of {@link peekFile}: same pooled-buffer strategy (no per-call
+ * allocation for small reads), but the read is positioned at `size - len` so the
+ * window ends at EOF. When the file is shorter than `maxBytes`, the whole file is
+ * returned. A multi-byte codepoint straddling the leading cut decodes to a
+ * replacement char — callers that parse line-oriented tails drop the partial
+ * leading line anyway.
+ */
+export async function peekFileTail<T>(filePath: string, maxBytes: number, op: (tail: Uint8Array) => T): Promise<T> {
+	if (maxBytes <= 0) {
+		return op(EMPTY_BUFFER);
+	}
+
+	const fileHandle = await fs.promises.open(filePath, "r");
+	try {
+		const { size } = await fileHandle.stat();
+		const len = Math.min(maxBytes, size);
+		if (len <= 0) {
+			return op(EMPTY_BUFFER);
+		}
+		return await withAsyncPoolBuffer(len, async buffer => {
+			const { bytesRead } = await fileHandle.read(buffer, 0, buffer.byteLength, size - len);
+			return op(buffer.subarray(0, bytesRead));
+		});
+	} finally {
+		await fileHandle.close();
+	}
+}
+
+/**
+ * Read up to the first `prefixBytes` and last `suffixBytes` of `filePath`, then
+ * pass both slices to `op`.
+ *
+ * Uses a single open/stat sequence. When the whole file fits in the head window,
+ * the tail is sliced from the already-read head bytes instead of issuing a
+ * second read.
+ */
+export async function peekFileEnds<T>(
+	filePath: string,
+	prefixBytes: number,
+	suffixBytes: number,
+	op: (head: Uint8Array, tail: Uint8Array) => T,
+): Promise<T> {
+	if (prefixBytes <= 0 && suffixBytes <= 0) {
+		return op(EMPTY_BUFFER, EMPTY_BUFFER);
+	}
+
+	const fileHandle = await fs.promises.open(filePath, "r");
+	try {
+		const { size } = await fileHandle.stat();
+		const headLen = prefixBytes > 0 ? Math.min(prefixBytes, size) : 0;
+		const tailLen = suffixBytes > 0 ? Math.min(suffixBytes, size) : 0;
+
+		const head = headLen > 0 ? Buffer.allocUnsafe(headLen) : EMPTY_BUFFER;
+		const headBytesRead = headLen > 0 ? (await fileHandle.read(head, 0, head.byteLength, 0)).bytesRead : 0;
+		const headSlice = head.subarray(0, headBytesRead);
+
+		if (tailLen <= 0) {
+			return op(headSlice, EMPTY_BUFFER);
+		}
+		if (size <= headLen) {
+			return op(headSlice, headSlice.subarray(Math.max(0, headBytesRead - tailLen)));
+		}
+
+		const tail = Buffer.allocUnsafe(tailLen);
+		const { bytesRead: tailBytesRead } = await fileHandle.read(tail, 0, tail.byteLength, size - tailLen);
+		return op(headSlice, tail.subarray(0, tailBytesRead));
+	} finally {
+		await fileHandle.close();
+	}
+}

package/src/tab-spacing.ts

@@ -4,17 +4,25 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { isEnoent } from "./fs-error";
+import { isFsError } from "./fs-error";
 
 export const MIN_TAB_WIDTH = 1;
 export const MAX_TAB_WIDTH = 16;
 export const DEFAULT_TAB_WIDTH = 3;
 
+/**
+ * Per-component path length cap on common filesystems (`NAME_MAX = 255` on
+ * Linux ext4 / macOS APFS / Windows NTFS). Paths with components longer than
+ * this cannot be opened at all, so editorconfig discovery short-circuits to
+ * the default instead of running into `ENAMETOOLONG` from `readFileSync`.
+ */
+const NAME_MAX_BYTES = 255;
+
 const EDITORCONFIG_NAME = ".editorconfig";
 
 let defaultTabWidth = DEFAULT_TAB_WIDTH;
 
-const editorConfigCache = new Map<string, ParsedEditorConfig>();
+const editorConfigCache = new Map<string, ParsedEditorConfig | null>();
 const editorConfigChainCache = new Map<string, ChainEntry[]>();
 const indentationCache = new Map<string, number>();
 
@@ -145,14 +153,18 @@ function parseCachedEditorConfig(configPath: string): ParsedEditorConfig | undef
 	const key = path.resolve(configPath);
 	const hit = editorConfigCache.get(key);
 	if (hit !== undefined) {
-		return hit;
+		return hit ?? undefined;
 	}
 
 	let content: string;
 	try {
 		content = fs.readFileSync(key, "utf8");
 	} catch (err) {
-		if (isEnoent(err)) return undefined;
+		// editorconfig discovery is best-effort. Any filesystem error
+		// (`ENOENT`, `ENAMETOOLONG`, `ENOTDIR`, `EACCES`, `ELOOP`, `EINVAL`,
+		// …) means "no usable config at this path" — never a fatal condition
+		// for callers like the edit renderer that hand us arbitrary strings.
+		if (isFsError(err)) return undefined;
 		throw err;
 	}
 	const parsed = parseEditorConfigFile(content);
@@ -279,6 +291,15 @@ function resolveEditorConfigTabWidth(match: EditorConfigMatch | undefined, fallb
 	return undefined;
 }
 
+function hasOverlongPathComponent(filePath: string): boolean {
+	for (const part of filePath.split(/[\\/]/)) {
+		if (part.length > 0 && Buffer.byteLength(part) > NAME_MAX_BYTES) {
+			return true;
+		}
+	}
+	return false;
+}
+
 export function getDefaultTabWidth(): number {
 	return defaultTabWidth;
 }
@@ -298,6 +319,15 @@ export function getIndentation(file?: string | null, projectDir?: string | null)
 
 	const cwd = projectDir ?? process.cwd();
 	const absoluteFile = resolveFilePath(cwd, file);
+
+	// Renderers can hand us arbitrary strings (e.g. a malformed edit tool
+	// call whose `file_path` is gibberish). Reject paths whose normalized
+	// absolute form still has any component longer than `NAME_MAX_BYTES` —
+	// the editorconfig chain would only trip `ENAMETOOLONG` from
+	// `readFileSync` and escape.
+	if (hasOverlongPathComponent(absoluteFile)) {
+		return fallback;
+	}
 	const absKey = absoluteFile;
 	const cached = indentationCache.get(absKey);
 	if (cached !== undefined) {