@vibe-agent-toolkit/utils 0.2.0-rc.11 → 0.2.0-rc.12

package/dist/archive/archive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive.js","sourceRoot":"","sources":["../../src/archive/archive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,eAAe,EAAe,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAClF,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE5E,OAAO,EAAqB,qBAAqB,EAA0C,mBAAmB,EAAE,mBAAmB,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACnK,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAExD,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAwCxD,MAAM,OAAO,GAAgH;IAC3H,GAAG,EAAE,OAAO;IACZ,GAAG,EAAE,OAAO;CACb,CAAC;AAEF,mGAAmG;AACnG,MAAM,SAAS,GAAG,KAAK,CAAC;AACxB,MAAM,eAAe,GAAG,KAAK,CAAC;AAC9B,MAAM,eAAe,GAAG,KAAK,CAAC;AAC9B,MAAM,SAAS,GAAG,KAAK,CAAC;AAExB;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAe,EAAE,UAAmB;IACpE,MAAM,OAAO,GAAG,OAAO,GAAG,eAAe,CAAC;IAC1C,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,OAAO,GAAG,SAAS,CAAC;AACvG,CAAC;AAED,MAAM,OAAO,GAAG,CAAC,MAAqB,EAAU,EAAE,CAAC,CAAC,MAAM,IAAI,MAAM,CAAC,CAAC,CAAC,cAAc,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAEnH;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAY,EAAE,IAAY,EAAE,MAAqB;IACrF,OAAO,MAAM,WAAW,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,oBAAoB,cAAc,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,KAAK,IAAI,EAAE;QAChI,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,IAAI,CAAC,CAAC;QAC1C,IAAI,CAAC;YACH,IAAI,CAAC,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,GAAG,eAAe,CAAC,MAAM,CAAC;gBAAE,MAAM,QAAQ,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;YACvG,OAAO,MAAM,MAAM,CAAC,QAAQ,EAAE,CAAC;QACjC,CAAC;gBAAS,CAAC;YACT,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACvB,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED,KAAK,UAAU,OAAO,CAAC,MAAqB,EAAE,MAAqB;IACjE,IAAI,MAAM,IAAI,MAAM;QAAE,OAAO,MAAM,eAAe,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACrF,IAAI,MAAM,CAAC,KAAK,CAAC,UAAU,GAAG,eAAe,CAAC,MAAM,CAAC;QAAE,MAAM,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAC5F,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,UAAU,EAAE,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;AAC5F,CAAC;AAED;;;;GAIG;AACH,SAAS,aAAa,CAAC,OAAe,EAAE,MAAqB;IAC3D,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;IACvB,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,MAAM,IAAI,qBAAqB,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,EAAE,qBAAqB,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACjH,CAAC;IACD,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC;QAChC,MAAM,IAAI,qBAAqB,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,EAAE,YAAY,MAAM,CAAC,IAAI,oBAAoB,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IAClH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAMD,KAAK,UAAU,WAAW,CAAC,MAAqB,EAAE,OAA2B;IAC3E,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9B,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACtG,MAAM,OAAO,GAAG,IAAI,GAAG,CAA8B,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IAChG,OAAO;QACL,KAAK;QACL,OAAO,EAAE,OAAO;QAChB,OAAO;QACP,IAAI,CAAC,KAAK;YACR,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YAClC,IAAI,MAAM,KAAK,SAAS;gBAAE,MAAM,IAAI,SAAS,CAAC,IAAI,KAAK,CAAC,IAAI,wBAAwB,KAAK,EAAE,CAAC,CAAC;YAC7F,OAAO,aAAa,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QACtC,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,MAAqB,EAAE,OAA2B;IAClF,OAAO,MAAM,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC5C,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,MAAqB,EAAE,OAA2B;IAClF,OAAO,CAAC,MAAM,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;AACtD,CAAC;AAED;;;;;GAKG;AACH,KAAK,UAAU,UAAU,CAAC,MAAqB,EAAE,OAA2B;IAC1E,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClD,MAAM,OAAO,GAAG,mBAAmB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACpD,IAAI,OAAO,KAAK,SAAS;QAAE,MAAM,IAAI,mBAAmB,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAChF,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,sFAAsF;AACtF,MAAM,WAAW,GAAG,CAAC,MAAqB,EAAE,OAA8B,EAA4B,EAAE,CACtG,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,CAAC;AAEnH,qIAAqI;AACrI,KAAK,UAAU,WAAW,CAAC,OAAe,EAAE,IAAY,EAAE,MAAqB;IAC7E,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChD,MAAM,OAAO,GAAG,aAAa,MAAM,CAAC,IAAI,OAAO,OAAO,EAAE,CAAC;IACzD,IAAI,MAAM,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QAChC,kEAAkE;QAClE,IAAI,QAAQ,KAAK,EAAE;YAAE,MAAM,kBAAkB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;QACvE,OAAO;IACT,CAAC;IACD,MAAM,IAAI,GAAG,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC5C,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;IACpF,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAC7B,qGAAqG;QACrG,MAAM,MAAM,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;IACvF,CAAC;YAAS,CAAC;QACT,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,MAAqB,EAAE,IAAY,EAAE,OAA8B;IACtG,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjD,IAAI,CAAC;QACH,oFAAoF;QACpF,MAAM,cAAc,CAAC,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,WAAW,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IAC1G,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,MAAM,eAAe,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,WAAW,MAAM,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IACvG,CAAC;IACD,OAAO,MAAM,CAAC,OAAO,CAAC;AACxB,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,MAAqB,EAAE,OAA8B;IACtF,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjD,OAAO,YAAY,CAAC,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE;QAClE,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC7C,4DAA4D;QAC5D,IAAI,KAAK,KAAK,EAAE;YAAE,OAAO,EAAE,CAAC;QAC5B,OAAO,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;IACzI,CAAC,CAAC,CAAC,CAAC;AACN,CAAC"}

