@linxiraos/pi-utils 1.0.0

package/src/frontmatter.ts

@@ -0,0 +1,205 @@
+import { YAML } from "bun";
+import { truncate } from "./format";
+import * as logger from "./logger";
+
+function stripHtmlComments(content: string): string {
+	return content.replace(/<!--[\s\S]*?-->/g, "");
+}
+
+/** Convert kebab-case to camelCase (e.g. "thinking-level" -> "thinkingLevel") */
+function kebabToCamel(key: string): string {
+	if (!key.includes("-")) return key;
+	return key.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+/**
+ * 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 = normalizeFrontmatterKeys(v);
+			out[i] = nv;
+			if (nv !== v) changed = true;
+		}
+		return (changed ? (out as unknown) : obj) as T;
+	}
+	let changed = false;
+	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 = normalizeFrontmatterKeys(value);
+		result[nk] = nv;
+		if (nk !== key || nv !== value) changed = true;
+	}
+	return (changed ? result : obj) as T;
+}
+
+const PLAIN_SCALAR_KEY_VALUE = /^(\s*[A-Za-z_][\w-]*:\s+)(\S.*?)(\s*)$/;
+const FLOW_OR_EXPLICIT_VALUE_START = new Set(['"', "'", "[", "{", "|", ">", "!", "&", "*", "#"]);
+
+function quoteAmbiguousPlainScalars(metadata: string): string | undefined {
+	let changed = false;
+	const lines = metadata.split("\n").map(line => {
+		const match = line.match(PLAIN_SCALAR_KEY_VALUE);
+		if (!match) return line;
+		const [, prefix, rawValue, suffix] = match;
+		const value = rawValue.trimEnd();
+		if (!value.includes(": ")) return line;
+		if (FLOW_OR_EXPLICIT_VALUE_START.has(value[0])) return line;
+		changed = true;
+		return `${prefix}${JSON.stringify(value)}${suffix}`;
+	});
+	return changed ? lines.join("\n") : undefined;
+}
+
+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>;
+}
+
+export class FrontmatterError extends Error {
+	constructor(
+		error: Error,
+		readonly source?: unknown,
+	) {
+		super(`Failed to parse YAML frontmatter (${source}): ${error.message}`, { cause: error });
+		this.name = "FrontmatterError";
+	}
+
+	override toString(): string {
+		// Format the error with stack and detail, including the error message, stack, and source if present
+		const details: string[] = [this.message];
+		if (this.source !== undefined) {
+			details.push(`Source: ${JSON.stringify(this.source)}`);
+		}
+		if (this.cause && typeof this.cause === "object" && "stack" in this.cause && this.cause.stack) {
+			details.push(`Stack:\n${this.cause.stack}`);
+		} else if (this.stack) {
+			details.push(`Stack:\n${this.stack}`);
+		}
+		return details.join("\n\n");
+	}
+}
+
+export interface FrontmatterOptions {
+	/** Source of the content (alias: source) */
+	location?: unknown;
+	/** Source of the content (alias for location) */
+	source?: unknown;
+	/** Fallback frontmatter values */
+	fallback?: Record<string, unknown>;
+	/** Normalize the content */
+	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;
+}
+
+/**
+ * Parse YAML frontmatter from markdown content
+ * Returns { frontmatter, body } where body has frontmatter stripped
+ */
+export function parseFrontmatter(
+	content: string,
+	options?: FrontmatterOptions,
+): { frontmatter: Record<string, unknown>; body: string } {
+	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 newlineNormalized = normalize ? content.replace(/\r\n?/g, "\n") : content;
+	const normalized = normalize && repair ? stripHtmlComments(newlineNormalized) : newlineNormalized;
+	if (!normalized.startsWith("---")) {
+		return { frontmatter, body: normalized };
+	}
+
+	const endIndex = normalized.indexOf("\n---", 3);
+	if (endIndex === -1) {
+		return { frontmatter, body: normalized };
+	}
+
+	const metadata = normalized.slice(4, endIndex);
+	const body = normalized.slice(endIndex + 4).trim();
+
+	try {
+		const loaded = parseYamlRecord(metadata, repair);
+		return { frontmatter: finalizeKeys({ ...frontmatter, ...loaded }), body };
+	} catch (error) {
+		const quotedMetadata = repair ? quoteAmbiguousPlainScalars(metadata) : undefined;
+		if (quotedMetadata) {
+			try {
+				const loaded = parseYamlRecord(quotedMetadata, true);
+				return { frontmatter: finalizeKeys({ ...frontmatter, ...loaded }), body };
+			} catch {
+				// Fall through to the existing warning + simple key/value fallback.
+			}
+		}
+
+		const err = new FrontmatterError(
+			error instanceof Error ? error : new Error(`YAML: ${error}`),
+			loc ?? `Inline '${truncate(content, 64)}'`,
+		);
+		if (level === "warn" || level === "fatal") {
+			logger.warn("Failed to parse YAML frontmatter", { err: err.toString() });
+		}
+		if (level === "fatal") {
+			throw err;
+		}
+
+		// Simple key: value fallback. Reparse each value on its own so one
+		// malformed line (e.g. `scope: "text","thinking"`) can't leave sibling
+		// values wrapped in literal quotes; values that don't parse as YAML fall
+		// back to the raw trimmed string (issue #4796).
+		for (const line of metadata.split("\n")) {
+			const match = line.match(/^([\w-]+):\s*(.*)$/);
+			if (!match) continue;
+			const raw = match[2].trim();
+			let value: unknown = raw;
+			if (raw.length > 0) {
+				try {
+					const parsed = YAML.parse(raw);
+					if (parsed !== null && typeof parsed !== "object") value = parsed;
+					else if (Array.isArray(parsed)) value = parsed;
+				} catch {
+					// keep the raw string
+				}
+			}
+			frontmatter[match[1]] = value;
+		}
+
+		return { frontmatter: finalizeKeys(frontmatter), body };
+	}
+}

