@oh-my-pi/pi-utils 15.1.0 → 15.1.2

package/dist/types/abortable.d.ts

@@ -0,0 +1,27 @@
+export declare class AbortError extends Error {
+    constructor(signal: AbortSignal);
+}
+/**
+ * Creates an abortable stream from a given stream and signal.
+ *
+ * @param stream - The stream to make abortable
+ * @param signal - The signal to abort the stream
+ * @returns The abortable stream
+ */
+export declare function createAbortableStream<T>(stream: ReadableStream<T>, signal?: AbortSignal): ReadableStream<T>;
+/**
+ * Runs a promise-returning function (`pr`). If the given AbortSignal is aborted before or during
+ * execution, the promise is rejected with a standard error.
+ *
+ * @param signal - Optional AbortSignal to cancel the operation
+ * @param pr - Function returning a promise to run
+ * @returns Promise resolving as `pr` would, or rejecting on abort
+ */
+export declare function untilAborted<T>(signal: AbortSignal | undefined | null, pr: Promise<T> | (() => Promise<T>)): Promise<T>;
+/**
+ * Memoizes a function with no arguments, calling it once and caching the result.
+ *
+ * @param fn - Function to be called once
+ * @returns A function that returns the cached result of `fn`
+ */
+export declare function once<T>(fn: () => T): () => T;

package/dist/types/async.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Wrap a promise with a timeout and optional abort signal.
+ * Rejects with the given message if the timeout fires first.
+ * Cleans up all listeners on settlement.
+ */
+export declare function withTimeout<T>(promise: Promise<T>, ms: number, message: string, signal?: AbortSignal): Promise<T>;

package/dist/types/cli.d.ts

@@ -0,0 +1,117 @@
+export interface FlagDescriptor<K extends "string" | "boolean" | "integer" = "string" | "boolean" | "integer"> {
+    kind: K;
+    description?: string;
+    char?: string;
+    default?: unknown;
+    multiple?: boolean;
+    options?: readonly string[];
+    required?: boolean;
+}
+export interface ArgDescriptor {
+    kind: "string";
+    description?: string;
+    required?: boolean;
+    multiple?: boolean;
+    options?: readonly string[];
+}
+interface FlagInput {
+    description?: string;
+    char?: string;
+    default?: unknown;
+    multiple?: boolean;
+    options?: readonly string[];
+    required?: boolean;
+}
+interface ArgInput {
+    description?: string;
+    required?: boolean;
+    multiple?: boolean;
+    options?: readonly string[];
+}
+/** Builders that match the `Flags.*()` / `Args.*()` API from oclif. */
+export declare const Flags: {
+    string<T extends FlagInput>(opts?: T): FlagDescriptor<"string"> & T;
+    boolean<T_1 extends FlagInput>(opts?: T_1): FlagDescriptor<"boolean"> & T_1;
+    integer<T_2 extends FlagInput & {
+        default?: number;
+    }>(opts?: T_2): FlagDescriptor<"integer"> & T_2;
+};
+export declare const Args: {
+    string<T extends ArgInput>(opts?: T): ArgDescriptor & T;
+};
+type FlagValue<D extends FlagDescriptor> = D["kind"] extends "boolean" ? D extends {
+    default: boolean;
+} ? boolean : boolean | undefined : D["kind"] extends "integer" ? D extends {
+    default: number;
+} ? number : number | undefined : D extends {
+    multiple: true;
+} ? string[] | undefined : string | undefined;
+type ArgValue<D extends ArgDescriptor> = D extends {
+    multiple: true;
+} ? string[] | undefined : string | undefined;
+type FlagValues<T extends Record<string, FlagDescriptor>> = {
+    [K in keyof T]: FlagValue<T[K]>;
+};
+type ArgValues<T extends Record<string, ArgDescriptor>> = {
+    [K in keyof T]: ArgValue<T[K]>;
+};
+export interface ParseOutput<F extends Record<string, FlagDescriptor> = Record<string, FlagDescriptor>, A extends Record<string, ArgDescriptor> = Record<string, ArgDescriptor>> {
+    flags: FlagValues<F>;
+    args: ArgValues<A>;
+    argv: string[];
+}
+export interface CommandCtor {
+    new (argv: string[], config: CliConfig): Command;
+    description?: string;
+    hidden?: boolean;
+    strict?: boolean;
+    aliases?: string[];
+    examples?: string[];
+    flags?: Record<string, FlagDescriptor>;
+    args?: Record<string, ArgDescriptor>;
+}
+/** Configuration passed to every command instance and help renderers. */
+export interface CliConfig {
+    bin: string;
+    version: string;
+    /** All registered commands keyed by their canonical name. */
+    commands: Map<string, CommandCtor>;
+}
+/** Minimal Command base matching the oclif surface we use. */
+export declare abstract class Command {
+    argv: string[];
+    config: CliConfig;
+    constructor(argv: string[], config: CliConfig);
+    abstract run(): Promise<void>;
+    /**
+     * Parse argv against the static `flags` and `args` declared on the
+     * concrete command class. Returns a typed `{ flags, args, argv }` object.
+     */
+    parse<C extends CommandCtor>(_Cmd: C): Promise<ParseOutput<NonNullable<C["flags"]> extends Record<string, FlagDescriptor> ? NonNullable<C["flags"]> : Record<string, FlagDescriptor>, NonNullable<C["args"]> extends Record<string, ArgDescriptor> ? NonNullable<C["args"]> : Record<string, ArgDescriptor>>>;
+}
+/** Render full root help: header, default command details, subcommand list. */
+export declare function renderRootHelp(config: CliConfig): void;
+/** Render help for a single command. */
+export declare function renderCommandHelp(bin: string, id: string, Cmd: CommandCtor): void;
+/** A lazily-loaded command: canonical name, loader, and optional aliases. */
+export interface CommandEntry {
+    name: string;
+    load: () => Promise<CommandCtor>;
+    aliases?: string[];
+}
+export interface RunOptions {
+    bin: string;
+    version: string;
+    argv: string[];
+    commands: CommandEntry[];
+    /** Custom help renderer. Receives fully-populated config. */
+    help?: (config: CliConfig) => Promise<void> | void;
+}
+/**
+ * Main entry point — replaces `run()` from @oclif/core.
+ *
+ * Each command is explicitly registered with a lazy loader.
+ * No filesystem scanning, no plugin system, no package.json reading.
+ */
+export declare function run(opts: RunOptions): Promise<void>;
+export {};

