@linxiraos/pi-utils 1.0.0

package/dist/types/file-lock.d.ts

@@ -0,0 +1,23 @@
+import { FileLock as NativeFileLock } from "@linxiraos/pi-natives";
+/** Controls bounded waiting when an advisory file lock is contended. */
+export interface FileLockOptions {
+    /** Maximum acquisition attempts, including the initial attempt. */
+    retries?: number;
+    /** Delay between acquisition attempts. */
+    retryDelayMs?: number;
+    /** Maximum age of the lock before it is considered stale and can be broken. */
+    staleMs?: number;
+}
+declare function getLockPath(filePath: string): string;
+declare function tryAcquireLock(lockPath: string): NativeFileLock | null;
+/** Run `fn` while holding an OS-backed exclusive lock for `filePath`. */
+export declare function withFileLock<T>(filePath: string, fn: () => Promise<T>, options?: FileLockOptions): Promise<T>;
+/**
+ * Test-only acquisition handle for forcing ownership handoffs. This is not
+ * part of the supported package API.
+ */
+export declare const __internalsForTesting: {
+    tryAcquireLock: typeof tryAcquireLock;
+    getLockPath: typeof getLockPath;
+};
+export {};

package/dist/types/format.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Format a duration in milliseconds to a short human-readable string.
+ * Examples: "123ms", "1.5s", "30m15s", "2h30m", "3d2h"
+ */
+export declare function formatDuration(ms: number): string;
+/**
+ * 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 declare function formatNumber(n: number): string;
+/**
+ * Format a byte count to a human-readable string.
+ * Examples: "512B", "1.5KB", "2.3MB", "1.2GB"
+ */
+export declare function formatBytes(bytes: number): string;
+/**
+ * Truncate a string to maxLen characters, appending an ellipsis if truncated.
+ * For display-width-aware truncation (terminals), use truncateToWidth from @linxiraos/pi-tui.
+ */
+export declare function truncate(str: string, maxLen: number, ellipsis?: string): string;
+/**
+ * Format count with pluralized label (e.g., "3 files", "1 error").
+ */
+export declare function formatCount(label: string, count: number): string;
+/**
+ * Format age from seconds to human-readable string.
+ */
+export declare function formatAge(ageSeconds: number | null | undefined): string;
+/**
+ * Pluralize a label based on the count.
+ */
+export declare function pluralize(label: string, count: number): string;
+/**
+ * Format a ratio as a percentage.
+ */
+export declare function formatPercent(ratio: number): string;

package/dist/types/frontmatter.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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 declare function normalizeFrontmatterKeys<T>(obj: T): T;
+export declare class FrontmatterError extends Error {
+    readonly source?: unknown;
+    constructor(error: Error, source?: unknown);
+    toString(): string;
+}
+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 declare function parseFrontmatter(content: string, options?: FrontmatterOptions): {
+    frontmatter: Record<string, unknown>;
+    body: string;
+};

package/dist/types/fs-error.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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 declare function isFsError(err: unknown): err is FsError;
+export declare function isEnoent(err: unknown): err is FsError;
+export declare function isEacces(err: unknown): err is FsError;
+export declare function isEisdir(err: unknown): err is FsError;
+export declare function isEnotdir(err: unknown): err is FsError;
+export declare function isEexist(err: unknown): err is FsError;
+export declare function isEnotempty(err: unknown): err is FsError;
+export declare function hasFsCode(err: unknown, code: string): err is FsError;

package/dist/types/glob.d.ts