package/dist/archive/entries.d.ts

@@ -0,0 +1,132 @@
+/**
+ * What an archive holds, and the ONE policy for which archives VAT extracts — decided from the
+ * entry list alone, before anything is written. Pure: nothing here reads or writes.
+ */
+import { VatError } from '../errors/vat-error.js';
+/** The archive formats VAT reads: a ZIP, or a tar stream (gzipped or plain). */
+export type ArchiveFormat = 'zip' | 'tar';
+/** What one entry of an archive is. `other` is a device, a FIFO, a socket or a type VAT does not know. */
+export type ArchiveEntryKind = 'file' | 'directory' | 'link' | 'hardlink' | 'other';
+/** One entry of an archive, as the archive spells it. */
+export interface ArchiveEntry {
+    /** The entry's name as the archive spells it, every backslash read as `/` ({@link entryNameOf}). */
+    readonly name: string;
+    readonly kind: ArchiveEntryKind;
+    /** The uncompressed size the entry's header declares, in bytes; `0` for anything but a file. */
+    readonly size: number;
+}
+/** How much an archive may hold. Every reader is given one: there is no default, because an omitted bound is the failure. */
+export interface ArchiveLimits {
+    /** The most entries — files, directories and everything else — the archive may list. */
+    readonly maxEntries: number;
+    /** The most bytes its files may expand to, summed. */
+    readonly maxBytes: number;
+}
+/** The code of every {@link ArchiveRefusedError}. */
+export declare const ARCHIVE_REFUSED_CODE = "ARCHIVE_REFUSED";
+/**
+ * Why an archive was refused:
+ * - `unreadable`: its bytes are no archive of the format;
+ * - `unsupported`: it IS an archive, and one VAT will not take — a ZIP64 ZIP, an end record or
+ *   directory two readers would read differently, or a tarball cut short inside an entry
+ *   (`entry` names it). Never passed on by any lane, where `unreadable` bytes may be. One entry
+ *   that does not inflate or hold what it declares, asked for after the archive opened, is
+ *   {@link ArchiveEntryReadError} instead;
+ * - `link`, `hardlink`, `special`: it holds an entry that is not a file or a directory;
+ * - `unsafe-name`: an entry is named outside the directory it is extracted into;
+ * - `name-clash`: two entries are one name, or one is a file with another at or under it;
+ * - `too-many-entries`, `too-large`: it is past an {@link ArchiveLimits} bound.
+ */
+export type ArchiveRefusalReason = 'unreadable' | 'unsupported' | 'link' | 'hardlink' | 'special' | 'unsafe-name' | 'name-clash' | 'too-many-entries' | 'too-large';
+/** An archive VAT will not read, extract or pass on: the input's refusal, never the run's. */
+export declare class ArchiveRefusedError extends VatError {
+    readonly reason: ArchiveRefusalReason;
+    /**
+     * The entry the refusal is about, as the archive spells it: the first offending one for a
+     * `link`, `hardlink`, `special`, `unsafe-name` or `name-clash`, and the cut-short entry of an
+     * `unsupported` tarball — the archive is refused as a whole all the same. None when no one entry
+     * is to blame (`unreadable`, a limit, a ZIP structure two readers would read differently).
+     */
+    readonly entry: string | undefined;
+    /**
+     * @param archive - What the operator named: the archive's path or URL
+     * @param refusal - Why, and the entry it is about
+     */
+    constructor(archive: string, refusal: {
+        readonly reason: ArchiveRefusalReason;
+        readonly entry?: string;
+        readonly why: string;
+    }, options?: ErrorOptions);
+}
+/** The code of every {@link ArchiveEntryReadError}. */
+export declare const ARCHIVE_ENTRY_UNREADABLE_CODE = "ARCHIVE_ENTRY_UNREADABLE";
+/**
+ * The refusal of ONE entry an opened archive was asked to read: it does not inflate, or does not
+ * hold what it declares. Its own code ({@link ARCHIVE_ENTRY_UNREADABLE_CODE}), so a lane that may
+ * skip one member tells it from every refusal of the whole archive by
+ * {@link isArchiveEntryReadRefusal} — the brand and the code, never the prototype chain and never
+ * whether an `entry` happens to be set (a clash, a link and a cut-short tarball name one too).
+ */
+export declare class ArchiveEntryReadError extends VatError {
+    readonly entry: string;
+    /**
+     * @param archive - What the operator named: the archive's path or URL
+     * @param entry - The entry, as the archive spells it
+     * @param what - What is wrong with it, completing "its entry `x` …"
+     */
+    constructor(archive: string, entry: string, what: string, options?: ErrorOptions);
+}
+/**
+ * Whether `error` is the archive module refusing one entry's read ({@link ArchiveEntryReadError}):
+ * by the brand and {@link ARCHIVE_ENTRY_UNREADABLE_CODE}, so a `dist` copy of the class answers as a
+ * `src` one does.
+ */
+export declare function isArchiveEntryReadRefusal(error: unknown): error is ArchiveEntryReadError;
+/** A refusal before it names its archive: what {@link archiveEntryRefusal} answers. */
+export interface EntryRefusal {
+    readonly reason: ArchiveRefusalReason;
+    readonly entry: string;
+    readonly why: string;
+}
+/**
+ * An entry's name as both readers hand it on, on every host: the archive's spelling with every
+ * backslash read as `/` — the separator VAT reads it as everywhere, in a tarball as in a ZIP. The
+ * tar library already does this on win32, and only there; doing it here for both formats on every
+ * host keeps one listing, so a refusal names an entry the same way wherever VAT runs.
+ *
+ * @param spelled - The name as the format's library decoded it
+ * @returns The name with forward slashes
+ */
+export declare function entryNameOf(spelled: string): string;
+/**
+ * Where an entry lands under the directory it is extracted into: its segments, a backslash read
+ * as a separator on every host (as a ZIP written on Windows spells one), empty and `.` segments
+ * dropped. Only for a name {@link unsafeNameReason} accepts.
+ */
+export declare function placeOf(name: string): string[];
+/**
+ * The first reason `entries` cannot be extracted, or `undefined` when every entry may be. An
+ * archive is extracted whole or not at all, so one offending entry refuses it:
+ *
+ * - an entry that is not a regular file or a directory — a symbolic link, a hard link, a device,
+ *   a FIFO (`npm pack` and a skill ZIP hold none);
+ * - a name that is absolute, begins with a drive letter, is a UNC path, holds a `..` segment or a
+ *   NUL (a backslash is read as a separator on every host); or one with a segment Windows cannot
+ *   hold as spelled — a `:`, one of `<` `>` `"` `|` `?` `*`, a control character (code points
+ *   1–31), a trailing `.` or space, a device name (`CON`, `com1.txt`) — on every host;
+ * - two entries that are one name — exactly, or once folded as a case-insensitive or
+ *   normalising volume folds them ({@link foldedSegment}) — or a file with another entry under it.
+ *
+ * @param entries - Every entry of the archive, in archive order
+ * @returns The refusal of the first offending entry, in archive order
+ */
+export declare function archiveEntryRefusal(entries: readonly ArchiveEntry[]): EntryRefusal | undefined;
+/**
+ * Refuse `archive` when its entries cannot all be extracted ({@link archiveEntryRefusal}).
+ *
+ * @param archive - What the operator named, for the message
+ * @param entries - Every entry of the archive, in archive order
+ * @throws ArchiveRefusedError naming the first offending entry
+ */
+export declare function assertArchiveExtractable(archive: string, entries: readonly ArchiveEntry[]): void;
+//# sourceMappingURL=entries.d.ts.map