package/dist/types/color.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Color manipulation utilities for hex colors.
+ *
+ * @example
+ * ```ts
+ * import { hexToHsv, hsvToHex } from "@oh-my-pi/pi-utils";
+ *
+ * // Work with HSV directly
+ *
+ * // Or work with HSV directly
+ * const hsv = hexToHsv("#4ade80");
+ * hsv.h = (hsv.h + 90) % 360;
+ * const newHex = hsvToHex(hsv);
+ * ```
+ */
+export interface HSV {
+    /** Hue in degrees (0-360) */
+    h: number;
+    /** Saturation (0-1) */
+    s: number;
+    /** Value/brightness (0-1) */
+    v: number;
+}
+export interface RGB {
+    /** Red (0-255) */
+    r: number;
+    /** Green (0-255) */
+    g: number;
+    /** Blue (0-255) */
+    b: number;
+}
+/**
+ * Parse a hex color string to RGB.
+ * Supports #RGB, #RRGGBB formats.
+ */
+export declare function hexToRgb(hex: string): RGB;
+/**
+ * Convert RGB to hex color string.
+ */
+export declare function rgbToHex(rgb: RGB): string;
+/**
+ * Convert RGB to HSV.
+ */
+export declare function rgbToHsv(rgb: RGB): HSV;
+/**
+ * Convert HSV to RGB.
+ */
+export declare function hsvToRgb(hsv: HSV): RGB;
+/**
+ * Convert hex color to HSV.
+ */
+export declare function hexToHsv(hex: string): HSV;
+/**
+ * Convert HSV to hex color.
+ */
+export declare function hsvToHex(hsv: HSV): string;
+/**
+ * Shift the hue of a hex color by a given number of degrees.
+ */
+export declare function shiftHue(hex: string, degrees: number): string;
+export interface HSVAdjustment {
+    /** Hue shift in degrees (additive) */
+    h?: number;
+    /** Saturation multiplier */
+    s?: number;
+    /** Value/brightness multiplier */
+    v?: number;
+}
+/**
+ * Adjust HSV components of a hex color.
+ *
+ * @param hex - Hex color string (#RGB or #RRGGBB)
+ * @param adj - Adjustments: h is additive degrees, s and v are multipliers
+ * @returns New hex color string
+ *
+ * @example
+ * ```ts
+ * // Shift hue +60°, reduce saturation to 71%
+ * adjustHsv("#00ff88", { h: 60, s: 0.71 }) // "#4a9eff"
+ * ```
+ */
+export declare function adjustHsv(hex: string, adj: HSVAdjustment): string;

