dir-archiver 2.2.0 → 3.0.1

package/docs/how-to/ci-release-artifact.md

@@ -0,0 +1,32 @@
+# How-to: create a CI release artifact
+
+## Goal
+Produce a release ZIP in CI and emit a machine-readable JSON summary.
+
+## Prereqs
+- Node `>=24`
+- `npm install`
+- `npm run build`
+
+## Copy/paste
+Minimal CI shell snippet:
+
+```sh
+node examples/ci-release-artifact.mjs
+```
+
+Equivalent CLI flow:
+
+```sh
+dir-archiver write --source ./dist --output ./release.zip --include-base-directory --json
+dir-archiver detect --input ./release.zip --json
+```
+
+## What you should see
+- JSON output containing `artifact`, `format`, and `entryCount`.
+- `format` is `zip` when the destination extension is `.zip`.
+
+## Safety notes
+> [!NOTE]
+> Keep `--json` enabled in CI so build steps can parse deterministic fields
+> instead of scraping human-readable text.

package/docs/how-to/ci-usage.md

@@ -0,0 +1,34 @@
+# How-to: use dir-archiver in CI pipelines
+
+## Goal
+Normalize incoming archives and gate releases with deterministic audit results.
+
+## Prereqs
+- `dir-archiver` available in CI
+- Input archive path from build pipeline
+
+## Copy/paste
+Normalize:
+
+```sh
+dir-archiver normalize \
+  --input ./incoming.zip \
+  --output ./normalized.zip \
+  --profile strict \
+  --json
+```
+
+Audit gate:
+
+```sh
+dir-archiver audit --input ./incoming.zip --profile agent --json
+```
+
+## What you should see
+- Normalize emits JSON report with deterministic summary fields.
+- Audit exits with code `0` when safe and `1` when operational risk is detected.
+
+## Safety notes
+> [!NOTE]
+> Exit code `2` indicates CLI usage mistakes (missing/invalid flags), not
+> archive safety problems.

package/docs/how-to/extract-untrusted.md

@@ -0,0 +1,57 @@
+# How-to: extract untrusted archives safely
+
+## Goal
+Prevent path traversal and decompression amplification from turning extraction
+into a filesystem or resource-exhaustion risk.
+
+## Prereqs
+- Node `>=24`
+- `npm install`
+- `npm run build`
+
+## Copy/paste
+Recommended pattern (audit first, then extract with limits):
+
+```ts
+import { audit, extract } from "dir-archiver";
+
+const input = "./incoming.zip";
+const report = await audit(input, { profile: "agent" });
+if (!report.ok) {
+  console.error(JSON.stringify({ ok: false, issues: report.issues }, null, 2));
+  process.exit(1);
+}
+
+await extract(input, "./out", {
+  profile: "strict",
+  maxEntryBytes: 64 * 1024 * 1024,
+  maxTotalExtractedBytes: 512 * 1024 * 1024,
+});
+```
+
+Runnable example file:
+
+```sh
+node examples/extract-untrusted.mjs
+```
+
+## What you should see
+- The audit step succeeds before extraction starts.
+- The example intentionally sets a low extraction limit and reports
+  `DIRARCHIVER_RESOURCE_LIMIT`.
+
+## Safety notes
+> [!CAUTION]
+> Never extract untrusted archives without limits. Attackers can use deeply
+> nested or highly compressed entries to trigger large disk writes
+> (`CWE-409`-style decompression amplification).
+>
+> [!CAUTION]
+> Keep `profile: "strict"` or `"agent"` for untrusted input. These profiles
+> reject traversal-style paths and unsafe entry classes during extraction.
+>
+> [!WARNING]
+> Symlink and hardlink handling changes the risk envelope:
+> - `allowSymlinks` defaults to `false`.
+> - `allowHardlinks` currently remains unsupported and triggers
+>   `DIRARCHIVER_UNSUPPORTED_ENTRY`.

package/docs/how-to/index.md

@@ -0,0 +1,7 @@
+# How-to index
+
+Task guides:
+
+- [Create CI release artifacts](ci-release-artifact.md)
+- [Extract untrusted archives safely](extract-untrusted.md)
+- [Use in CI pipelines](ci-usage.md)

package/docs/index.md