package/src/fs-error.ts

@@ -0,0 +1,56 @@
+/**
+ * Type-safe filesystem error handling utilities.
+ *
+ * Use these to check error codes without string matching on messages:
+ *
+ * @example
+ * ```ts
+ * import { isEnoent, isFsError } from "@linxiraos/pi-utils";
+ *
+ * try {
+ *     return await Bun.file(path).text();
+ * } catch (err) {
+ *     if (isEnoent(err)) return null;
+ *     throw err;
+ * }
+ * ```
+ */
+
+export interface FsError extends Error {
+	code: string;
+	errno?: number;
+	syscall?: string;
+	path?: string;
+}
+
+export function isFsError(err: unknown): err is FsError {
+	return err instanceof Error && "code" in err && typeof (err as FsError).code === "string";
+}
+
+export function isEnoent(err: unknown): err is FsError {
+	return isFsError(err) && err.code === "ENOENT";
+}
+
+export function isEacces(err: unknown): err is FsError {
+	return isFsError(err) && err.code === "EACCES";
+}
+
+export function isEisdir(err: unknown): err is FsError {
+	return isFsError(err) && err.code === "EISDIR";
+}
+
+export function isEnotdir(err: unknown): err is FsError {
+	return isFsError(err) && err.code === "ENOTDIR";
+}
+
+export function isEexist(err: unknown): err is FsError {
+	return isFsError(err) && err.code === "EEXIST";
+}
+
+export function isEnotempty(err: unknown): err is FsError {
+	return isFsError(err) && err.code === "ENOTEMPTY";
+}
+
+export function hasFsCode(err: unknown, code: string): err is FsError {
+	return isFsError(err) && err.code === code;
+}

package/src/glob.ts