package/dist/types/dirs.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Centralized path helpers for omp config directories.
+ *
+ * Uses PI_CONFIG_DIR (default ".omp") for the config root and
+ * PI_CODING_AGENT_DIR to override the agent directory.
+ *
+ * On Linux, if XDG_DATA_HOME / XDG_STATE_HOME / XDG_CACHE_HOME environment
+ * variables are set, paths are redirected to XDG-compliant locations under
+ * $XDG_*_HOME/omp/. This requires running `omp config migrate` first to
+ * move data to the new locations. No filesystem existence checks are performed
+ * — if the env var is set, omp trusts that the migration has been done.
+ */
+/** App name (e.g. "omp") */
+export declare const APP_NAME: string;
+/** Config directory name (e.g. ".omp") */
+export declare const CONFIG_DIR_NAME: string;
+/** Version (e.g. "1.0.0") */
+export declare const VERSION: string;
+/** Minimum Bun version */
+export declare const MIN_BUN_VERSION: string;
+export declare function resolveEquivalentPath(inputPath: string): string;
+export declare function normalizePathForComparison(inputPath: string): string;
+export declare function pathIsWithin(root: string, candidate: string): boolean;
+export declare function relativePathWithinRoot(root: string, candidate: string): string | null;
+/** Get the project directory. */
+export declare function getProjectDir(): string;
+/** Set the project directory. */
+export declare function setProjectDir(dir: string): void;
+/** Get the config directory name relative to home (e.g. ".omp" or PI_CONFIG_DIR override). */
+export declare function getConfigDirName(): string;
+/** Get the config agent directory name relative to home (e.g. ".omp/agent" or PI_CONFIG_DIR + "/agent"). */
+export declare function getConfigAgentDirName(): string;
+/** Get the config root directory (~/.omp). */
+export declare function getConfigRootDir(): string;
+/** Set the coding agent directory. Creates a fresh resolver, invalidating all cached paths. */
+export declare function setAgentDir(dir: string): void;
+/** Get the agent config directory (~/.omp/agent). */
+export declare function getAgentDir(): string;
+/** Get the project-local config directory (.omp). */
+export declare function getProjectAgentDir(cwd?: string): string;
+/** Get the reports directory (~/.omp/reports). */
+export declare function getReportsDir(): string;
+/** Get the logs directory (~/.omp/logs). */
+export declare function getLogsDir(): string;
+/** Get the path to a dated log file (~/.omp/logs/omp.YYYY-MM-DD.log). */
+export declare function getLogPath(date?: Date): string;
+/**
+ * Get the plugins directory (~/.omp/plugins or its XDG equivalent).
+ *
+ * No-arg form (production callers) goes through the XDG-aware DirResolver so
+ * reads and writes always agree. The optional `home` parameter is for test
+ * isolation: when it differs from `os.homedir()` it short-circuits the resolver
+ * and returns `<home>/<configDir>/plugins` so tests with a temp HOME get a
+ * deterministic path. Passing `os.homedir()` explicitly is identical to the
+ * no-arg form — XDG semantics are preserved.
+ */
+export declare function getPluginsDir(home?: string): string;
+/** Where npm installs packages (~/.omp/plugins/node_modules). */
+export declare function getPluginsNodeModules(): string;
+/** Plugin manifest (~/.omp/plugins/package.json). */
+export declare function getPluginsPackageJson(): string;
+/** Plugin lock file (~/.omp/plugins/omp-plugins.lock.json). */
+export declare function getPluginsLockfile(): string;
+/** Get the remote mount directory (~/.omp/remote). */
+export declare function getRemoteDir(): string;
+/** Get the PR worktrees directory (~/.omp/wt). */
+export declare function getWorktreesDir(): string;
+/** Get the SSH control socket directory (~/.omp/ssh-control). */
+export declare function getSshControlDir(): string;
+/** Get the remote host info directory (~/.omp/remote-host). */
+export declare function getRemoteHostDir(): string;
+/** Get the managed Python venv directory (~/.omp/python-env). */
+export declare function getPythonEnvDir(): string;
+/** Get the shared Python gateway state directory (~/.omp/agent/python-gateway; XDG default: $XDG_STATE_HOME/omp/python-gateway). */
+export declare function getPythonGatewayDir(): string;
+/** Get the puppeteer sandbox directory (~/.omp/puppeteer). */
+export declare function getPuppeteerDir(): string;
+/** Get the worktree base directory (~/.omp/wt). */
+export declare function getWorktreeBaseDir(): string;
+/** Get the path to a worktree directory (~/.omp/wt/<project>/<id>). */
+export declare function getWorktreeDir(encodedProject: string, id: string): string;
+/** Get the GPU cache path (~/.omp/gpu_cache.json). */
+export declare function getGpuCachePath(): string;
+/**
+ * Get the GitHub view cache database path (~/.omp/cache/github-cache.db).
+ * Honors the `OMP_GITHUB_CACHE_DB` env var when set so tests can isolate the
+ * cache file without touching the rest of the config root.
+ */
+export declare function getGithubCacheDbPath(): string;
+/** Get the natives directory (~/.omp/natives). */
+export declare function getNativesDir(): string;
+/** Get the stats database path (~/.omp/stats.db). */
+export declare function getStatsDbPath(): string;
+/** Get the autoresearch state directory (~/.omp/autoresearch). */
+export declare function getAutoresearchDir(): string;
+/** Get the per-project autoresearch state directory (~/.omp/autoresearch/<encoded-project>). */
+export declare function getAutoresearchProjectDir(encodedProject: string): string;
+/** Get the per-project autoresearch SQLite database path (~/.omp/autoresearch/<encoded-project>.db). */
+export declare function getAutoresearchDbPath(encodedProject: string): string;
+/** Get the per-run artifact directory (~/.omp/autoresearch/<encoded-project>/runs/<runId>). */
+export declare function getAutoresearchRunDir(encodedProject: string, runId: number): string;
+/** Get the path to agent.db (SQLite database for settings and auth storage). */
+export declare function getAgentDbPath(agentDir?: string): string;
+/** Get the path to history.db (SQLite database for session history). */
+export declare function getHistoryDbPath(agentDir?: string): string;
+/** Get the path to models.db (model cache database). */
+export declare function getModelDbPath(agentDir?: string): string;
+/** Get the sessions directory (~/.omp/agent/sessions). */
+export declare function getSessionsDir(agentDir?: string): string;
+/** Get the content-addressed blob store directory (~/.omp/agent/blobs). */
+export declare function getBlobsDir(agentDir?: string): string;
+/** Get the custom themes directory (~/.omp/agent/themes). */
+export declare function getCustomThemesDir(agentDir?: string): string;
+/** Get the tools directory (~/.omp/agent/tools). */
+export declare function getToolsDir(agentDir?: string): string;
+/** Get the slash commands directory (~/.omp/agent/commands). */
+export declare function getCommandsDir(agentDir?: string): string;
+/** Get the prompts directory (~/.omp/agent/prompts). */
+export declare function getPromptsDir(agentDir?: string): string;
+/** Get the user-level Python modules directory (~/.omp/agent/modules). */
+export declare function getAgentModulesDir(agentDir?: string): string;
+/** Get the memories directory (~/.omp/agent/memories). */
+export declare function getMemoriesDir(agentDir?: string): string;
+/** Get the terminal sessions directory (~/.omp/agent/terminal-sessions). */
+export declare function getTerminalSessionsDir(agentDir?: string): string;
+/** Get the crash log path (~/.omp/agent/omp-crash.log). */
+export declare function getCrashLogPath(agentDir?: string): string;
+/** Get the debug log path (~/.omp/agent/omp-debug.log). */
+export declare function getDebugLogPath(agentDir?: string): string;
+/** Get the project-level Python modules directory (.omp/modules). */
+export declare function getProjectModulesDir(cwd?: string): string;
+/** Get the project-level prompts directory (.omp/prompts). */
+export declare function getProjectPromptsDir(cwd?: string): string;
+/** Get the project-level plugin overrides path (.omp/plugin-overrides.json). */
+export declare function getProjectPluginOverridesPath(cwd?: string): string;
+/** Get the primary MCP config file path (first candidate). */
+export declare function getMCPConfigPath(scope: "user" | "project", cwd?: string): string;
+/** Get the SSH config file path. */
+export declare function getSSHConfigPath(scope: "user" | "project", cwd?: string): string;