package/dist/archive/entries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entries.d.ts","sourceRoot":"","sources":["../../src/archive/entries.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAc,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAI9D,gFAAgF;AAChF,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,KAAK,CAAC;AAE1C,0GAA0G;AAC1G,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC;AAEpF,yDAAyD;AACzD,MAAM,WAAW,YAAY;IAC3B,oGAAoG;IACpG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,gGAAgG;IAChG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,6HAA6H;AAC7H,MAAM,WAAW,aAAa;IAC5B,wFAAwF;IACxF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,qDAAqD;AACrD,eAAO,MAAM,oBAAoB,oBAAoB,CAAC;AAEtD;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,oBAAoB,GAAG,YAAY,GAAG,aAAa,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,GAAG,aAAa,GAAG,YAAY,GAAG,kBAAkB,GAAG,WAAW,CAAC;AAOpK,8FAA8F;AAC9F,qBAAa,mBAAoB,SAAQ,QAAQ;IAC/C,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAEnC;;;OAGG;gBACS,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;QAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;KAAE,EAAE,OAAO,CAAC,EAAE,YAAY;CAKvJ;AAED,uDAAuD;AACvD,eAAO,MAAM,6BAA6B,6BAA6B,CAAC;AAExE;;;;;;GAMG;AACH,qBAAa,qBAAsB,SAAQ,QAAQ;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB;;;;OAIG;gBACS,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAIjF;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,qBAAqB,CAExF;AAED,uFAAuF;AACvF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD;AAKD;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAE9C;AA0GD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,YAAY,GAAG,SAAS,CAO9F;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,IAAI,CAGhG"}

