@oh-my-pi/pi-utils 17.4.0 → 17.4.2

package/dist/types/ar/arj.d.ts

@@ -0,0 +1,5 @@
+import type { FormatReader } from "./types.js";
+/** Probe whether bytes begin with a CRC-framed ARJ main header. */
+export declare function sniffArj(bytes: Uint8Array): boolean;
+/** Index an ARJ archive and lazily decode stored, static-Huffman, and fast-LZSS members. */
+export declare const readArj: FormatReader;

package/dist/types/ar/asar.d.ts

@@ -0,0 +1,7 @@
+import type { FormatReader } from "./types.js";
+/** Read an Electron ASAR index while keeping packed and unpacked member payloads lazy. */
+export declare const readAsar: FormatReader;
+/** Whether bytes begin with a structurally plausible Electron ASAR Pickle header. */
+export declare function sniffAsar(bytes: Uint8Array): boolean;
+/** Encode file members in Electron's Pickle-framed ASAR layout. */
+export declare function encodeAsar(members: Iterable<readonly [string, Uint8Array]>): Promise<Uint8Array>;

package/dist/types/ar/bytes.d.ts

@@ -0,0 +1,20 @@
+/** Shared UTF-8 decoder for archive member names and text payloads. */
+export declare const UTF8_DECODER: TextDecoder;
+export declare function readUInt16LE(bytes: Uint8Array, offset: number): number;
+export declare function readUInt32LE(bytes: Uint8Array, offset: number): number;
+/** Read a u64 as a JS number, rejecting values beyond `Number.MAX_SAFE_INTEGER`. */
+export declare function readUInt64LE(bytes: Uint8Array, offset: number): number;
+export declare function readUInt16BE(bytes: Uint8Array, offset: number): number;
+export declare function readUInt32BE(bytes: Uint8Array, offset: number): number;
+/** Read a big-endian u64 as a JS number, rejecting unsafe values. */
+export declare function readUInt64BE(bytes: Uint8Array, offset: number): number;
+export declare function writeUInt16LE(buf: Uint8Array, offset: number, value: number): void;
+export declare function writeUInt32LE(buf: Uint8Array, offset: number, value: number): void;
+/** Write a safe-integer u64 (values beyond 2^53-1 must be rejected upstream). */
+export declare function writeUInt64LE(buf: Uint8Array, offset: number, value: number): void;
+/** Whether `bytes` contains the ASCII string `value` at `offset`. */
+export declare function bytesMatchAscii(bytes: Uint8Array, offset: number, value: string): boolean;
+/** Whether `bytes` is exactly the ASCII string `value`. */
+export declare function bytesEqualAscii(bytes: Uint8Array, value: string): boolean;
+/** First index at or after `start` where the ASCII string `value` occurs, or -1. */
+export declare function indexOfAscii(bytes: Uint8Array, value: string, start: number): number;

package/dist/types/ar/cab.d.ts

@@ -0,0 +1,5 @@
+import type { FormatReader } from "./types.js";
+/** Probe a byte prefix for the Microsoft Cabinet `MSCF` signature. */
+export declare function sniffCab(bytes: Uint8Array): boolean;
+/** Index a Microsoft Cabinet archive and defer folder decompression until a member is read. */
+export declare const readCab: FormatReader;

package/dist/types/ar/checksums.d.ts

@@ -0,0 +1,10 @@
+/** CRC-32 (IEEE 802.3, reflected). Chainable: pass the previous value as `seed`. */
+export declare function crc32(bytes: Uint8Array, seed?: number): number;
+/**
+ * CRC-64/XZ (ECMA-182, reflected) as used by `.xz` block checks. Chainable
+ * via `seed`. State is split into 32-bit halves so the hot loop stays on
+ * fast integer paths instead of per-byte BigInt arithmetic.
+ */
+export declare function crc64(bytes: Uint8Array, seed?: bigint): bigint;
+/** CRC-16/ARC (reflected, poly 0xA001, init 0) as used by LZH member data and ARJ. */
+export declare function crc16Arc(bytes: Uint8Array, seed?: number): number;

package/dist/types/ar/codecs/bzip2.d.ts

@@ -0,0 +1,4 @@
+/** Return whether bytes begin with a valid bzip2 stream signature. */
+export declare function isBzip2(bytes: Uint8Array): boolean;
+/** Decompress concatenated bzip2 streams while enforcing a hard output bound. */
+export declare function bzip2Decompress(bytes: Uint8Array, maxOutput: number): Promise<Uint8Array>;

