@oh-my-pi-zen/pi-utils 16.3.6-zen.1

package/dist/types/dirs.d.ts

@@ -0,0 +1,260 @@
+/**
+ * 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;
+/**
+ * Normalize and validate a profile name. Returns `undefined` for the implicit
+ * default (empty string, whitespace, or the explicit "default" sentinel) and
+ * throws for syntactically invalid or platform-reserved names.
+ *
+ * Exported so consumers of `@oh-my-pi-zen/pi-utils/dirs` (CLI bootstrap, tests,
+ * downstream tools) can validate user input without re-deriving the rules.
+ */
+export declare function normalizeProfileName(profile: string | undefined): string | undefined;
+/**
+ * Resolve the active profile from the two profile env vars. `OMP_PROFILE` is the
+ * canonical variable and takes precedence; `PI_PROFILE` is the legacy
+ * compatibility fallback, consulted only when `OMP_PROFILE` is undefined. An
+ * explicitly-empty `OMP_PROFILE` therefore selects the default profile rather
+ * than silently inheriting `PI_PROFILE`. Delegates validation/normalization to
+ * {@link normalizeProfileName} (which throws on a syntactically invalid value).
+ */
+export declare function resolveProfileEnv(omp: string | undefined, pi: string | undefined): string | undefined;
+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;
+/**
+ * Whether `dir` resolves to an existing directory. Any stat failure — a deleted
+ * path (ENOENT), permission error, or a non-directory — returns `false`, so
+ * callers can decide whether a directory is safe to `chdir` into or adopt as a
+ * working directory before {@link setProjectDir} throws on it.
+ */
+export declare function directoryExists(dir: string): Promise<boolean>;
+/** 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;
+/**
+ * Rebuild the dirs resolver from the current environment, reusing the profile
+ * resolved at module load. Directory-affecting keys (XDG_*_HOME and, in default
+ * mode, `PI_CODING_AGENT_DIR`) loaded from a profile/agent `.env` only reach
+ * `process.env` *after* this module froze the resolver at import time, so
+ * `env.ts` calls this once after applying its `.env` files. The agent `.env`
+ * location derives from the profile name + home before this runs, so the
+ * rebuild re-reads only the directory vars, never the profile selection. The
+ * `preProfileAgentDirEnv` snapshot is intentionally left untouched.
+ */
+export declare function refreshDirsFromEnv(): void;
+/** 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;
+/**
+ * Test-only: reset the pre-profile `PI_CODING_AGENT_DIR` snapshot to whatever
+ * the current environment looks like. Cross-suite test pollution can otherwise
+ * leak a stale snapshot through `setAgentDir` and corrupt `setProfile(undefined)`
+ * restore semantics. Production code MUST NOT call this — the snapshot's
+ * lifecycle is owned by `setAgentDir` / `setProfile` and a runtime caller has
+ * no business clearing it.
+ */
+export declare function __resetProfileSnapshotForTests(): void;
+/**
+ * Test-only: rebuild profile + directory state from the current process env.
+ * Production code keeps the module-load profile stable; tests that mutate
+ * `setAgentDir`/`setProfile` need an exact restore point after they put env vars
+ * back.
+ */
+export declare function __resetDirsFromEnvForTests(): void;
+/** Activate a named profile. Passing undefined or "default" returns to the default profile. */
+export declare function setProfile(profile: string | undefined): void;
+/** Get the active named profile. Undefined means the default profile. */
+export declare function getActiveProfile(): string | undefined;
+/** Resolve the config root that backs a profile without activating it. */
+export declare function getProfileRootDir(profile: string | undefined): string;
+/** 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(home?: string): string;
+/** Plugin manifest (~/.omp/plugins/package.json). */
+export declare function getPluginsPackageJson(home?: string): string;
+/** Plugin lock file (~/.omp/plugins/omp-plugins.lock.json). */
+export declare function getPluginsLockfile(home?: string): string;
+/** Get the remote mount directory (~/.omp/remote). */
+export declare function getRemoteDir(): string;
+/**
+ * Relocate the base directory for agent-managed worktrees (PR checkouts, task
+ * isolation, and `omp worktree` cleanup all read the same base). Driven by the
+ * `worktree.base` setting in coding-agent; pass `undefined`/empty to clear and
+ * fall back to `OMP_WORKTREE_DIR` or the `~/.omp/wt` default.
+ *
+ * `~` is expanded and a relative path is rejected (see {@link resolveWorktreeBase}).
+ * Returns the absolute path that took effect, or `undefined` if the input was
+ * cleared or rejected — callers can warn on a non-empty input that returns
+ * `undefined`.
+ */
+export declare function setWorktreesDir(dir: string | undefined): string | undefined;
+/**
+ * Get the agent-managed worktrees directory. Resolution order: the
+ * `OMP_WORKTREE_DIR` env var, then the {@link setWorktreesDir} override (the
+ * `worktree.base` setting), then the `~/.omp/wt` default. The env var and the
+ * override are both `~`-expanded and must be absolute; a relative value is
+ * ignored and resolution falls through.
+ */
+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 DOCS_RS cache directory () */
+export declare function getDocsRsCacheDir(): string;
+/**Get AutoQa db directory */
+export declare function getAutoQaDbDir(): string;
+/**
+ * Stable 7-character hex digest of an absolute filesystem path.
+ *
+ * Used to pack the project identity into a single short fs-safe segment
+ * (e.g. PR-checkout and task-isolation worktree dirs under `~/.omp/wt/`).
+ * Bun.hash is non-cryptographic — collision space is ~2^28, which is fine
+ * for naming a handful of repos on a single machine. Same input on the
+ * same Bun runtime yields the same output.
+ */
+export declare function hashPath(absPath: string): string;
+/** Get the path to a single worktree directory (~/.omp/wt/<segment>). */
+export declare function getWorktreeDir(segment: 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 encrypted auth-broker snapshot cache path (~/.omp/cache/auth-broker-snapshot.enc).
+ * Honors the `OMP_AUTH_BROKER_SNAPSHOT_CACHE` env var when set so tests and
+ * operators can isolate or relocate the cache file.
+ */
+export declare function getAuthBrokerSnapshotCachePath(): string;
+/** Get the local FastEmbed model cache directory (~/.omp/cache/fastembed). */
+export declare function getFastembedCacheDir(): string;
+/** Get the on-demand fastembed runtime install root (~/.omp/cache/fastembed-runtime). */
+export declare function getFastembedRuntimeDir(): 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 last-seen-changelog-version marker file (~/.omp/agent/last-changelog-version). */
+export declare function getLastChangelogVersionPath(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 tiny title model cache directory (~/.omp/agent/cache/tiny-models). */
+export declare function getTinyModelsCacheDir(agentDir?: string): string;
+/** Get the document conversion cache directory (~/.omp/agent/cache/document-conversions; XDG default: $XDG_CACHE_HOME/omp/cache/document-conversions). */
+export declare function getDocumentConversionCacheDir(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;
+/**
+ * Persistent per-install UUID stored at `~/.omp/install-id`.
+ *
+ * Generated lazily on first call and persisted with `O_CREAT|O_EXCL` so
+ * concurrent first-call races don't clobber each other (loser re-reads the
+ * winner's id). Survives independently of agent state: deleting
+ * `~/.omp/agent/` does not regenerate it. Server-side dedup for grievance
+ * pushes (and similar telemetry) keys on this id.
+ *
+ * Anchored to the base config root (`~/.omp/install-id`) regardless of the
+ * active profile: install identity is per-install, not per-profile, so every
+ * profile shares one id and the global cache stays correct no matter the
+ * profile / `getInstallId` call order.
+ */
+export declare function getInstallId(): string;
+/** Test-only: clear cached install id. Never call from production code. */
+export declare function __resetInstallIdCacheForTests(): void;

package/dist/types/env.d.ts

@@ -0,0 +1,74 @@
+export * from "./worker-host";
+/**
+ * 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 declare function isValidEnvName(name: string): boolean;
+/**
+ * The only names that are genuinely unsafe to forward to a native `execve`
+ * spawn: empty, containing `=` (would corrupt the `KEY=VALUE` framing) or
+ * NUL (terminates the C string mid-entry). Windows ships standard variables
+ * whose names contain parentheses (e.g. `ProgramFiles(x86)`, `CommonProgramFiles(x86)`)
+ * — those MUST survive the scrub so downstream resolvers (Git Bash discovery
+ * in `procmgr.ts`, etc.) can still read them.
+ */
+export declare function isSafeEnvName(name: string): boolean;
+export declare function isSafeEnvValue(value: string): boolean;
+export declare function isMacosMallocStackLoggingEnvName(name: string): boolean;
+export declare function filterProcessEnv(env: Record<string, string | undefined>): Record<string, string>;
+/**
+ * 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 declare function parseEnvFile(filePath: string): Record<string, string>;
+/**
+ * Intentional re-export of Bun.env.
+ *
+ * All users should import this env module (import { $env } from "@oh-my-pi-zen/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 real-terminal side effects must be suppressed: stdout escape/frame
+ * writes, stdin raw-mode + resume, CSI/OSC capability probes, SIGWINCH, window
+ * title changes, and emergency restore. Defaults to {@link isBunTestRuntime} so
+ * `bun test` launched inside a real TTY never paints the TUI, leaks probe
+ * queries, or hijacks the developer's stdin; production runtimes stay
+ * interactive.
+ *
+ * Terminal-contract tests that must exercise the real I/O path opt out with
+ * `setTerminalHeadless(false)` and restore it afterwards.
+ */
+export declare function isTerminalHeadless(): boolean;
+/**
+ * Override the {@link isTerminalHeadless} default and return the previous value
+ * so callers can restore exact prior state (`const prev = setTerminalHeadless(false); … setTerminalHeadless(prev);`).
+ */
+export declare function setTerminalHeadless(headless: boolean): 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,94 @@
+/**
+ * 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 5 min` / `try again in ~158 min`
+ *
+ * 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>;
+    /**
+     * Optional retry gate for HTTP responses whose status is retryable. Receives a
+     * cloned body string so callers can fail fast on deterministic provider
+     * failures that happen to use a 5xx status.
+     */
+    shouldRetryResponse?: (response: Response, bodyText: string, attempt: number) => boolean | Promise<boolean>;
+    /**
+     * Bun extension forwarded verbatim to the underlying `fetch` call. `false`
+     * disables Bun's native ~300s pre-response timeout (callers that own a
+     * configurable first-event/idle watchdog or an external `AbortSignal`
+     * supply this so the runtime ceiling cannot pre-empt them); a positive
+     * number sets a custom ceiling in ms. Bare browser/Node fetch ignores it.
+     */
+    timeout?: number | false;
+}
+/**
+ * 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: 401`, `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-zen/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-zen/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/index.d.ts

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

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

@@ -0,0 +1,48 @@
+/**
+ * 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;

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;