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

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.0",
 	"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.0",
 		"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();
+	}
+}