package/dist/types/env.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Intentional re-export of Bun.env.
+ *
+ * All users should import this env module (import { $env } from "@oh-my-pi/pi-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.
+ */
+export declare const $env: 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 declare function $pickenv(...keys: string[]): string | undefined;
+/**
+ * Parses a positive decimal integer from `$env[name]`.
+ * Empty, invalid, NaN, zero, or negative values return `defaultValue`.
+ */
+export declare function $envpos(name: string, defaultValue: number): number;
+/** True when `BUN_ENV` or `NODE_ENV` is the string `test`. */
+export declare function isBunTestRuntime(): boolean;
+/**
+ * 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 declare function isCompiledBinary(): boolean;
+export declare function $flag(name: string, def?: boolean): boolean;

package/dist/types/fetch-retry.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Server-suggested retry delay extraction. Merges the patterns historically used
+ * by the OpenAI Codex 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 declare function extractRetryHint(source: Response | Headers | null | undefined, body?: string): number | 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>;
+}
+/**
+ * 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 declare function fetchWithRetry(url: string | URL | ((attempt: number) => string | URL), options?: FetchWithRetryOptions): Promise<Response>;
+/**
+ * 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 (429)` or `HTTP 503`.
+ */
+export declare function extractHttpStatusFromError(error: unknown): number | 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 declare function isRetryableStatus(status: number): boolean;
+/**
+ * `true` if the message describes an unexpected socket closure — Bun and some
+ * proxies surface these for any HTTP/2 stream reset.
+ */
+export declare function isUnexpectedSocketCloseMessage(message: string): boolean;
+/**
+ * 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 declare function isRetryableError(error: unknown): boolean;

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 @oh-my-pi/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,25 @@
+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";
+}
+/**
+ * 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 "@oh-my-pi/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/hook-fetch.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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 declare function hookFetch(handler: FetchHandler): Disposable;

package/dist/types/index.d.ts

@@ -0,0 +1,28 @@
+export { createAbortableStream, once, untilAborted } from "./abortable";
+export * from "./async";
+export * from "./color";
+export * from "./dirs";
+export * from "./env";
+export * from "./fetch-retry";
+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 * as prompt from "./prompt";
+export * as ptree from "./ptree";
+export { AbortError, ChildProcess, Exception, NonZeroExitError } from "./ptree";
+export * from "./snowflake";
+export * from "./stream";
+export * from "./tab-spacing";
+export * from "./temp";
+export * from "./type-guards";
+export * from "./which";
+export declare function structuredCloneJSON<T>(value: T): T;

package/dist/types/json.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Try to parse JSON, returning null on failure.
+ */
+export declare function tryParseJson<T = unknown>(content: string): T | null;

package/dist/types/logger.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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 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;
+/**
+ * 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 that side-effect
+ * starters (see module-timer.ts) and explicit starters (main.ts) 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 the module-load timing plugin to splice load
+ * events into the tree retroactively.
+ */
+export declare function recordModuleLoadSpan(path: string, start: number, durationMs: number): void;
+/**
+ * End timing window and clear buffers.
+ */
+export declare function endTiming(): void;
+/**
+ * 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/mermaid-ascii.d.ts

@@ -0,0 +1,11 @@
+import { type AsciiRenderOptions } from "beautiful-mermaid";
+export type { AsciiRenderOptions as MermaidAsciiRenderOptions };
+export declare function renderMermaidAscii(source: string, options?: AsciiRenderOptions): string;
+export declare function renderMermaidAsciiSafe(source: string, options?: AsciiRenderOptions): string | null;
+/**
+ * Extract mermaid code blocks from markdown text.
+ */
+export declare function extractMermaidBlocks(markdown: string): {
+    source: string;
+    hash: bigint | number;
+}[];

package/dist/types/mime.d.ts

@@ -0,0 +1,29 @@
+export declare const SUPPORTED_IMAGE_MIME_TYPES: Set<string>;
+export type ImageMetadata = {
+    mimeType: "image/png";
+    width?: number;
+    height?: number;
+    channels?: number;
+    hasAlpha?: boolean;
+} | {
+    mimeType: "image/jpeg";
+    width?: number;
+    height?: number;
+    channels?: number;
+    hasAlpha?: false;
+} | {
+    mimeType: "image/gif";
+    width?: number;
+    height?: number;
+    channels?: 3;
+    hasAlpha?: never;
+} | {
+    mimeType: "image/webp";
+    width?: number;
+    height?: number;
+    channels?: number;
+    hasAlpha?: boolean;
+};
+export declare function parseImageMetadata(header: Uint8Array): ImageMetadata | null;
+export declare function readImageMetadataSync(filePath: string, maxBytes?: number): ImageMetadata | null;
+export declare function readImageMetadata(filePath: string, maxBytes?: number): Promise<ImageMetadata | null>;

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

@@ -0,0 +1,9 @@
+/**
+ * Synchronously reads up to `maxBytes` from the start of `filePath` and returns `op(header)`.
+ * If the file is shorter, `header` is only the bytes actually read.
+ */
+export declare function peekFileSync<T>(filePath: string, maxBytes: number, op: (header: Uint8Array) => T): T;
+/**
+ * Like {@link peekFileSync} but uses async I/O.
+ */
+export declare function peekFile<T>(filePath: string, maxBytes: number, op: (header: Uint8Array) => T): Promise<T>;

package/dist/types/postmortem.d.ts

@@ -0,0 +1,29 @@
+export declare enum Reason {
+    PRE_EXIT = "pre_exit",// Pre-exit phase (not used by default)
+    EXIT = "exit",// Normal process exit
+    SIGINT = "sigint",// Ctrl-C or SIGINT
+    SIGTERM = "sigterm",// SIGTERM
+    SIGHUP = "sighup",// SIGHUP
+    UNCAUGHT_EXCEPTION = "uncaught_exception",// Fatal exception
+    UNHANDLED_REJECTION = "unhandled_rejection",// Unhandled promise rejection
+    MANUAL = "manual"
+}
+/**
+ * Register a process cleanup callback, to be run on shutdown, signal, or fatal error.
+ *
+ * Returns a Callback instance that can be used to cancel (unregister) or manually clean up.
+ * If register is called after cleanup already began, invokes callback on a microtask.
+ */
+export declare function register(id: string, callback: (reason: Reason) => void | Promise<void>): () => void;
+/**
+ * Runs all cleanup callbacks without exiting.
+ * Use this in workers or when you need to clean up but continue execution.
+ */
+export declare function cleanup(): Promise<void>;
+/**
+ * Runs all cleanup callbacks and exits.
+ *
+ * In main thread: waits for stdout drain, then calls process.exit().
+ * In workers: runs cleanup only (process.exit would kill entire process).
+ */
+export declare function quit(code?: number): Promise<void>;

package/dist/types/procmgr.d.ts

@@ -0,0 +1,35 @@
+import type { Subprocess } from "bun";
+export interface ShellConfig {
+    shell: string;
+    args: string[];
+    env: Record<string, string>;
+    prefix: string | undefined;
+}
+/**
+ * Strip disabled macOS malloc-stack-logging vars from `process.env` in place.
+ *
+ * macOS leaves `MallocStackLogging=0` (or similar) inherited by debug-attached
+ * shells. Bun's libc init then prints `MallocStackLogging: can't turn off
+ * malloc stack logging because it was not enabled.` to stderr for every
+ * subprocess. Scrubbing once at startup means every child we spawn — bash,
+ * bun subagents, plugin installs, ptree commands — inherits a clean env.
+ */
+export declare function scrubProcessEnv(): void;
+/**
+ * Resolve a basic shell (bash or sh) as fallback.
+ */
+export declare function resolveBasicShell(): string | undefined;
+/**
+ * Get shell configuration based on platform.
+ * Resolution order:
+ * 1. User-specified shellPath in settings.json
+ * 2. On Windows: Git Bash in known locations, then bash on PATH
+ * 3. On Unix: $SHELL if bash/zsh, then fallback paths
+ * 4. Fallback: sh
+ */
+export declare function getShellConfig(customShellPath?: string): ShellConfig;
+/**
+ * Check if a process is running.
+ */
+export declare function isPidRunning(pid: number | Subprocess): boolean;
+export declare function onProcessExit(proc: Subprocess | number, abortSignal?: AbortSignal): Promise<boolean>;

package/dist/types/prompt.d.ts

@@ -0,0 +1,18 @@
+import type { HelperDelegate, HelperOptions, Template, TemplateDelegate } from "handlebars";
+export type { HelperDelegate, HelperOptions, Template, TemplateDelegate };
+export type PromptRenderPhase = "pre-render" | "post-render";
+export interface PromptFormatOptions {
+    renderPhase?: PromptRenderPhase;
+    replaceAsciiSymbols?: boolean;
+    normalizeRfc2119?: boolean;
+}
+export declare function format(content: string, options?: PromptFormatOptions): string;
+export interface TemplateContext extends Record<string, unknown> {
+    args?: string[];
+    ARGUMENTS?: string;
+    arguments?: string;
+}
+export declare function registerHelper(name: string, fn: HelperDelegate): void;
+export declare function registerPartial(name: string, fn: Template): void;
+export declare function compile(template: string): (context: TemplateContext) => string;
+export declare function render(template: string, context?: TemplateContext): string;

package/dist/types/ptree.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Process tree management utilities for Bun subprocesses.
+ *
+ * - Track managed child processes for cleanup on shutdown (postmortem).
+ * - Drain stdout/stderr to avoid subprocess pipe deadlocks.
+ * - Cross-platform tree kill for process groups (Windows taskkill, Unix -pid).
+ * - Convenience helpers: captureText / execText, AbortSignal, timeouts.
+ */
+import type { Spawn, Subprocess } from "bun";
+type InMask = "pipe" | "ignore" | Buffer | Uint8Array | null;
+/** A Bun subprocess with stdout/stderr always piped (stdin may vary). */
+type PipedSubprocess<In extends InMask = InMask> = Subprocess<In, "pipe", "pipe">;
+/**
+ * Base for all exceptions representing child process nonzero exit, killed, or
+ * cancellation.
+ */
+export declare abstract class Exception extends Error {
+    readonly exitCode: number;
+    readonly stderr: string;
+    constructor(message: string, exitCode: number, stderr: string);
+    abstract readonly aborted: boolean;
+}
+/** Exception for nonzero exit codes (not cancellation). */
+export declare class NonZeroExitError extends Exception {
+    static readonly MAX_TRACE: number;
+    constructor(exitCode: number, stderr: string);
+    get aborted(): boolean;
+}
+/** Exception for explicit process abortion (via signal). */
+export declare class AbortError extends Exception {
+    readonly reason: unknown;
+    constructor(reason: unknown, stderr: string);
+    get aborted(): boolean;
+}
+/** Exception for process timeout. */
+export declare class TimeoutError extends AbortError {
+    constructor(timeout: number, stderr: string);
+}
+/** Options for waiting for process exit and capturing output. */
+export interface WaitOptions {
+    allowNonZero?: boolean;
+    allowAbort?: boolean;
+    stderr?: "full" | "buffer";
+}
+/** Result from wait and exec. */
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    ok: boolean;
+    exitError?: Exception;
+}
+/**
+ * ChildProcess wraps a managed subprocess, capturing stderr tail, providing
+ * cross-platform kill/detach logic plus AbortSignal integration.
+ *
+ * Stdout is exposed directly from the underlying Bun subprocess; consumers
+ * must read it (via text(), wait(), etc.) to prevent pipe deadlock.
+ * Stderr is eagerly drained into an internal buffer.
+ */
+export declare class ChildProcess<In extends InMask = InMask> {
+    #private;
+    readonly proc: PipedSubprocess<In>;
+    readonly exposeStderr: boolean;
+    constructor(proc: PipedSubprocess<In>, exposeStderr: boolean);
+    get pid(): number;
+    get exited(): Promise<number>;
+    get exitCode(): number | null;
+    get exitReason(): Exception | undefined;
+    get killed(): boolean;
+    get stdin(): Bun.SpawnOptions.WritableToIO<In>;
+    /** Raw stdout stream. Must be consumed to prevent pipe deadlock. */
+    get stdout(): ReadableStream<Uint8Array<ArrayBuffer>>;
+    /** Optional stderr stream (only when requested in spawn options). */
+    get stderr(): ReadableStream<Uint8Array<ArrayBufferLike>> | undefined;
+    get exitedCleanly(): Promise<number>;
+    /** Returns the truncated stderr tail (last 32KB). */
+    peekStderr(): string;
+    nothrow(): this;
+    kill(reason?: Exception): void;
+    text(): Promise<string>;
+    blob(): Promise<Blob>;
+    json(): Promise<unknown>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    bytes(): Promise<Uint8Array>;
+    wait(opts?: WaitOptions): Promise<ExecResult>;
+    attachSignal(signal: AbortSignal): void;
+    attachTimeout(ms: number): void;
+    [Symbol.dispose](): void;
+}
+/** Options for child spawn. Always pipes stdout/stderr. */
+type ChildSpawnOptions<In extends InMask = InMask> = Omit<Spawn.SpawnOptions<In, "pipe", "pipe">, "stdout" | "stderr" | "detached"> & {
+    signal?: AbortSignal;
+    detached?: boolean;
+    stderr?: "full" | null;
+};
+/** Spawn a child process with piped stdout/stderr. */
+export declare function spawn<In extends InMask = InMask>(cmd: string[], opts?: ChildSpawnOptions<In>): ChildProcess<In>;
+/** Options for exec. */
+export interface ExecOptions extends Omit<ChildSpawnOptions, "stderr" | "stdin">, WaitOptions {
+    input?: string | Buffer | Uint8Array;
+}
+/** Spawn, wait, and return captured output. */
+export declare function exec(cmd: string[], opts?: ExecOptions): Promise<ExecResult>;
+type SignalValue = AbortSignal | number | null | undefined;
+/** Combine AbortSignals and timeout values into a single signal. */
+export declare function combineSignals(...signals: SignalValue[]): AbortSignal | undefined;
+export {};

