@sayknow-cli/utils 0.4.2 → 0.4.4

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/broken-pipe.d.ts

@@ -0,0 +1,27 @@
+/**
+ * True when an error from a writer that owns its sink reports that the peer
+ * closed that sink. This intentionally accepts structural error objects rather
+ * than requiring an `Error` instance.
+ */
+export declare function isKnownSinkPeerClosedError(error: unknown): boolean;
+/**
+ * Backward-compatible local-sink classifier for output writers. Callers must
+ * use it only when they own the sink that produced the error.
+ */
+export declare function isBrokenPipeError(error: unknown): boolean;
+/**
+ * A classifier for process-level stdout `EPIPE` errors. Its direct-write
+ * evidence is private to each factory instance, so only the owner that
+ * intercepted `process.stdout.write` can mark an error for this classifier.
+ */
+export interface ProcessStdoutEpipeClassifier {
+    markDirectProcessStdoutWriteError(error: unknown): void;
+    isAttributableProcessStdoutEpipe(error: unknown): boolean;
+}
+export declare function createProcessStdoutEpipeClassifier(): ProcessStdoutEpipeClassifier;
+/**
+ * Exit code for a producer terminated because its output pipe broke:
+ * 128 + SIGPIPE (13), matching what shells report for SIGPIPE-killed tools
+ * in `foo | head`-style pipelines.
+ */
+export declare const BROKEN_PIPE_EXIT_CODE = 141;

package/dist/types/cli.d.ts

