@sayknow-cli/utils 0.2.2

package/src/env.ts

@@ -0,0 +1,278 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { getAgentDir, getConfigRootDir } from "./dirs";
+import { isSafeEnvName, isSafeEnvValue } from "./spawn-env";
+
+export { filterProcessEnv, isSafeEnvName, isSafeEnvValue } from "./spawn-env";
+
+const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * Strict shell-identifier shape. Used for dotenv keys we accept into
+ * `Bun.env` — those should be referenceable as `$NAME` from POSIX shells,
+ * so we reject anything outside `[A-Za-z_][A-Za-z0-9_]*`.
+ */
+export function isValidEnvName(name: string): boolean {
+	return ENV_NAME_RE.test(name);
+}
+
+function stripInlineShellComment(value: string): string {
+	let quote: '"' | "'" | undefined;
+	for (let i = 0; i < value.length; i++) {
+		const char = value[i];
+		if (char === "\\") {
+			i++;
+			continue;
+		}
+		if ((char === '"' || char === "'") && (!quote || quote === char)) {
+			quote = quote ? undefined : char;
+			continue;
+		}
+		if (char === "#" && !quote && (i === 0 || /\s/.test(value[i - 1] ?? ""))) {
+			return value.slice(0, i).trimEnd();
+		}
+	}
+	return value.trimEnd();
+}
+
+/**
+ * Parses simple POSIX shell environment assignments from files such as
+ * ~/.zshrc without executing user shell code. Supports `export KEY=value` and
+ * `KEY=value`, including single/double quoted literal values. Dynamic shell
+ * expressions are intentionally ignored because evaluating startup files would
+ * run arbitrary code during CLI startup.
+ */
+export function parseShellEnvFile(filePath: string): Record<string, string> {
+	const result: Record<string, string> = {};
+	try {
+		const content = fs.readFileSync(filePath, "utf-8");
+		for (const line of content.split("\n")) {
+			const trimmed = line.trim();
+			if (!trimmed || trimmed.startsWith("#")) continue;
+
+			const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$/.exec(trimmed);
+			if (!match) continue;
+
+			const key = match[1];
+			if (!isValidEnvName(key)) continue;
+
+			let value = stripInlineShellComment(match[2] ?? "").trim();
+			if (value.endsWith(";")) value = value.slice(0, -1).trimEnd();
+			if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+				value = value.slice(1, -1);
+			}
+			if (!isSafeEnvValue(value)) continue;
+			if (/[$`]/.test(value)) continue;
+
+			result[key] = value;
+		}
+	} catch {
+		// File doesn't exist or can't be read - return empty result
+	}
+
+	return result;
+}
+
+/**
+ * Parses a .env file synchronously and extracts key-value string pairs.
+ * Ignores lines that are empty or start with '#'. Trims whitespace.
+ * Allows values to be quoted with single or double quotes.
+ * Returns an object of key-value pairs.
+ */
+export function parseEnvFile(filePath: string): Record<string, string> {
+	const result: Record<string, string> = {};
+	try {
+		const content = fs.readFileSync(filePath, "utf-8");
+		for (const line of content.split("\n")) {
+			const trimmed = line.trim();
+			// Skip comments and blank lines
+			if (!trimmed || trimmed.startsWith("#")) continue;
+
+			const eqIndex = trimmed.indexOf("=");
+			if (eqIndex === -1) continue;
+
+			const key = trimmed.slice(0, eqIndex).trim();
+			if (!isValidEnvName(key)) continue;
+
+			let value = trimmed.slice(eqIndex + 1).trim();
+
+			// Remove surrounding quotes (" or ')
+			if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+				value = value.slice(1, -1);
+			}
+			if (!isSafeEnvValue(value)) continue;
+
+			result[key] = value;
+		}
+	} catch {
+		// File doesn't exist or can't be read - return empty result
+	}
+
+	return result;
+}
+
+function resolveFileEnvValue(file: Record<string, string>, name: string): string | undefined {
+	if (!isSafeEnvName(name)) return undefined;
+	const value = file[name];
+	if (value === undefined || !isSafeEnvValue(value)) return undefined;
+	const trimmed = value.trim();
+	return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function filterCredentialInheritedEnv(env: Record<string, string | undefined>): Record<string, string> {
+	const result: Record<string, string> = {};
+	for (const key in env) {
+		const value = env[key];
+		if (!isSafeEnvName(key) || value === undefined || !isSafeEnvValue(value)) continue;
+
+		// Bun may have already loaded cwd/.env before JS runs. It does not expose the
+		// source of each entry, so an exact match with projectEnv is ambiguous. Use
+		// the safer credential rule: ambiguous project matches are excluded from the
+		// credential-only inherited snapshot, while remaining available through $env.
+		const projectValue = resolveFileEnvValue(projectEnv, key);
+		if (projectValue !== undefined && projectValue === value) continue;
+
+		result[key] = value;
+	}
+	return result;
+}
+
+// Eagerly parse the user's $HOME/.env and the current project's .env (from cwd)
+const homeShellEnv = {
+	...parseShellEnvFile(path.join(os.homedir(), ".zshenv")),
+	...parseShellEnvFile(path.join(os.homedir(), ".zprofile")),
+	...parseShellEnvFile(path.join(os.homedir(), ".zshrc")),
+	...parseShellEnvFile(path.join(os.homedir(), ".bash_profile")),
+	...parseShellEnvFile(path.join(os.homedir(), ".bashrc")),
+};
+const homeEnv = parseEnvFile(path.join(os.homedir(), ".env"));
+const piEnv = parseEnvFile(path.join(getConfigRootDir(), ".env"));
+const agentEnv = parseEnvFile(path.join(getAgentDir(), ".env"));
+const projectEnv = parseEnvFile(path.join(process.cwd(), ".env"));
+
+const inheritedEnv = filterCredentialInheritedEnv(Bun.env);
+
+export function $inheritedEnv(name: string): string | undefined {
+	return resolveFileEnvValue(inheritedEnv, name);
+}
+
+function resolveLiveCredentialEnvValue(name: string): string | undefined {
+	if (!isSafeEnvName(name)) return undefined;
+	const value = Bun.env[name];
+	if (value === undefined || !isSafeEnvValue(value)) return undefined;
+	const trimmed = value.trim();
+	if (trimmed.length === 0) return undefined;
+
+	const projectValue = resolveFileEnvValue(projectEnv, name);
+	if (
+		projectValue !== undefined &&
+		projectValue === trimmed &&
+		resolveFileEnvValue(inheritedEnv, name) === undefined
+	) {
+		return undefined;
+	}
+
+	return trimmed;
+}
+
+for (const file of [projectEnv, agentEnv, piEnv, homeEnv, homeShellEnv]) {
+	for (const key in file) {
+		if (!Bun.env[key]) {
+			Bun.env[key] = file[key];
+		}
+	}
+}
+
+/**
+ * Intentional re-export of Bun.env.
+ *
+ * All users should import this env module (import { $env } from "@sayknow-cli/utils")
+ * before using environment variables. This ensures that .env files have been loaded and
+ * overrides (project, home) have been applied, so $env always reflects the correct values.
+ *
+ * Provider credential resolution must not use this merged view because it includes the
+ * caller's cwd/.env. Use $credentialEnv/$pickCredentialEnv for model authentication.
+ */
+export const $env: Record<string, string> = Bun.env as Record<string, string>;
+
+/**
+ * Resolve the first environment variable value from the given keys.
+ * @param keys - The keys to resolve.
+ * @returns The first environment variable value, or undefined if no value is found.
+ */
+export function $pickenv(...keys: string[]): string | undefined {
+	for (const key of keys) {
+		const value = Bun.env[key]?.trim();
+		if (value) {
+			return value;
+		}
+	}
+	return undefined;
+}
+
+/**
+ * Resolve credential-bearing environment variables without consulting the caller's project .env.
+ *
+ * SKC loads cwd/.env into $env for project-aware tools, but model-provider authentication should
+ * only use values explicitly inherited from the launching shell or SKC/user-owned config files.
+ */
+export function $credentialEnv(name: string): string | undefined {
+	return (
+		$inheritedEnv(name) ??
+		resolveLiveCredentialEnvValue(name) ??
+		resolveFileEnvValue(agentEnv, name) ??
+		resolveFileEnvValue(piEnv, name) ??
+		resolveFileEnvValue(homeEnv, name) ??
+		resolveFileEnvValue(homeShellEnv, name)
+	);
+}
+
+/**
+ * Resolve the first credential env value from the given keys, excluding cwd/.env overlays.
+ */
+export function $pickCredentialEnv(...keys: string[]): string | undefined {
+	for (const key of keys) {
+		const value = $credentialEnv(key);
+		if (value) return value;
+	}
+	return undefined;
+}
+
+/**
+ * Parses a positive decimal integer from `$env[name]`.
+ * Empty, invalid, NaN, zero, or negative values return `defaultValue`.
+ */
+export function $envpos(name: string, defaultValue: number): number {
+	const raw = $env[name];
+	if (!raw) return defaultValue;
+	const parsed = Number.parseInt(raw, 10);
+	if (Number.isNaN(parsed) || parsed <= 0) return defaultValue;
+	return parsed;
+}
+
+/** True when `BUN_ENV` or `NODE_ENV` is the string `test`. */
+export function isBunTestRuntime(): boolean {
+	return Bun.env.BUN_ENV === "test" || Bun.env.NODE_ENV === "test";
+}
+
+/**
+ * True when this code is running inside a `bun build --compile` standalone
+ * binary. Detects via the embedded virtual-filesystem path markers
+ * (`$bunfs`, `~BUN`, or its URL-encoded form `%7EBUN`) in `import.meta.url`,
+ * which Bun rewrites for every module bundled into the executable. The
+ * `PI_COMPILED` env var (set by the build script's `--define`) is checked
+ * first for cheap fast-path detection.
+ */
+export function isCompiledBinary(): boolean {
+	if (Bun.env.PI_COMPILED) return true;
+	const url = import.meta.url;
+	return url.includes("$bunfs") || url.includes("~BUN") || url.includes("%7EBUN");
+}
+
+const TRUTHY: Dict<boolean> = { "1": true, Y: true, TRUE: true, YES: true, ON: true };
+export function $flag(name: string, def: boolean = false): boolean {
+	const value = $env[name];
+	if (!value) return def;
+	return TRUTHY[value] === true;
+}

package/src/fetch-retry.ts

@@ -0,0 +1,298 @@
+import { scheduler } from "node:timers/promises";
+
+// "reset after 1h2m3s" / "10m15s" / "39s"
+const QUOTA_RESET_PATTERN = /reset after (?:(\d+)h)?(?:(\d+)m)?(\d+(?:\.\d+)?)s/i;
+// "Please retry in 250ms" / "Please retry in 12s"
+const PLEASE_RETRY_PATTERN = /Please retry in ([0-9.]+)(ms|s)/i;
+// JSON field: "retryDelay": "34.074824224s"
+const RETRY_DELAY_FIELD_PATTERN = /"retryDelay":\s*"([0-9.]+)(ms|s)"/i;
+// "try again in 250ms" / "try again in 12s" / "try again in 12sec"
+const TRY_AGAIN_PATTERN = /try again in\s+(\d+(?:\.\d+)?)\s*(ms|s)(?:ec)?/i;
+
+/**
+ * Server-suggested retry delay extraction. Merges the patterns historically used
+ * by the OpenAI code provider and Google Gemini retry helpers.
+ *
+ * Header sources (checked in order):
+ *  - `Retry-After` (numeric seconds, or HTTP date)
+ *  - `x-ratelimit-reset` (Unix epoch seconds)
+ *  - `x-ratelimit-reset-after` (seconds)
+ *
+ * Body patterns:
+ *  - `Your quota will reset after 18h31m10s` / `10m15s` / `39s`
+ *  - `Please retry in 250ms` / `Please retry in 12s`
+ *  - `"retryDelay": "34.074824224s"` (JSON error detail field)
+ *  - `try again in 250ms` / `try again in 12s` / `try again in 12sec`
+ *
+ * Returns `undefined` if no signal is found.
+ */
+export function extractRetryHint(source: Response | Headers | null | undefined, body?: string): number | undefined {
+	const headers = source instanceof Headers ? source : (source?.headers ?? undefined);
+	if (headers) {
+		const retryAfter = headers.get("retry-after");
+		if (retryAfter) {
+			const seconds = Number(retryAfter);
+			if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);
+			const parsedDate = Date.parse(retryAfter);
+			if (!Number.isNaN(parsedDate)) return Math.max(0, parsedDate - Date.now());
+		}
+		const rateLimitReset = headers.get("x-ratelimit-reset");
+		if (rateLimitReset) {
+			const resetSeconds = Number.parseInt(rateLimitReset, 10);
+			if (!Number.isNaN(resetSeconds)) {
+				const delta = resetSeconds * 1000 - Date.now();
+				if (delta > 0) return delta;
+			}
+		}
+		const rateLimitResetAfter = headers.get("x-ratelimit-reset-after");
+		if (rateLimitResetAfter) {
+			const seconds = Number(rateLimitResetAfter);
+			if (Number.isFinite(seconds) && seconds > 0) return seconds * 1000;
+		}
+	}
+
+	if (!body) return undefined;
+
+	const quotaMatch = QUOTA_RESET_PATTERN.exec(body);
+	if (quotaMatch) {
+		const hours = quotaMatch[1] ? Number.parseInt(quotaMatch[1], 10) : 0;
+		const minutes = quotaMatch[2] ? Number.parseInt(quotaMatch[2], 10) : 0;
+		const seconds = Number.parseFloat(quotaMatch[3]!);
+		if (!Number.isNaN(seconds)) {
+			const totalMs = ((hours * 60 + minutes) * 60 + seconds) * 1000;
+			if (totalMs > 0) return totalMs;
+		}
+	}
+	for (const pattern of [PLEASE_RETRY_PATTERN, RETRY_DELAY_FIELD_PATTERN, TRY_AGAIN_PATTERN]) {
+		const match = pattern.exec(body);
+		if (match?.[1]) {
+			const value = Number.parseFloat(match[1]);
+			if (Number.isFinite(value) && value > 0) {
+				return match[2]!.toLowerCase() === "ms" ? value : value * 1000;
+			}
+		}
+	}
+	return undefined;
+}
+
+export interface FetchWithRetryOptions extends RequestInit {
+	/** Total fetch attempts (initial + retries). Default `5`. */
+	maxAttempts?: number;
+	/**
+	 * Per-delay cap. Server-provided `Retry-After` hints exceeding this return
+	 * the current response immediately — caller deals with the `!response.ok`.
+	 * Default `60_000`.
+	 */
+	maxDelayMs?: number;
+	/**
+	 * Fallback delay schedule when no server hint is present. Number, array
+	 * (indexed by attempt, clamped to last), or function. Default exponential
+	 * `500ms * 2 ** attempt` capped at `maxDelayMs`.
+	 */
+	defaultDelayMs?: number | readonly number[] | ((attempt: number) => number);
+	/**
+	 * Optional per-attempt overlay merged into the base `RequestInit` each try.
+	 * Headers from the overlay shallow-merge over the base. Useful for auth
+	 * token refresh or user-agent rotation.
+	 */
+	prepareInit?: (attempt: number) => RequestInit | Promise<RequestInit>;
+	/**
+	 * Optional `fetch` implementation override. Defaults to `globalThis.fetch`.
+	 * Useful for routing requests through a proxy, instrumented transport, or
+	 * mock during tests.
+	 */
+	fetch?: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+}
+
+const DEFAULT_MAX_DELAY_MS = 60_000;
+const DEFAULT_MAX_ATTEMPTS = 5;
+
+/**
+ * Fetch with bounded retries and sensible defaults. Retries on any
+ * `isRetryableStatus` (5xx, 408, 429) and on transient network errors. Server
+ * `Retry-After`/quota hints are honoured up to `maxDelayMs`; a hint that exceeds
+ * the cap returns the current response so the caller can fail fast. Aborts on
+ * `init.signal` propagate as `"Request was aborted"`.
+ *
+ * The caller is responsible for inspecting `!response.ok` once the call returns.
+ */
+export async function fetchWithRetry(
+	url: string | URL | ((attempt: number) => string | URL),
+	options: FetchWithRetryOptions = {},
+): Promise<Response> {
+	const {
+		maxAttempts = DEFAULT_MAX_ATTEMPTS,
+		maxDelayMs = DEFAULT_MAX_DELAY_MS,
+		defaultDelayMs,
+		prepareInit,
+		fetch: fetchImpl = fetch,
+		...baseInit
+	} = options;
+	const signal = baseInit.signal as AbortSignal | undefined;
+
+	for (let attempt = 0; ; attempt++) {
+		if (signal?.aborted) throw new Error("Request was aborted");
+		const requestUrl = typeof url === "function" ? url(attempt) : url;
+		const init = prepareInit ? mergeInit(baseInit, await prepareInit(attempt)) : baseInit;
+
+		let response: Response;
+		try {
+			response = await fetchImpl(requestUrl, init);
+		} catch (error) {
+			if (signal?.aborted) throw new Error("Request was aborted");
+			const wrapped = wrapNetworkError(error);
+			if (attempt + 1 >= maxAttempts) throw wrapped;
+			await scheduler.wait(resolveDefaultDelay(defaultDelayMs, attempt, maxDelayMs), { signal });
+			continue;
+		}
+
+		if (!isRetryableStatus(response.status)) return response;
+		if (attempt + 1 >= maxAttempts) return response;
+
+		const hint = extractRetryHint(response, await response.clone().text());
+		if (hint !== undefined && hint > maxDelayMs) return response;
+
+		const delayMs = Math.min(hint ?? resolveDefaultDelay(defaultDelayMs, attempt, maxDelayMs), maxDelayMs);
+		await scheduler.wait(delayMs, { signal });
+	}
+}
+
+function mergeInit(base: RequestInit, overlay: RequestInit): RequestInit {
+	const merged: RequestInit = { ...base, ...overlay };
+	if (base.headers || overlay.headers) {
+		const baseHeaders = new Headers(base.headers ?? undefined);
+		const overlayHeaders = new Headers(overlay.headers ?? undefined);
+		overlayHeaders.forEach((value, key) => {
+			baseHeaders.set(key, value);
+		});
+		merged.headers = baseHeaders;
+	}
+	return merged;
+}
+
+function wrapNetworkError(error: unknown): Error {
+	if (error instanceof Error) {
+		if (error.name === "AbortError" || error.message === "Request was aborted") {
+			return new Error("Request was aborted");
+		}
+		if (error.message === "fetch failed" && error.cause instanceof Error) {
+			return new Error(`Network error: ${error.cause.message}`);
+		}
+		return error;
+	}
+	return new Error(String(error));
+}
+
+function resolveDefaultDelay(
+	option: FetchWithRetryOptions["defaultDelayMs"],
+	attempt: number,
+	maxDelayMs: number,
+): number {
+	if (option === undefined) return Math.min(500 * 2 ** attempt, maxDelayMs);
+	if (typeof option === "number") return Math.min(option, maxDelayMs);
+	if (typeof option === "function") return Math.min(option(attempt), maxDelayMs);
+	return Math.min(option[Math.min(attempt, option.length - 1)] ?? 0, maxDelayMs);
+}
+
+/**
+ * Inspect an arbitrary error value (or its `cause` chain, up to depth 2) for an
+ * HTTP status code. Reads `status`, `statusCode`, and `response.status` fields,
+ * coerces string values, and falls back to scanning the error message for
+ * common patterns like `Error: 401`, `error (429)`, or `HTTP 503`.
+ */
+export function extractHttpStatusFromError(error: unknown): number | undefined {
+	return extractHttpStatusFromErrorInternal(error, 0);
+}
+
+type HttpErrorLike = {
+	message?: string;
+	name?: string;
+	status?: number | string;
+	statusCode?: number | string;
+	response?: { status?: number | string };
+	cause?: unknown;
+};
+
+function extractHttpStatusFromErrorInternal(error: unknown, depth: number): number | undefined {
+	if (!error || typeof error !== "object" || depth > 2) return undefined;
+	const info = error as HttpErrorLike;
+	const rawStatus = info.status ?? info.statusCode ?? info.response?.status;
+
+	let status: number | undefined;
+	if (typeof rawStatus === "number" && Number.isFinite(rawStatus)) {
+		status = rawStatus;
+	} else if (typeof rawStatus === "string") {
+		const parsed = Number(rawStatus);
+		if (Number.isFinite(parsed)) status = parsed;
+	}
+	if (status !== undefined && status >= 100 && status <= 599) return status;
+
+	if (info.message) {
+		const extracted = extractStatusFromMessage(info.message);
+		if (extracted !== undefined) return extracted;
+	}
+	if (info.cause) return extractHttpStatusFromErrorInternal(info.cause, depth + 1);
+	return undefined;
+}
+
+const STATUS_MESSAGE_PATTERNS = [
+	/\berror\s*[:=]\s*(\d{3})\b/i,
+	/error\s*\((\d{3})\)/i,
+	/status\s*[:=]?\s*(\d{3})/i,
+	/\bhttp\s*(\d{3})\b/i,
+	/\b(\d{3})\s*(?:status|error)\b/i,
+] as const;
+
+function extractStatusFromMessage(message: string): number | undefined {
+	for (const pattern of STATUS_MESSAGE_PATTERNS) {
+		const match = pattern.exec(message);
+		if (!match) continue;
+		const value = Number(match[1]);
+		if (Number.isFinite(value) && value >= 100 && value <= 599) return value;
+	}
+	return undefined;
+}
+
+/**
+ * `true` if the given HTTP status code is one we treat as transient: 408
+ * (Request Timeout), 429 (Too Many Requests), or any 5xx (server error).
+ */
+export function isRetryableStatus(status: number): boolean {
+	return status >= 500 || status === 408 || status === 429;
+}
+
+/**
+ * `true` if the message describes an unexpected socket closure — Bun and some
+ * proxies surface these for any HTTP/2 stream reset.
+ */
+export function isUnexpectedSocketCloseMessage(message: string): boolean {
+	return /\b(?:the\s+)?socket connection (?:was )?closed unexpectedly\b/i.test(message);
+}
+
+const TRANSIENT_MESSAGE_PATTERN =
+	/overloaded|rate.?limit|too many requests|service.?unavailable|server error|internal error|connection.?error|unable to connect|fetch failed|network error|stream stall|other side closed/i;
+
+const VALIDATION_MESSAGE_PATTERN =
+	/invalid|validation|bad request|unsupported|schema|missing required|not found|unauthorized|forbidden/i;
+
+/**
+ * Identify errors that should be retried: aborts/timeouts in the error name or
+ * message, retryable HTTP statuses (see `isRetryableStatus`), unexpected socket
+ * closes, and the standard transient phrases. 4xx statuses other than 408/429
+ * and validation-shaped messages short-circuit to `false`.
+ */
+export function isRetryableError(error: unknown): boolean {
+	const info = error as { message?: string; name?: string } | null;
+	const message = info?.message ?? "";
+	const name = info?.name ?? "";
+	if (name === "AbortError" || /timeout|timed out|aborted/i.test(message)) return true;
+
+	const status = extractHttpStatusFromError(error);
+	if (status !== undefined) {
+		if (isRetryableStatus(status)) return true;
+		if (status >= 400 && status < 500) return false;
+	}
+
+	if (VALIDATION_MESSAGE_PATTERN.test(message)) return false;
+	return isUnexpectedSocketCloseMessage(message) || TRANSIENT_MESSAGE_PATTERN.test(message);
+}

package/src/format.ts

@@ -0,0 +1,112 @@
+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 when non-zero, rounded otherwise.
+ * Examples: "999", "1K", "1.5K", "25K", "1M", "1.5M", "25M", "1.5B"
+ */
+export function formatNumber(n: number): string {
+	if (n < 1_000) return n.toString();
+	if (n < 10_000) return `${trim1(n / 1_000)}K`;
+	if (n < 1_000_000) return `${Math.round(n / 1_000)}K`;
+	if (n < 10_000_000) return `${trim1(n / 1_000_000)}M`;
+	if (n < 1_000_000_000) return `${Math.round(n / 1_000_000)}M`;
+	if (n < 10_000_000_000) return `${trim1(n / 1_000_000_000)}B`;
+	return `${Math.round(n / 1_000_000_000)}B`;
+}
+
+/** Format with up to 1 decimal place, dropping trailing `.0`. */
+function trim1(n: number): string {
+	const s = n.toFixed(1);
+	return s.endsWith(".0") ? s.slice(0, -2) : s;
+}
+
+/**
+ * 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 @sayknow-cli/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)}%`;
+}