@@ -0,0 +1,189 @@
+import * as path from "node:path";
+import { Glob } from "bun";
+import { getProjectDir } from "./dirs";
+
+export interface GlobPathsOptions {
+	/** Base directory for glob patterns. Defaults to getProjectDir(). */
+	cwd?: string;
+	/** Glob exclusion patterns. */
+	exclude?: string[];
+	/** Abort signal to cancel the glob. */
+	signal?: AbortSignal;
+	/** Timeout in milliseconds for the glob operation. */
+	timeoutMs?: number;
+	/** Include dotfiles when true. */
+	dot?: boolean;
+	/** Only return files (skip directories). Default: true. */
+	onlyFiles?: boolean;
+	/** Respect .gitignore files when true. Walks up directory tree to find all applicable .gitignore files. */
+	gitignore?: boolean;
+}
+
+/** Patterns always excluded (.git is never useful in glob results). */
+const ALWAYS_IGNORED = ["**/.git", "**/.git/**"];
+
+/** node_modules exclusion patterns (skipped if pattern explicitly references node_modules). */
+const NODE_MODULES_IGNORED = ["**/node_modules", "**/node_modules/**"];
+
+/**
+ * Parse a single .gitignore file and return glob-compatible exclude patterns.
+ * @param content - Raw content of the .gitignore file
+ * @param gitignoreDir - Absolute path to the directory containing the .gitignore
+ * @param baseDir - Absolute path to the glob's cwd (for relativizing rooted patterns)
+ */
+function parseGitignorePatterns(content: string, gitignoreDir: string, baseDir: string): string[] {
+	const patterns: string[] = [];
+
+	for (const rawLine of content.split("\n")) {
+		const line = rawLine.trim();
+		// Skip empty lines and comments
+		if (!line || line.startsWith("#")) {
+			continue;
+		}
+		// Skip negation patterns (unsupported for simple exclude)
+		if (line.startsWith("!")) {
+			continue;
+		}
+
+		let pattern = line;
+
+		// Handle trailing slash (directory-only match)
+		// For glob exclude, we treat it as matching the dir and its contents
+		const isDirectoryOnly = pattern.endsWith("/");
+		if (isDirectoryOnly) {
+			pattern = pattern.slice(0, -1);
+		}
+
+		// Handle rooted patterns (start with /)
+		if (pattern.startsWith("/")) {
+			// Rooted pattern: relative to the .gitignore location
+			const absolutePattern = path.join(gitignoreDir, pattern.slice(1));
+			const relativeToBase = path.relative(baseDir, absolutePattern);
+			if (relativeToBase.startsWith("..")) {
+				// Pattern is outside the search directory, skip
+				continue;
+			}
+			pattern = relativeToBase.replace(/\\/g, "/");
+			if (isDirectoryOnly) {
+				patterns.push(pattern);
+				patterns.push(`${pattern}/**`);
+			} else {
+				patterns.push(pattern);
+			}
+		} else {
+			// Unrooted pattern: match anywhere in the tree
+			if (pattern.includes("/")) {
+				// Contains slash: match from any directory level
+				patterns.push(`**/${pattern}`);
+				if (isDirectoryOnly) {
+					patterns.push(`**/${pattern}/**`);
+				}
+			} else {
+				// No slash: match file/dir name anywhere
+				patterns.push(`**/${pattern}`);
+				if (isDirectoryOnly) {
+					patterns.push(`**/${pattern}/**`);
+				}
+			}
+		}
+	}
+
+	return patterns;
+}
+
+/**
+ * Load .gitignore patterns from a directory and its parents.
+ * Walks up the directory tree to find all applicable .gitignore files.
+ * Returns glob-compatible exclude patterns.
+ */
+export async function loadGitignorePatterns(baseDir: string): Promise<string[]> {
+	const patterns: string[] = [];
+	const absoluteBase = path.resolve(baseDir);
+
+	let current = absoluteBase;
+	const maxDepth = 50; // Prevent infinite loops
+
+	for (let i = 0; i < maxDepth; i++) {
+		const gitignorePath = path.join(current, ".gitignore");
+
+		try {
+			const content = await Bun.file(gitignorePath).text();
+			const filePatterns = parseGitignorePatterns(content, current, absoluteBase);
+			patterns.push(...filePatterns);
+		} catch {
+			// .gitignore doesn't exist or can't be read, continue
+		}
+
+		const parent = path.dirname(current);
+		if (parent === current) {
+			// Reached filesystem root
+			break;
+		}
+		current = parent;
+	}
+
+	return patterns;
+}
+
+/**
+ * Resolve filesystem paths matching glob patterns with optional exclude filters.
+ * Returns paths relative to the provided cwd (or getProjectDir()).
+ * Errors and abort/timeouts are surfaced to the caller.
+ */
+export async function globPaths(patterns: string | string[], options: GlobPathsOptions = {}): Promise<string[]> {
+	const { cwd, exclude, signal, timeoutMs, dot, onlyFiles = true, gitignore } = options;
+
+	// Build exclude list: always exclude .git, exclude node_modules unless pattern references it
+	const patternArray = Array.isArray(patterns) ? patterns : [patterns];
+	const mentionsNodeModules = patternArray.some(p => p.includes("node_modules"));
+
+	const baseExclude = mentionsNodeModules ? [...ALWAYS_IGNORED] : [...ALWAYS_IGNORED, ...NODE_MODULES_IGNORED];
+	let effectiveExclude = exclude ? [...baseExclude, ...exclude] : baseExclude;
+
+	if (gitignore) {
+		const gitignorePatterns = await loadGitignorePatterns(cwd ?? getProjectDir());
+		effectiveExclude = [...effectiveExclude, ...gitignorePatterns];
+	}
+
+	const base = cwd ?? getProjectDir();
+	const allResults: string[] = [];
+
+	// Combine timeout and abort signals
+	const timeoutSignal = timeoutMs ? AbortSignal.timeout(timeoutMs) : undefined;
+	const combinedSignal =
+		signal && timeoutSignal ? AbortSignal.any([signal, timeoutSignal]) : (signal ?? timeoutSignal);
+
+	for (const pattern of patternArray) {
+		const glob = new Glob(pattern);
+		const scanOptions = {
+			cwd: base,
+			dot,
+			onlyFiles,
+			throwErrorOnBrokenSymlink: false,
+		};
+
+		for await (const entry of glob.scan(scanOptions)) {
+			if (combinedSignal?.aborted) {
+				const reason = combinedSignal.reason;
+				if (reason instanceof Error) throw reason;
+				throw new DOMException("Aborted", "AbortError");
+			}
+
+			// Check exclusion patterns
+			const normalized = entry.replace(/\\/g, "/");
+			let excluded = false;
+			for (const excludePattern of effectiveExclude) {
+				const excludeGlob = new Glob(excludePattern);
+				if (excludeGlob.match(normalized)) {
+					excluded = true;
+					break;
+				}
+			}
+			if (!excluded) {
+				allResults.push(normalized);
+			}
+		}
+	}
+
+	return allResults;
+}

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/index.ts