package/dist/types/ring.d.ts

@@ -0,0 +1,93 @@
+/**
+ * A fixed-capacity circular buffer that supports efficient push/pop/shift/unshift operations.
+ * When the buffer is full, adding new items overwrites the oldest items (FIFO behavior).
+ *
+ * @template T The type of elements stored in the buffer.
+ */
+export declare class RingBuffer<T> {
+    #private;
+    readonly capacity: number;
+    /**
+     * Creates a new ring buffer with the specified capacity.
+     *
+     * @param capacity - The maximum number of elements the buffer can hold. Must be positive.
+     */
+    constructor(capacity: number);
+    /**
+     * The number of elements currently in the buffer.
+     */
+    get length(): number;
+    /**
+     * Whether the buffer is at full capacity.
+     */
+    get isFull(): boolean;
+    /**
+     * Whether the buffer is empty (contains no elements).
+     */
+    get isEmpty(): boolean;
+    /**
+     * Adds an item to the end of the buffer.
+     * If the buffer is full, the oldest item is overwritten and returned.
+     *
+     * @param item - The item to add.
+     * @returns The overwritten item if the buffer was full, otherwise `undefined`.
+     */
+    push(item: T): T | undefined;
+    /**
+     * Removes and returns the first (oldest) item from the buffer.
+     *
+     * @returns The removed item, or `undefined` if the buffer is empty.
+     */
+    shift(): T | undefined;
+    /**
+     * Removes and returns the last (newest) item from the buffer.
+     *
+     * @returns The removed item, or `undefined` if the buffer is empty.
+     */
+    pop(): T | undefined;
+    /**
+     * Adds an item to the beginning of the buffer.
+     * If the buffer is full, the newest item is overwritten and returned.
+     *
+     * @param item - The item to add.
+     * @returns The overwritten item if the buffer was full, otherwise `undefined`.
+     */
+    unshift(item: T): T | undefined;
+    /**
+     * Returns the element at the specified index without removing it.
+     * Supports negative indices (e.g., `-1` for the last element).
+     *
+     * @param index - The zero-based index, or negative index from the end.
+     * @returns The element at the index, or `undefined` if the index is out of bounds.
+     */
+    at(index: number): T | undefined;
+    /**
+     * Returns the first (oldest) element without removing it.
+     *
+     * @returns The first element, or `undefined` if the buffer is empty.
+     */
+    peek(): T | undefined;
+    /**
+     * Returns the last (newest) element without removing it.
+     *
+     * @returns The last element, or `undefined` if the buffer is empty.
+     */
+    peekBack(): T | undefined;
+    /**
+     * Removes all elements from the buffer, resetting it to an empty state.
+     */
+    clear(): void;
+    /**
+     * Returns an iterator that yields elements in logical order (oldest to newest).
+     * Allows the buffer to be used with `for...of` loops and spread syntax.
+     *
+     * @yields Elements in FIFO order.
+     */
+    [Symbol.iterator](): Iterator<T>;
+    /**
+     * Creates a new array containing all elements in logical order (oldest to newest).
+     *
+     * @returns A new array with all buffer elements.
+     */
+    toArray(): T[];
+}