package/dist/types/ar/codecs/gzip.d.ts

@@ -0,0 +1,6 @@
+/** gzip magic: 0x1f 0x8b. */
+export declare function isGzip(bytes: Uint8Array): boolean;
+/** Decompress one gzip stream, bounded so a gzip bomb cannot inflate without limit. */
+export declare function gzipDecompress(bytes: Uint8Array, maxOutput: number): Promise<Uint8Array>;
+/** Compress bytes as one gzip stream (tar.gz writing). */
+export declare function gzipCompress(bytes: Uint8Array): Promise<Uint8Array>;

package/dist/types/ar/codecs/lzma.d.ts

@@ -0,0 +1,6 @@
+/** Decompress a raw LZMA1 stream using the standard five-byte properties. */
+export declare function lzmaDecompress(props: Uint8Array, bytes: Uint8Array, outSize: number): Promise<Uint8Array>;
+/** Decompress an LZMA-alone container, including unknown-size end-marked streams. */
+export declare function lzmaAloneDecompress(bytes: Uint8Array, maxOutput: number): Promise<Uint8Array>;
+/** Decompress an LZMA2 stream, enforcing its dictionary and output limits. */
+export declare function lzma2Decompress(dictSizeProp: number, bytes: Uint8Array, maxOutput: number): Promise<Uint8Array>;

package/dist/types/ar/codecs/lzw.d.ts

@@ -0,0 +1,4 @@
+/** Return whether bytes begin with the ncompress `.Z` magic number. */
+export declare function isCompressZ(bytes: Uint8Array): boolean;
+/** Decompress an ncompress `.Z` stream while enforcing a hard output bound. */
+export declare function lzwDecompress(bytes: Uint8Array, maxOutput: number): Promise<Uint8Array>;

package/dist/types/ar/codecs/lzx.d.ts

@@ -0,0 +1,7 @@
+/** Stateful Microsoft LZX decoder used by CAB folders, retaining trees and window history between 32 KiB frames. */
+export declare class LzxDecoder {
+    #private;
+    constructor(windowBits: number);
+    /** Decode one CAB CFDATA LZX frame while preserving the folder's dictionary and Huffman state. */
+    decompressFrame(bytes: Uint8Array, outputSize: number): Uint8Array;
+}

package/dist/types/ar/codecs/xz.d.ts

@@ -0,0 +1,4 @@
+/** Whether bytes begin with the XZ stream-header magic. */
+export declare function isXz(bytes: Uint8Array): boolean;
+/** Decompress all concatenated streams in an XZ container within `maxOutput`. */
+export declare function xzDecompress(bytes: Uint8Array, maxOutput: number): Promise<Uint8Array>;

package/dist/types/ar/codecs/zstd.d.ts

@@ -0,0 +1,6 @@
+/** zstd frame magic: 28 b5 2f fd. */
+export declare function isZstd(bytes: Uint8Array): boolean;
+/** Decompress one zstd frame, bounded to `maxOutput` bytes. */
+export declare function zstdDecompress(bytes: Uint8Array, maxOutput: number): Promise<Uint8Array>;
+/** Compress bytes as one zstd frame (tar.zst writing). */
+export declare function zstdCompress(bytes: Uint8Array): Promise<Uint8Array>;

package/dist/types/ar/cpio.d.ts

@@ -0,0 +1,7 @@
+import type { ArchiveIndexEntry, FormatReader, FormatReadOptions } from "./types.js";
+/** Parse an already-materialized CPIO stream for direct and RPM-composed readers. */
+export declare function readCpioEntriesFromBuffer(bytes: Uint8Array, options: FormatReadOptions): ArchiveIndexEntry[];
+/** Read and index a CPIO archive, materializing its inherently sequential stream once. */
+export declare const readCpio: FormatReader;
+/** Detect newc, CRC, odc, or either-endian old binary CPIO headers. */
+export declare function sniffCpio(bytes: Uint8Array): boolean;

package/dist/types/ar/deb.d.ts

@@ -0,0 +1,5 @@
+import type { FormatReader } from "./types.js";
+/** Read a Debian binary package and expose its control and data tar members. */
+export declare const readDeb: FormatReader;
+/** Detect a Debian package by its ar header and first debian-binary member. */
+export declare function sniffDeb(bytes: Uint8Array): boolean;