@@ -0,0 +1,24 @@
+# Documentation
+
+Use this map to pick the right doc quickly.
+
+## Start here
+- [Tutorial: bundle a plugin directory](tutorial/bundle-a-plugin.md)
+- [Tutorial: first archive flow](tutorial/first-archive-flow.md)
+
+## How-to guides
+- [How-to index](how-to/index.md)
+- [Create CI release artifacts](how-to/ci-release-artifact.md)
+- [Extract untrusted archives safely](how-to/extract-untrusted.md)
+- [Use in CI pipelines](how-to/ci-usage.md)
+
+## Reference
+- [Contract](../CONTRACT.md)
+- [CLI reference](reference/cli.md)
+- [Options reference](reference/options.md)
+- [Reference index](reference/index.md)
+- [Security policy](../SECURITY.md)
+
+## Explanation
+- [Explanation index](explanation/index.md)
+- [Profile behavior and tradeoffs](explanation/profiles.md)

package/docs/reference/cli.md

@@ -0,0 +1,277 @@
+# CLI reference
+
+## Goal
+Provide one canonical reference for `dir-archiver` CLI commands, flags, JSON
+outputs, and exit-code behavior.
+
+## Prereqs
+- Build CLI once: `npm run build`
+- Binary path in this repo: `dist/cli.js`
+
+## Copy/paste
+Show usage:
+
+```sh
+node dist/cli.js
+```
+
+Run examples:
+
+```sh
+node examples/run-all.mjs
+```
+
+## What you should see
+- Exit code `2` with usage diagnostics for invalid invocations.
+- Exit code `0` for successful commands.
+- JSON payloads on stdout when `--json` is set.
+
+## Safety notes
+> [!NOTE]
+> For automation, always pass `--json` and consume stable codes/fields instead
+> of parsing human-readable output.
+
+## Common flags
+
+| Flag | Alias | Default | Notes |
+| --- | --- | --- | --- |
+| `--source` | `--src` | command-specific | Input directory/file for `write`. |
+| `--input` | `-i` | command-specific | Archive path for `open`, `detect`, `list`, `audit`, `extract`, `normalize`. |
+| `--output` | `--dest`, `-o` | command-specific | Destination path for `write`, `extract`, `normalize`. |
+| `--format` | - | inferred/auto | Values: `zip`, `tar`, `tgz`, `tar.gz`, `gz`, `bz2`, `tar.bz2`, `zst`, `tar.zst`, `br`, `tar.br`, `xz`, `tar.xz`. |
+| `--profile` | - | `strict` | Values: `compat`, `strict`, `agent`. |
+| `--json` | - | `false` | Emit machine-readable JSON on stdout. |
+| `--include-base-directory` | `--includebasedir` | `false` | Wrap archive content under the source directory name in `write`. |
+| `--follow-symlinks` | `--followsymlinks` | `false` | Follow symlink targets when archiving source input. |
+| `--exclude` | - | `[]` | Exclude path globs in `write`. Repeatable. |
+| `--allow-symlinks` | - | `false` | Permit symlink extraction targets. |
+| `--allow-hardlinks` | - | `false` | Permit hardlink extraction targets. |
+| `--max-entry-bytes` | - | unset | Maximum bytes per extracted entry. |
+| `--max-total-extracted-bytes` | - | unset | Maximum aggregate extracted bytes per run. |
+
+## Commands
+
+### `write`
+
+Synopsis:
+
+```sh
+dir-archiver write --source <path> --src <path> --output <archive> --dest <archive> [--format <format>] [--include-base-directory|--includebasedir] [--follow-symlinks|--followsymlinks] [--exclude <path>...]
+```
+
+Example:
+
+```sh
+dir-archiver write --source ./plugin --output ./bundle.zip --include-base-directory --exclude .git --json
+```
+
+JSON output shape:
+
+```json
+{
+  "format": "zip",
+  "source": "./plugin",
+  "destination": "./bundle.zip",
+  "entryCount": 3,
+  "wrappedDirectoryCodec": false
+}
+```
+
+### `open`
+
+Synopsis:
+
+```sh
+dir-archiver open --input <archive> [--format <format>] [--profile <profile>] [--json]
+```
+
+Example:
+
+```sh
+dir-archiver open --input ./bundle.zip --json
+```
+
+JSON output shape:
+
+```json
+{
+  "format": "zip",
+  "detection": {
+    "schemaVersion": "1",
+    "inputKind": "file",
+    "detected": {
+      "container": "zip",
+      "compression": "none",
+      "layers": ["zip"]
+    },
+    "confidence": "high",
+    "notes": ["Format inferred from magic bytes"]
+  }
+}
+```
+
+### `detect`
+
+Synopsis:
+
+```sh
+dir-archiver detect --input <archive> [--json]
+```
+
+Example:
+
+```sh
+dir-archiver detect --input ./bundle.zip --json
+```
+
+JSON output shape:
+
+```json
+{
+  "format": "zip",
+  "detection": {
+    "schemaVersion": "1",
+    "inputKind": "file",
+    "detected": {
+      "container": "zip",
+      "compression": "none",
+      "layers": ["zip"]
+    },
+    "confidence": "high",
+    "notes": ["Format inferred from magic bytes"]
+  }
+}
+```
+
+### `list`
+
+Synopsis:
+
+```sh
+dir-archiver list --input <archive> [--json]
+```
+
+Example:
+
+```sh
+dir-archiver list --input ./bundle.zip --json
+```
+
+JSON output shape:
+
+```json
+{
+  "format": "zip",
+  "detection": { "...": "same shape as detect/open" },
+  "entries": [
+    {
+      "format": "zip",
+      "name": "plugin/index.js",
+      "size": "42",
+      "isDirectory": false,
+      "isSymlink": false
+    }
+  ]
+}
+```
+
+### `audit`
+
+Synopsis:
+
+```sh
+dir-archiver audit --input <archive> [--profile <profile>] [--json]
+```
+
+Example:
+
+```sh
+dir-archiver audit --input ./bundle.zip --profile agent --json
+```
+
+JSON output shape:
+
+```json
+{
+  "schemaVersion": "1",
+  "ok": true,
+  "summary": {
+    "entries": 3,
+    "warnings": 0,
+    "errors": 0
+  },
+  "issues": []
+}
+```
+
+### `extract`
+
+Synopsis:
+
+```sh
+dir-archiver extract --input <archive> --output <directory> [--profile <profile>] [--allow-symlinks] [--allow-hardlinks] [--max-entry-bytes <n>] [--max-total-extracted-bytes <n>] [--json]
+```
+
+Example:
+
+```sh
+dir-archiver extract --input ./bundle.zip --output ./out --profile strict --max-total-extracted-bytes 536870912 --json
+```
+
+JSON output shape:
+
+```json
+{
+  "format": "zip",
+  "destination": "./out",
+  "extractedFiles": 2,
+  "extractedDirectories": 1,
+  "skippedEntries": 0,
+  "issues": []
+}
+```
+
+### `normalize`
+
+Synopsis:
+
+```sh
+dir-archiver normalize --input <archive> --output <archive> [--profile <profile>] [--json]
+```
+
+Example:
+
+```sh
+dir-archiver normalize --input ./incoming.zip --output ./normalized.zip --profile strict --json
+```
+
+JSON output shape:
+
+```json
+{
+  "format": "zip",
+  "report": {
+    "schemaVersion": "1",
+    "ok": true,
+    "summary": {
+      "entries": 10,
+      "outputEntries": 10,
+      "droppedEntries": 0,
+      "renamedEntries": 0,
+      "warnings": 0,
+      "errors": 0
+    },
+    "issues": []
+  }
+}
+```
+
+## Exit codes and stderr/stdout contract
+
+- Exit `0`: success.
+- Exit `1`: operational failure (typed `DirArchiverError` JSON on stderr).
+- Exit `2`: usage/validation failure (`DIRARCHIVER_USAGE` with `issues`).
+
+For machine consumers:
+- stdout is reserved for success payloads (especially with `--json`).
+- stderr is reserved for diagnostics/failures.

