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

package/src/frontmatter.ts

@@ -12,15 +12,20 @@ function kebabToCamel(key: string): string {
 	return key.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
 }
 
-/** Recursively normalize object keys from kebab-case to camelCase */
-function normalizeKeys<T>(obj: T): T {
+/**
+ * Recursively normalize object keys from kebab-case to camelCase — the
+ * representation convention for frontmatter consumed inside this codebase.
+ * Exported for loaders that parse with `rawKeys: true` to validate exact
+ * spec-defined keys, then normalize for storage.
+ */
+export function normalizeFrontmatterKeys<T>(obj: T): T {
 	if (obj === null || typeof obj !== "object") return obj;
 	if (Array.isArray(obj)) {
 		let changed = false;
 		const out: unknown[] = new Array(obj.length);
 		for (let i = 0; i < obj.length; i++) {
 			const v = obj[i];
-			const nv = normalizeKeys(v);
+			const nv = normalizeFrontmatterKeys(v);
 			out[i] = nv;
 			if (nv !== v) changed = true;
 		}
@@ -30,7 +35,7 @@ function normalizeKeys<T>(obj: T): T {
 	const result: Record<string, unknown> = {};
 	for (const [key, value] of Object.entries(obj as Record<string, unknown>)) {
 		const nk = key.includes("-") ? kebabToCamel(key) : key;
-		const nv = normalizeKeys(value);
+		const nv = normalizeFrontmatterKeys(value);
 		result[nk] = nv;
 		if (nk !== key || nv !== value) changed = true;
 	}
@@ -55,8 +60,8 @@ function quoteAmbiguousPlainScalars(metadata: string): string | undefined {
 	return changed ? lines.join("\n") : undefined;
 }
 
-function parseYamlRecord(metadata: string): Record<string, unknown> | null {
-	const loaded = YAML.parse(metadata.replaceAll("\t", "  "));
+function parseYamlRecord(metadata: string, repairTabs: boolean): Record<string, unknown> | null {
+	const loaded = YAML.parse(repairTabs ? metadata.replaceAll("\t", "  ") : metadata);
 	if (loaded === null || loaded === undefined) return null;
 	if (typeof loaded !== "object" || Array.isArray(loaded)) return null;
 	return loaded as Record<string, unknown>;
@@ -97,6 +102,20 @@ export interface FrontmatterOptions {
 	normalize?: boolean;
 	/** Level of error handling */
 	level?: "off" | "warn" | "fatal";
+	/**
+	 * Attempt lenient recovery of near-miss input before failing: quote
+	 * ambiguous plain scalars, replace tabs with spaces, and strip leading HTML
+	 * comments ahead of the opening delimiter. Default `true`. Spec-conformant
+	 * loaders set `false` so malformed input is rejected instead of silently
+	 * repaired (CRLF newline normalization still applies).
+	 */
+	repair?: boolean;
+	/**
+	 * Preserve frontmatter keys verbatim instead of normalizing kebab-case to
+	 * camelCase. Default `false`. Strict spec loaders use this so a standard
+	 * key (e.g. `allowed-tools`) is never aliased with its camelCase form.
+	 */
+	rawKeys?: boolean;
 }
 
 /**
@@ -107,11 +126,22 @@ export function parseFrontmatter(
 	content: string,
 	options?: FrontmatterOptions,
 ): { frontmatter: Record<string, unknown>; body: string } {
-	const { location, source, fallback, normalize = true, level = "warn" } = options ?? {};
+	const {
+		location,
+		source,
+		fallback,
+		normalize = true,
+		level = "warn",
+		repair = true,
+		rawKeys = false,
+	} = options ?? {};
+	const finalizeKeys = (fm: Record<string, unknown>): Record<string, unknown> =>
+		rawKeys ? fm : normalizeFrontmatterKeys(fm);
 	const loc = location ?? source;
 	const frontmatter: Record<string, unknown> = { ...fallback };
 
-	const normalized = normalize ? stripHtmlComments(content.replace(/\r\n?/g, "\n")) : content;
+	const newlineNormalized = normalize ? content.replace(/\r\n?/g, "\n") : content;
+	const normalized = normalize && repair ? stripHtmlComments(newlineNormalized) : newlineNormalized;
 	if (!normalized.startsWith("---")) {
 		return { frontmatter, body: normalized };
 	}
@@ -125,14 +155,14 @@ export function parseFrontmatter(
 	const body = normalized.slice(endIndex + 4).trim();
 
 	try {
-		const loaded = parseYamlRecord(metadata);
-		return { frontmatter: normalizeKeys({ ...frontmatter, ...loaded }), body };
+		const loaded = parseYamlRecord(metadata, repair);
+		return { frontmatter: finalizeKeys({ ...frontmatter, ...loaded }), body };
 	} catch (error) {
-		const quotedMetadata = quoteAmbiguousPlainScalars(metadata);
+		const quotedMetadata = repair ? quoteAmbiguousPlainScalars(metadata) : undefined;
 		if (quotedMetadata) {
 			try {
-				const loaded = parseYamlRecord(quotedMetadata);
-				return { frontmatter: normalizeKeys({ ...frontmatter, ...loaded }), body };
+				const loaded = parseYamlRecord(quotedMetadata, true);
+				return { frontmatter: finalizeKeys({ ...frontmatter, ...loaded }), body };
 			} catch {
 				// Fall through to the existing warning + simple key/value fallback.
 			}
@@ -170,6 +200,6 @@ export function parseFrontmatter(
 			frontmatter[match[1]] = value;
 		}
 
-		return { frontmatter: normalizeKeys(frontmatter) as Record<string, unknown>, body };
+		return { frontmatter: finalizeKeys(frontmatter), body };
 	}
 }

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}`);
 }
 
 /**