package/dist/archive/entries.js

@@ -0,0 +1,223 @@
+/**
+ * What an archive holds, and the ONE policy for which archives VAT extracts — decided from the
+ * entry list alone, before anything is written. Pure: nothing here reads or writes.
+ */
+import { isVatError, VatError } from '../errors/vat-error.js';
+import { foldedSegment } from '../name-fold.js';
+import { hasParentTraversalSegment, toForwardSlashAnyPlatform } from '../path-core.js';
+/** The code of every {@link ArchiveRefusedError}. */
+export const ARCHIVE_REFUSED_CODE = 'ARCHIVE_REFUSED';
+/** The sentence every archive refusal is: the archive named, then why. */
+function refusalMessage(archive, why) {
+    return `${archive} is not an archive VAT accepts, nothing was changed: ${why}`;
+}
+/** An archive VAT will not read, extract or pass on: the input's refusal, never the run's. */
+export class ArchiveRefusedError extends VatError {
+    reason;
+    /**
+     * The entry the refusal is about, as the archive spells it: the first offending one for a
+     * `link`, `hardlink`, `special`, `unsafe-name` or `name-clash`, and the cut-short entry of an
+     * `unsupported` tarball — the archive is refused as a whole all the same. None when no one entry
+     * is to blame (`unreadable`, a limit, a ZIP structure two readers would read differently).
+     */
+    entry;
+    /**
+     * @param archive - What the operator named: the archive's path or URL
+     * @param refusal - Why, and the entry it is about
+     */
+    constructor(archive, refusal, options) {
+        super(ARCHIVE_REFUSED_CODE, refusalMessage(archive, refusal.why), options);
+        this.reason = refusal.reason;
+        this.entry = refusal.entry;
+    }
+}
+/** The code of every {@link ArchiveEntryReadError}. */
+export const ARCHIVE_ENTRY_UNREADABLE_CODE = 'ARCHIVE_ENTRY_UNREADABLE';
+/**
+ * The refusal of ONE entry an opened archive was asked to read: it does not inflate, or does not
+ * hold what it declares. Its own code ({@link ARCHIVE_ENTRY_UNREADABLE_CODE}), so a lane that may
+ * skip one member tells it from every refusal of the whole archive by
+ * {@link isArchiveEntryReadRefusal} — the brand and the code, never the prototype chain and never
+ * whether an `entry` happens to be set (a clash, a link and a cut-short tarball name one too).
+ */
+export class ArchiveEntryReadError extends VatError {
+    entry;
+    /**
+     * @param archive - What the operator named: the archive's path or URL
+     * @param entry - The entry, as the archive spells it
+     * @param what - What is wrong with it, completing "its entry `x` …"
+     */
+    constructor(archive, entry, what, options) {
+        super(ARCHIVE_ENTRY_UNREADABLE_CODE, refusalMessage(archive, `its entry \`${entry}\` ${what}`), options);
+        this.entry = entry;
+    }
+}
+/**
+ * Whether `error` is the archive module refusing one entry's read ({@link ArchiveEntryReadError}):
+ * by the brand and {@link ARCHIVE_ENTRY_UNREADABLE_CODE}, so a `dist` copy of the class answers as a
+ * `src` one does.
+ */
+export function isArchiveEntryReadRefusal(error) {
+    return isVatError(error, ARCHIVE_ENTRY_UNREADABLE_CODE);
+}
+/**
+ * An entry's name as both readers hand it on, on every host: the archive's spelling with every
+ * backslash read as `/` — the separator VAT reads it as everywhere, in a tarball as in a ZIP. The
+ * tar library already does this on win32, and only there; doing it here for both formats on every
+ * host keeps one listing, so a refusal names an entry the same way wherever VAT runs.
+ *
+ * @param spelled - The name as the format's library decoded it
+ * @returns The name with forward slashes
+ */
+export function entryNameOf(spelled) {
+    return toForwardSlashAnyPlatform(spelled);
+}
+/** A Windows drive prefix (`C:`), which makes a name absolute or drive-relative there. */
+const DRIVE_PREFIX = /^[A-Za-z]:/;
+/**
+ * Where an entry lands under the directory it is extracted into: its segments, a backslash read
+ * as a separator on every host (as a ZIP written on Windows spells one), empty and `.` segments
+ * dropped. Only for a name {@link unsafeNameReason} accepts.
+ */
+export function placeOf(name) {
+    return toForwardSlashAnyPlatform(name).split('/').filter((segment) => segment !== '' && segment !== '.');
+}
+/**
+ * A Windows device name, whatever follows it after a `.` and whatever its case: `CON`, `prn.txt`,
+ * `Aux.tar.gz` (Microsoft: "NUL.txt and NUL.tar.gz are both equivalent to NUL"), `COM1`…`COM9`,
+ * `LPT1`…`LPT9`, and the superscript-digit forms `COM¹` `LPT³`, which Windows reads as digits. A
+ * space before the `.` is over-refused on purpose: Win32 drops it, so `con .md` may be `CON`.
+ *
+ * @vendor-claim reviewed=2026-10-26 verify=Re-read https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file — "File and Directory Names", the reserved-names list (item 9) and the trailing space or period rule (item 10)
+ */
+const WINDOWS_DEVICE_NAME = /^(?:con|prn|aux|nul|com[1-9¹²³]|lpt[1-9¹²³]) *(?:\.|$)/i;
+/**
+ * The other characters Windows reserves in a name (item 1 of the same page): `<` `>` `"` `|` `?`
+ * `*`, and the code points 1–31. (NUL, code point 0, has its own refusal; `/` and `\` are
+ * separators; `:` has its own reason.)
+ */
+const WINDOWS_RESERVED_CHARACTERS = new Set(['<', '>', '"', '|', '?', '*', ...Array.from({ length: 31 }, (_unused, index) => String.fromCodePoint(index + 1))]);
+/**
+ * Why one segment of a name is one Windows cannot hold as spelled, or `undefined`. Refused on EVERY
+ * host, so one archive has one verdict wherever VAT runs: on NTFS a `:` names a stream of the file
+ * before it (`notes:v2.md` writes into `notes`), a reserved character cannot be written at all, a
+ * device name opens the device, and a trailing `.` or space is dropped from the name a Win32 tool sees.
+ */
+function windowsSegmentReason(segment) {
+    if (segment.includes(':'))
+        return 'holds a `:`, which on NTFS names a stream of the file before it';
+    if ([...segment].some((character) => WINDOWS_RESERVED_CHARACTERS.has(character)))
+        return 'holds a character Windows does not allow in a name (`<` `>` `"` `|` `?` `*`, or a control character)';
+    if (segment.endsWith('.') || segment.endsWith(' '))
+        return 'ends in a `.` or a space, which Windows drops from a name';
+    return WINDOWS_DEVICE_NAME.test(segment) ? 'is a Windows device name' : undefined;
+}
+/** Why `name` would land outside the extraction directory, or somewhere other than it says, on some host; or `undefined`. */
+function unsafeNameReason(name) {
+    if (name.includes('\0'))
+        return 'holds a NUL character';
+    const spelled = toForwardSlashAnyPlatform(name);
+    if (spelled.startsWith('/'))
+        return 'is an absolute path';
+    if (DRIVE_PREFIX.test(spelled))
+        return 'begins with a drive letter';
+    if (hasParentTraversalSegment(name))
+        return 'holds a `..` segment';
+    for (const segment of placeOf(name)) {
+        const reason = windowsSegmentReason(segment);
+        if (reason !== undefined)
+            return reason;
+    }
+    return undefined;
+}
+/** What each entry kind that is not extracted is called, and its reason. */
+const UNEXTRACTED = {
+    link: { reason: 'link', what: 'a symbolic link' },
+    hardlink: { reason: 'hardlink', what: 'a hard link' },
+    other: { reason: 'special', what: 'a device, a named pipe or another special file' },
+};
+/** The refusal of an entry for what it is or how it is named, or `undefined`. */
+function entryRefusal(entry) {
+    if (entry.kind !== 'file' && entry.kind !== 'directory') {
+        const { reason, what } = UNEXTRACTED[entry.kind];
+        return { reason, entry: entry.name, why: `its entry \`${entry.name}\` is ${what}, and an archive may hold only files and directories` };
+    }
+    const unsafe = unsafeNameReason(entry.name);
+    if (unsafe !== undefined)
+        return { reason: 'unsafe-name', entry: entry.name, why: `its entry \`${entry.name}\` ${unsafe}, so it names no place inside the archive that every host can write` };
+    if (entry.kind === 'file' && placeOf(entry.name).length === 0) {
+        return { reason: 'unsafe-name', entry: entry.name, why: `its entry \`${entry.name}\` is a file that names no place inside the archive` };
+    }
+    return undefined;
+}
+/**
+ * Claim every place `entry` needs — each directory above it, and its own — refusing the first one
+ * an earlier entry holds differently: under another spelling of one folded name, or as a file
+ * where this entry needs a directory (or the reverse), or as the very same file.
+ */
+function claimPlaces(entry, claims) {
+    const place = placeOf(entry.name);
+    for (let depth = 1; depth <= place.length; depth += 1) {
+        const segments = place.slice(0, depth);
+        const kind = depth === place.length && entry.kind === 'file' ? 'file' : 'directory';
+        const key = segments.map((segment) => foldedSegment(segment)).join('/');
+        const spelled = segments.join('/');
+        const held = claims.get(key);
+        if (held === undefined) {
+            claims.set(key, { spelled, kind, entry: entry.name });
+        }
+        else if (held.spelled !== spelled) {
+            // A `:` and a trailing dot or space were refused with the name, so only the case and Unicode folds are left.
+            return {
+                reason: 'name-clash',
+                entry: entry.name,
+                why: `its entries \`${held.entry}\` and \`${entry.name}\` are one name where a volume folds letter case or Unicode form (\`${held.spelled}\` and \`${spelled}\`), so one would overwrite the other`,
+            };
+        }
+        else if (held.kind === 'file' || kind === 'file') {
+            const why = held.kind === kind
+                ? `it lists \`${entry.name}\` twice`
+                : `it holds both \`${held.entry}\` and \`${entry.name}\`, and \`${spelled}\` is a file in one and a directory in the other, so no directory can hold the two`;
+            return { reason: 'name-clash', entry: entry.name, why };
+        }
+    }
+    return undefined;
+}
+/**
+ * The first reason `entries` cannot be extracted, or `undefined` when every entry may be. An
+ * archive is extracted whole or not at all, so one offending entry refuses it:
+ *
+ * - an entry that is not a regular file or a directory — a symbolic link, a hard link, a device,
+ *   a FIFO (`npm pack` and a skill ZIP hold none);
+ * - a name that is absolute, begins with a drive letter, is a UNC path, holds a `..` segment or a
+ *   NUL (a backslash is read as a separator on every host); or one with a segment Windows cannot
+ *   hold as spelled — a `:`, one of `<` `>` `"` `|` `?` `*`, a control character (code points
+ *   1–31), a trailing `.` or space, a device name (`CON`, `com1.txt`) — on every host;
+ * - two entries that are one name — exactly, or once folded as a case-insensitive or
+ *   normalising volume folds them ({@link foldedSegment}) — or a file with another entry under it.
+ *
+ * @param entries - Every entry of the archive, in archive order
+ * @returns The refusal of the first offending entry, in archive order
+ */
+export function archiveEntryRefusal(entries) {
+    const claims = new Map();
+    for (const entry of entries) {
+        const refusal = entryRefusal(entry) ?? claimPlaces(entry, claims);
+        if (refusal !== undefined)
+            return refusal;
+    }
+    return undefined;
+}
+/**
+ * Refuse `archive` when its entries cannot all be extracted ({@link archiveEntryRefusal}).
+ *
+ * @param archive - What the operator named, for the message
+ * @param entries - Every entry of the archive, in archive order
+ * @throws ArchiveRefusedError naming the first offending entry
+ */
+export function assertArchiveExtractable(archive, entries) {
+    const refusal = archiveEntryRefusal(entries);
+    if (refusal !== undefined)
+        throw new ArchiveRefusedError(archive, refusal);
+}
+//# sourceMappingURL=entries.js.map