package/docs/reference/index.md

@@ -0,0 +1,7 @@
+# Reference index
+
+Use this page as the canonical reference entrypoint.
+
+- [CLI reference](cli.md)
+- [Options reference](options.md)
+- [Contract](../../CONTRACT.md)

package/docs/reference/options.md

@@ -0,0 +1,57 @@
+# Options reference
+
+This page is the single reference for public option fields in `dir-archiver`.
+For CLI commands and flags, see [CLI reference](cli.md).
+
+## `OpenOptions`
+
+Used by `open`, `detect`, `list`, and `audit`.
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `format` | `ArchiveFormat` | auto-detect | Force a format when detection by bytes/filename is ambiguous. |
+| `profile` | `compat \| strict \| agent` | bytefold default | Safety profile passed to archive readers/audit. |
+| `isStrict` | `boolean` | profile-driven | Explicit strict-mode override. |
+| `limits` | `ArchiveLimits` | none | Resource ceilings for parse/audit operations. |
+| `signal` | `AbortSignal` | none | Cancels long-running operations. |
+| `password` | `string` | none | Password for encrypted archives where supported. |
+| `filename` | `string` | none | Filename hint for extension-based detection. |
+
+## `ExtractOptions`
+
+`ExtractOptions` extends `OpenOptions`.
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `profile` | `compat \| strict \| agent` | `strict` | `extract` defaults to strict safety posture. |
+| `allowSymlinks` | `boolean` | `false` | When `false`, symlink entries are skipped. |
+| `allowHardlinks` | `boolean` | `false` | Hard-link entries are currently rejected with `DIRARCHIVER_UNSUPPORTED_ENTRY`. |
+| `maxEntryBytes` | `number` | none | Maximum bytes for one extracted file entry. |
+| `maxTotalExtractedBytes` | `number` | none | Maximum cumulative bytes written during extraction. |
+
+## `WriteOptions`
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `format` | `ArchiveFormat` | inferred from destination extension, fallback `zip` | Also wraps directory + single-file codec requests (`gz` -> `tar.gz`, etc.). |
+| `includeBaseDirectory` | `boolean` | `false` | Include source directory name as archive root path prefix. |
+| `followSymlinks` | `boolean` | `false` | Follow symlinks while traversing source directories. |
+| `exclude` | `string[]` | `[]` | Exact basename or relative-path matches to skip while traversing the source root (not glob patterns). |
+| `profile` | `ArchiveProfile` | none | Present in API type; currently reserved and not forwarded by `write()`. |
+| `limits` | `ArchiveLimits` | none | Present in API type; currently reserved and not forwarded by `write()`. |
+
+## Examples
+
+```ts
+import { extract, write } from "dir-archiver";
+
+await extract("./archive.zip", "./out", {
+  profile: "strict",
+  maxTotalExtractedBytes: 512 * 1024 * 1024,
+});
+
+await write("./project", "./project.zip", {
+  includeBaseDirectory: true,
+  exclude: ["tmp", "nested/skip.txt"],
+});
+```