@@ -0,0 +1,126 @@
+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 extends FlagInput>(opts?: T): FlagDescriptor<"boolean"> & T;
+    integer<T extends FlagInput & {
+        default?: number;
+    }>(opts?: T): FlagDescriptor<"integer"> & T;
+};
+export declare const Args: {
+    string<T extends ArgInput>(opts?: T): ArgDescriptor & T;
+};
+/**
+ * Thrown when CLI argument/flag parsing or validation fails (unknown flag,
+ * bad option value, missing required arg, etc.). `run()` catches this to print
+ * the message and render usage instead of crashing as an uncaught exception.
+ */
+export declare class CliParseError extends Error {
+    constructor(message: string);
+}
+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>;
+    delegateHelp?: boolean;
+}
+/** 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 "@sayknow-cli/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,165 @@
+/**
+ * Centralized path helpers for sayknow-cli config directories.
+ *
+ * Uses PI_CONFIG_DIR (default ".skc") 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/skc/. This requires running `skc config migrate` first to
+ * move data to the new locations. No filesystem existence checks are performed
+ * — if the env var is set, skc trusts that the migration has been done.
+ */
+/** App name (e.g. "skc") */
+export declare const APP_NAME: string;
+/** Config directory name (e.g. ".skc") */
+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;
+/**
+ * Build the diagnostic shown when the Bun runtime executing `skc` is older
+ * than {@link MIN_BUN_VERSION}. This is the most common Windows native-install
+ * failure (issue #525): `bun install -g sayknow-cli` probes a recent Bun while
+ * the `skc` launcher resolves an older Bun still on PATH. The message names the
+ * exact detected runtime path and gives a platform-specific upgrade + PATH fix
+ * instead of a bare `bun upgrade`.
+ *
+ * Pure and platform-parameterized so it can be unit-tested cross-platform.
+ */
+export declare function formatBunRuntimeError(opts: {
+    currentVersion: string;
+    minVersion: string;
+    execPath?: string;
+    platform?: NodeJS.Platform;
+}): string;
+export declare function resolveEquivalentPath(inputPath: string): string;
+export declare function normalizePathForComparison(inputPath: string, platform?: NodeJS.Platform): string;
+/** Return whether a relative path crosses above its root or is unexpectedly absolute. */
+export declare function relativePathEscapesRoot(relative: string): boolean;
+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. ".skc" or PI_CONFIG_DIR override). */
+export declare function getConfigDirName(): string;
+/** Get the config agent directory name relative to home (e.g. ".skc/agent" or PI_CONFIG_DIR + "/agent"). */
+export declare function getConfigAgentDirName(): string;
+/** Get the config root directory (~/.skc). */
+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 (~/.skc/agent). */
+export declare function getAgentDir(): string;
+/** Get the project-local config directory (.skc). */
+export declare function getProjectAgentDir(cwd?: string): string;
+/** Get the reports directory (~/.skc/reports). */
+export declare function getReportsDir(): string;
+/** Get the logs directory (~/.skc/logs). */
+export declare function getLogsDir(): string;
+/** Get the path to a dated log file (~/.skc/logs/skc.YYYY-MM-DD.log). */
+export declare function getLogPath(date?: Date): string;
+/**
+ * Get the plugins directory (~/.skc/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 (~/.skc/plugins/node_modules). */
+export declare function getPluginsNodeModules(): string;
+/** Plugin manifest (~/.skc/plugins/package.json). */
+export declare function getPluginsPackageJson(): string;
+/** Plugin lock file (~/.skc/plugins/skc-plugins.lock.json). */
+export declare function getPluginsLockfile(): string;
+/** Get the remote mount directory (~/.skc/remote). */
+export declare function getRemoteDir(): string;
+/** Get the agent-managed worktrees directory (~/.skc/wt). */
+export declare function getWorktreesDir(): string;
+/** Get the SSH control socket directory (~/.skc/ssh-control). */
+export declare function getSshControlDir(): string;
+/** Get the remote host info directory (~/.skc/remote-host). */
+export declare function getRemoteHostDir(): string;
+/** Get the managed Python venv directory (~/.skc/python-env). */
+export declare function getPythonEnvDir(): string;
+/** Get the shared Python gateway state directory (~/.skc/agent/python-gateway; XDG default: $XDG_STATE_HOME/skc/python-gateway). */
+export declare function getPythonGatewayDir(): string;
+/** Get the puppeteer sandbox directory (~/.skc/puppeteer). */
+export declare function getPuppeteerDir(): 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 `~/.skc/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 (~/.skc/wt/<segment>). */
+export declare function getWorktreeDir(segment: string): string;
+/** Get the GPU cache path (~/.skc/gpu_cache.json). */
+export declare function getGpuCachePath(): string;
+/**
+ * Get the GitHub view cache database path (~/.skc/cache/github-cache.db).
+ * Honors the `SKC_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 (~/.skc/natives). */
+export declare function getNativesDir(): string;
+/** Get the stats database path (~/.skc/stats.db). */
+export declare function getStatsDbPath(): string;
+/** Get the autoresearch state directory (~/.skc/autoresearch). */
+export declare function getAutoresearchDir(): string;
+/** Get the per-project autoresearch state directory (~/.skc/autoresearch/<encoded-project>). */
+export declare function getAutoresearchProjectDir(encodedProject: string): string;
+/** Get the per-project autoresearch SQLite database path (~/.skc/autoresearch/<encoded-project>.db). */
+export declare function getAutoresearchDbPath(encodedProject: string): string;
+/** Get the per-run artifact directory (~/.skc/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 (~/.skc/agent/sessions). */
+export declare function getSessionsDir(agentDir?: string): string;
+/** Get the content-addressed blob store directory (~/.skc/agent/blobs). */
+export declare function getBlobsDir(agentDir?: string): string;
+/** Get the custom themes directory (~/.skc/agent/themes). */
+export declare function getCustomThemesDir(agentDir?: string): string;
+/** Get the tools directory (~/.skc/agent/tools). */
+export declare function getToolsDir(agentDir?: string): string;
+/** Get the slash commands directory (~/.skc/agent/commands). */
+export declare function getCommandsDir(agentDir?: string): string;
+/** Get the prompts directory (~/.skc/agent/prompts). */
+export declare function getPromptsDir(agentDir?: string): string;
+/** Get the user-level Python modules directory (~/.skc/agent/modules). */
+export declare function getAgentModulesDir(agentDir?: string): string;
+/** Get the memories directory (~/.skc/agent/memories). */
+export declare function getMemoriesDir(agentDir?: string): string;
+/** Get the terminal sessions directory (~/.skc/agent/terminal-sessions). */
+export declare function getTerminalSessionsDir(agentDir?: string): string;
+/** Get the crash log path (~/.skc/agent/skc-crash.log). */
+export declare function getCrashLogPath(agentDir?: string): string;
+/** Get the debug log path (~/.skc/agent/skc-debug.log). */
+export declare function getDebugLogPath(agentDir?: string): string;
+/** Get the project-level Python modules directory (.skc/modules). */
+export declare function getProjectModulesDir(cwd?: string): string;
+/** Get the project-level prompts directory (.skc/prompts). */
+export declare function getProjectPromptsDir(cwd?: string): string;
+/** Get the project-level plugin overrides path (.skc/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,68 @@
+export { filterProcessEnv, isSafeEnvName, isSafeEnvValue } from "./spawn-env";
+/**
+ * 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;
+/**
+ * Parses simple POSIX shell environment assignments from files such as
+ * ~/.zshrc without executing user shell code. Supports `export KEY=value` and
+ * `KEY=value`, including single/double quoted literal values. Dynamic shell
+ * expressions are intentionally ignored because evaluating startup files would
+ * run arbitrary code during CLI startup.
+ */
+export declare function parseShellEnvFile(filePath: string): 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>;
+export declare function $inheritedEnv(name: string): string | undefined;
+/**
+ * Intentional re-export of Bun.env.
+ *
+ * All users should import this env module (import { $env } from "@sayknow-cli/utils")
+ * before using environment variables. This ensures that .env files have been loaded and
+ * overrides (project, home) have been applied, so $env always reflects the correct values.
+ *
+ * Provider credential resolution must not use this merged view because it includes the
+ * caller's cwd/.env. Use $credentialEnv/$pickCredentialEnv for model authentication.
+ */
+export 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;
+/**
+ * Resolve credential-bearing environment variables without consulting the caller's project .env.
+ *
+ * SKC loads cwd/.env into $env for project-aware tools, but model-provider authentication should
+ * only use values explicitly inherited from the launching shell or SKC/user-owned config files.
+ */
+export declare function $credentialEnv(name: string): string | undefined;
+/**
+ * Resolve the first credential env value from the given keys, excluding cwd/.env overlays.
+ */
+export declare function $pickCredentialEnv(...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 code provider and Google Gemini retry helpers.
+ *
+ * Header sources (checked in order):
+ *  - `Retry-After` (numeric seconds, or HTTP date)
+ *  - `x-ratelimit-reset` (Unix epoch seconds)
+ *  - `x-ratelimit-reset-after` (seconds)
+ *
+ * Body patterns:
+ *  - `Your quota will reset after 18h31m10s` / `10m15s` / `39s`
+ *  - `Please retry in 250ms` / `Please retry in 12s`
+ *  - `"retryDelay": "34.074824224s"` (JSON error detail field)
+ *  - `try again in 250ms` / `try again in 12s` / `try again in 12sec`
+ *
+ * Returns `undefined` if no signal is found.
+ */
+export 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: 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 @sayknow-cli/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 | undefined;
+    constructor(error: Error, source?: unknown | undefined);
+    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;
+};