text-compress 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 text-compress contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,186 @@
+# text-compress
+
+Brotli-compress text or entire folder trees into pasteable base64 or Z85 strings — ideal for chat, email, or code.
+
+**v2** ships as [`text-compress`](https://www.npmjs.com/package/text-compress). The original CLI [`@startdoing/tc`](https://www.npmjs.com/package/@startdoing/tc) stays frozen at **v1.0.4**.
+
+## Features
+
+- **Auto-detect** — pass a path; plain files compress, valid payloads decompress (no subcommand)
+- **Max-quality Brotli** via Node.js `zlib`
+- **Base64 (default)** — paste-safe (`A-Za-z0-9+/=`)
+- **Z85 base85** — ~8% smaller; punctuation-safe for code blocks
+- **Folder archives** — pack a directory tree into one string
+- **Password protection** — AES-256-GCM (`-p` / `--password`)
+- **v2 split parts** — self-describing parts; shuffled names, merged files, any sibling as entry
+- **CLI + library** — terminal or `import from "text-compress"`
+
+## Install
+
+```bash
+npm install -g text-compress
+```
+
+Or run without installing:
+
+```bash
+npx text-compress ./notes.md
+```
+
+Local development:
+
+```bash
+git clone <repo-url>
+cd text-compress
+git checkout v2
+npm install
+npm run build
+```
+
+## CLI
+
+No `compress` / `decompress` subcommand — the CLI picks the operation from the input.
+
+```bash
+# Compress a file
+text-compress ./notes.md
+
+# Compress with password
+text-compress ./notes.md -p "hello-world"
+
+# Decompress (auto-detected from valid compressed output)
+text-compress ./notes.txt -p "hello-world"
+
+# Compress a folder
+text-compress ./my-project
+
+# Base85 encoding (~8% smaller)
+text-compress ./notes.md -e 85
+
+# Split large output
+text-compress ./large-file.txt -s 4000
+
+# Inline text
+text-compress -t "hello world" -o output.txt
+
+# Force mode when auto-detect is wrong
+text-compress --compress ./looks-compressed.txt
+text-compress --decompress ./plain.md   # errors if not valid payload
+
+# Split set — pass any sibling
+text-compress ./output.7.txt
+```
+
+During development:
+
+```bash
+npm run dev -- ./notes.md
+npm run dev -- ./notes.txt -p "secret"
+```
+
+### Defaults
+
+| | Output when `-o` omitted |
+|--|--|
+| Compress file/text | `<input>.txt` |
+| Compress folder | `<folder-name>.txt` |
+| Decompress text | `<input>.de.txt` |
+| Decompress folder | `<input>.de/` |
+
+## Library
+
+```ts
+import {
+  compress,
+  decompress,
+  compressFolder,
+  decompressToPath,
+} from "text-compress";
+
+const encoded = compress("hello world");
+const restored = decompress(encoded);
+
+const locked = compress("hello world", 64, "my secret");
+const unlocked = decompress(locked, 64, "my secret");
+
+const { encoded: folderBlob } = compressFolder("./my-project");
+decompressToPath(folderBlob, "./restored-project");
+```
+
+| Function | Description |
+|---|---|
+| `compress(text, encoding?, password?)` | UTF-8 text → encoded string (`64` or `85`) |
+| `decompress(encoded, encoding?, password?)` | Encoded text payload → string |
+| `compressFolder(dirPath, encoding?, password?)` | Folder → `{ encoded, fileCount, ... }` |
+| `decompressToPath(encoded, destDir, encoding?, password?)` | Unpack folder archive |
+| `decompressPayload(encoded, encoding?, password?)` | Low-level `{ tag, data }` |
+
+## Encoding
+
+| Value | Format | Use when |
+|---|---|---|
+| `64` (default) | Base64 | Paste anywhere |
+| `85` | Z85 | Slightly smaller; paste in code blocks |
+
+Use the same encoding for compress and decompress. When `-e` is omitted on decompress, the CLI tries both.
+
+## Password protection
+
+```bash
+text-compress ./notes.md -p "my secret" -o locked.txt
+text-compress ./locked.txt -p "my secret" -o notes.md
+```
+
+Password-protected payloads error without `-p` (they are **not** silently re-compressed).
+
+## v2 split output
+
+Large outputs split into numbered files (`output.1.txt`, `output.02.txt`, …). Each part embeds order in a `TCP\x02` header.
+
+On decompress:
+
+- Pass **any** sibling file
+- Discovery uses the basename **prefix** (before the first `.`)
+- Extension ignored; invalid siblings skipped
+- Parts can be shuffled or merged into fewer files
+
+**Not compatible** with v1 split format (raw concatenation without headers).
+
+## Migration from @startdoing/tc v1
+
+| v1 (`@startdoing/tc@1.0.4`) | v2 (`text-compress`) |
+|---|---|
+| `tc compress notes.md` | `text-compress notes.md` |
+| `tc decompress out.txt` | `text-compress out.txt` |
+| `import from "@startdoing/tc"` | `import from "text-compress"` |
+| Raw split parts | Headered split parts |
+
+## Development
+
+```bash
+npm install
+npm test
+npm run build
+npm run check
+```
+
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) and [docs/LEARNING.md](docs/LEARNING.md).
+
+## Changelog
+
+### v2.0.0 — `text-compress` (2026-07-08)
+
+- New npm package **`text-compress`** (v1 remains `@startdoing/tc@1.0.4`)
+- Auto-detect compress vs decompress from input
+- Shorter CLI: `text-compress ./file.md` (no subcommand)
+- Self-describing split format (`TCP\x02` headers)
+- Prefix-based split discovery; skip invalid siblings
+- Force flags: `--compress` / `--decompress`
+
+### v1.x
+
+See git tag / branch `main` and [@startdoing/tc on npm](https://www.npmjs.com/package/@startdoing/tc).
+
+## License
+
+MIT

package/dist/api/folder.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @module api/folder
+ *
+ * High-level API for folder compression and decompression.
+ *
+ * ## In-memory path (`compressFolder`)
+ *
+ * Walks the tree, builds a binary archive in RAM, compresses, and encodes.
+ * Suitable for small-to-medium folders.
+ *
+ * ## Decompression (`decompressToPath`)
+ *
+ * Decodes, decompresses, checks the folder tag, and unpacks to disk.
+ */
+import type { Encoding } from "../types.js";
+/**
+ * Pack a directory tree into a single encoded string (in-memory).
+ *
+ * @returns Encoded blob plus statistics about the source folder.
+ */
+export declare function compressFolder(dirPath: string, encoding?: Encoding, password?: string): {
+    encoded: string;
+    fileCount: number;
+    dirCount: number;
+    originalBytes: number;
+    archiveBytes: number;
+};
+/**
+ * Decode and unpack a folder archive to a destination directory.
+ *
+ * @throws If the payload is text, not a folder archive.
+ */
+export declare function decompressToPath(encoded: string, destDir: string, encoding?: Encoding, password?: string): {
+    files: number;
+    dirs: number;
+    bytes: number;
+};
+//# sourceMappingURL=folder.d.ts.map

package/dist/api/folder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"folder.d.ts","sourceRoot":"","sources":["../../src/api/folder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAE3C;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,GAAE,QAAa,EAAE,QAAQ,CAAC,EAAE,MAAM;;;;;;EAazF;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,QAAa,EACvB,QAAQ,CAAC,EAAE,MAAM;;;;EAOlB"}

package/dist/api/folder.js

@@ -0,0 +1,50 @@
+/**
+ * @module api/folder
+ *
+ * High-level API for folder compression and decompression.
+ *
+ * ## In-memory path (`compressFolder`)
+ *
+ * Walks the tree, builds a binary archive in RAM, compresses, and encodes.
+ * Suitable for small-to-medium folders.
+ *
+ * ## Decompression (`decompressToPath`)
+ *
+ * Decodes, decompresses, checks the folder tag, and unpacks to disk.
+ */
+import { collectEntries } from "../archive/collect.js";
+import { serializeArchive } from "../archive/format.js";
+import { unpackDirectory } from "../archive/unpack.js";
+import { compressTaggedPayload, decompressPayload, TAG_FOLDER } from "../payload/tags.js";
+/**
+ * Pack a directory tree into a single encoded string (in-memory).
+ *
+ * @returns Encoded blob plus statistics about the source folder.
+ */
+export function compressFolder(dirPath, encoding = 64, password) {
+    const entries = collectEntries(dirPath);
+    const archive = serializeArchive(entries);
+    const encoded = compressTaggedPayload(TAG_FOLDER, archive, encoding, password);
+    const files = entries.filter((e) => e.type === "f");
+    const originalBytes = files.reduce((sum, e) => sum + (e.content?.length ?? 0), 0);
+    return {
+        encoded,
+        fileCount: files.length,
+        dirCount: entries.length - files.length,
+        originalBytes,
+        archiveBytes: archive.length,
+    };
+}
+/**
+ * Decode and unpack a folder archive to a destination directory.
+ *
+ * @throws If the payload is text, not a folder archive.
+ */
+export function decompressToPath(encoded, destDir, encoding = 64, password) {
+    const { tag, data } = decompressPayload(encoded, encoding, password);
+    if (tag !== TAG_FOLDER) {
+        throw new Error("This payload is compressed text, not a folder. Use decompress.");
+    }
+    return unpackDirectory(data, destDir);
+}
+//# sourceMappingURL=folder.js.map

package/dist/api/folder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"folder.js","sourceRoot":"","sources":["../../src/api/folder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAGzF;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe,EAAE,QAAQ,GAAa,EAAE,EAAE,QAAiB;IACxF,MAAM,OAAO,GAAG,cAAc,CAAC,OAAO,CAAC,CAAA;IACvC,MAAM,OAAO,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAA;IACzC,MAAM,OAAO,GAAG,qBAAqB,CAAC,UAAU,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAA;IAC9E,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,CAAA;IACnD,MAAM,aAAa,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IACjF,OAAO;QACL,OAAO;QACP,SAAS,EAAE,KAAK,CAAC,MAAM;QACvB,QAAQ,EAAE,OAAO,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM;QACvC,aAAa;QACb,YAAY,EAAE,OAAO,CAAC,MAAM;KAC7B,CAAA;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAe,EACf,OAAe,EACf,QAAQ,GAAa,EAAE,EACvB,QAAiB;IAEjB,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,iBAAiB,CAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAA;IACpE,IAAI,GAAG,KAAK,UAAU,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,gEAAgE,CAAC,CAAA;IACnF,CAAC;IACD,OAAO,eAAe,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;AACvC,CAAC"}

package/dist/api/text.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @module api/text
+ *
+ * High-level API for compressing and decompressing UTF-8 text strings.
+ *
+ * ## Pipeline
+ *
+ * ```
+ *   compress:   text → UTF-8 bytes → tag → Brotli → Base64/Z85
+ *   decompress: Base64/Z85 → Brotli → tag check → UTF-8 string
+ * ```
+ *
+ * Text and folder payloads share the same outer encoding but are
+ * distinguished by the leading tag byte after decompression.
+ */
+import type { Encoding } from "../types.js";
+/**
+ * Compress a UTF-8 string to a pasteable encoded blob.
+ *
+ * @param text - Input string (any Unicode code points).
+ * @param encoding - `64` (Base64) or `85` (Z85); default Base64.
+ */
+export declare function compress(text: string, encoding?: Encoding, password?: string): string;
+/**
+ * Decompress an encoded text payload back to a UTF-8 string.
+ *
+ * @throws If the payload is a folder archive (wrong tag).
+ */
+export declare function decompress(encoded: string, encoding?: Encoding, password?: string): string;
+//# sourceMappingURL=text.d.ts.map

package/dist/api/text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../../src/api/text.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAE3C;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,GAAE,QAAa,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAEzF;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,GAAE,QAAa,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAM9F"}

package/dist/api/text.js

@@ -0,0 +1,38 @@
+/**
+ * @module api/text
+ *
+ * High-level API for compressing and decompressing UTF-8 text strings.
+ *
+ * ## Pipeline
+ *
+ * ```
+ *   compress:   text → UTF-8 bytes → tag → Brotli → Base64/Z85
+ *   decompress: Base64/Z85 → Brotli → tag check → UTF-8 string
+ * ```
+ *
+ * Text and folder payloads share the same outer encoding but are
+ * distinguished by the leading tag byte after decompression.
+ */
+import { compressTaggedPayload, decompressPayload, TAG_TEXT } from "../payload/tags.js";
+/**
+ * Compress a UTF-8 string to a pasteable encoded blob.
+ *
+ * @param text - Input string (any Unicode code points).
+ * @param encoding - `64` (Base64) or `85` (Z85); default Base64.
+ */
+export function compress(text, encoding = 64, password) {
+    return compressTaggedPayload(TAG_TEXT, Buffer.from(text, "utf-8"), encoding, password);
+}
+/**
+ * Decompress an encoded text payload back to a UTF-8 string.
+ *
+ * @throws If the payload is a folder archive (wrong tag).
+ */
+export function decompress(encoded, encoding = 64, password) {
+    const raw = decompressPayload(encoded, encoding, password);
+    if (raw.tag !== TAG_TEXT) {
+        throw new Error("This payload is a compressed folder, not text. Use decompressToPath.");
+    }
+    return raw.data.toString("utf-8");
+}
+//# sourceMappingURL=text.js.map

package/dist/api/text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.js","sourceRoot":"","sources":["../../src/api/text.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAGvF;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAY,EAAE,QAAQ,GAAa,EAAE,EAAE,QAAiB;IAC/E,OAAO,qBAAqB,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAA;AACxF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,OAAe,EAAE,QAAQ,GAAa,EAAE,EAAE,QAAiB;IACpF,MAAM,GAAG,GAAG,iBAAiB,CAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAA;IAC1D,IAAI,GAAG,CAAC,GAAG,KAAK,QAAQ,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,sEAAsE,CAAC,CAAA;IACzF,CAAC;IACD,OAAO,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAA;AACnC,CAAC"}

package/dist/archive/collect.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @module archive/collect
+ *
+ * In-memory directory tree walker that produces a flat {@link ArchiveEntry}
+ * list suitable for {@link serializeArchive}.
+ *
+ * ## Traversal algorithm
+ *
+ * Depth-first pre-order walk with sorted children:
+ *
+ * 1. Emit a directory marker for every non-root directory.
+ * 2. For each child (sorted by `localeCompare`), recurse into subdirs or
+ *    read file content into memory.
+ * 3. Skip paths excluded by `.gitignore` rules (outside → inside).
+ *
+ * This path loads every file into RAM — use the streaming builder in
+ * `streaming/folder.ts` for large directory trees.
+ */
+import type { ArchiveEntry } from "./types.js";
+/**
+ * Walk a directory tree and collect all entries into a flat array.
+ *
+ * @param rootDir - Absolute path to the folder root.
+ */
+export declare function collectEntries(rootDir: string): ArchiveEntry[];
+//# sourceMappingURL=collect.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"collect.d.ts","sourceRoot":"","sources":["../../src/archive/collect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,EAAE,CAa9D"}

package/dist/archive/collect.js

@@ -0,0 +1,38 @@
+/**
+ * @module archive/collect
+ *
+ * In-memory directory tree walker that produces a flat {@link ArchiveEntry}
+ * list suitable for {@link serializeArchive}.
+ *
+ * ## Traversal algorithm
+ *
+ * Depth-first pre-order walk with sorted children:
+ *
+ * 1. Emit a directory marker for every non-root directory.
+ * 2. For each child (sorted by `localeCompare`), recurse into subdirs or
+ *    read file content into memory.
+ * 3. Skip paths excluded by `.gitignore` rules (outside → inside).
+ *
+ * This path loads every file into RAM — use the streaming builder in
+ * `streaming/folder.ts` for large directory trees.
+ */
+import { readFileSync } from "node:fs";
+import { walkDirectory } from "../fs/walk.js";
+/**
+ * Walk a directory tree and collect all entries into a flat array.
+ *
+ * @param rootDir - Absolute path to the folder root.
+ */
+export function collectEntries(rootDir) {
+    const entries = [];
+    walkDirectory(rootDir, {
+        onDirectory: (_absDir, relDir) => {
+            entries.push({ type: "d", relPath: relDir });
+        },
+        onFile: (abs, rel) => {
+            entries.push({ type: "f", relPath: rel, content: readFileSync(abs) });
+        },
+    });
+    return entries;
+}
+//# sourceMappingURL=collect.js.map

package/dist/archive/collect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collect.js","sourceRoot":"","sources":["../../src/archive/collect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAG7C;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,MAAM,OAAO,GAAmB,EAAE,CAAA;IAElC,aAAa,CAAC,OAAO,EAAE;QACrB,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YAC/B,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAA;QAC9C,CAAC;QACD,MAAM,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;YACnB,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;QACvE,CAAC;KACF,CAAC,CAAA;IAEF,OAAO,OAAO,CAAA;AAChB,CAAC"}

package/dist/archive/format.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @module archive/format
+ *
+ * Binary serialization and deserialization for folder archives.
+ *
+ * ## Wire format
+ *
+ * A flat sequence of length-prefixed entries (little-endian u32 lengths):
+ *
+ * ```
+ *   directory: [0x44] [pathLen: u32le] [path utf-8 bytes]
+ *   file:      [0x46] [pathLen: u32le] [path utf-8] [contentLen: u32le] [content bytes]
+ * ```
+ *
+ * Paths are POSIX-style (forward slashes) and relative to the archive root.
+ * File metadata (permissions, timestamps, symlinks) is intentionally dropped
+ * to keep the format minimal and deterministic.
+ *
+ * ## Design choices
+ *
+ * - **Flat list vs tree** — A pre-order walk produces a flat list that is
+ *   trivial to stream to disk without building an in-memory tree.
+ * - **Little-endian u32** — Matches Node's `writeUInt32LE`; portable across
+ *   all platforms this library targets.
+ * - **Sorted children** — `collectEntries` sorts directory entries by name
+ *   so the same folder always produces the same byte sequence (deterministic
+ *   output aids testing and deduplication).
+ *
+ * ## Security
+ *
+ * `deserializeArchive` rejects paths containing `..` or starting with `/`
+ * to prevent zip-slip style directory traversal on unpack.
+ */
+import { type ArchiveEntry } from "./types.js";
+/**
+ * Serialize an array of archive entries into a single binary buffer.
+ *
+ * @param entries - Flat list from `collectEntries` or manual construction.
+ */
+export declare function serializeArchive(entries: ArchiveEntry[]): Buffer;
+/**
+ * Parse a binary archive buffer back into entry objects.
+ *
+ * @throws On unknown type bytes, truncated data, or unsafe paths.
+ */
+export declare function deserializeArchive(buffer: Buffer): ArchiveEntry[];
+/**
+ * Write a single directory entry to an open file descriptor.
+ *
+ * Used by the streaming archive builder to avoid buffering the entire
+ * archive in memory.
+ */
+export declare function writeDirEntry(fd: number, relPath: string): void;
+/**
+ * Write a single file entry to an open file descriptor, streaming content
+ * from disk in chunks.
+ *
+ * @param copyChunkSize - Read buffer size for streaming file content.
+ * @returns Number of content bytes written.
+ */
+export declare function writeFileEntry(fd: number, relPath: string, filePath: string, copyChunkSize: number): number;
+//# sourceMappingURL=format.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/archive/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAGH,OAAO,EAAE,KAAK,YAAY,EAAyB,MAAM,YAAY,CAAA;AAErE;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,MAAM,CAiBhE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,EAAE,CA4BjE;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAO/D;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,GACpB,MAAM,CA6BR"}

package/dist/archive/format.js

@@ -0,0 +1,143 @@
+/**
+ * @module archive/format
+ *
+ * Binary serialization and deserialization for folder archives.
+ *
+ * ## Wire format
+ *
+ * A flat sequence of length-prefixed entries (little-endian u32 lengths):
+ *
+ * ```
+ *   directory: [0x44] [pathLen: u32le] [path utf-8 bytes]
+ *   file:      [0x46] [pathLen: u32le] [path utf-8] [contentLen: u32le] [content bytes]
+ * ```
+ *
+ * Paths are POSIX-style (forward slashes) and relative to the archive root.
+ * File metadata (permissions, timestamps, symlinks) is intentionally dropped
+ * to keep the format minimal and deterministic.
+ *
+ * ## Design choices
+ *
+ * - **Flat list vs tree** — A pre-order walk produces a flat list that is
+ *   trivial to stream to disk without building an in-memory tree.
+ * - **Little-endian u32** — Matches Node's `writeUInt32LE`; portable across
+ *   all platforms this library targets.
+ * - **Sorted children** — `collectEntries` sorts directory entries by name
+ *   so the same folder always produces the same byte sequence (deterministic
+ *   output aids testing and deduplication).
+ *
+ * ## Security
+ *
+ * `deserializeArchive` rejects paths containing `..` or starting with `/`
+ * to prevent zip-slip style directory traversal on unpack.
+ */
+import { closeSync, openSync, readSync, statSync, writeSync } from "node:fs";
+import { ENTRY_DIR, ENTRY_FILE } from "./types.js";
+/**
+ * Serialize an array of archive entries into a single binary buffer.
+ *
+ * @param entries - Flat list from `collectEntries` or manual construction.
+ */
+export function serializeArchive(entries) {
+    const chunks = [];
+    for (const entry of entries) {
+        const pathBuf = Buffer.from(entry.relPath, "utf-8");
+        const pathLenBuf = Buffer.alloc(4);
+        pathLenBuf.writeUInt32LE(pathBuf.length, 0);
+        if (entry.type === "d") {
+            chunks.push(Buffer.from([ENTRY_DIR]), pathLenBuf, pathBuf);
+        }
+        else {
+            const content = entry.content ?? Buffer.alloc(0);
+            const contentLenBuf = Buffer.alloc(4);
+            contentLenBuf.writeUInt32LE(content.length, 0);
+            chunks.push(Buffer.from([ENTRY_FILE]), pathLenBuf, pathBuf, contentLenBuf, content);
+        }
+    }
+    return Buffer.concat(chunks);
+}
+/**
+ * Parse a binary archive buffer back into entry objects.
+ *
+ * @throws On unknown type bytes, truncated data, or unsafe paths.
+ */
+export function deserializeArchive(buffer) {
+    const entries = [];
+    let offset = 0;
+    while (offset < buffer.length) {
+        const type = buffer[offset];
+        offset += 1;
+        const pathLen = buffer.readUInt32LE(offset);
+        offset += 4;
+        const relPath = buffer.subarray(offset, offset + pathLen).toString("utf-8");
+        offset += pathLen;
+        if (relPath.startsWith("/") || relPath.split("/").includes("..")) {
+            throw new Error(`Unsafe path in archive: "${relPath}"`);
+        }
+        if (type === ENTRY_DIR) {
+            entries.push({ type: "d", relPath });
+        }
+        else if (type === ENTRY_FILE) {
+            const contentLen = buffer.readUInt32LE(offset);
+            offset += 4;
+            const content = buffer.subarray(offset, offset + contentLen);
+            offset += contentLen;
+            entries.push({ type: "f", relPath, content });
+        }
+        else {
+            throw new Error(`Corrupt archive: unknown entry type byte 0x${type.toString(16)}`);
+        }
+    }
+    return entries;
+}
+/**
+ * Write a single directory entry to an open file descriptor.
+ *
+ * Used by the streaming archive builder to avoid buffering the entire
+ * archive in memory.
+ */
+export function writeDirEntry(fd, relPath) {
+    const pathBuf = Buffer.from(relPath, "utf-8");
+    const pathLenBuf = Buffer.alloc(4);
+    pathLenBuf.writeUInt32LE(pathBuf.length, 0);
+    writeSync(fd, Buffer.from([ENTRY_DIR]));
+    writeSync(fd, pathLenBuf);
+    writeSync(fd, pathBuf);
+}
+/**
+ * Write a single file entry to an open file descriptor, streaming content
+ * from disk in chunks.
+ *
+ * @param copyChunkSize - Read buffer size for streaming file content.
+ * @returns Number of content bytes written.
+ */
+export function writeFileEntry(fd, relPath, filePath, copyChunkSize) {
+    const pathBuf = Buffer.from(relPath, "utf-8");
+    const pathLenBuf = Buffer.alloc(4);
+    pathLenBuf.writeUInt32LE(pathBuf.length, 0);
+    const contentLen = statSync(filePath).size;
+    const contentLenBuf = Buffer.alloc(4);
+    contentLenBuf.writeUInt32LE(contentLen, 0);
+    writeSync(fd, Buffer.from([ENTRY_FILE]));
+    writeSync(fd, pathLenBuf);
+    writeSync(fd, pathBuf);
+    writeSync(fd, contentLenBuf);
+    const srcFd = openSync(filePath, "r");
+    try {
+        const buf = Buffer.alloc(copyChunkSize);
+        let copied = 0;
+        while (copied < contentLen) {
+            const toRead = Math.min(buf.length, contentLen - copied);
+            const n = readSync(srcFd, buf, 0, toRead, copied);
+            if (n <= 0)
+                break;
+            writeSync(fd, buf, 0, n);
+            copied += n;
+        }
+    }
+    finally {
+        closeSync(srcFd);
+    }
+    return contentLen;
+}
+//# sourceMappingURL=format.js.map

package/dist/archive/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/archive/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAC5E,OAAO,EAAqB,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAErE;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAuB;IACtD,MAAM,MAAM,GAAa,EAAE,CAAA;IAC3B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QACnD,MAAM,UAAU,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;QAClC,UAAU,CAAC,aAAa,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAA;QAE3C,IAAI,KAAK,CAAC,IAAI,KAAK,GAAG,EAAE,CAAC;YACvB,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,CAAA;QAC5D,CAAC;aAAM,CAAC;YACN,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;YAChD,MAAM,aAAa,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;YACrC,aAAa,CAAC,aAAa,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAA;YAC9C,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,EAAE,aAAa,EAAE,OAAO,CAAC,CAAA;QACrF,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;AAC9B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAc;IAC/C,MAAM,OAAO,GAAmB,EAAE,CAAA;IAClC,IAAI,MAAM,GAAG,CAAC,CAAA;IACd,OAAO,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;QAC9B,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAA;QAC3B,MAAM,IAAI,CAAC,CAAA;QACX,MAAM,OAAO,GAAG,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,CAAA;QAC3C,MAAM,IAAI,CAAC,CAAA;QACX,MAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAA;QAC3E,MAAM,IAAI,OAAO,CAAA;QAEjB,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACjE,MAAM,IAAI,KAAK,CAAC,4BAA4B,OAAO,GAAG,CAAC,CAAA;QACzD,CAAC;QAED,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAA;QACtC,CAAC;aAAM,IAAI,IAAI,KAAK,UAAU,EAAE,CAAC;YAC/B,MAAM,UAAU,GAAG,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,CAAA;YAC9C,MAAM,IAAI,CAAC,CAAA;YACX,MAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAAC,CAAA;YAC5D,MAAM,IAAI,UAAU,CAAA;YACpB,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAA;QAC/C,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,KAAK,CAAC,8CAA8C,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC,CAAA;QACpF,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAA;AAChB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,EAAU,EAAE,OAAe;IACvD,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;IAC7C,MAAM,UAAU,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;IAClC,UAAU,CAAC,aAAa,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAA;IAC3C,SAAS,CAAC,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAA;IACvC,SAAS,CAAC,EAAE,EAAE,UAAU,CAAC,CAAA;IACzB,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,CAAA;AACxB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,EAAU,EACV,OAAe,EACf,QAAgB,EAChB,aAAqB;IAErB,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;IAC7C,MAAM,UAAU,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;IAClC,UAAU,CAAC,aAAa,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAA;IAC3C,MAAM,UAAU,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAA;IAC1C,MAAM,aAAa,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;IACrC,aAAa,CAAC,aAAa,CAAC,UAAU,EAAE,CAAC,CAAC,CAAA;IAE1C,SAAS,CAAC,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAA;IACxC,SAAS,CAAC,EAAE,EAAE,UAAU,CAAC,CAAA;IACzB,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,CAAA;IACtB,SAAS,CAAC,EAAE,EAAE,aAAa,CAAC,CAAA;IAE5B,MAAM,KAAK,GAAG,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAA;IACrC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,CAAA;QACvC,IAAI,MAAM,GAAG,CAAC,CAAA;QACd,OAAO,MAAM,GAAG,UAAU,EAAE,CAAC;YAC3B,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,CAAA;YACxD,MAAM,CAAC,GAAG,QAAQ,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;YACjD,IAAI,CAAC,IAAI,CAAC;gBAAE,MAAK;YACjB,SAAS,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;YACxB,MAAM,IAAI,CAAC,CAAA;QACb,CAAC;IACH,CAAC;YAAS,CAAC;QACT,SAAS,CAAC,KAAK,CAAC,CAAA;IAClB,CAAC;IAED,OAAO,UAAU,CAAA;AACnB,CAAC"}