package/docs/tutorial/bundle-a-plugin.md

@@ -0,0 +1,42 @@
+# Tutorial: bundle a plugin directory
+
+## Goal
+Create a distributable ZIP that keeps a stable root folder and excludes local
+development files.
+
+## Prereqs
+- Node `>=24`
+- `npm install`
+- `npm run build`
+
+## Copy/paste
+CLI-style command:
+
+```sh
+dir-archiver write \
+  --includebasedir \
+  --src . \
+  --dest ../bundle.zip \
+  --exclude .git \
+  --exclude node_modules \
+  --exclude package-lock.json \
+  --exclude package.json \
+  --json
+```
+
+Runnable example file:
+
+```sh
+node examples/bundle-a-plugin.mjs
+```
+
+## What you should see
+- A ZIP file is created.
+- JSON output reports `format: "zip"`.
+- Excluded paths (`.git`, `node_modules`, lock/package manifests) are omitted.
+
+## Safety notes
+> [!NOTE]
+> `--includebasedir` preserves one top-level folder in the archive. This keeps
+> extraction deterministic and prevents files from scattering into whichever
+> directory the user extracts into.

package/docs/tutorial/first-archive-flow.md

@@ -0,0 +1,33 @@
+# Tutorial: first archive flow
+
+## Goal
+Write an archive, detect its format, and extract it with strict safety defaults.
+
+## Prereqs
+- Node `>=24`
+- `npm install`
+- `npm run build`
+
+## Copy/paste
+```ts
+import { write, detect, extract } from "dir-archiver";
+
+await write("./project", "./project.zip", {
+  format: "zip",
+  includeBaseDirectory: true,
+});
+
+const detected = await detect("./project.zip");
+await extract("./project.zip", "./out", { profile: "strict" });
+
+console.log(detected.format);
+```
+
+## What you should see
+- `detected.format` prints `zip`.
+- `./out` contains the extracted files.
+
+## Safety notes
+> [!NOTE]
+> Use `profile: "strict"` for extraction unless you have a documented reason to
+> weaken constraints.

package/jsr.json

@@ -0,0 +1,35 @@
+{
+  "name": "@ismail-elkorchi/dir-archiver",
+  "version": "3.0.1",
+  "license": "MIT",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "imports": {
+    "@ismail-elkorchi/bytefold": "jsr:@ismail-elkorchi/bytefold@^0.8.1",
+    "@ismail-elkorchi/bytefold/node": "jsr:@ismail-elkorchi/bytefold/node@^0.8.1",
+    "@ismail-elkorchi/bytefold/deno": "jsr:@ismail-elkorchi/bytefold/deno@^0.8.1",
+    "@ismail-elkorchi/bytefold/bun": "jsr:@ismail-elkorchi/bytefold/bun@^0.8.1"
+  },
+  "publish": {
+    "include": [
+      "LICENSE",
+      "README.md",
+      "CHANGELOG.md",
+      "CONTRACT.md",
+      "SECURITY.md",
+      "CONTRIBUTING.md",
+      "SUPPORT.md",
+      "docs/**",
+      "src/**",
+      "jsr.json",
+      "package.json"
+    ],
+    "exclude": [
+      "dist/**",
+      "test/**",
+      "node_modules/**",
+      ".github/**"
+    ]
+  }
+}