@f5xc-salesdemos/pi-utils 14.0.2

package/src/format.ts

@@ -0,0 +1,106 @@
+const SEC = 1_000;
+const MIN = 60 * SEC;
+const HOUR = 60 * MIN;
+const DAY = 24 * HOUR;
+
+/**
+ * Format a duration in milliseconds to a short human-readable string.
+ * Examples: "123ms", "1.5s", "30m15s", "2h30m", "3d2h"
+ */
+export function formatDuration(ms: number): string {
+	if (ms < SEC) return `${ms}ms`;
+	if (ms < MIN) return `${(ms / SEC).toFixed(1)}s`;
+	if (ms < HOUR) {
+		const mins = Math.floor(ms / MIN);
+		const secs = Math.floor((ms % MIN) / SEC);
+		return secs > 0 ? `${mins}m${secs}s` : `${mins}m`;
+	}
+	if (ms < DAY) {
+		const hours = Math.floor(ms / HOUR);
+		const mins = Math.floor((ms % HOUR) / MIN);
+		return mins > 0 ? `${hours}h${mins}m` : `${hours}h`;
+	}
+	const days = Math.floor(ms / DAY);
+	const hours = Math.floor((ms % DAY) / HOUR);
+	return hours > 0 ? `${days}d${hours}h` : `${days}d`;
+}
+
+/**
+ * Format a number with K/M/B suffix for compact display.
+ * Uses 1 decimal for small leading digits, rounded otherwise.
+ * Examples: "999", "1.5K", "25K", "1.5M", "25M", "1.5B"
+ */
+export function formatNumber(n: number): string {
+	if (n < 1_000) return n.toString();
+	if (n < 10_000) return `${(n / 1_000).toFixed(1)}K`;
+	if (n < 1_000_000) return `${Math.round(n / 1_000)}K`;
+	if (n < 10_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+	if (n < 1_000_000_000) return `${Math.round(n / 1_000_000)}M`;
+	if (n < 10_000_000_000) return `${(n / 1_000_000_000).toFixed(1)}B`;
+	return `${Math.round(n / 1_000_000_000)}B`;
+}
+
+/**
+ * Format a byte count to a human-readable string.
+ * Examples: "512B", "1.5KB", "2.3MB", "1.2GB"
+ */
+export function formatBytes(bytes: number): string {
+	if (bytes < 1024) return `${bytes}B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+	if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+	return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)}GB`;
+}
+
+/**
+ * Truncate a string to maxLen characters, appending an ellipsis if truncated.
+ * For display-width-aware truncation (terminals), use truncateToWidth from @f5xc-salesdemos/pi-tui.
+ */
+export function truncate(str: string, maxLen: number, ellipsis = "…"): string {
+	if (str.length <= maxLen) return str;
+	const sliceLen = Math.max(0, maxLen - ellipsis.length);
+	return `${str.slice(0, sliceLen)}${ellipsis}`;
+}
+
+/**
+ * Format count with pluralized label (e.g., "3 files", "1 error").
+ */
+export function formatCount(label: string, count: number): string {
+	const safeCount = Number.isFinite(count) ? count : 0;
+	return `${safeCount} ${pluralize(label, safeCount)}`;
+}
+
+/**
+ * Format age from seconds to human-readable string.
+ */
+export function formatAge(ageSeconds: number | null | undefined): string {
+	if (!ageSeconds) return "";
+	const mins = Math.floor(ageSeconds / 60);
+	const hours = Math.floor(mins / 60);
+	const days = Math.floor(hours / 24);
+	const weeks = Math.floor(days / 7);
+	const months = Math.floor(days / 30);
+
+	if (months > 0) return `${months}mo ago`;
+	if (weeks > 0) return `${weeks}w ago`;
+	if (days > 0) return `${days}d ago`;
+	if (hours > 0) return `${hours}h ago`;
+	if (mins > 0) return `${mins}m ago`;
+	return "just now";
+}
+
+/**
+ * Pluralize a label based on the count.
+ */
+export function pluralize(label: string, count: number): string {
+	if (count === 1) return label;
+	if (/(?:ch|sh|s|x|z)$/i.test(label)) return `${label}es`;
+	if (/[^aeiou]y$/i.test(label)) return `${label.slice(0, -1)}ies`;
+	return `${label}s`;
+}
+
+/**
+ * Format a ratio as a percentage.
+ */
+export function formatPercent(ratio: number): string {
+	return `${(ratio * 100).toFixed(1)}%`;
+}

package/src/frontmatter.ts

@@ -0,0 +1,118 @@
+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 {
+	return key.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+/** Recursively normalize object keys from kebab-case to camelCase */
+function normalizeKeys<T>(obj: T): T {
+	if (obj === null || typeof obj !== "object") {
+		return obj;
+	}
+	if (Array.isArray(obj)) {
+		return obj.map(normalizeKeys) as T;
+	}
+	const result: Record<string, unknown> = {};
+	for (const [key, value] of Object.entries(obj as Record<string, unknown>)) {
+		const normalizedKey = kebabToCamel(key);
+		result[normalizedKey] = normalizeKeys(value);
+	}
+	return result as T;
+}
+
+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";
+	}
+
+	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";
+}
+
+/**
+ * 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" } = options ?? {};
+	const loc = location ?? source;
+	const frontmatter: Record<string, unknown> = { ...fallback };
+
+	const normalized = normalize ? stripHtmlComments(content.replace(/\r\n/g, "\n").replace(/\r/g, "\n")) : content;
+	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 {
+		// Replace tabs with spaces for YAML compatibility, use failsafe mode for robustness
+		const loaded = YAML.parse(metadata.replaceAll("\t", "  ")) as Record<string, unknown> | null;
+		return { frontmatter: normalizeKeys({ ...frontmatter, ...loaded }), body };
+	} catch (error) {
+		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 YAML parsing - just key: value pairs
+		for (const line of metadata.split("\n")) {
+			const match = line.match(/^([\w-]+):\s*(.*)$/);
+			if (match) {
+				frontmatter[match[1]] = match[2].trim();
+			}
+		}
+
+		return { frontmatter: normalizeKeys(frontmatter) as Record<string, unknown>, 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 "@f5xc-salesdemos/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/hook-fetch.ts

@@ -0,0 +1,30 @@
+/**
+ * Intercept `globalThis.fetch` with a middleware-style handler.
+ *
+ * Returns a `Disposable` so callers can use `using` for automatic cleanup:
+ *
+ * ```ts
+ * using _hook = hookFetch((input, init, next) => {
+ *   if (shouldIntercept(input)) {
+ *     return new Response("mocked");
+ *   }
+ *   return next(input, init);
+ * });
+ * ```
+ */
+export type FetchHandler = (
+	input: string | URL | Request,
+	init: RequestInit | undefined,
+	next: typeof fetch,
+) => Response | Promise<Response>;
+
+export function hookFetch(handler: FetchHandler): Disposable {
+	const original = globalThis.fetch;
+	globalThis.fetch = ((input: string | URL | Request, init?: RequestInit) =>
+		handler(input, init, original)) as typeof fetch;
+	return {
+		[Symbol.dispose]() {
+			globalThis.fetch = original;
+		},
+	};
+}

package/src/index.ts

@@ -0,0 +1,47 @@
+export { abortableSleep, createAbortableStream, once, untilAborted } from "./abortable";
+export * from "./async";
+export * from "./color";
+export * from "./dirs";
+export * from "./env";
+export * from "./format";
+export * from "./frontmatter";
+export * from "./fs-error";
+export * from "./glob";
+export * from "./hook-fetch";
+export * from "./json";
+export * as logger from "./logger";
+export * from "./mermaid-ascii";
+export * from "./mime";
+export * from "./peek-file";
+export * as postmortem from "./postmortem";
+export * as procmgr from "./procmgr";
+export { setNativeKillTree } from "./procmgr";
+export * as prompt from "./prompt";
+export * as ptree from "./ptree";
+export { AbortError, ChildProcess, Exception, NonZeroExitError } from "./ptree";
+export * from "./snowflake";
+export * from "./stream";
+export * from "./temp";
+export * from "./type-guards";
+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;
+}

package/src/json.ts

@@ -0,0 +1,10 @@
+/**
+ * Try to parse JSON, returning null on failure.
+ */
+export function tryParseJson<T = unknown>(content: string): T | null {
+	try {
+		return JSON.parse(content) as T;
+	} catch {
+		return null;
+	}
+}