@oh-my-pi/pi-utils 17.2.9 → 17.2.10

package/src/headers.ts

@@ -0,0 +1,167 @@
+/** Behavior-compatible reimplementation of header-generator's used surface. */
+
+/** A browser family supported by the curated header profiles. */
+export type BrowserName = "chrome" | "firefox" | "safari";
+
+/** A desktop operating system supported by the curated header profiles. */
+export type OperatingSystem = "windows" | "macos" | "linux";
+
+/** Constructor and per-call constraints for header generation. */
+export interface HeaderGeneratorOptions {
+	/** Browser families eligible for a draw. */
+	browsers: BrowserName[];
+	/** Browser selection query; the supported `last 3 versions` query uses the curated versions. */
+	browserListQuery: string;
+	/** Desktop operating systems eligible for a draw. */
+	operatingSystems: OperatingSystem[];
+	/** Device classes eligible for a draw. */
+	devices: "desktop"[];
+	/** Ordered locales for the Accept-Language value. */
+	locales: string[];
+	/** HTTP protocol generation mode. */
+	httpVersion: "1" | "2";
+	/** Whether impossible constraints throw instead of relaxing to a coherent profile. */
+	strict: boolean;
+	/** Random source returning a value in the range from zero (inclusive) to one (exclusive). */
+	rng: () => number;
+}
+
+/** A generated HTTP request header map. */
+export type Headers = Record<string, string>;
+
+type ResolvedOptions = Omit<HeaderGeneratorOptions, "rng">;
+
+type BrowserProfile = {
+	browser: BrowserName;
+	operatingSystem: OperatingSystem;
+	version: number;
+	userAgent: string;
+};
+
+const DEFAULT_OPTIONS: ResolvedOptions = {
+	browsers: ["chrome", "firefox", "safari"],
+	browserListQuery: "",
+	operatingSystems: ["windows", "macos", "linux"],
+	devices: ["desktop"],
+	locales: ["en-US", "en"],
+	httpVersion: "2",
+	strict: false,
+};
+
+const VERSIONS: Readonly<Record<BrowserName, readonly number[]>> = {
+	chrome: [149, 150, 151],
+	firefox: [147, 148, 149],
+	safari: [26, 26.1, 26.2],
+};
+
+function pick<T>(values: readonly T[], rng: () => number): T {
+	const random = rng();
+	const index = Math.min(values.length - 1, Math.max(0, Math.floor(random * values.length)));
+	const value = values[index];
+	if (value === undefined) throw new Error("Cannot choose from an empty header profile list");
+	return value;
+}
+
+function formatLocales(locales: readonly string[]): string {
+	return locales
+		.slice(0, 10)
+		.map((locale, index) => {
+			if (index === 0) return locale;
+			const quality = Math.max(0.1, 1 - index / 10).toFixed(1);
+			return `${locale};q=${quality}`;
+		})
+		.join(",");
+}
+
+function makeUserAgent(browser: BrowserName, operatingSystem: OperatingSystem, version: number): string {
+	if (browser === "safari") {
+		return `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/${version.toFixed(1)} Safari/605.1.15`;
+	}
+
+	const platform =
+		operatingSystem === "windows"
+			? "Windows NT 10.0; Win64; x64"
+			: operatingSystem === "macos"
+				? "Macintosh; Intel Mac OS X 10_15_7"
+				: "X11; Linux x86_64";
+	if (browser === "firefox") {
+		return `Mozilla/5.0 (${platform}; rv:${version}.0) Gecko/20100101 Firefox/${version}.0`;
+	}
+	return `Mozilla/5.0 (${platform}) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${version}.0.0.0 Safari/537.36`;
+}
+
+function makeProfile(options: ResolvedOptions, rng: () => number): BrowserProfile {
+	const candidates: Array<{ browser: BrowserName; operatingSystem: OperatingSystem }> = [];
+	for (const browser of options.browsers) {
+		for (const operatingSystem of options.operatingSystems) {
+			if (browser === "safari" && operatingSystem !== "macos") continue;
+			candidates.push({ browser, operatingSystem });
+		}
+	}
+
+	if (candidates.length === 0) {
+		if (options.strict) throw new Error("No coherent browser profile matches the requested options");
+		candidates.push({ browser: "chrome", operatingSystem: "windows" });
+	}
+
+	const candidate = pick(candidates, rng);
+	const version = pick(VERSIONS[candidate.browser], rng);
+	return {
+		...candidate,
+		version,
+		userAgent: makeUserAgent(candidate.browser, candidate.operatingSystem, version),
+	};
+}
+
+/** Generates coherent modern desktop browser navigation headers. */
+export class HeaderGenerator {
+	#options: ResolvedOptions;
+	#rng: () => number;
+
+	/** Creates a generator with reusable constraints and an optionally injectable RNG. */
+	constructor(options: Partial<HeaderGeneratorOptions> = {}) {
+		this.#rng = options.rng ?? Math.random;
+		this.#options = { ...DEFAULT_OPTIONS, ...options };
+		if (this.#options.devices.some(device => device !== "desktop") && this.#options.strict) {
+			throw new Error("Only desktop browser profiles are available");
+		}
+		if (this.#options.locales.length === 0 && this.#options.strict) {
+			throw new Error("At least one locale is required");
+		}
+	}
+
+	/** Generates one header set, applying per-call constraints and request overrides. */
+	getHeaders(options: Partial<HeaderGeneratorOptions> = {}, overrides: Headers = {}): Headers {
+		const resolved = { ...this.#options, ...options };
+		const rng = options.rng ?? this.#rng;
+		const profile = makeProfile(resolved, rng);
+		const headers: Headers = {
+			accept:
+				profile.browser === "chrome"
+					? "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7"
+					: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+			"user-agent": profile.userAgent,
+			"accept-encoding": profile.browser === "safari" ? "gzip, deflate, br" : "gzip, deflate, br, zstd",
+			"accept-language": formatLocales(resolved.locales.length > 0 ? resolved.locales : DEFAULT_OPTIONS.locales),
+			"upgrade-insecure-requests": "1",
+			"sec-fetch-dest": "document",
+			"sec-fetch-mode": "navigate",
+			"sec-fetch-site": "none",
+			"sec-fetch-user": "?1",
+		};
+
+		if (profile.browser === "chrome") {
+			headers["sec-ch-ua"] =
+				`"Google Chrome";v="${profile.version}", "Chromium";v="${profile.version}", "Not_A Brand";v="24"`;
+			headers["sec-ch-ua-mobile"] = "?0";
+			headers["sec-ch-ua-platform"] =
+				profile.operatingSystem === "windows"
+					? '"Windows"'
+					: profile.operatingSystem === "macos"
+						? '"macOS"'
+						: '"Linux"';
+		}
+
+		return { ...headers, ...overrides };
+	}
+}

package/src/logger/rotating-file.ts

@@ -0,0 +1,149 @@
+/** Behavior-compatible reimplementation of winston-daily-rotate-file's used surface. */
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+interface AuditEntry {
+	readonly date: number;
+	readonly name: string;
+	readonly hash: string;
+}
+
+interface AuditState {
+	readonly keep: { readonly days: false; readonly amount: number };
+	readonly auditLog: string;
+	readonly files: AuditEntry[];
+	readonly hashType: "sha256";
+}
+
+/** Configuration for a process-local rotating file sink. */
+export interface RotatingFileOptions {
+	readonly directory: string;
+	readonly filenamePrefix: string;
+	readonly filenameSuffix: string;
+	readonly auditFile: string;
+	readonly maxBytes: number;
+	readonly maxFiles: number;
+}
+
+function isAuditEntry(value: unknown): value is AuditEntry {
+	if (value === null || typeof value !== "object") return false;
+	const entry = value as Record<string, unknown>;
+	return typeof entry.date === "number" && typeof entry.name === "string" && typeof entry.hash === "string";
+}
+
+/** Synchronous append sink with local-day and size rotation plus bounded retention. */
+export class RotatingFileSink {
+	readonly #directory: string;
+	readonly #filenamePrefix: string;
+	readonly #filenameSuffix: string;
+	readonly #auditFile: string;
+	readonly #maxBytes: number;
+	readonly #maxFiles: number;
+	#files: AuditEntry[];
+	#activeDay: string | undefined;
+	#activeIndex = 0;
+	#activePath: string | undefined;
+	#activeBytes = 0;
+	#closed = false;
+
+	constructor(options: RotatingFileOptions) {
+		this.#directory = options.directory;
+		this.#filenamePrefix = options.filenamePrefix;
+		this.#filenameSuffix = options.filenameSuffix;
+		this.#auditFile = options.auditFile;
+		this.#maxBytes = options.maxBytes;
+		this.#maxFiles = options.maxFiles;
+		this.#files = this.#readAudit();
+		const now = new Date();
+		this.#selectFile(this.#localDay(now));
+		const activePath = this.#activePath;
+		if (activePath) {
+			this.#registerFile(activePath, now.getTime());
+			fs.closeSync(fs.openSync(activePath, "a"));
+		}
+	}
+
+	/** Append one already-formatted log record. */
+	write(line: string): void {
+		if (this.#closed) return;
+		const now = new Date();
+		this.#selectFile(this.#localDay(now));
+		const activePath = this.#activePath;
+		if (!activePath) return;
+		this.#registerFile(activePath, now.getTime());
+		const record = `${line}${os.EOL}`;
+		fs.appendFileSync(activePath, record, "utf8");
+		this.#activeBytes += Buffer.byteLength(record);
+	}
+
+	/** Stop accepting records. Synchronous writes require no drain phase. */
+	close(): void {
+		this.#closed = true;
+	}
+
+	#localDay(date: Date): string {
+		return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}`;
+	}
+
+	#selectFile(day: string): void {
+		if (day !== this.#activeDay) {
+			this.#activeDay = day;
+			this.#activeIndex = 0;
+			this.#setActivePath(day, 0);
+		}
+		while (this.#activeBytes > this.#maxBytes) {
+			this.#activeIndex++;
+			this.#setActivePath(day, this.#activeIndex);
+		}
+	}
+
+	#setActivePath(day: string, index: number): void {
+		const suffix = index === 0 ? "" : `.${index}`;
+		this.#activePath = path.join(
+			this.#directory,
+			`${this.#filenamePrefix}.${day}.${this.#filenameSuffix}.log${suffix}`,
+		);
+		try {
+			this.#activeBytes = fs.statSync(this.#activePath).size;
+		} catch {
+			this.#activeBytes = 0;
+		}
+	}
+
+	#registerFile(filePath: string, date: number): void {
+		if (this.#files.some(file => file.name === filePath)) return;
+		const hash = crypto.createHash("sha256").update(`${filePath}LOG_FILE${date}`).digest("hex");
+		this.#files.push({ date, name: filePath, hash });
+		while (this.#files.length > this.#maxFiles) {
+			const removed = this.#files.shift();
+			if (!removed) break;
+			try {
+				fs.rmSync(removed.name, { force: true });
+			} catch {
+				// Retention is best-effort; the current record must still be written.
+			}
+		}
+		this.#writeAudit();
+	}
+
+	#readAudit(): AuditEntry[] {
+		try {
+			const parsed = JSON.parse(fs.readFileSync(this.#auditFile, "utf8")) as { files?: unknown };
+			return Array.isArray(parsed.files) ? parsed.files.filter(isAuditEntry) : [];
+		} catch {
+			return [];
+		}
+	}
+
+	#writeAudit(): void {
+		const state: AuditState = {
+			keep: { days: false, amount: this.#maxFiles },
+			auditLog: this.#auditFile,
+			files: this.#files,
+			hashType: "sha256",
+		};
+		fs.writeFileSync(this.#auditFile, JSON.stringify(state, undefined, 4), "utf8");
+	}
+}

package/src/logger.ts

@@ -1,5 +1,3 @@
-/// <reference path="./winston-daily-rotate-file.d.ts" />
-
 /**
  * Centralized logger for omp.
  *
@@ -16,11 +14,8 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { isPromise } from "node:util/types";
-import type DailyRotateFile from "winston-daily-rotate-file";
-// Import the implementation directly because the package index imports and mutates
-// Winston. The exact workspace catalog pin protects this internal entrypoint.
-import DailyRotateFileImplementation from "winston-daily-rotate-file/daily-rotate-file.js";
 import { getLogsDir } from "./dirs";
+import { RotatingFileSink } from "./logger/rotating-file";
 import { drainModuleLoadEvents } from "./timing-buffer";
 /** Severity names accepted by the centralized logger. */
 export type LogLevel = "error" | "warn" | "info" | "debug";
@@ -200,24 +195,18 @@ function formatLogInfo(info: NormalizedLogInfo): string {
 	return JSON.stringify(entry, jsonReplacer) as string;
 }
 
-type FileTransport = DailyRotateFile & {
-	log(info: Record<symbol, string>, callback: () => void): void;
-	close(): void;
-};
-
-/** Build a rotating file transport with process-local rotation and shared retention. */
-function makeFileTransport(dir?: string): FileTransport {
+/** Build a rotating file sink with process-local rotation and shared retention. */
+function makeFileTransport(dir?: string): RotatingFileSink {
 	const logsDir = ensureDir(dir ?? getLogsDir());
 	pruneStaleProcessLogs(logsDir);
-	return new DailyRotateFileImplementation({
-		dirname: logsDir,
-		filename: `omp.%DATE%.${process.pid}.log`,
-		datePattern: "YYYY-MM-DD",
-		maxSize: "10m",
+	return new RotatingFileSink({
+		directory: logsDir,
+		filenamePrefix: "omp",
+		filenameSuffix: String(process.pid),
+		maxBytes: 10 * 1024 * 1024,
 		maxFiles: 5,
-		zippedArchive: false,
 		auditFile: path.join(logsDir, `.omp.${process.pid}-audit.json`),
-	}) as FileTransport;
+	});
 }
 
 /**
@@ -227,16 +216,13 @@ function makeFileTransport(dir?: string): FileTransport {
 let transportOpts: { console?: boolean; file?: boolean | string } = { file: true };
 
 interface LocalTransports {
-	readonly file: FileTransport | undefined;
+	readonly file: RotatingFileSink | undefined;
 	readonly console: boolean;
 }
 
 /** Local transports, constructed lazily on first log emission. */
 let activeTransports: LocalTransports | undefined;
 
-const TRANSPORT_MESSAGE = Symbol.for("message");
-const onTransportLogged = (): void => {};
-
 function buildTransports(opts: { console?: boolean; file?: boolean | string }): LocalTransports {
 	return {
 		file: opts.file ? makeFileTransport(typeof opts.file === "string" ? opts.file : undefined) : undefined,
@@ -254,11 +240,9 @@ function emitLocally(level: LogLevel, message: string, context: Record<string, u
 	const info = normalizeLogInfo(level, message, context);
 	if (!transports.file && !transports.console) return;
 
-	// Winston applied the shared format before dispatch, then the same format a
-	// second time inside Console. Keep those evaluation and timestamp semantics.
 	const line = formatLogInfo(info);
-	if (transports.file) transports.file.log({ [TRANSPORT_MESSAGE]: line }, onTransportLogged);
-	if (transports.console) process.stdout.write(`${formatLogInfo(info)}${os.EOL}`);
+	if (transports.file) transports.file.write(line);
+	if (transports.console) fs.writeSync(1, `${formatLogInfo(info)}${os.EOL}`);
 }
 
 /**

package/src/lru.ts

@@ -0,0 +1,185 @@
+/** Behavior-compatible reimplementation of lru-cache's used surface. */
+
+/** Why an entry left the cache. */
+export type DisposeReason = "evict" | "set" | "delete" | "expire";
+
+/** Options supported by {@link LRUCache}. */
+export interface LRUCacheOptions<K, V> {
+	/** Maximum number of retained entries. */
+	max?: number;
+	/** Maximum aggregate calculated size. */
+	maxSize?: number;
+	/** Maximum calculated size of one entry. */
+	maxEntrySize?: number;
+	/** Calculates an entry's size. */
+	sizeCalculation?: (value: V, key: K) => number;
+	/** Entry lifetime in milliseconds; zero disables expiry. */
+	ttl?: number;
+	/** Refreshes an entry's lifetime when it is read. */
+	updateAgeOnGet?: boolean;
+	/** Called synchronously before an entry is removed. */
+	dispose?: (value: V, key: K, reason: DisposeReason) => void;
+}
+
+interface Entry<V> {
+	value: V;
+	size: number;
+	start: number;
+}
+
+function positiveInteger(value: number | undefined, name: string): number {
+	if (value === undefined) return 0;
+	if (!Number.isInteger(value) || value < 0) throw new TypeError(`${name} must be a non-negative integer`);
+	return value;
+}
+
+/** A bounded least-recently-used cache with optional size and lifetime limits. */
+export class LRUCache<K, V> {
+	readonly #entries = new Map<K, Entry<V>>();
+	readonly #max: number;
+	readonly #maxSize: number;
+	readonly #maxEntrySize: number;
+	readonly #sizeCalculation: ((value: V, key: K) => number) | undefined;
+	readonly #ttl: number;
+	readonly #updateAgeOnGet: boolean;
+	readonly #dispose: ((value: V, key: K, reason: DisposeReason) => void) | undefined;
+	#calculatedSize = 0;
+
+	/** Creates an empty cache. */
+	constructor(options: LRUCacheOptions<K, V>) {
+		this.#max = positiveInteger(options.max, "max");
+		this.#maxSize = positiveInteger(options.maxSize, "maxSize");
+		const explicitMaxEntrySize = positiveInteger(options.maxEntrySize, "maxEntrySize");
+		this.#maxEntrySize = explicitMaxEntrySize || this.#maxSize;
+		this.#ttl = positiveInteger(options.ttl, "ttl");
+		if (this.#max === 0 && this.#maxSize === 0 && this.#ttl === 0) {
+			throw new TypeError("At least one of max, maxSize, or ttl is required");
+		}
+		if ((this.#maxSize !== 0 || this.#maxEntrySize !== 0) && options.sizeCalculation === undefined) {
+			throw new TypeError("sizeCalculation is required when a size limit is set");
+		}
+		this.#sizeCalculation = options.sizeCalculation;
+		this.#updateAgeOnGet = options.updateAgeOnGet === true;
+		this.#dispose = options.dispose;
+	}
+
+	/** Number of entries, including stale entries not yet removed by `get`. */
+	get size(): number {
+		return this.#entries.size;
+	}
+
+	/** Aggregate calculated size of retained entries. */
+	get calculatedSize(): number {
+		return this.#calculatedSize;
+	}
+
+	/** Stores a value and makes it most recently used. */
+	set(key: K, value: V | undefined): this {
+		if (value === undefined) {
+			this.delete(key);
+			return this;
+		}
+
+		const size = this.#entrySize(value, key);
+		const previous = this.#entries.get(key);
+		if (this.#maxEntrySize !== 0 && size > this.#maxEntrySize) {
+			if (previous !== undefined) this.#remove(key, previous, "set");
+			return this;
+		}
+
+		if (previous !== undefined) {
+			if (previous.value !== value) this.#dispose?.(previous.value, key, "set");
+			this.#calculatedSize -= previous.size;
+			this.#entries.delete(key);
+		}
+
+		while (
+			(this.#max !== 0 && this.#entries.size >= this.#max) ||
+			(this.#maxSize !== 0 && this.#calculatedSize + size > this.#maxSize)
+		) {
+			const oldest = this.#entries.entries().next().value as [K, Entry<V>] | undefined;
+			if (oldest === undefined) break;
+			this.#remove(oldest[0], oldest[1], "evict");
+		}
+		this.#entries.set(key, { value, size, start: this.#ttl === 0 ? 0 : performance.now() });
+		this.#calculatedSize += size;
+		return this;
+	}
+
+	/** Returns a value and makes a fresh entry most recently used. */
+	get(key: K): V | undefined {
+		const entry = this.#entries.get(key);
+		if (entry === undefined) return undefined;
+		if (this.#isStale(entry)) {
+			this.#remove(key, entry, "expire");
+			return undefined;
+		}
+		if (this.#updateAgeOnGet && this.#ttl !== 0) entry.start = performance.now();
+		this.#entries.delete(key);
+		this.#entries.set(key, entry);
+		return entry.value;
+	}
+
+	/** Reports whether a fresh value is present without changing recency. */
+	has(key: K): boolean {
+		const entry = this.#entries.get(key);
+		return entry !== undefined && !this.#isStale(entry);
+	}
+
+	/** Returns a fresh value without changing recency or removing stale data. */
+	peek(key: K): V | undefined {
+		const entry = this.#entries.get(key);
+		return entry === undefined || this.#isStale(entry) ? undefined : entry.value;
+	}
+
+	/** Removes a value, returning whether one was present. */
+	delete(key: K): boolean {
+		const entry = this.#entries.get(key);
+		if (entry === undefined) return false;
+		this.#remove(key, entry, "delete");
+		return true;
+	}
+
+	/** Removes every value from least to most recently used. */
+	clear(): void {
+		for (const [key, entry] of this.#entries) this.#dispose?.(entry.value, key, "delete");
+		this.#entries.clear();
+		this.#calculatedSize = 0;
+	}
+
+	/** Iterates fresh keys from most to least recently used. */
+	*keys(): Generator<K, void, unknown> {
+		const entries = [...this.#entries.entries()];
+		for (let index = entries.length - 1; index >= 0; index--) {
+			const [key, entry] = entries[index]!;
+			if (!this.#isStale(entry)) yield key;
+		}
+	}
+
+	/** Iterates fresh values from most to least recently used. */
+	*values(): Generator<V, void, unknown> {
+		const entries = [...this.#entries.values()];
+		for (let index = entries.length - 1; index >= 0; index--) {
+			const entry = entries[index]!;
+			if (!this.#isStale(entry)) yield entry.value;
+		}
+	}
+
+	#entrySize(value: V, key: K): number {
+		if (this.#sizeCalculation === undefined) return 0;
+		const size = this.#sizeCalculation(value, key);
+		if (!Number.isInteger(size) || size <= 0)
+			throw new TypeError("sizeCalculation return invalid (expect positive integer)");
+		return size;
+	}
+
+	#isStale(entry: Entry<V>): boolean {
+		return this.#ttl !== 0 && performance.now() - entry.start > this.#ttl;
+	}
+
+	#remove(key: K, entry: Entry<V>, reason: DisposeReason): void {
+		this.#dispose?.(entry.value, key, reason);
+		this.#entries.delete(key);
+		this.#calculatedSize -= entry.size;
+	}
+}