package/dist/archive/entries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entries.js","sourceRoot":"","sources":["../../src/archive/entries.ts"],"names":[],"mappings":"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"}

package/dist/archive/limits.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The bounds on what an archive may hold, and the refusals for one past them. An archive past a
+ * bound is the INPUT's refusal: a tarball that would fill the disk is refused for what it is,
+ * before a byte of it is written, never reported as VAT's staging running out.
+ */
+import { ArchiveRefusedError, type ArchiveLimits } from './entries.js';
+/**
+ * What an archive VAT installs from — an npm package tarball, a skill ZIP — may hold. Two orders
+ * of magnitude above any real skill package, and small enough to read in memory.
+ */
+export declare const ARCHIVE_LIMITS: ArchiveLimits;
+/** The most bytes VAT downloads for an archive it is given a URL for. */
+export declare const ARCHIVE_DOWNLOAD_MAX_BYTES: number;
+/**
+ * The most bytes an archive within `limits` can be, read whole — as a file, or as a tar stream
+ * once inflated: its files' bytes and its own structure.
+ */
+export declare function archiveBytesCap(limits: ArchiveLimits): number;
+/** The refusal of an archive listing more entries than `limits` allows. */
+export declare function tooManyEntries(archive: string, limits: ArchiveLimits): ArchiveRefusedError;
+/** The refusal of an archive that expands past `limits`. */
+export declare function tooLarge(archive: string, limits: ArchiveLimits, cause?: unknown): ArchiveRefusedError;
+/** The refusal of bytes that are no archive of the format: the one reason a lane may pass bytes on. */
+export declare function unreadableArchive(archive: string, why: string, cause?: unknown): ArchiveRefusedError;
+/**
+ * The refusal of an archive that parsed, as it is opened, for an entry that does not hold what it
+ * declares: `unsupported`, naming it. Refused as a whole — a read of one entry that fails is
+ * an `ArchiveEntryReadError` instead.
+ */
+export declare function unsupportedEntry(archive: string, entry: string, what: string): ArchiveRefusedError;
+/**
+ * Hold an entry list to `limits`: its count, and the sum of the sizes its files declare.
+ *
+ * @throws ArchiveRefusedError `too-many-entries` or `too-large`
+ */
+export declare function assertWithinLimits(archive: string, entries: ReadonlyArray<{
+    readonly size: number;
+}>, limits: ArchiveLimits): void;
+//# sourceMappingURL=limits.d.ts.map