@@ -0,0 +1,59 @@
+export { once, untilAborted } from "./abortable";
+export * from "./async";
+export * from "./binary";
+export * from "./color";
+export * from "./dirs";
+export * from "./env";
+export * from "./fetch-retry";
+export * from "./file-lock";
+export * from "./format";
+export * from "./frontmatter";
+export * from "./fs-error";
+export * from "./glob";
+export * from "./json";
+export * from "./json-parse";
+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";
+export * from "./process-name";
+export * as procmgr from "./procmgr";
+export * as prompt from "./prompt";
+export * as ptree from "./ptree";
+export { AbortError, ChildProcess, Exception, NonZeroExitError } from "./ptree";
+export * from "./runtime-install";
+export * from "./sanitize-text";
+export * from "./snowflake";
+export * from "./stderr-guard";
+export * from "./stream";
+export * from "./tab-spacing";
+export * from "./temp";
+export * from "./tls-fetch";
+export * from "./type-guards";
+export * from "./version";
+export * from "./which";
+
+function isPlainObject(val: object): val is Record<string, unknown> {
+	return Object.getPrototypeOf(val) === Object.prototype || Array.isArray(val);
+}
+
+export function structuredCloneJSON<T>(value: T): T {
+	// primitives|null|undefined, copy
+	if (!value || typeof value !== "object") {
+		return value;
+	}
+
+	// deep clone
+	if (isPlainObject(value)) {
+		try {
+			return structuredClone(value);
+		} catch {
+			// might still fail due to nested structures
+		}
+	}
+	return JSON.parse(JSON.stringify(value)) as T;
+}