package/dist/types/ar/entries.d.ts

@@ -0,0 +1,22 @@
+import { type ArchiveLimits } from "./limits.js";
+import type { ArchiveIndexEntry } from "./types.js";
+/**
+ * Insert `entry` into the index map with archive append/update semantics:
+ * files replace directories of the same path, directories never shadow files,
+ * and same-kind duplicates keep the later record while earlier metadata fills
+ * gaps (matching system tar extraction). Returns the retained entry, or
+ * `undefined` when the incoming entry was dropped.
+ */
+export declare function upsertArchiveEntry(map: Map<string, ArchiveIndexEntry>, entry: ArchiveIndexEntry): ArchiveIndexEntry | undefined;
+/**
+ * Synthesize directory entries for every ancestor of every indexed path, so
+ * containers that omit directory records (ZIP, cpio, most tars) still list
+ * correctly. Enforces `limits.maxEntries` as the map grows.
+ */
+export declare function ensureParentDirectories(map: Map<string, ArchiveIndexEntry>, limits: ArchiveLimits): void;
+/**
+ * Rewrite `archivePath` through symlink aliases until it no longer crosses
+ * one. Bounded: an exact revisit and an alias chain that keeps growing the
+ * path (e.g. `a -> a/b`) both throw a catchable cyclic-symlink error.
+ */
+export declare function resolveArchiveLinkPath(entries: ReadonlyMap<string, ArchiveIndexEntry>, archivePath: string, maxLinkDepth: number): string;