package/dist/archive/limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../../src/archive/limits.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,mBAAmB,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAIvE;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,aAA2D,CAAC;AAEzF,yEAAyE;AACzE,eAAO,MAAM,0BAA0B,QAAY,CAAC;AAKpD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAE7D;AAED,2EAA2E;AAC3E,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,mBAAmB,CAE1F;AAED,4DAA4D;AAC5D,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,mBAAmB,CAErG;AAED,uGAAuG;AACvG,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,mBAAmB,CAEpG;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,mBAAmB,CAElG;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,EAAE,MAAM,EAAE,aAAa,GAAG,IAAI,CAOlI"}

package/dist/archive/limits.js

@@ -0,0 +1,59 @@
+/**
+ * The bounds on what an archive may hold, and the refusals for one past them. An archive past a
+ * bound is the INPUT's refusal: a tarball that would fill the disk is refused for what it is,
+ * before a byte of it is written, never reported as VAT's staging running out.
+ */
+import { ArchiveRefusedError } from './entries.js';
+const MIB = 1024 * 1024;
+/**
+ * What an archive VAT installs from — an npm package tarball, a skill ZIP — may hold. Two orders
+ * of magnitude above any real skill package, and small enough to read in memory.
+ */
+export const ARCHIVE_LIMITS = { maxEntries: 50_000, maxBytes: 256 * MIB };
+/** The most bytes VAT downloads for an archive it is given a URL for. */
+export const ARCHIVE_DOWNLOAD_MAX_BYTES = 100 * MIB;
+/** What an archive's own structure may add per entry (headers, padding, a long-name record) on top of its files' bytes. */
+const OVERHEAD_PER_ENTRY = 2048;
+/**
+ * The most bytes an archive within `limits` can be, read whole — as a file, or as a tar stream
+ * once inflated: its files' bytes and its own structure.
+ */
+export function archiveBytesCap(limits) {
+    return limits.maxBytes + limits.maxEntries * OVERHEAD_PER_ENTRY + MIB;
+}
+/** The refusal of an archive listing more entries than `limits` allows. */
+export function tooManyEntries(archive, limits) {
+    return new ArchiveRefusedError(archive, { reason: 'too-many-entries', why: `it holds more than ${limits.maxEntries} entries, the most VAT reads from one archive` });
+}
+/** The refusal of an archive that expands past `limits`. */
+export function tooLarge(archive, limits, cause) {
+    return new ArchiveRefusedError(archive, { reason: 'too-large', why: `it expands to more than ${limits.maxBytes} bytes, the most VAT reads from one archive` }, { cause });
+}
+/** The refusal of bytes that are no archive of the format: the one reason a lane may pass bytes on. */
+export function unreadableArchive(archive, why, cause) {
+    return new ArchiveRefusedError(archive, { reason: 'unreadable', why }, { cause });
+}
+/**
+ * The refusal of an archive that parsed, as it is opened, for an entry that does not hold what it
+ * declares: `unsupported`, naming it. Refused as a whole — a read of one entry that fails is
+ * an `ArchiveEntryReadError` instead.
+ */
+export function unsupportedEntry(archive, entry, what) {
+    return new ArchiveRefusedError(archive, { reason: 'unsupported', entry, why: `its entry \`${entry}\` ${what}` });
+}
+/**
+ * Hold an entry list to `limits`: its count, and the sum of the sizes its files declare.
+ *
+ * @throws ArchiveRefusedError `too-many-entries` or `too-large`
+ */
+export function assertWithinLimits(archive, entries, limits) {
+    if (entries.length > limits.maxEntries)
+        throw tooManyEntries(archive, limits);
+    let total = 0;
+    for (const entry of entries) {
+        total += entry.size;
+        if (total > limits.maxBytes)
+            throw tooLarge(archive, limits);
+    }
+}
+//# sourceMappingURL=limits.js.map