@@ -0,0 +1,28 @@
+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;
+}
+/**
+ * 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 declare function loadGitignorePatterns(baseDir: string): Promise<string[]>;
+/**
+ * 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 declare function globPaths(patterns: string | string[], options?: GlobPathsOptions): Promise<string[]>;

package/dist/types/headers.d.ts

@@ -0,0 +1,34 @@
+/** 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>;
+/** Generates coherent modern desktop browser navigation headers. */
+export declare class HeaderGenerator {
+    #private;
+    /** Creates a generator with reusable constraints and an optionally injectable RNG. */
+    constructor(options?: Partial<HeaderGeneratorOptions>);
+    /** Generates one header set, applying per-call constraints and request overrides. */
+    getHeaders(options?: Partial<HeaderGeneratorOptions>, overrides?: Headers): Headers;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,39 @@
+export { once, untilAborted } from "./abortable.js";
+export * from "./async.js";
+export * from "./binary.js";
+export * from "./color.js";
+export * from "./dirs.js";
+export * from "./env.js";
+export * from "./fetch-retry.js";
+export * from "./file-lock.js";
+export * from "./format.js";
+export * from "./frontmatter.js";
+export * from "./fs-error.js";
+export * from "./glob.js";
+export * from "./json.js";
+export * from "./json-parse.js";
+export * as logger from "./logger.js";
+export * from "./loop-phase.js";
+export * from "./mermaid-ascii.js";
+export * from "./mime.js";
+export * from "./path.js";
+export * from "./path-tree.js";
+export * from "./peek-file.js";
+export * as postmortem from "./postmortem.js";
+export * from "./process-name.js";
+export * as procmgr from "./procmgr.js";
+export * as prompt from "./prompt.js";
+export * as ptree from "./ptree.js";
+export { AbortError, ChildProcess, Exception, NonZeroExitError } from "./ptree.js";
+export * from "./runtime-install.js";
+export * from "./sanitize-text.js";
+export * from "./snowflake.js";
+export * from "./stderr-guard.js";
+export * from "./stream.js";
+export * from "./tab-spacing.js";
+export * from "./temp.js";
+export * from "./tls-fetch.js";
+export * from "./type-guards.js";
+export * from "./version.js";
+export * from "./which.js";
+export declare function structuredCloneJSON<T>(value: T): T;

package/dist/types/json-parse.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Lightweight string-level repair of the escape/control-char hazards that make
+ * otherwise-valid JSON fail `JSON.parse`: raw control characters inside strings
+ * are escaped, and invalid `\x` escapes have their backslash escaped. Returns the
+ * input unchanged when no repair is needed. Pure string→string; does not parse.
+ */
+export declare function repairJson(json: string): string;
+/**
+ * Final-parse a JSON value, repairing the common LLM malformations
+ * ({@link RelaxedJson}). Tries strict `JSON.parse` first (fast path, exact JSON
+ * semantics), then the relaxed parser. Throws when the input is unrepairable,
+ * truncated, or carries trailing garbage — so callers can skip a bad tool call
+ * rather than execute a half-formed one.
+ */
+export declare function parseJsonWithRepair<T>(json: string): T;
+/**
+ * Parse possibly-incomplete JSON during streaming. Always returns a value, never
+ * throws: `{}` for empty/whitespace/unrecoverable buffers, and an auto-closed
+ * best-effort object for truncated ones.
+ */
+export declare function parseStreamingJson<T = Record<string, unknown>>(partialJson: string | undefined): T;
+/**
+ * Default minimum byte growth before `parseStreamingJsonThrottled` will
+ * re-parse a streaming tool-call argument buffer. Bounds the mid-stream
+ * partial-parse cost from quadratic to linear in N.
+ */
+export declare const STREAMING_JSON_PARSE_MIN_GROWTH = 256;
+/**
+ * Throttled variant of {@link parseStreamingJson} for the per-delta hot path.
+ *
+ * Tool calls arrive as a long sequence of small deltas — calling
+ * `parseStreamingJson(buffer)` on every delta re-parses the entire buffer
+ * each time, giving O(N²) work in the total buffer length. Throttling skips
+ * the re-parse until at least `minGrowthBytes` of new content has arrived
+ * since the last successful parse, bounding mid-stream cost to O(N).
+ *
+ * Each provider tracks the last parsed length on its tool-call block, so the
+ * final `toolcall_end` parse (which providers already perform unconditionally)
+ * is the authoritative full parse — the throttle only delays mid-stream UI
+ * updates by at most `minGrowthBytes` of accumulated partial content.
+ *
+ * @returns the parsed object plus the new `parsedLen` to persist; or `null`
+ *          when the buffer has not grown enough to warrant a re-parse.
+ */
+export declare function parseStreamingJsonThrottled<T = Record<string, unknown>>(partialJson: string | undefined, lastParsedLen: number, minGrowthBytes?: number): {
+    value: T;
+    parsedLen: number;
+} | null;
+/**
+ * Classification of a streaming buffer against strict JSON (RFC 8259):
+ * - `"complete"`: exactly one whole JSON value (plus surrounding whitespace).
+ * - `"prefix"`: a proper prefix of some valid JSON value — more bytes can
+ *   still complete it.
+ * - `"invalid"`: no suffix can ever make it valid strict JSON (e.g. a raw
+ *   control character inside a string, or a second top-level value).
+ */
+export type JsonPrefixState = "complete" | "prefix" | "invalid";
+/**
+ * Classify `text` as a strict-JSON value, prefix, or dead end.
+ *
+ * Providers use this to disambiguate identifierless streaming tool-call
+ * deltas: a chunk starting with `{` is a *new* sibling call only if the
+ * current call's argument buffer cannot absorb it — the buffer is already a
+ * complete value, already unsalvageable (lossy hosts abandon buffers
+ * mid-string, leaving raw control characters strict JSON forbids), or the
+ * concatenation would break it. Unlike {@link parseStreamingJson} this is
+ * deliberately strict: forgiving repair would mask exactly the corruption
+ * signals the caller needs.
+ *
+ * A top-level number at end-of-input classifies as `"complete"` even though
+ * more digits could extend it; tool-argument buffers are always objects, so
+ * the ambiguity is immaterial here.
+ */
+export declare function classifyJsonPrefix(text: string): JsonPrefixState;

package/dist/types/json.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Try to parse JSON, returning null on failure.
+ */
+export declare function tryParseJson<T = unknown>(content: string): T | null;
+/**
+ * Serialize JSON while preserving bigint precision as decimal strings.
+ *
+ * Tool arguments normally arrive from JSON providers, but extension hooks and
+ * host integrations can supply JavaScript bigint values. Native
+ * `JSON.stringify` throws for those values, which makes otherwise valid agent
+ * history impossible to persist, replay, or compact. A decimal string is the
+ * only lossless JSON representation.
+ */
+export declare function stringifyJson(value: unknown, space?: string | number): string | undefined;

package/dist/types/logger/rotating-file.d.ts

@@ -0,0 +1,18 @@
+/** 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;
+}
+/** Synchronous append sink with local-day and size rotation plus bounded retention. */
+export declare class RotatingFileSink {
+    #private;
+    constructor(options: RotatingFileOptions);
+    /** Append one already-formatted log record. */
+    write(line: string): void;
+    /** Stop accepting records. Synchronous writes require no drain phase. */
+    close(): void;
+}

package/dist/types/logger.d.ts

@@ -0,0 +1,96 @@
+/** Severity names accepted by the centralized logger. */
+export type LogLevel = "error" | "warn" | "info" | "debug";
+/** Structured log event forwarded to out-of-band sinks such as OpenTelemetry. */
+export interface LogEvent {
+    readonly level: LogLevel;
+    readonly message: string;
+    readonly context: Record<string, unknown> | undefined;
+    readonly timestamp: Date;
+}
+/** Receives each structured log event after the local transport path runs. */
+export type LogSink = (event: LogEvent) => void;
+/** Register an out-of-band log sink and return a disposer. */
+export declare function registerLogSink(sink: LogSink): () => void;
+/**
+ * Replace the active log transports. Pass `console: true, file: false` for
+ * long-running services (the auth broker, etc.) that want their structured
+ * logs piped into a process supervisor instead of the rotating file.
+ */
+export declare function setTransports(opts: {
+    console?: boolean;
+    file?: boolean | string;
+}): void;
+/**
+ * Log an error message.
+ * @param message - The message to log.
+ * @param context - The context to log.
+ */
+export declare function error(message: string, context?: Record<string, unknown>): void;
+/**
+ * Log a warning message.
+ * @param message - The message to log.
+ * @param context - The context to log.
+ */
+export declare function warn(message: string, context?: Record<string, unknown>): void;
+/**
+ * Log an informational message.
+ * @param message - The message to log.
+ * @param context - The context to log.
+ */
+export declare function info(message: string, context?: Record<string, unknown>): void;
+/**
+ * Log a debug message.
+ * @param message - The message to log.
+ * @param context - The context to log.
+ */
+export declare function debug(message: string, context?: Record<string, unknown>): void;
+/**
+ * Streaming startup markers, enabled by `PI_DEBUG_STARTUP`. Unlike the
+ * PI_TIMING tree (printed only after startup completes), these write one
+ * synchronous stderr line as each phase begins/ends, so a hard hang still
+ * shows the last phase that started. `fs.writeSync(2)` is used deliberately:
+ * it cannot be reordered or buffered past a synchronous block of the event
+ * loop (dlopen, sync fs on a dead mount, spawnSync).
+ */
+export declare function startupMarker(text: string): void;
+export declare function timingModeIncludes(option: "full" | "x"): boolean;
+export declare function shouldExitAfterTimings(): boolean;
+/**
+ * Print collected timings as an indented tree.
+ * Each span shows wall duration; parents with children also show "(self)" for unattributed time.
+ * Sibling spans are sorted by start time. Spans whose intervals overlap with siblings ran in parallel.
+ */
+export declare function printTimings(): void;
+/**
+ * Begin recording startup timings under a new root span.
+ * Idempotent: a second call while already recording is a no-op, so an explicit
+ * starter (main.ts) and any future early starter can coexist.
+ */
+export declare function startTiming(): void;
+/**
+ * Record an externally-measured span as a leaf child of the active span (or root
+ * when no span is active). Used by {@link spliceModuleLoadBuffer} to fold
+ * preload-captured module windows into the tree.
+ */
+export declare function recordModuleLoadSpan(path: string, start: number, durationMs: number, bodyMs?: number, imports?: string[]): void;
+/**
+ * End timing window and clear buffers.
+ */
+export declare function endTiming(): void;
+/**
+ * Ops of the currently-open span chain (root → deepest), following the most
+ * recently started unfinished child at each level. Lets a startup watchdog
+ * name the phase a stalled startup is stuck in.
+ */
+export declare function openSpanPath(): string[];
+/**
+ * Time a span. Three forms:
+ *   time(op)                    — point event (zero-duration breadcrumb)
+ *   time(op, fn, ...args)        — wrap fn in a span; returns fn's return value (sync or Promise)
+ *
+ * Spans nest hierarchically via AsyncLocalStorage: a child started inside another span's fn
+ * (even across awaits) becomes that span's child. Parallel children are recorded as siblings
+ * with overlapping intervals.
+ */
+export declare function time(op: string): void;
+export declare function time<T, A extends unknown[]>(op: string, fn: (...args: A) => T, ...args: A): T;

package/dist/types/loop-phase.d.ts

@@ -0,0 +1,10 @@
+export declare function pushLoopPhase(label: string): void;
+export declare function popLoopPhase(): void;
+export declare function currentLoopPhase(): string | undefined;
+/**
+ * Phase to blame for a just-detected loop block: the live top phase if one is
+ * still held, else the most recent phase pushed since the last call. Clears the
+ * recent slot so a block in a later, phase-less interval is not misattributed
+ * to a phase that already finished.
+ */
+export declare function takeRecentLoopPhase(): string | undefined;

package/dist/types/lru.d.ts

@@ -0,0 +1,46 @@
+/** 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;
+}
+/** A bounded least-recently-used cache with optional size and lifetime limits. */
+export declare class LRUCache<K, V> {
+    #private;
+    /** Creates an empty cache. */
+    constructor(options: LRUCacheOptions<K, V>);
+    /** Number of entries, including stale entries not yet removed by `get`. */
+    get size(): number;
+    /** Aggregate calculated size of retained entries. */
+    get calculatedSize(): number;
+    /** Stores a value and makes it most recently used. */
+    set(key: K, value: V | undefined): this;
+    /** Returns a value and makes a fresh entry most recently used. */
+    get(key: K): V | undefined;
+    /** Reports whether a fresh value is present without changing recency. */
+    has(key: K): boolean;
+    /** Returns a fresh value without changing recency or removing stale data. */
+    peek(key: K): V | undefined;
+    /** Removes a value, returning whether one was present. */
+    delete(key: K): boolean;
+    /** Removes every value from least to most recently used. */
+    clear(): void;
+    /** Iterates fresh keys from most to least recently used. */
+    keys(): Generator<K, void, unknown>;
+    /** Iterates fresh values from most to least recently used. */
+    values(): Generator<V, void, unknown>;
+}