package/dist/types/ar/error.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Error raised for invalid, unsupported, or unsafe archive input. The message
+ * is safe to surface directly to users/models; callers that need a different
+ * error taxonomy (e.g. the coding agent's `ToolError`) match on this class.
+ */
+export declare class ArchiveError extends Error {
+    constructor(message: string);
+}

package/dist/types/ar/index.d.ts

@@ -0,0 +1,11 @@
+export * from "./bytes.js";
+export * from "./entries.js";
+export * from "./error.js";
+export * from "./limits.js";
+export * from "./open.js";
+export * from "./paths.js";
+export * from "./reader.js";
+export * from "./registry.js";
+export * from "./source.js";
+export * from "./types.js";
+export * from "./write.js";

package/dist/types/ar/iso.d.ts

@@ -0,0 +1,5 @@
+import type { FormatReader } from "./types.js";
+/** Probe an ISO 9660 primary-volume signature at sector 16. */
+export declare function sniffIso(bytes: Uint8Array): boolean;
+/** Index an ISO 9660 image lazily, preferring a valid Joliet supplementary tree. */
+export declare const readIso: FormatReader;

package/dist/types/ar/limits.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Resource ceilings enforced before archive metadata can drive expensive
+ * work. All sizes are attacker-controlled inputs until proven otherwise, so
+ * every allocation-driving field is checked against these before use.
+ * Mirrors `Limits` in the Rust `omp-ar` crate.
+ */
+export interface ArchiveLimits {
+    /** Max indexed entries per archive. */
+    maxEntries: number;
+    /** Max bytes for any archive fully materialized in memory (tar buffers, solid/decompressed streams). */
+    maxInMemorySize: number;
+    /** Max bytes for archive metadata (ZIP central directory, ASAR JSON header, RAR/7z header areas). */
+    maxIndexSize: number;
+    /** Max declared bytes for a single extracted member. */
+    maxMemberSize: number;
+    /** Max byte length of a member path or link target. */
+    maxPathBytes: number;
+    /** Max symlink rewrites while resolving one path. */
+    maxLinkDepth: number;
+}
+export declare const DEFAULT_ARCHIVE_LIMITS: ArchiveLimits;
+/** Reject an archive that would be fully materialized beyond `maxInMemorySize`. */
+export declare function assertInMemorySize(size: number, limits: ArchiveLimits): void;
+/** Reject archive metadata (index/header) beyond `maxIndexSize`. */
+export declare function assertIndexSize(size: number, limits: ArchiveLimits, what: string): void;
+/**
+ * Reject a member whose declared (uncompressed) size exceeds `maxMemberSize`.
+ * The declared size is metadata — a crafted entry can claim multi-GB sizes
+ * that would be allocated up front before any data decompresses.
+ */
+export declare function assertArchiveMemberSize(size: number, memberPath: string, limits: ArchiveLimits): void;
+/** Reject an index that grew beyond `maxEntries` while parsing. */
+export declare function assertEntryCount(count: number, limits: ArchiveLimits): void;

package/dist/types/ar/lzh.d.ts

@@ -0,0 +1,7 @@
+import type { FormatReader } from "./types.js";
+/** @internal Decode the static-Huffman LZSS stream shared by LZH and ARJ methods 1-3. */
+export declare function decompressLhStatic(packed: Uint8Array, outSize: number, dictionarySize: number, positionBits: number, positionSymbols: number, label: string): Uint8Array;
+/** Probe whether bytes begin with an LZH/LHA member header. */
+export declare function sniffLzh(bytes: Uint8Array): boolean;
+/** Index an LZH/LHA archive and lazily decode its members from the bounded archive buffer. */
+export declare const readLzh: FormatReader;

package/dist/types/ar/open.d.ts

@@ -0,0 +1,45 @@
+import { type ArchiveLimits } from "./limits.js";
+import { ArchiveReader } from "./reader.js";
+import type { ArchiveDirectoryEntry, ArchiveFormat, ArchiveMemberContent, ArchivePathCandidate, ArchiveSource } from "./types.js";
+/** Options accepted by every archive-opening entry point. */
+export interface OpenArchiveOptions {
+    /** Override individual resource ceilings; unset fields keep defaults. */
+    limits?: Partial<ArchiveLimits>;
+}
+/**
+ * Open an archive for browsing and member reads. File- and source-backed
+ * containers with random-access layouts (ZIP, ASAR, RAR, 7z, ISO, CAB) index
+ * lazily; stream containers (tar family, cpio, ar) buffer once under limits.
+ */
+export declare function openArchive(input: ArchiveSource, options?: OpenArchiveOptions): Promise<ArchiveReader>;
+/**
+ * Split an `archive.ext:inner/path` reference into every plausible
+ * `{ archivePath, subPath }` pair, longest archive prefix first. A path may
+ * contain more than one archive extension, so each candidate is a guess at
+ * where the archive ends and the member portion begins.
+ */
+export declare function parseArchivePathCandidates(filePath: string): ArchivePathCandidate[];
+/** Render directory entries one per line: `name/` for dirs, `name (size)` for files. */
+export declare function formatArchiveEntryLines(entries: readonly ArchiveDirectoryEntry[]): string[];
+/** Render the top-level entries of an in-memory archive as one line each. */
+export declare function listArchiveRoot(bytes: Uint8Array, format: ArchiveFormat, opts?: {
+    limit?: number;
+}): Promise<string>;
+/**
+ * Fully materialize every file member into a `path → bytes` map. Use this
+ * for whole-archive rewrite; browsing and single-member reads should use
+ * {@link openArchive} so payloads remain lazy. Total extracted bytes are
+ * bounded by `limits.maxInMemorySize`.
+ */
+export declare function readArchiveEntries(input: ArchiveSource, options?: OpenArchiveOptions): Promise<Map<string, Uint8Array>>;
+/** Convert member content for packing: strings become UTF-8 bytes. */
+export declare function memberContentToBytes(content: ArchiveMemberContent): Promise<Uint8Array>;
+/** Read one materialized member as UTF-8 text, or `undefined` when absent. */
+export declare function archiveEntryText(entries: ReadonlyMap<string, Uint8Array>, entryPath: string): string | undefined;
+/**
+ * Extract every member to `destDir`: files (with mode bits when recorded),
+ * directories, and symlinks (targets validated to stay inside `destDir`).
+ * Entries that would escape via `..` or absolute paths are rejected.
+ * Returns the number of filesystem entries written.
+ */
+export declare function extractArchive(input: ArchiveSource, destDir: string, options?: OpenArchiveOptions): Promise<number>;

package/dist/types/ar/paths.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Normalize a user-supplied lookup path inside an archive. Returns `""` for
+ * the archive root, `undefined` when the path escapes the root via `..`.
+ */
+export declare function normalizeArchiveLookupPath(rawPath?: string): string | undefined;
+/**
+ * Normalize an archive member path from container metadata. Returns
+ * `undefined` for empty paths and paths that escape the root via `..`.
+ */
+export declare function normalizeArchiveEntryPath(rawPath: string): string | undefined;
+/** Whether raw container metadata spells a directory via a trailing separator. */
+export declare function isArchiveDirectoryName(rawPath: string): boolean;
+/** Clamp an attacker-controlled path to a short preview for error messages. */
+export declare function formatArchivePathForError(value: string): string;
+/** Reject a member path/link target longer than `maxPathBytes`. */
+export declare function assertArchivePathBytes(size: number, field: string, maxPathBytes: number): void;
+/** {@link assertArchivePathBytes} for an already-decoded string. */
+export declare function assertArchivePathString(value: string, field: string, maxPathBytes: number): void;

package/dist/types/ar/rar/rar4-decoder.d.ts

@@ -0,0 +1,6 @@
+/** Stateful decoder for the RAR 2.9 LZ/Huffman algorithm used by RAR3/4 archives. */
+export declare class Rar4Decoder {
+    #private;
+    reset(): void;
+    decode(packed: Uint8Array, unpackedSize: number, dictionarySize: number, solid: boolean, version: number): Uint8Array;
+}

package/dist/types/ar/rar/rar5-decoder.d.ts

@@ -0,0 +1,6 @@
+/** Stateful RAR5 LZSS decoder; reuse one instance for members in a solid chain. */
+export declare class Rar5Decoder {
+    #private;
+    reset(): void;
+    decode(packed: Uint8Array, unpackedSize: number, dictionarySize: number, solid: boolean, version: number): Uint8Array;
+}

package/dist/types/ar/rar.d.ts

@@ -0,0 +1,5 @@
+import type { FormatReader } from "./types.js";
+/** Probe the RAR 1.5-4.x or RAR5 signature. */
+export declare function sniffRar(bytes: Uint8Array): boolean;
+/** Index a RAR4 or RAR5 archive and defer member decompression until extraction. */
+export declare const readRar: FormatReader;

package/dist/types/ar/reader.d.ts

@@ -0,0 +1,28 @@
+import { type ArchiveLimits } from "./limits.js";
+import type { ArchiveDirectoryEntry, ArchiveFormat, ArchiveIndexEntry, ArchiveNode, ExtractedArchiveFile } from "./types.js";
+/** Raise the canonical error for a symlink whose target cannot be materialized. */
+export declare function throwUnreadableArchiveLink(targetPath: string, memberPath: string): never;
+/**
+ * An indexed, read-only view over a single archive. Member payloads stay
+ * lazy behind their format's `MemberSource`; symlink aliases are traversed
+ * lazily so N files behind M directory aliases never inflate the index to
+ * N×M entries during listing.
+ */
+export declare class ArchiveReader {
+    #private;
+    readonly format: ArchiveFormat;
+    readonly limits: ArchiveLimits;
+    constructor(format: ArchiveFormat, entries: ArchiveIndexEntry[], limits?: ArchiveLimits);
+    /**
+     * Raw index entries, including link records and synthesized directories.
+     * For extraction/merge flows that need storage kinds; path lookups should
+     * use {@link getNode}/{@link readFile}, which resolve symlink aliases.
+     */
+    indexEntries(): IterableIterator<ArchiveIndexEntry>;
+    /** Resolve a path to its node, or `undefined` when absent or escaping the root. */
+    getNode(subPath?: string): ArchiveNode | undefined;
+    /** List one directory's children, sorted case-insensitively by name. */
+    listDirectory(subPath?: string): ArchiveDirectoryEntry[];
+    /** Extract one file member's bytes, following symlink aliases. */
+    readFile(subPath: string): Promise<ExtractedArchiveFile>;
+}

package/dist/types/ar/registry.d.ts

@@ -0,0 +1,17 @@
+import type { ArchiveFormat, FormatReader } from "./types.js";
+/**
+ * Regex alternation of every recognized archive extension, longest first so
+ * `.tar.gz` wins over `.gz`. Shared with `parseArchivePathCandidates` as its
+ * split pattern so extension recognition and path splitting never drift.
+ */
+export declare const ARCHIVE_EXTENSION_ALTERNATION: string;
+/** Infer an archive format from a filesystem path's extension. */
+export declare function archiveFormatFromPath(filePath: string): ArchiveFormat | undefined;
+/** The format reader responsible for `format`. */
+export declare function formatReaderFor(format: ArchiveFormat): FormatReader;
+/**
+ * Sniff an archive format from its bytes. Pass the full buffer when
+ * available: most probes read the head, but tar needs offset 257, ISO offset
+ * 32769, and the trailing ZIP central-directory scan needs the tail.
+ */
+export declare function sniffArchiveFormat(bytes: Uint8Array): ArchiveFormat | undefined;

package/dist/types/ar/rpm.d.ts

@@ -0,0 +1,5 @@
+import type { FormatReader } from "./types.js";
+/** Read an RPM lead, headers, compressed payload, and its contained CPIO entries. */
+export declare const readRpm: FormatReader;
+/** Detect the four-byte RPM package lead magic. */
+export declare function sniffRpm(bytes: Uint8Array): boolean;

package/dist/types/ar/sevenzip/decode.d.ts

@@ -0,0 +1,33 @@
+import type { ArchiveLimits } from "../limits.js";
+import type { ByteSource } from "../source.js";
+/** One 7z coder and its global folder-stream coordinates. */
+export interface SevenZipCoder {
+    id: bigint;
+    properties: Uint8Array;
+    inputStart: number;
+    outputStart: number;
+    numInputs: number;
+    numOutputs: number;
+}
+/** One binding from a coder output stream to another coder input stream. */
+export interface SevenZipBindPair {
+    input: number;
+    output: number;
+}
+/** Parsed folder graph and its lazy packed-data coordinates. */
+export interface SevenZipFolderRecord {
+    coders: SevenZipCoder[];
+    bindPairs: SevenZipBindPair[];
+    packedIndices: number[];
+    unpackSizes: number[];
+    packOffsets: number[];
+    packSizes: number[];
+    packCrcs: Array<number | undefined>;
+    crc?: number;
+}
+/** Shared lazy decoder/cache for a single 7z folder (solid block). */
+export declare class SevenZipFolderSource {
+    #private;
+    constructor(source: ByteSource, folder: SevenZipFolderRecord, limits: ArchiveLimits);
+    read(): Promise<Uint8Array>;
+}

package/dist/types/ar/sevenzip.d.ts

@@ -0,0 +1,5 @@
+import type { FormatReader } from "./types.js";
+/** Whether bytes begin with the canonical 7z signature. */
+export declare function sniffSevenZip(bytes: Uint8Array): boolean;
+/** Index a 7z archive and lazily decode member folders on extraction. */
+export declare const readSevenZip: FormatReader;

package/dist/types/ar/source.d.ts

@@ -0,0 +1,54 @@
+/**
+ * A byte window into an archive — file-backed (lazy, ranged reads) or
+ * in-memory. Format readers index through this so ZIP/ASAR/RAR payloads are
+ * only read when a member is actually extracted.
+ */
+export interface ByteSource {
+    readonly size: number;
+    read(start: number, end: number): Promise<Uint8Array>;
+}
+/** Reject a nonsensical `[start, end)` range before any read. */
+export declare function assertValidRange(start: number, end: number): void;
+/** Read an exact in-memory range, throwing (not clamping) when it runs past the buffer. */
+export declare function readMemoryRange(buffer: Uint8Array, start: number, end: number): Uint8Array;
+/** Wrap borrowed bytes as a {@link ByteSource}. */
+export declare function memoryByteSource(buffer: Uint8Array): ByteSource;
+/** Lazily read ranges of a file on disk as a {@link ByteSource}. */
+export declare function fileByteSource(filePath: string): ByteSource;
+/** Materialize an entire {@link ByteSource}; use only under a limits check. */
+export declare function readAllBytes(source: ByteSource): Promise<Uint8Array>;
+/** Options for {@link httpByteSource}. */
+export interface HttpByteSourceOptions {
+    /** Extra request headers (e.g. authorization). */
+    headers?: Record<string, string>;
+    /** Fetch implementation seam for tests; defaults to global `fetch`. */
+    fetch?: typeof fetch;
+    /**
+     * When the server ignores `Range` (responds 200), the body is buffered in
+     * memory instead, capped to this many bytes. Default 256 MiB.
+     */
+    maxFallbackBytes?: number;
+}
+/**
+ * A {@link ByteSource} over HTTP(S) range requests, so remote archives can be
+ * indexed and read member-by-member without downloading the whole file.
+ * Probes with `Range: bytes=0-0`; servers without range support fall back to
+ * one bounded full download. Wrap with {@link cachingByteSource} to coalesce
+ * the many small header reads format parsers issue.
+ */
+export declare function httpByteSource(url: string | URL, options?: HttpByteSourceOptions): Promise<ByteSource>;
+/** Options for {@link cachingByteSource}. */
+export interface CachingByteSourceOptions {
+    /** Cache block size in bytes. Default 256 KiB. */
+    blockSize?: number;
+    /** Max cached blocks. Default 64 (16 MiB at the default block size). */
+    maxBlocks?: number;
+}
+/**
+ * Wrap a high-latency {@link ByteSource} (HTTP, network filesystems) with an
+ * aligned-block LRU cache. Small header reads coalesce into shared block
+ * fetches (concurrent readers of one block share a single in-flight request);
+ * reads spanning more than two blocks bypass the cache to avoid copying large
+ * member payloads through it.
+ */
+export declare function cachingByteSource(source: ByteSource, options?: CachingByteSourceOptions): ByteSource;

package/dist/types/ar/tar.d.ts

@@ -0,0 +1,9 @@
+import type { ArchiveIndexEntry, FormatReader, FormatReadOptions } from "./types.js";
+/** Index an already-decompressed tar buffer with bounded GNU, ustar, and PAX handling. */
+export declare function readTarEntriesFromBuffer(buffer: Uint8Array, options: FormatReadOptions): ArchiveIndexEntry[];
+/** Read and index a tar source after one bounded whole-stream read. */
+export declare const readTar: FormatReader;
+/** Detect a tar header, including legacy pre-ustar archives, by its checksum. */
+export declare function sniffTar(bytes: Uint8Array): boolean;
+/** Encode files as a deterministic ustar archive, using PAX records for overflow paths. */
+export declare function encodeTar(members: Iterable<readonly [string, Uint8Array]>): Promise<Uint8Array>;

package/dist/types/ar/types.d.ts

@@ -0,0 +1,99 @@
+import type { ArchiveLimits } from "./limits.js";
+import type { ByteSource } from "./source.js";
+/** Archive container formats readable by the unified archive API. */
+export type ArchiveFormat = "zip" | "tar" | "tar.gz" | "tar.bz2" | "tar.xz" | "tar.zst" | "tar.Z" | "asar" | "rar" | "7z" | "iso" | "cab" | "cpio" | "rpm" | "ar" | "deb" | "lzh" | "arj" | "gz" | "bz2" | "xz" | "zst" | "Z" | "lzma";
+/** Archive formats the unified API can serialize. Everything else is read-only. */
+export type WritableArchiveFormat = "zip" | "tar" | "tar.gz" | "tar.zst" | "asar";
+/**
+ * Where to read an archive from: an extension-inferred filesystem path, a
+ * format-tagged filesystem path, in-memory bytes, or any caller-provided
+ * {@link ByteSource} (e.g. `httpByteSource` for ranged remote reads).
+ * File- and source-backed ZIP/ASAR/RAR/7z/ISO are read lazily.
+ */
+export type ArchiveSource = string | {
+    bytes: Uint8Array;
+    format: ArchiveFormat;
+} | {
+    path: string;
+    format: ArchiveFormat;
+} | {
+    source: ByteSource;
+    format: ArchiveFormat;
+    path?: string;
+};
+/** Content for a member when packing or extracting an archive. */
+export type ArchiveMemberContent = string | Uint8Array | Blob;
+/** One `archive.ext:inner/path` split candidate (see `parseArchivePathCandidates`). */
+export interface ArchivePathCandidate {
+    archivePath: string;
+    subPath: string;
+}
+/** A file or directory node visible through an `ArchiveReader`. */
+export interface ArchiveNode {
+    path: string;
+    isDirectory: boolean;
+    size: number;
+    mtimeMs?: number;
+    /** Unix permission/type bits when the container records them. */
+    mode?: number;
+}
+/** An {@link ArchiveNode} with its name relative to the listed directory. */
+export interface ArchiveDirectoryEntry extends ArchiveNode {
+    name: string;
+}
+/** An {@link ArchiveNode} with its extracted payload. */
+export interface ExtractedArchiveFile extends ArchiveNode {
+    bytes: Uint8Array;
+}
+/**
+ * Format-owned handle that extracts one member's bytes on demand. Instances
+ * may share per-archive state (solid-block decoders, 7z folder caches).
+ * Prefer classes with prototype methods over closures: archives can index
+ * hundreds of thousands of members.
+ */
+export interface MemberSource {
+    /**
+     * Read this member's bytes. `size` is the entry's declared uncompressed
+     * size (already bounds-checked); `memberPath` is for error messages.
+     * Implementations must verify the produced byte count (and checksums when
+     * the container records them) and throw {@link ArchiveError} on mismatch.
+     */
+    read(size: number, memberPath: string): Promise<Uint8Array>;
+}
+/**
+ * How an indexed entry's bytes are stored. `link` entries alias another
+ * archive path and are resolved lazily by the reader core; `member` entries
+ * defer to their format module.
+ */
+export type EntryStorage = {
+    type: "link";
+    targetPath: string;
+    /** Follow before target kind is known (ASAR link records do not encode it). */
+    resolveTarget: boolean;
+} | {
+    type: "member";
+    source: MemberSource;
+};
+/** One indexed entry as produced by a format reader, before core resolution. */
+export interface ArchiveIndexEntry extends ArchiveNode {
+    storage?: EntryStorage;
+}
+/** Context passed to every format reader. */
+export interface FormatReadOptions {
+    limits: ArchiveLimits;
+    /**
+     * Filesystem path of the archive when file-backed. Formats that reference
+     * sibling files use it (ASAR `.unpacked` payloads, multi-volume RAR).
+     */
+    archivePath?: string;
+}
+/**
+ * Contract implemented by every format module: index `source` into normalized
+ * entries without materializing member payloads unless the container forces
+ * it (tar streams, solid archives). Implementations must:
+ * - normalize paths via `normalizeArchiveEntryPath` and drop unrepresentable ones,
+ * - enforce `options.limits` before metadata-driven allocations,
+ * - throw {@link ArchiveError} for malformed, truncated, encrypted, or
+ *   unsupported input — never a bare `Error`, and never process-fatal paths.
+ */
+export type FormatReader = (source: ByteSource, options: FormatReadOptions) => Promise<ArchiveIndexEntry[]>;

package/dist/types/ar/unix-ar.d.ts

@@ -0,0 +1,7 @@
+import type { ArchiveIndexEntry, FormatReader, FormatReadOptions } from "./types.js";
+/** Parse a fully materialized Unix ar archive for composition by formats such as deb. */
+export declare function readUnixArEntriesFromBuffer(bytes: Uint8Array, options: FormatReadOptions): ArchiveIndexEntry[];
+/** Read a Unix ar, static-library, or COFF import-library container. */
+export declare const readUnixAr: FormatReader;
+/** Detect the Unix ar global header. */
+export declare function sniffUnixAr(bytes: Uint8Array): boolean;

package/dist/types/ar/write.d.ts

@@ -0,0 +1,10 @@
+import type { ArchiveFormat, ArchiveMemberContent, WritableArchiveFormat } from "./types.js";
+/** Whether `format` can be serialized by {@link writeArchive} (rest are read-only). */
+export declare function isWritableArchiveFormat(format: ArchiveFormat): format is WritableArchiveFormat;
+/**
+ * Serialize `entries` into an archive of `format` in memory. String members
+ * are encoded as UTF-8; member names are normalized to forward slashes.
+ */
+export declare function encodeArchive(format: WritableArchiveFormat, entries: Iterable<readonly [string, ArchiveMemberContent]>): Promise<Uint8Array>;
+/** {@link encodeArchive}, written to `destPath` (parent directories auto-created). */
+export declare function writeArchive(destPath: string, format: WritableArchiveFormat, entries: Iterable<readonly [string, ArchiveMemberContent]>): Promise<void>;

package/dist/types/ar/zip.d.ts

@@ -0,0 +1,10 @@
+import { type ArchiveLimits } from "./limits.js";
+import type { FormatReader } from "./types.js";
+/** Index a ZIP/ZIP64 archive lazily from its central directory. */
+export declare const readZip: FormatReader;
+/** Detect a ZIP local header, empty-archive end record, or leading data descriptor. */
+export declare function sniffZip(bytes: Uint8Array): boolean;
+/** Materialize every regular ZIP member into a path-to-bytes map for document converters. */
+export declare function readZipEager(bytes: Uint8Array, limits?: ArchiveLimits): Promise<Map<string, Uint8Array>>;
+/** Encode deterministic stored/deflated ZIP bytes, emitting ZIP64 end records when the entry count requires them. */
+export declare function encodeZip(members: Iterable<readonly [string, Uint8Array]>): Promise<Uint8Array>;