package/dist/archive/limits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.js","sourceRoot":"","sources":["../../src/archive/limits.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,mBAAmB,EAAsB,MAAM,cAAc,CAAC;AAEvE,MAAM,GAAG,GAAG,IAAI,GAAG,IAAI,CAAC;AAExB;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAkB,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,GAAG,GAAG,EAAE,CAAC;AAEzF,yEAAyE;AACzE,MAAM,CAAC,MAAM,0BAA0B,GAAG,GAAG,GAAG,GAAG,CAAC;AAEpD,2HAA2H;AAC3H,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAEhC;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,MAAqB;IACnD,OAAO,MAAM,CAAC,QAAQ,GAAG,MAAM,CAAC,UAAU,GAAG,kBAAkB,GAAG,GAAG,CAAC;AACxE,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,cAAc,CAAC,OAAe,EAAE,MAAqB;IACnE,OAAO,IAAI,mBAAmB,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,kBAAkB,EAAE,GAAG,EAAE,sBAAsB,MAAM,CAAC,UAAU,+CAA+C,EAAE,CAAC,CAAC;AACvK,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,QAAQ,CAAC,OAAe,EAAE,MAAqB,EAAE,KAAe;IAC9E,OAAO,IAAI,mBAAmB,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,2BAA2B,MAAM,CAAC,QAAQ,6CAA6C,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;AAC5K,CAAC;AAED,uGAAuG;AACvG,MAAM,UAAU,iBAAiB,CAAC,OAAe,EAAE,GAAW,EAAE,KAAe;IAC7E,OAAO,IAAI,mBAAmB,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,GAAG,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;AACpF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe,EAAE,KAAa,EAAE,IAAY;IAC3E,OAAO,IAAI,mBAAmB,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,GAAG,EAAE,eAAe,KAAK,MAAM,IAAI,EAAE,EAAE,CAAC,CAAC;AACnH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe,EAAE,OAAiD,EAAE,MAAqB;IAC1H,IAAI,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC,UAAU;QAAE,MAAM,cAAc,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC9E,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,KAAK,IAAI,KAAK,CAAC,IAAI,CAAC;QACpB,IAAI,KAAK,GAAG,MAAM,CAAC,QAAQ;YAAE,MAAM,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC/D,CAAC;AACH,CAAC"}