package/dist/types/snowflake.d.ts

@@ -0,0 +1,25 @@
+type Snowflake = string & {
+    readonly __brand: unique symbol;
+};
+declare namespace Snowflake {
+    const PATTERN: RegExp;
+    const EPOCH_TIMESTAMP = 1420070400000;
+    const MAX_SEQUENCE = 4194303;
+    function formatParts(dt: number, seq: number): Snowflake;
+    class Source {
+        #private;
+        constructor(sequence?: number);
+        get sequence(): number;
+        set sequence(v: number);
+        reset(): void;
+        generate(timestamp: number): Snowflake;
+    }
+    function next(timestamp?: number): Snowflake;
+    function valid(value: string): value is Snowflake;
+    function lowerbound(timelike: Date | number | Snowflake): Snowflake;
+    function upperbound(timelike: Date | number | Snowflake): Snowflake;
+    function getSequence(value: Snowflake): number;
+    function getTimestamp(value: Snowflake): number;
+    function getDate(value: Snowflake): Date;
+}
+export { Snowflake };

package/dist/types/stream.d.ts

@@ -0,0 +1,68 @@
+export declare function readLines(stream: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<Uint8Array>;
+export declare function readJsonl<T>(stream: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<T>;
+/**
+ * Stream parsed JSON objects from SSE `data:` lines.
+ *
+ * Thin wrapper over {@link readSseEvents}: yields one parsed JSON value per
+ * dispatched SSE event, skipping events with empty `data` and stopping at the
+ * OpenAI-style `[DONE]` sentinel. If your consumer doesn't care about `event:`
+ * names or doesn't need a custom parse step, use this; otherwise call
+ * `readSseEvents` directly.
+ *
+ * @example
+ * ```ts
+ * for await (const obj of readSseJson(response.body!)) {
+ *   console.log(obj);
+ * }
+ * ```
+ */
+export type SseEventObserver = (event: ServerSentEvent) => void;
+export declare function readSseJson<T>(stream: ReadableStream<Uint8Array>, signal?: AbortSignal, onEvent?: SseEventObserver): AsyncGenerator<T>;
+/**
+ * A single Server-Sent Event dispatched on a blank-line boundary.
+ *
+ * - `event` is the value of the most recent `event:` field, or `null` if none.
+ * - `data` is the concatenation (joined by `\n`) of every `data:` field in the
+ *   event, exactly as required by the SSE spec.
+ * - `raw` is the list of decoded non-empty lines that made up the event,
+ *   preserved for diagnostic context (error reporting, debugging). The
+ *   dispatching blank line is not included.
+ */
+export interface ServerSentEvent {
+    event: string | null;
+    data: string;
+    raw: string[];
+}
+/**
+ * Stream raw Server-Sent Events from an HTTP response body.
+ *
+ * Yields one `ServerSentEvent` per blank-line dispatch. The consumer is
+ * responsible for parsing `data` (e.g. JSON, plain text, error envelope).
+ * Use `readSseJson` instead when every event is a single `data:` JSON object
+ * and you don't need access to the `event:` field.
+ *
+ * Internally backed by a Buffer-based line reader (`ConcatSink`) so chunk
+ * concatenation is O(n) and never triggers per-line string slicing of the
+ * accumulated buffer.
+ *
+ * @example
+ * ```ts
+ * for await (const sse of readSseEvents(response.body!)) {
+ *   if (sse.event === "ping") continue;
+ *   const obj = JSON.parse(sse.data);
+ * }
+ * ```
+ */
+export declare function readSseEvents(stream: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<ServerSentEvent>;
+/**
+ * Parse a complete JSONL string, skipping malformed lines instead of throwing.
+ *
+ * Uses `Bun.JSONL.parseChunk` internally. On parse errors, the malformed
+ * region is skipped up to the next newline and parsing continues.
+ *
+ * @example
+ * ```ts
+ * const entries = parseJsonlLenient<MyType>(fileContents);
+ * ```
+ */
+export declare function parseJsonlLenient<T>(buffer: string): T[];

package/dist/types/tab-spacing.d.ts

@@ -0,0 +1,9 @@
+export declare const MIN_TAB_WIDTH = 1;
+export declare const MAX_TAB_WIDTH = 16;
+export declare const DEFAULT_TAB_WIDTH = 3;
+export declare function getDefaultTabWidth(): number;
+export declare function setDefaultTabWidth(width: number): void;
+/**
+ * Visible tab width in columns for `file` (from `.editorconfig` + default), or the default when `file` is omitted.
+ */
+export declare function getIndentation(file?: string | null, projectDir?: string | null): number;

package/dist/types/temp.d.ts

@@ -0,0 +1,14 @@
+export declare class TempDir {
+    #private;
+    private constructor();
+    static createSync(prefix?: string): TempDir;
+    static create(prefix?: string): Promise<TempDir>;
+    path(): string;
+    absolute(): string;
+    remove(): Promise<void>;
+    removeSync(): void;
+    toString(): string;
+    join(...paths: string[]): string;
+    [Symbol.asyncDispose](): Promise<void>;
+    [Symbol.dispose](): void;
+}

package/dist/types/type-guards.d.ts

@@ -0,0 +1,3 @@
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function asRecord(value: unknown): Record<string, unknown> | null;
+export declare function toError(value: unknown): Error;

package/dist/types/which.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Cache policy for which lookups.
+ */
+export declare const enum WhichCachePolicy {
+    /**
+     * Use cached result if available.
+     */
+    Cached = 0,
+    /**
+     * Bypass cache and perform a new lookup.
+     */
+    Bypass = 1,
+    /**
+     * Always update cache.
+     */
+    Fresh = 2,
+    /**
+     * Read-only, serves from cache if present, but doesn't write.
+     */
+    ReadOnly = 3
+}
+export interface WhichOptions extends Bun.WhichOptions {
+    /**
+     * Cache policy for the lookup.
+     * Defaults to `WhichCachePolicy.Fresh`.
+     */
+    cache?: WhichCachePolicy;
+}
+export declare const whichFresh: typeof Bun.which;
+/**
+ * Locate binary on PATH (with flexible caching).
+ *
+ * @param command - Binary name to resolve
+ * @param options - Bun.WhichOptions plus `cache` control
+ * @returns Filesystem path if found, else null
+ */
+export declare function $which(command: string, options?: WhichOptions): string | null;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-utils",
-	"version": "15.1.0",
+	"version": "15.1.2",
 	"description": "Shared utilities for pi packages",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -21,7 +21,7 @@
 		"streams"
 	],
 	"main": "./src/index.ts",
-	"types": "./src/index.ts",
+	"types": "./dist/types/index.d.ts",
 	"scripts": {
 		"check": "biome check . && bun run check:types",
 		"check:types": "tsgo -p tsconfig.json --noEmit",
@@ -38,21 +38,22 @@
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14",
-		"@oh-my-pi/pi-natives": "15.1.0"
+		"@oh-my-pi/pi-natives": "15.1.2"
 	},
 	"engines": {
 		"bun": ">=1.3.14"
 	},
 	"files": [
-		"src"
+		"src",
+		"dist/types"
 	],
 	"exports": {
 		".": {
-			"types": "./src/index.ts",
+			"types": "./dist/types/index.d.ts",
 			"import": "./src/index.ts"
 		},
 		"./*": {
-			"types": "./src/*.ts",
+			"types": "./dist/types/*.d.ts",
 			"import": "./src/*.ts"
 		},
 		"./*.js": "./src/*.ts"

package/src/frontmatter.ts

@@ -86,7 +86,7 @@ export function parseFrontmatter(
 	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;
+	const normalized = normalize ? stripHtmlComments(content.replace(/\r\n?/g, "\n")) : content;
 	if (!normalized.startsWith("---")) {
 		return { frontmatter, body: normalized };
 	}