@t4h.framework/zip 0.0.0-experimental-20260907231524

package/.ai/skills/framework-zip/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: framework-zip
+description: >-
+  Guides correct use of @t4h.framework/zip in workflows: opening a ZIP archive
+  that arrives from SFTP, HTTP or storage, listing what is inside it without
+  downloading it, and extracting the entries that matter into `Binary` files
+  that `read`, `split` and `sftp.put` accept. Use whenever a workflow receives
+  a `.zip` (a compressed batch file, a bundle of invoices, a partner's return
+  package), whenever the user mentions unzipping, decompressing, inflate,
+  deflate, zip entries, or the symbols `unzip`, `list`, `ZipEntry`,
+  `ZipExtractActivity`, and above all when someone is about to hand-roll a
+  lazy `Binary` that inflates on `stream()` in App code. Prefer this skill
+  over `node:zlib` in workflow code and over any hand-written ZIP parsing.
+---
+
+# @t4h.framework/zip
+
+Reading ZIP archives inside a workflow. Package path: `framework/packages/zip`.
+Peer dependencies: `@t4h.framework/core`, `@t4h.framework/fs`.
+
+## Import surface
+
+```typescript
+import { list, unzip } from '@t4h.framework/zip'
+```
+
+Two durable activities, nothing else to wire:
+
+- `unzip(archive, options?)` — extracts entries into files, resolves with
+  `ZipEntry[]` (`{ path, binary, contentLength, compressedLength,
+compressionMethod, crc32, lastModifiedAt, directory }`), directories
+  excluded, in central directory order.
+- `list(archive, options?)` — the same metadata **without** `binary` and
+  without transferring content, directories included.
+
+`archive` is any `Binary`: `sftp.get`, an HTTP response body, `write`, a slice.
+
+## Workflow usage
+
+The canonical pipeline — fetch a compressed batch, extract the one file that
+carries the records, fan it out:
+
+```typescript
+import { split, Split } from '@t4h.framework/fs'
+import { unzip } from '@t4h.framework/zip'
+
+const main = new Workflow(inputSchema, async input => {
+  const archive = await sftp.get(input.path)
+
+  const [file] = await unzip(archive, { include: 'MOVIMENTO.TXT' })
+
+  if (!file) throw new Error(`${input.path} has no movement file`)
+
+  return await split(file.binary, processRecord, {
+    delimiter: Split.line(),
+  })
+})
+```
+
+Deciding from metadata first, when most runs do not need the content:
+
+```typescript
+const entries = await list(archive)
+
+const invoice = entries.find(entry => entry.path.endsWith(`/${id}.txt`))
+
+if (!invoice) return { status: 'missing' }
+
+const [extracted] = await unzip(archive, { include: invoice.path })
+```
+
+## Options
+
+| Option        | Applies to      | Default | Behavior                                                               |
+| ------------- | --------------- | ------- | ---------------------------------------------------------------------- |
+| `include`     | `unzip`, `list` | —       | Glob or array of globs an entry must match.                            |
+| `exclude`     | `unzip`, `list` | —       | Globs that drop entries, applied after `include`.                      |
+| `encoding`    | `unzip`, `list` | `utf8`  | Decoding of entry names not flagged UTF-8 (legacy archives: `latin1`). |
+| `contentType` | `unzip`         | —       | Content type of the extracted files; omitted, the claim infers it.     |
+
+Patterns match the whole entry path, case sensitively: `*` and `?` never cross
+a `/`, `**` does (`'**.csv'` reaches any depth, `'invoices/*'` one level). An
+`include` matching nothing resolves with an empty array — always check.
+
+## Behaviors you can rely on
+
+- **Content never enters the workflow.** Only file references do; the bytes go
+  from the archive to storage, inflated in a stream with backpressure.
+- **You pay for what you extract.** A ZIP's index sits at the end of the file,
+  so the listing is a ranged read of the tail and each entry is fetched by
+  offset — pulling one file out of a 6 MB archive does not download 6 MB. A
+  binary the claim cannot slice (SFTP, HTTP) is streamed **once** into storage
+  first, then read by range.
+- **Corruption fails the activity.** CRC-32 and size are verified as the entry
+  flows to storage.
+- **Hostile paths are refused** before anything is written (`../`, absolute,
+  drive qualified).
+- **Format coverage.** Stored and deflate, ZIP64, data descriptors, archive
+  comments, UTF-8 and legacy names, empty entries. Encrypted entries and other
+  compression methods are refused with a `TypeError`.
+
+## Limits
+
+- **No writing.** The package reads archives; it does not create them. A file
+  to send compressed has to be produced another way.
+- **Deflate and stored only.** bzip2, LZMA and zstd entries are refused.
+- **Extraction is one activity per call.** The result is recorded whole, so a
+  `unzip` with no `include` over a 3 000-entry archive puts 3 000 references in
+  the history and 3 000 files in storage. Filter.
+- **What is bounded and what is not.** Entry content, the reads over the
+  archive and the history are constant whatever the archive weighs. Memory
+  grows with the _number_ of entries — the central directory is read whole,
+  50 to 100 bytes per entry — not with their size. A zip bomb costs storage,
+  not memory: the read stops at the declared compressed size and the inflate is
+  aborted the moment the output goes past the declared uncompressed size, so a
+  lying entry never writes more than it declares — one that honestly declares
+  40 GB still writes 40 GB, and `list` shows `contentLength` beforehand. A
+  non-sliceable source adds one durable copy of the archive, and whether that
+  copy streams is the `FileSystemClaim`'s contract, as it is for `split`.
+
+## Runtime requirements
+
+- Claim provider: `FileSystemClaim` (from `@t4h.framework/fs`).
+- Production allowlist: register `ZipExtractActivity` and `ZipListActivity`
+  via `runtime.addActivity`.
+
+## Anti-patterns
+
+- **Hand-rolling a lazy `Binary` that inflates on `stream()`.** The usual shape
+  is a `class ZipEntryBinary extends Binary` in App code that parses the local
+  header on demand. It passes locally and breaks in production: a `Binary`
+  given to a primitive is the input of a durable activity, serialized to
+  storage before the activity runs, and rehydrated in a process where the
+  closure no longer exists. Its `contentLength` also has to lie — the real size
+  lives in the central directory — so every ranged `read` over it truncates.
+  `unzip` does the same work inside an activity; that is the supported way.
+- **Inflating in workflow code.** `createInflateRaw` in a workflow re-runs on
+  every replay and holds the content in workflow memory. Extraction belongs to
+  an activity.
+- **Calling `unzip` per record.** Extract once, high in the workflow, and pass
+  the entry `Binary` down to children. `unzip` inside a loop or inside a helper
+  every child calls turns one extraction into thousands of activities.
+- **Extracting to read metadata.** If the run only needs a name, a size or a
+  date, `list` answers without transferring content.
+- **Trusting `include` to find something.** It is a filter: no match is an
+  empty array, not an error.
+
+## Related skills
+
+- `framework-fs-split` — `split`/`join`/`read`: what to do with the entry once
+  it is a `Binary`.
+- `framework-sftp` — `sftp.get` is where most archives come from.
+- `framework-transforms` — JSON inside the archive: normalize to NDJSON before
+  fanning out.

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# @t4h.framework/zip
+
+## 0.0.0-experimental-20260907231524
+
+### Minor Changes
+
+- [#163](https://github.com/tech4humans-brasil/framework/pull/163) [`ff14777`](https://github.com/tech4humans-brasil/framework/commit/ff147776f44b5cb6ebb4310f44fd57aecf1df79e) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - Adds `@t4h.framework/zip`: reading ZIP archives from inside a workflow.
+
+  `unzip(archive, options?)` extracts the entries into files and resolves with
+  `ZipEntry[]` — `{ path, binary, contentLength, compressedLength,
+compressionMethod, crc32, lastModifiedAt, directory }` — and
+  `list(archive, options?)` returns the same metadata without transferring any
+  content. `include`/`exclude` globs select what is extracted or listed,
+  `encoding` decodes legacy entry names and `contentType` labels the extracted
+  files.
+
+  Both read the archive back to front through `FileSystemClaim.slice`: the tail
+  of the file gives the whole listing (about a kilobyte on an archive without a
+  comment) and each entry is fetched by byte range, inflated in a stream and
+  written through `FileSystemClaim.write` with backpressure — content never
+  enters workflow memory or the history, and extracting one file out of a large
+  archive does not download the archive. A binary the claim cannot slice (SFTP,
+  HTTP) is streamed once into a durable copy first, the same trade `split` makes.
+
+  Every entry is verified against its CRC-32 and declared size while it flows to
+  storage, and the inflate is aborted the moment the output goes past that size,
+  so an entry that lies never writes more than it declares. Entry paths that
+  escape the extraction directory, encrypted entries and compression methods
+  other than stored and deflate are refused. ZIP64, data descriptors, archive
+  comments, UTF-8 and legacy names are handled.
+
+  This replaces hand-rolled lazy `Binary` subclasses that inflate on `stream()`
+  in App code: those are serialized as activity input, cannot be rehydrated after
+  a replay in another process, and have to lie about `contentLength`.

package/README.md

@@ -0,0 +1,208 @@
+# @t4h.framework/zip
+
+Reads ZIP archives inside a workflow. `list` tells you what is in an archive
+without transferring its content, and `unzip` unpacks the entries you ask for
+into files — each one a `Binary`, the same reference every other package
+consumes.
+
+Both are durable activities: the work happens once, the result is recorded in
+the workflow history, and a replay never re-reads the archive.
+
+## Installation
+
+```bash
+npm install @t4h.framework/zip
+# or
+yarn add @t4h.framework/zip
+```
+
+Peer dependencies: `@t4h.framework/core` and `@t4h.framework/fs` — entries are
+written through the `FileSystemClaim`, so a file system provider must be
+registered in the runtime.
+
+## Basic usage
+
+```typescript
+import { unzip } from '@t4h.framework/zip'
+
+const [entry] = await unzip(archive)
+
+// entry.binary is a regular Binary: read a window, split it, upload it
+const header = await read(entry.binary, { range: { start: 0, end: 240 } })
+```
+
+`archive` is any `Binary`: an `sftp.get`, an HTTP response body, a file written
+by `write`. `unzip` resolves with one `ZipEntry` per file in the archive, in
+central directory order, directories excluded.
+
+## Extract only what you need
+
+An archive with three thousand invoices in it does not have to become three
+thousand files:
+
+```typescript
+const [invoice] = await unzip(archive, { include: 'invoices/0001.txt' })
+
+const csvs = await unzip(archive, {
+  include: '**.csv',
+  exclude: '**/draft-*.csv',
+})
+```
+
+`include` and `exclude` are glob patterns (or arrays of them) matched against
+the whole entry path:
+
+| Pattern        | Matches                                 |
+| -------------- | --------------------------------------- |
+| `notes.txt`    | exactly that path                       |
+| `*.txt`        | `.txt` files at the root of the archive |
+| `invoices/*`   | anything directly inside `invoices/`    |
+| `**.csv`       | `.csv` files at any depth               |
+| `report-?.txt` | `report-1.txt`, not `report-42.txt`     |
+
+Matching is case sensitive, `include` runs before `exclude`, and an `include`
+that matches nothing resolves with an empty array rather than throwing.
+
+## Listing without unpacking
+
+```typescript
+import { list } from '@t4h.framework/zip'
+
+const entries = await list(archive)
+// [{ path, contentLength, compressedLength, compressionMethod,
+//    crc32, lastModifiedAt, directory }, ...]
+```
+
+`list` reads the archive's index (its central directory), which lives in the
+last few kilobytes of the file — so on a sliceable binary a listing costs about
+a kilobyte, whatever the archive weighs. Use it whenever the decision (does
+this archive contain the file I need? how big is it?) can be made from metadata
+alone, and unzip afterwards only if the content is really needed.
+
+Unlike `unzip`, `list` reports directory entries too, flagged with
+`directory: true`.
+
+## How the bytes move
+
+The package never holds an archive, or an entry, in memory.
+
+1. **Ranged reads.** A ZIP is read back to front — the central directory sits
+   at the end of the file and points backwards at each entry — so every read
+   goes through `FileSystemClaim.slice`: the tail for the index, one local
+   header per entry, then the entry's compressed range.
+2. **Streaming inflate.** That range is streamed through `inflateRaw` and
+   straight into `FileSystemClaim.write`, with backpressure all the way.
+   Extracting a thousand entries costs the same memory as extracting one.
+3. **One entry at a time.** Entries are extracted sequentially, on purpose:
+   parallel extraction would multiply the memory and the storage pressure for
+   no gain on a single source stream.
+4. **Verified content.** Every entry is checked against the CRC-32 and the size
+   the archive declares while it flows to storage, so a truncated download or a
+   corrupted archive fails the activity instead of quietly producing a shorter
+   file.
+
+### Binaries that cannot be sliced
+
+Ranged reads need a binary the file system claim owns. An `sftp.get` reference
+or an HTTP body is not one: for those, the archive is streamed **once** into
+storage (`zip/<activity-id>.zip`) and the ranges are read from that copy — the
+same trade `split` makes. It costs one pass and one durable copy of the
+archive, and everything downstream behaves identically.
+
+Nothing has to be configured for this; it is the fallback, not a mode.
+
+## Memory: what scales with what
+
+Bounded, whatever the archive weighs: entry content (source range →
+`inflateRaw` → CRC-32 → `FileSystemClaim.write`, one entry at a time), the
+reads over the archive (a ranged read of the tail plus one 30-byte local header
+per entry) and the workflow history (references only).
+
+What scales, and with what:
+
+- **The central directory is read whole**, so memory grows with the _number_ of
+  entries — 50 to 100 bytes each. Three thousand entries is 200 KB; a million
+  is around 100 MB.
+- **`unzip` without `include` extracts everything**: one file in storage and
+  one reference in the history per entry.
+- **A zip bomb costs storage, not memory.** The read stops at the declared
+  compressed size, and the inflate is aborted the moment the output goes past
+  the declared uncompressed size — an entry that lies never writes more than it
+  declares. One that honestly declares 40 GB still writes 40 GB, so check
+  `contentLength` with `list` beforehand.
+- **A non-sliceable source** is streamed once into a durable copy of the
+  archive; whether that copy streams is the `FileSystemClaim`'s contract.
+- **Downstream is yours.** `buffer(await entry.binary.stream())` pulls the file
+  into workflow memory; `read` is capped at 1 MiB and `split` streams.
+
+## Never build a lazy `Binary` by hand
+
+The temptation, when a workflow needs one entry out of a zip, is to write a
+`Binary` subclass that inflates on `stream()` and pass it around. It works in
+the dev server and breaks in production:
+
+- A `Binary` handed to a primitive becomes the **input of a durable activity**,
+  and that input is serialized to storage before the activity runs. A class
+  holding a closure over another stream has nothing to serialize into.
+- After a replay the activity may run in **another process**, where the object
+  no longer exists.
+- `contentLength` has to lie (the uncompressed size is only in the central
+  directory), and every consumer that trusts it — a ranged `read`, a
+  `Content-Length` header — is then wrong.
+
+`unzip` is the supported answer: it does the same work inside an activity, and
+what travels is a file reference the runtime knows how to rehydrate.
+
+## Cost model
+
+`unzip` and `list` are activities, so each call is one history entry with the
+work behind it done exactly once. The reference to watch is **how many times
+you call them**, not how big the archive is:
+
+```typescript
+// once per run, however many records follow
+const [entry] = await unzip(archive, { include: 'MOVIMENTO.TXT' })
+
+const batch = await split(entry.binary, processRecord, {
+  delimiter: Split.line(),
+})
+```
+
+Calling `unzip` once per record instead — inside a loop, or inside a helper
+called by every child — turns one extraction into thousands of activities, each
+with its own history entry and its own copy of the entry in storage. Extract
+high, pass the `Binary` down.
+
+## Limits
+
+- **Deflate and stored only** (methods `0` and `8`) — the two an archiver
+  produces without being asked. Anything else (bzip2, LZMA, zstd) is refused
+  with a `TypeError` naming the method.
+- **No encryption.** An encrypted entry is refused; the ZIP crypto formats are
+  either broken (ZipCrypto) or vendor-specific (AES extensions).
+- **No writing.** This package reads archives; it does not create them.
+- **Reading, not extracting to disk.** Entries land wherever the
+  `FileSystemClaim` puts them, under `zip/<activity-id>/<entry path>`.
+- **Hostile paths are refused.** An entry whose path is absolute, drive
+  qualified or contains `..` fails the whole activity before anything is
+  written (the "zip slip" class of archive).
+
+ZIP64 archives, entries written with a data descriptor (the streaming writers'
+flavour, where the local header has no sizes), UTF-8 and legacy entry names,
+archive comments and empty entries are all handled.
+
+## Errors
+
+| Situation                                       | Error         |
+| ----------------------------------------------- | ------------- |
+| Not a ZIP, or truncated beyond repair           | `SyntaxError` |
+| CRC-32 or size mismatch on an entry             | `SyntaxError` |
+| Encrypted entry, unsupported compression method | `TypeError`   |
+| Entry path escaping the extraction directory    | `TypeError`   |
+| Multi-disk archive                              | `TypeError`   |
+
+## Runtime requirements
+
+- Claim provider: `FileSystemClaim` (from `@t4h.framework/fs`).
+- Production allowlist: register `ZipExtractActivity` and `ZipListActivity`
+  through `runtime.addActivity`.

package/dist/activities/ZipExtractActivity.d.ts

@@ -0,0 +1,20 @@
+import { type Binary, SyncActivity } from '@t4h.framework/core';
+import type { ZipEntry } from '../typings/ZipEntry.js';
+export type UnzipOptions = {
+    include?: string | readonly string[];
+    exclude?: string | readonly string[];
+    encoding?: BufferEncoding;
+    contentType?: string;
+};
+export type ZipExtractActivityInput = {
+    binary: Binary;
+    options: UnzipOptions;
+};
+export declare class ZipExtractActivity extends SyncActivity<readonly [binary: Binary, options: UnzipOptions], ZipExtractActivityInput, ZipEntry[], ZipEntry[]> {
+    private readonly claims;
+    toInput(binary: Binary, options: UnzipOptions): ZipExtractActivityInput;
+    run({ binary, options, }: ZipExtractActivityInput): Promise<ZipEntry[]>;
+    toOutput(output: ZipEntry[]): ZipEntry[];
+}
+export declare function unzip(binary: Binary, options?: UnzipOptions): Promise<ZipEntry[]>;
+//# sourceMappingURL=ZipExtractActivity.d.ts.map

package/dist/activities/ZipExtractActivity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ZipExtractActivity.d.ts","sourceRoot":"","sources":["../../src/activities/ZipExtractActivity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAkB,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAQ/E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAEtD,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAA;IACpC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAA;IACpC,QAAQ,CAAC,EAAE,cAAc,CAAA;IACzB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,CAAA;AAED,MAAM,MAAM,uBAAuB,GAAG;IACpC,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,YAAY,CAAA;CACtB,CAAA;AAED,qBAAa,kBAAmB,SAAQ,YAAY,CAClD,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,CAAC,EAChD,uBAAuB,EACvB,QAAQ,EAAE,EACV,QAAQ,EAAE,CACX;IACC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAErB;IAEK,OAAO,CACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,YAAY,GACpB,uBAAuB;IAIb,GAAG,CAAC,EACf,MAAM,EACN,OAAO,GACR,EAAE,uBAAuB,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IA0BzC,QAAQ,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,QAAQ,EAAE;CAGhD;AAED,wBAAsB,KAAK,CACzB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,QAAQ,EAAE,CAAC,CAErB"}

package/dist/activities/ZipExtractActivity.js

@@ -0,0 +1,40 @@
+import { Claim, History, SyncActivity } from '@t4h.framework/core';
+import { FileSystemClaim } from '@t4h.framework/fs';
+import { extractEntry } from '../helpers/extract-entry.js';
+import { openArchive } from '../helpers/open-archive.js';
+import { assertEntryPath } from '../tools/assert-entry-path.js';
+import { selectEntries } from '../tools/select-entries.js';
+import { toEntryInfo } from '../tools/to-entry-info.js';
+export class ZipExtractActivity extends SyncActivity {
+    claims = new Claim({
+        fs: FileSystemClaim,
+    });
+    toInput(binary, options) {
+        return { binary, options };
+    }
+    async run({ binary, options, }) {
+        const { source, entries } = await openArchive(this.claims.fs, binary, {
+            encoding: options.encoding ?? 'utf8',
+            durablePath: `zip/${this.id}.zip`,
+        });
+        const selected = selectEntries(entries, options).filter(entry => !entry.directory);
+        for (const entry of selected)
+            assertEntryPath(entry.path);
+        const extracted = [];
+        for (const entry of selected) {
+            const content = await extractEntry(this.claims.fs, source, entry, {
+                path: `zip/${this.id}/${entry.path}`,
+                contentType: options.contentType,
+            });
+            extracted.push({ ...toEntryInfo(entry), binary: content });
+        }
+        return extracted;
+    }
+    toOutput(output) {
+        return output;
+    }
+}
+export async function unzip(binary, options = {}) {
+    return await History.reconciler(ZipExtractActivity, binary, options);
+}
+//# sourceMappingURL=ZipExtractActivity.js.map

package/dist/activities/ZipExtractActivity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ZipExtractActivity.js","sourceRoot":"","sources":["../../src/activities/ZipExtractActivity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAC/E,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAEnD,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAA;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAA;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAA;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAA;AAevD,MAAM,OAAO,kBAAmB,SAAQ,YAKvC;IACkB,MAAM,GAAG,IAAI,KAAK,CAAC;QAClC,EAAE,EAAE,eAAe;KACpB,CAAC,CAAA;IAEK,OAAO,CACZ,MAAc,EACd,OAAqB;QAErB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAA;IAC5B,CAAC;IAEM,KAAK,CAAC,GAAG,CAAC,EACf,MAAM,EACN,OAAO,GACiB;QACxB,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE;YACpE,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,MAAM;YACpC,WAAW,EAAE,OAAO,IAAI,CAAC,EAAE,MAAM;SAClC,CAAC,CAAA;QAEF,MAAM,QAAQ,GAAG,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,MAAM,CACrD,KAAK,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,SAAS,CAC1B,CAAA;QAED,KAAK,MAAM,KAAK,IAAI,QAAQ;YAAE,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;QAEzD,MAAM,SAAS,GAAe,EAAE,CAAA;QAEhC,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;YAC7B,MAAM,OAAO,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE;gBAChE,IAAI,EAAE,OAAO,IAAI,CAAC,EAAE,IAAI,KAAK,CAAC,IAAI,EAAE;gBACpC,WAAW,EAAE,OAAO,CAAC,WAAW;aACjC,CAAC,CAAA;YAEF,SAAS,CAAC,IAAI,CAAC,EAAE,GAAG,WAAW,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAA;QAC5D,CAAC;QAED,OAAO,SAAS,CAAA;IAClB,CAAC;IAEM,QAAQ,CAAC,MAAkB;QAChC,OAAO,MAAM,CAAA;IACf,CAAC;CACF;AAED,MAAM,CAAC,KAAK,UAAU,KAAK,CACzB,MAAc,EACd,UAAwB,EAAE;IAE1B,OAAO,MAAM,OAAO,CAAC,UAAU,CAAC,kBAAkB,EAAE,MAAM,EAAE,OAAO,CAAC,CAAA;AACtE,CAAC"}

package/dist/activities/ZipListActivity.d.ts

@@ -0,0 +1,19 @@
+import { type Binary, SyncActivity } from '@t4h.framework/core';
+import type { ZipEntryInfo } from '../typings/ZipEntry.js';
+export type ZipListOptions = {
+    include?: string | readonly string[];
+    exclude?: string | readonly string[];
+    encoding?: BufferEncoding;
+};
+export type ZipListActivityInput = {
+    binary: Binary;
+    options: ZipListOptions;
+};
+export declare class ZipListActivity extends SyncActivity<readonly [binary: Binary, options: ZipListOptions], ZipListActivityInput, ZipEntryInfo[], ZipEntryInfo[]> {
+    private readonly claims;
+    toInput(binary: Binary, options: ZipListOptions): ZipListActivityInput;
+    run({ binary, options, }: ZipListActivityInput): Promise<ZipEntryInfo[]>;
+    toOutput(output: ZipEntryInfo[]): ZipEntryInfo[];
+}
+export declare function list(binary: Binary, options?: ZipListOptions): Promise<ZipEntryInfo[]>;
+//# sourceMappingURL=ZipListActivity.d.ts.map

package/dist/activities/ZipListActivity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ZipListActivity.d.ts","sourceRoot":"","sources":["../../src/activities/ZipListActivity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAkB,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAM/E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AAE1D,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAA;IACpC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAA;IACpC,QAAQ,CAAC,EAAE,cAAc,CAAA;CAC1B,CAAA;AAED,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,cAAc,CAAA;CACxB,CAAA;AAED,qBAAa,eAAgB,SAAQ,YAAY,CAC/C,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,CAAC,EAClD,oBAAoB,EACpB,YAAY,EAAE,EACd,YAAY,EAAE,CACf;IACC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAErB;IAEK,OAAO,CACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,cAAc,GACtB,oBAAoB;IAIV,GAAG,CAAC,EACf,MAAM,EACN,OAAO,GACR,EAAE,oBAAoB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAS1C,QAAQ,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,YAAY,EAAE;CAGxD;AAED,wBAAsB,IAAI,CACxB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,YAAY,EAAE,CAAC,CAEzB"}

package/dist/activities/ZipListActivity.js

@@ -0,0 +1,27 @@
+import { Claim, History, SyncActivity } from '@t4h.framework/core';
+import { FileSystemClaim } from '@t4h.framework/fs';
+import { openArchive } from '../helpers/open-archive.js';
+import { selectEntries } from '../tools/select-entries.js';
+import { toEntryInfo } from '../tools/to-entry-info.js';
+export class ZipListActivity extends SyncActivity {
+    claims = new Claim({
+        fs: FileSystemClaim,
+    });
+    toInput(binary, options) {
+        return { binary, options };
+    }
+    async run({ binary, options, }) {
+        const { entries } = await openArchive(this.claims.fs, binary, {
+            encoding: options.encoding ?? 'utf8',
+            durablePath: `zip/${this.id}.zip`,
+        });
+        return selectEntries(entries, options).map(toEntryInfo);
+    }
+    toOutput(output) {
+        return output;
+    }
+}
+export async function list(binary, options = {}) {
+    return await History.reconciler(ZipListActivity, binary, options);
+}
+//# sourceMappingURL=ZipListActivity.js.map

package/dist/activities/ZipListActivity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ZipListActivity.js","sourceRoot":"","sources":["../../src/activities/ZipListActivity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAC/E,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAEnD,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAA;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAA;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAA;AAcvD,MAAM,OAAO,eAAgB,SAAQ,YAKpC;IACkB,MAAM,GAAG,IAAI,KAAK,CAAC;QAClC,EAAE,EAAE,eAAe;KACpB,CAAC,CAAA;IAEK,OAAO,CACZ,MAAc,EACd,OAAuB;QAEvB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAA;IAC5B,CAAC;IAEM,KAAK,CAAC,GAAG,CAAC,EACf,MAAM,EACN,OAAO,GACc;QACrB,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE;YAC5D,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,MAAM;YACpC,WAAW,EAAE,OAAO,IAAI,CAAC,EAAE,MAAM;SAClC,CAAC,CAAA;QAEF,OAAO,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,CAAA;IACzD,CAAC;IAEM,QAAQ,CAAC,MAAsB;QACpC,OAAO,MAAM,CAAA;IACf,CAAC;CACF;AAED,MAAM,CAAC,KAAK,UAAU,IAAI,CACxB,MAAc,EACd,UAA0B,EAAE;IAE5B,OAAO,MAAM,OAAO,CAAC,UAAU,CAAC,eAAe,EAAE,MAAM,EAAE,OAAO,CAAC,CAAA;AACnE,CAAC"}

package/dist/helpers/ZipChecksum.d.ts

@@ -0,0 +1,15 @@
+import { Transform, type TransformCallback } from 'node:stream';
+export type ZipChecksumExpectation = {
+    path: string;
+    crc32: number;
+    contentLength: number;
+};
+export declare class ZipChecksum extends Transform {
+    private readonly expected;
+    private checksum;
+    private length;
+    constructor(expected: ZipChecksumExpectation);
+    _transform(chunk: Buffer, _encoding: BufferEncoding, callback: TransformCallback): void;
+    _flush(callback: TransformCallback): void;
+}
+//# sourceMappingURL=ZipChecksum.d.ts.map

package/dist/helpers/ZipChecksum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ZipChecksum.d.ts","sourceRoot":"","sources":["../../src/helpers/ZipChecksum.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAG/D,MAAM,MAAM,sBAAsB,GAAG;IACnC,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,aAAa,EAAE,MAAM,CAAA;CACtB,CAAA;AAED,qBAAa,WAAY,SAAQ,SAAS;IAK5B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAJrC,OAAO,CAAC,QAAQ,CAAI;IAEpB,OAAO,CAAC,MAAM,CAAI;gBAEW,QAAQ,EAAE,sBAAsB;IAI7C,UAAU,CACxB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,cAAc,EACzB,QAAQ,EAAE,iBAAiB,GAC1B,IAAI;IAgBS,MAAM,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI;CAiB1D"}

package/dist/helpers/ZipChecksum.js

@@ -0,0 +1,28 @@
+import { Transform } from 'node:stream';
+import { crc32 } from 'node:zlib';
+export class ZipChecksum extends Transform {
+    expected;
+    checksum = 0;
+    length = 0;
+    constructor(expected) {
+        super();
+        this.expected = expected;
+    }
+    _transform(chunk, _encoding, callback) {
+        const { path, contentLength } = this.expected;
+        if (this.length + chunk.length > contentLength)
+            return callback(new SyntaxError(`ZIP entry "${path}" unpacked past the ${contentLength} bytes the archive declares`));
+        this.checksum = crc32(chunk, this.checksum);
+        this.length += chunk.length;
+        callback(null, chunk);
+    }
+    _flush(callback) {
+        const { path, crc32: expectedChecksum, contentLength } = this.expected;
+        if (this.length !== contentLength)
+            return callback(new SyntaxError(`ZIP entry "${path}" unpacked to ${this.length} bytes, the archive declares ${contentLength}`));
+        if (this.checksum !== expectedChecksum)
+            return callback(new SyntaxError(`ZIP entry "${path}" failed its CRC-32 check`));
+        callback();
+    }
+}
+//# sourceMappingURL=ZipChecksum.js.map

package/dist/helpers/ZipChecksum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ZipChecksum.js","sourceRoot":"","sources":["../../src/helpers/ZipChecksum.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAA0B,MAAM,aAAa,CAAA;AAC/D,OAAO,EAAE,KAAK,EAAE,MAAM,WAAW,CAAA;AAQjC,MAAM,OAAO,WAAY,SAAQ,SAAS;IAKX;IAJrB,QAAQ,GAAG,CAAC,CAAA;IAEZ,MAAM,GAAG,CAAC,CAAA;IAElB,YAA6B,QAAgC;QAC3D,KAAK,EAAE,CAAA;QADoB,aAAQ,GAAR,QAAQ,CAAwB;IAE7D,CAAC;IAEe,UAAU,CACxB,KAAa,EACb,SAAyB,EACzB,QAA2B;QAE3B,MAAM,EAAE,IAAI,EAAE,aAAa,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAA;QAE7C,IAAI,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,GAAG,aAAa;YAC5C,OAAO,QAAQ,CACb,IAAI,WAAW,CACb,cAAc,IAAI,uBAAuB,aAAa,6BAA6B,CACpF,CACF,CAAA;QAEH,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAA;QAC3C,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC,MAAM,CAAA;QAE3B,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;IACvB,CAAC;IAEe,MAAM,CAAC,QAA2B;QAChD,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAA;QAEtE,IAAI,IAAI,CAAC,MAAM,KAAK,aAAa;YAC/B,OAAO,QAAQ,CACb,IAAI,WAAW,CACb,cAAc,IAAI,iBAAiB,IAAI,CAAC,MAAM,gCAAgC,aAAa,EAAE,CAC9F,CACF,CAAA;QAEH,IAAI,IAAI,CAAC,QAAQ,KAAK,gBAAgB;YACpC,OAAO,QAAQ,CACb,IAAI,WAAW,CAAC,cAAc,IAAI,2BAA2B,CAAC,CAC/D,CAAA;QAEH,QAAQ,EAAE,CAAA;IACZ,CAAC;CACF"}

package/dist/helpers/ZipSource.d.ts

@@ -0,0 +1,17 @@
+import type { Readable } from 'node:stream';
+import type { Binary } from '@t4h.framework/core';
+import type { FileSystemClaim } from '@t4h.framework/fs';
+export declare class ZipSliceUnavailableError extends Error {
+    readonly reason: unknown;
+    constructor(reason: unknown);
+}
+export declare class ZipSource {
+    private readonly fs;
+    readonly binary: Binary;
+    constructor(fs: FileSystemClaim, binary: Binary);
+    get contentLength(): number;
+    read(start: number, end: number): Promise<Buffer>;
+    stream(start: number, end: number): Promise<Readable>;
+    private slice;
+}
+//# sourceMappingURL=ZipSource.d.ts.map

package/dist/helpers/ZipSource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ZipSource.d.ts","sourceRoot":"","sources":["../../src/helpers/ZipSource.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAG3C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAExD,qBAAa,wBAAyB,SAAQ,KAAK;aACrB,MAAM,EAAE,OAAO;gBAAf,MAAM,EAAE,OAAO;CAK5C;AAED,qBAAa,SAAS;IAElB,OAAO,CAAC,QAAQ,CAAC,EAAE;aACH,MAAM,EAAE,MAAM;gBADb,EAAE,EAAE,eAAe,EACpB,MAAM,EAAE,MAAM;IAGhC,IAAW,aAAa,IAAI,MAAM,CAEjC;IAEY,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAMjD,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;YAWpD,KAAK;CAOpB"}

package/dist/helpers/ZipSource.js

@@ -0,0 +1,40 @@
+import { buffer } from 'node:stream/consumers';
+export class ZipSliceUnavailableError extends Error {
+    reason;
+    constructor(reason) {
+        super('The file system claim could not slice the archive');
+        this.reason = reason;
+        this.name = 'ZipSliceUnavailableError';
+    }
+}
+export class ZipSource {
+    fs;
+    binary;
+    constructor(fs, binary) {
+        this.fs = fs;
+        this.binary = binary;
+    }
+    get contentLength() {
+        return this.binary.contentLength;
+    }
+    async read(start, end) {
+        if (end <= start)
+            return Buffer.alloc(0);
+        return await buffer(await this.stream(start, end));
+    }
+    async stream(start, end) {
+        if (start < 0 || end > this.contentLength)
+            throw new SyntaxError(`ZIP archive is truncated: bytes ${start}-${end} are outside a file of ${this.contentLength} bytes`);
+        const slice = await this.slice(start, end);
+        return await slice.stream();
+    }
+    async slice(start, end) {
+        try {
+            return await this.fs.slice(this.binary, { start, end });
+        }
+        catch (error) {
+            throw new ZipSliceUnavailableError(error);
+        }
+    }
+}
+//# sourceMappingURL=ZipSource.js.map

package/dist/helpers/ZipSource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ZipSource.js","sourceRoot":"","sources":["../../src/helpers/ZipSource.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAA;AAK9C,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IACrB;IAA5B,YAA4B,MAAe;QACzC,KAAK,CAAC,mDAAmD,CAAC,CAAA;QADhC,WAAM,GAAN,MAAM,CAAS;QAGzC,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAA;IACxC,CAAC;CACF;AAED,MAAM,OAAO,SAAS;IAED;IACD;IAFlB,YACmB,EAAmB,EACpB,MAAc;QADb,OAAE,GAAF,EAAE,CAAiB;QACpB,WAAM,GAAN,MAAM,CAAQ;IAC7B,CAAC;IAEJ,IAAW,aAAa;QACtB,OAAO,IAAI,CAAC,MAAM,CAAC,aAAa,CAAA;IAClC,CAAC;IAEM,KAAK,CAAC,IAAI,CAAC,KAAa,EAAE,GAAW;QAC1C,IAAI,GAAG,IAAI,KAAK;YAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;QAExC,OAAO,MAAM,MAAM,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAA;IACpD,CAAC;IAEM,KAAK,CAAC,MAAM,CAAC,KAAa,EAAE,GAAW;QAC5C,IAAI,KAAK,GAAG,CAAC,IAAI,GAAG,GAAG,IAAI,CAAC,aAAa;YACvC,MAAM,IAAI,WAAW,CACnB,mCAAmC,KAAK,IAAI,GAAG,0BAA0B,IAAI,CAAC,aAAa,QAAQ,CACpG,CAAA;QAEH,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;QAE1C,OAAO,MAAM,KAAK,CAAC,MAAM,EAAE,CAAA;IAC7B,CAAC;IAEO,KAAK,CAAC,KAAK,CAAC,KAAa,EAAE,GAAW;QAC5C,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAA;QACzD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,wBAAwB,CAAC,KAAK,CAAC,CAAA;QAC3C,CAAC;IACH,CAAC;CACF"}