package/dist/archive/records.d.ts

@@ -0,0 +1,14 @@
+/** What the two format readers hand the archive module: an entry, and how to get at its bytes. */
+import type { ArchiveEntry } from './entries.js';
+/** One entry as a reader parsed it. */
+export interface ArchiveRecord extends ArchiveEntry {
+    /** Whether the archive marks the file executable — the only permission bit an extraction carries over. */
+    readonly executable: boolean;
+    /**
+     * A file's bytes. A reader that inflates lazily does so here.
+     *
+     * @throws Whatever the format's reader throws for an entry that does not inflate
+     */
+    readonly read: () => Buffer;
+}
+//# sourceMappingURL=records.d.ts.map

package/dist/archive/records.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"records.d.ts","sourceRoot":"","sources":["../../src/archive/records.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAElG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,uCAAuC;AACvC,MAAM,WAAW,aAAc,SAAQ,YAAY;IACjD,0GAA0G;IAC1G,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,MAAM,CAAC;CAC7B"}

package/dist/archive/records.js

@@ -0,0 +1,3 @@
+/** What the two format readers hand the archive module: an entry, and how to get at its bytes. */
+export {};
+//# sourceMappingURL=records.js.map

package/dist/archive/records.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"records.js","sourceRoot":"","sources":["../../src/archive/records.ts"],"names":[],"mappings":"AAAA,kGAAkG"}

package/dist/archive/tar-reader.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The tar reader: every entry of a tar stream (gzipped or plain), parsed in memory and bounded
+ * while it is parsed. One of the two files in VAT that import an archive library.
+ */
+import { type ArchiveLimits } from './entries.js';
+import type { ArchiveRecord } from './records.js';
+/**
+ * Every entry of the tar archive `bytes`, in archive order, each as the archive spells it ({@link entryNameOf}) — links,
+ * devices and unsafe names included: listing judges nothing. Synchronous and in memory.
+ *
+ * @param bytes - The archive, gzipped or plain
+ * @param archive - What the operator named, for a refusal's message
+ * @param limits - The bounds the archive is held to as it is parsed
+ * @throws ArchiveRefusedError `unreadable` for bytes that are no tar archive; `unsupported`, naming
+ *   the entry, for one whose entry is cut short; `too-many-entries` or `too-large` for one past `limits`
+ */
+export declare function readTar(bytes: Buffer, archive: string, limits: ArchiveLimits): ArchiveRecord[];
+//# sourceMappingURL=tar-reader.d.ts.map

package/dist/archive/tar-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tar-reader.d.ts","sourceRoot":"","sources":["../../src/archive/tar-reader.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,OAAO,EAA+C,KAAK,aAAa,EAAe,MAAM,cAAc,CAAC;AAE5G,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AA+HlD;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,aAAa,EAAE,CA4B9F"}