dir-archiver 3.0.0 → 3.0.2

package/CHANGELOG.md

@@ -0,0 +1,100 @@
+# Changes to Dir Archiver
+
+### Unreleased
+
+* No entries yet.
+
+### 3.0.2 (June 19, 2026)
+
+* Fix JSR documentation checks for current and pinned Deno doc output.
+* Update `argv-flags` to 1.0.5.
+* Bump GitHub Actions dependencies in CI and release workflows.
+
+### 3.0.1 (March 3, 2026)
+
+* Rework README/docs information architecture for fast first-use onboarding.
+* Expand `docs/reference/cli.md` as the canonical CLI command/flag/output reference.
+* Add runnable offline examples and wire `npm run examples:run` into check flows.
+* Add example doc blocks (Goal/Prereqs/Run/Expected output/Safety notes) for each example file.
+* Keep archive runtime behavior and CLI semantics unchanged.
+
+### 3.0.0 (February 28, 2026)
+
+* Rewrite dir-archiver as a bytefold-backed orchestration layer over `open`, `detect`, `list`, `audit`, `extract`, `normalize`, and `write`.
+* Expand format support to the full bytefold `ArchiveFormat` surface (zip/tar/layered codecs).
+* Add runtime adapters for Node.js, Deno, and Bun with unified API behavior.
+* Add strict/agent extraction security enforcement and stable `DirArchiverError.code` contracts.
+* Add CLI v3 contract with schema-driven parsing via `argv-flags`, machine JSON mode, and explicit exit code semantics.
+* Add capability-derived runtime matrix tests, determinism fingerprints, and adversarial security fixtures.
+* Add downstream compatibility gates against released dependencies and `main` branches.
+* Enforce ESM-only, workflow-policy, docs-policy, and runtime-policy gates via `npm run check`.
+* Align dependency source to released `@ismail-elkorchi/bytefold@^0.7.2` (remove local/git-sha dependency path).
+* Bump runtime floor to Node.js >=24 and keep Deno/Bun support through dedicated runtime checks.
+
+### 2.2.0 (January 28, 2026)
+
+* Migrate source to TypeScript with strict compiler options.
+* Build compiled output into `dist/` with declaration files.
+* Add strict ESLint configuration alongside TypeScript typechecking.
+* Require Node.js >=18.
+* CLI exits with a non-zero status when required arguments are missing.
+* Add a CLI smoke test.
+* Skip symlinks by default and add an option to follow them.
+* Exclude entries by name anywhere unless a relative path is specified.
+* Normalize exclude path separators so Windows-style paths work cross-platform.
+* Accept absolute exclude paths when they resolve inside the source tree.
+* Make exclude matching case-insensitive on Windows.
+* Normalize archive entry paths to forward slashes for cross-platform zip compatibility.
+* Traverse entries in deterministic order.
+* Honor explicit true/false values for CLI boolean flags.
+* Improve error handling for archive creation failures.
+* Bump argv-flags to 0.2.1 (inline flag values).
+
+### 2.1.2 (January 28, 2026)
+
+* Add a smoke test suite and npm test script.
+* Add CI to run linting and tests.
+* Declare Node.js >=14 in package metadata.
+
+### 2.1.1 (January 28, 2026)
+
+* Avoid archiving the destination zip when it lives inside the source directory ([#5](https://github.com/Ismail-elkorchi/dir-archiver/issues/5)).
+* `createZip()` now returns a Promise that resolves when the archive is closed ([#13](https://github.com/Ismail-elkorchi/dir-archiver/issues/13)).
+* Bump archiver to 7.0.1 to address dependency deprecation warnings ([#14](https://github.com/Ismail-elkorchi/dir-archiver/issues/14)).
+
+### 2.1.0 (October 25, 2022)
+
+* Add ESLint ([#12](https://github.com/Ismail-elkorchi/dir-archiver/pull/12)).
+* Several enhancements to better support Microsoft Windows ([Diff](https://github.com/Ismail-elkorchi/dir-archiver/compare/2.0.0...v2.1.0)).
+
+### 2.0.0 (September 20, 2022)
+
+* Bump archiver from 5.2.0 to 5.3.1 ([42c30b7](https://github.com/Ismail-elkorchi/dir-archiver/commit/42c30b7a3b7fa0b3101e21559f1774f45d2f06ce)).
+* Add an option to include the base directory in the archive root ([#11](https://github.com/Ismail-elkorchi/dir-archiver/pull/11)).
+
+### 1.2.0 (February 28, 2021)
+
+* Bump archiver from 4.0.2 to 5.2.0 ([b84c347](https://github.com/Ismail-elkorchi/dir-archiver/commit/b84c34731617c57b7c439f15910fcc8fa00747b2)).
+* Make exclude paths relative to run directory ([#4](https://github.com/Ismail-elkorchi/dir-archiver/pull/4)).
+* Remove the destination zip if it exists already ([#7](https://github.com/Ismail-elkorchi/dir-archiver/pull/7)).
+
+### 1.1.2 (July 21, 2020)
+
+* Bump lodash from 4.17.15 to 4.17.19.
+* Bump archiver from 4.0.1 to 4.0.2.
+
+### 1.1.1 (May 14, 2020)
+
+* CLI : prevent execution if the required arguments are missing.
+
+### 1.1.0 (May 13, 2020)
+
+* Add cli script.
+
+### 1.0.1 (May 12, 2020)
+
+* Fix the installation instructions.
+
+### 1.0.0 (May 12, 2020)
+
+* initial release.

package/CONTRACT.md

@@ -0,0 +1,94 @@
+# dir-archiver contract
+
+This document defines the current public behavior contract for `dir-archiver`.
+
+## Runtime support
+
+- Node.js LTS (minimum aligned with bytefold `engines.node`).
+- Latest stable Deno.
+- Latest stable Bun.
+
+## Public operations
+
+- `open(input, options)`
+- `detect(input, options)`
+- `list(input, options)`
+- `audit(input, options)`
+- `extract(input, destination, options)`
+- `normalize(input, destination, options)`
+- `write(source, destination, options)`
+
+Profiles are passed through to bytefold for read/audit/extract/normalize flows (`compat | strict | agent`).
+`WriteOptions.profile` and `WriteOptions.limits` are currently reserved and not forwarded by `write()`.
+
+Detailed option fields and examples are maintained in
+`docs/reference/options.md`.
+
+## Format surface
+
+The package accepts the full bytefold `ArchiveFormat` union:
+
+`zip`, `tar`, `tgz`, `tar.gz`, `gz`, `bz2`, `tar.bz2`, `zst`, `tar.zst`, `br`, `tar.br`, `xz`, `tar.xz`.
+
+### Directory input with single-file codec
+
+When `write()` receives a directory source and the requested format is a single-file codec:
+
+- `gz` -> `tar.gz`
+- `bz2` -> `tar.bz2`
+- `xz` -> `tar.xz`
+- `zst` -> `tar.zst`
+- `br` -> `tar.br`
+
+This conversion is deterministic and reported via `WriteResult.wrappedDirectoryCodec`.
+
+## Determinism rules
+
+- Directory traversal order is lexicographic and stable.
+- Archive entry paths are normalized to `/`.
+- `normalize()` defaults to deterministic mode (`isDeterministic: true`).
+
+## Resource limits
+
+Extraction limits are explicit options:
+
+- `maxEntryBytes`
+- `maxTotalExtractedBytes`
+
+Budget overruns fail with stable code `DIRARCHIVER_RESOURCE_LIMIT`.
+
+## Security model
+
+- Extraction treats archive entries as untrusted.
+- Absolute paths, drive-prefixed paths, and traversal (`..`) are rejected with `DIRARCHIVER_PATH_TRAVERSAL`.
+- Strict/agent extraction runs an audit gate before writing files.
+- Hard links are rejected with `DIRARCHIVER_UNSUPPORTED_ENTRY`.
+- Symlinks are skipped unless explicitly enabled.
+
+## Error code stability
+
+Consumers rely on `DirArchiverError.code`, not message text.
+Current stable codes:
+
+- `DIRARCHIVER_INVALID_SOURCE`
+- `DIRARCHIVER_INVALID_DESTINATION`
+- `DIRARCHIVER_PATH_TRAVERSAL`
+- `DIRARCHIVER_UNSUPPORTED_ENTRY`
+- `DIRARCHIVER_RESOURCE_LIMIT`
+- `DIRARCHIVER_RUNTIME_UNSUPPORTED`
+- `DIRARCHIVER_NORMALIZE_UNSUPPORTED`
+- `DIRARCHIVER_USAGE`
+
+## CLI exit codes
+
+- `0`: success
+- `1`: operational failure
+- `2`: usage/validation failure
+
+Canonical command/flag documentation lives in `docs/reference/cli.md`.
+
+## API surface snapshot oracle
+
+`test/api-snapshot.test.mjs` compares module exports with
+`test/fixtures/api-surface.v3.json`.
+Any intentional API change updates both this contract and the snapshot.

package/CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# Contributing
+
+## Development setup
+
+```sh
+npm ci
+npm run check:fast
+npm run check
+```
+
+## Verification commands
+
+- `npm run check:fast`: lint + Node test suite (no runtime matrix).
+- `npm run check`: full repository gate (policy checks, lint, tests, security tests, runtime matrix).
+
+## Change requirements
+
+- Keep ESM-only packaging.
+- Preserve Node + Deno + Bun compatibility.
+- Add/update tests for behavior changes.
+- Update `CONTRACT.md` for API or guarantee changes.
+
+## Runtime dependency freshness policy
+
+- Keep direct runtime dependencies in `package.json` and `package-lock.json` on the latest published stable versions before every release.
+- Validate with `npm run deps:fresh` (this gate runs in the release workflow).
+- If a dependency is stale, update it in a dedicated PR and run `npm run check`.
+
+## Pull request checklist
+
+- [ ] `npm run check` passes locally
+- [ ] docs updated for user-facing changes
+- [ ] changelog entry added for release-relevant updates

package/README.md

@@ -1,88 +1,64 @@
----
-role: overview
-audience: users
-source_of_truth: README.md
-update_triggers:
-  - public API changes
-  - CLI contract changes
-  - runtime support changes
----
-
 # dir-archiver
 
-`dir-archiver` v3 is a bytefold-backed archive orchestration layer for Node.js, Deno, and Bun.  
-ESM-only. Safety profiles: `compat | strict | agent`.
+Deterministic directory archiving and extraction over zip, tar, and layered compression.
 
-## Install
+Supports Node.js, Deno, and Bun.
 
-### npm
+## What it is
 
-```sh
-npm install dir-archiver
-```
+`dir-archiver` provides one API surface for archive operations with explicit safety profiles and stable error codes.
 
-### JSR
+## Install
 
 ```sh
+npm install dir-archiver
 deno add jsr:@ismail-elkorchi/dir-archiver
 ```
 
-## Quickstart (API)
+## Quickstart
 
 ```ts
-import { write, detect, list, extract } from 'dir-archiver';
+import { write, detect, extract } from "dir-archiver";
 
-await write('./project', './project.zip', {
-  format: 'zip',
+await write("./project", "./project.zip", {
+  format: "zip",
   includeBaseDirectory: true,
-  profile: 'strict'
 });
 
-const detected = await detect('./project.zip');
-const listed = await list('./project.zip');
-await extract('./project.zip', './out', { profile: 'strict' });
+const detected = await detect("./project.zip");
+await extract("./project.zip", "./out", { profile: "strict" });
 
-console.log(detected.format, listed.entries.length);
+console.log(detected.format);
 ```
 
-## Public operations
-
-- `open(input, options)`
-- `detect(input, options)`
-- `list(input, options)`
-- `audit(input, options)`
-- `extract(input, destination, options)`
-- `normalize(input, destination, options)`
-- `write(source, destination, options)`
+## When not to use
 
-Format surface matches bytefold `ArchiveFormat` support.  
-Directory + single-file codec requests are normalized to `tar.<codec>` (`gz`, `bz2`, `xz`, `zst`, `br`).
+- You only need a low-level parser for a single format.
+- You target CommonJS-only environments or Node < 24.
+- You need interactive archive browsing UI features.
 
-## CLI
+## When to use
 
-```sh
-dir-archiver write --source ./project --output ./project.zip --format zip --json
-dir-archiver detect --input ./project.zip --json
-dir-archiver list --input ./project.zip --json
-dir-archiver audit --input ./project.zip --profile agent --json
-dir-archiver extract --input ./project.zip --output ./out --profile strict --json
-dir-archiver normalize --input ./project.zip --output ./normalized.zip --json
-```
+- You need one API for detect, list, audit, extract, normalize, and write.
+- You want deterministic normalization for CI pipelines.
+- You need safety profiles for untrusted inputs.
 
-Exit codes:
+## Compatibility
 
-- `0` success
-- `1` operational failure
-- `2` usage/validation failure
+- Module system: ESM-only.
+- Runtimes: Node `>=24`, current Deno, current Bun.
+- CLI and API contracts are documented in [Contract](https://github.com/Ismail-elkorchi/dir-archiver/blob/main/CONTRACT.md).
 
-## Security model
+## Documentation
 
-- Archive extraction treats input as untrusted by default.
-- Traversal/absolute paths are blocked in strict/agent profiles.
-- See `SECURITY.md` and `docs/security-triage.md`.
+- [Docs index](https://github.com/Ismail-elkorchi/dir-archiver/blob/main/docs/index.md)
+- [Tutorial: bundle a plugin directory](https://github.com/Ismail-elkorchi/dir-archiver/blob/main/docs/tutorial/bundle-a-plugin.md)
+- [Reference: CLI](https://github.com/Ismail-elkorchi/dir-archiver/blob/main/docs/reference/cli.md)
 
-## Docs
+## Verification
 
-- `docs/V3_CONTRACT.md`
-- `CHANGELOG.md`
-- `SECURITY.md`
+```sh
+npm run examples:run
+npm run check:fast
+npm run check
+```

package/SECURITY.md

@@ -0,0 +1,23 @@
+# Security policy
+
+## Threat model
+
+- Archive inputs are untrusted by default.
+- Common risks include path traversal, symlink abuse, hard-link abuse, and resource exhaustion.
+- Runtime/feature mismatches are treated as explicit typed failures.
+
+## Safe usage guidance
+
+- Prefer `strict` or `agent` profiles for extraction and audit.
+- Audit untrusted archives before extraction (`audit` + `assertSafe` paths).
+- Set resource limits (`maxEntryBytes`, `maxTotalExtractedBytes`) for hostile inputs.
+
+## Reporting vulnerabilities
+
+Report security issues through GitHub Security Advisories for this repository.
+
+## Disclosure workflow
+
+1. Reproduce and classify impact.
+2. Patch with tests.
+3. Publish release notes and remediation guidance.

package/SUPPORT.md

@@ -0,0 +1,16 @@
+# Support
+
+## Usage questions
+
+Open a GitHub issue and include:
+- runtime (`node`, `deno`, `bun`)
+- package version
+- minimal reproducible example
+
+## Bug reports
+
+Use GitHub issues with expected vs actual behavior and sample command/input.
+
+## Security reports
+
+Follow `SECURITY.md` for private disclosure.

package/dist/cli.js

@@ -4,6 +4,7 @@ import { DirArchiverError } from './errors.js';
 import { parseCliArgs } from './cli-args.js';
 const usage = `Usage:
   dir-archiver write --source <path> --output <archive> [--format <format>] [--include-base-directory] [--exclude <path>...]
+  dir-archiver open --input <archive> [--profile compat|strict|agent]
   dir-archiver detect --input <archive>
   dir-archiver list --input <archive>
   dir-archiver audit --input <archive> [--profile compat|strict|agent]

package/dist/core.d.ts

@@ -1,31 +1,100 @@
 import type { ArchiveAuditReport, ArchiveReader } from '@ismail-elkorchi/bytefold';
 import type { DetectResult, DirArchiverInput, ExtractOptions, ExtractResult, ListResult, NormalizeOptions, NormalizeResult, OpenOptions, WriteOptions, WriteResult } from './types.js';
 /**
- * Opens an archive input with bytefold runtime bindings.
+ * Opens an archive and returns the live bytefold reader.
+ *
+ * Use this when you need direct access to low-level reader capabilities such
+ * as `entries()`, `audit()`, or normalization support checks. The returned
+ * reader is not auto-disposed, so callers should close or dispose it when the
+ * active runtime exposes a cleanup hook.
+ *
+ * @param input Archive bytes, path, URL, stream, or blob to open.
+ * @param options Format hints, safety profile, limits, and cancellation
+ * signal forwarded to bytefold.
+ * @returns A live `ArchiveReader` for advanced inspection flows.
  */
 export declare const open: (input: DirArchiverInput, options?: OpenOptions) => Promise<ArchiveReader>;
 /**
- * Detects archive format and exposes bytefold detection metadata.
+ * Detects an archive format without extracting or listing its contents.
+ *
+ * This is the lightest-weight way to confirm the container and compression
+ * layers before choosing a follow-up operation.
+ *
+ * @param input Archive bytes, path, URL, stream, or blob to inspect.
+ * @param options Format hints and parse controls applied during detection.
+ * @returns The resolved archive format and any bytefold detection metadata.
  */
 export declare const detect: (input: DirArchiverInput, options?: OpenOptions) => Promise<DetectResult>;
 /**
- * Lists archive entries without extracting to disk.
+ * Lists archive entries without extracting anything to disk.
+ *
+ * Each entry is projected into a JSON-safe summary so CLI and API callers can
+ * inspect paths, sizes, and link metadata before deciding to extract.
+ *
+ * @param input Archive bytes, path, URL, stream, or blob to inspect.
+ * @param options Format hints and parse controls applied while reading the
+ * archive directory.
+ * @returns Archive metadata plus the entry summaries visible to callers.
  */
 export declare const list: (input: DirArchiverInput, options?: OpenOptions) => Promise<ListResult>;
 /**
- * Runs bytefold audit checks for the selected safety profile.
+ * Audits an archive against the selected bytefold safety profile.
+ *
+ * Use this before extraction when you need a report of unsafe paths, link
+ * entries, or format-specific concerns without writing files to disk.
+ *
+ * @param input Archive bytes, path, URL, stream, or blob to audit.
+ * @param options Safety profile, limits, and format hints used during the
+ * audit pass.
+ * @returns The bytefold audit report for the requested profile.
  */
 export declare const audit: (input: DirArchiverInput, options?: OpenOptions) => Promise<ArchiveAuditReport>;
 /**
- * Writes a normalized deterministic archive when supported by the format.
+ * Rewrites an archive into its normalized deterministic representation.
+ *
+ * Normalization is available only when the opened archive reader exposes
+ * bytefold normalization support. Unsupported formats throw
+ * `DIRARCHIVER_NORMALIZE_UNSUPPORTED`.
+ *
+ * @param input Archive bytes, path, URL, stream, or blob to normalize.
+ * @param destination Output archive path that will receive the normalized
+ * bytes.
+ * @param options Format hints and normalization controls applied during the
+ * read and write pass.
+ * @returns The source format and bytefold normalization report.
+ * @throws {DirArchiverError} When the selected archive format cannot be
+ * normalized by the active runtime.
  */
 export declare const normalize: (input: DirArchiverInput, destination: string, options?: NormalizeOptions) => Promise<NormalizeResult>;
 /**
- * Extracts entries to a destination directory with safety enforcement.
+ * Extracts an archive into a destination directory with safety enforcement.
+ *
+ * `extract()` defaults to `profile: 'strict'`. Under `strict` or `agent`, the
+ * archive is audited before bytes are written to disk and unsafe entries raise
+ * a `DirArchiverError` instead of being silently materialized.
+ *
+ * @param input Archive bytes, path, URL, stream, or blob to extract.
+ * @param destination Directory that will receive extracted files.
+ * @param options Extraction policy, safety profile, and resource limits.
+ * @returns A summary of what was extracted, skipped, and flagged.
+ * @throws {DirArchiverError} When audit checks fail, resource limits are
+ * exceeded, or unsupported entry types are encountered.
  */
 export declare const extract: (input: DirArchiverInput, destination: string, options?: ExtractOptions) => Promise<ExtractResult>;
 /**
- * Writes an archive from a file or directory source.
+ * Writes an archive from a file or directory source path.
+ *
+ * Directory sources are traversed deterministically. When callers request a
+ * single-file compression codec such as `gz` for a directory source,
+ * `dir-archiver` wraps the directory in the corresponding tar-based container
+ * (`tar.gz`, `tar.zst`, and so on).
+ *
+ * @param source File or directory path to archive.
+ * @param destination Output archive path.
+ * @param options Format selection, traversal rules, and exclusion controls.
+ * @returns A summary of the emitted archive format and entry count.
+ * @throws {DirArchiverError} When the requested output format is unsupported by
+ * the active bytefold writer.
  */
 export declare const write: (source: string, destination: string, options?: WriteOptions) => Promise<WriteResult>;
 export declare const copyStreamToFile: (source: string, destination: string) => Promise<void>;

package/dist/core.js

@@ -12,14 +12,31 @@ const DIRECTORY_TO_SINGLE_FILE_CODEC = {
 };
 const writeUnsupportedFormats = new Set(['tar.bz2', 'bz2', 'tar.xz', 'xz']);
 /**
- * Opens an archive input with bytefold runtime bindings.
+ * Opens an archive and returns the live bytefold reader.
+ *
+ * Use this when you need direct access to low-level reader capabilities such
+ * as `entries()`, `audit()`, or normalization support checks. The returned
+ * reader is not auto-disposed, so callers should close or dispose it when the
+ * active runtime exposes a cleanup hook.
+ *
+ * @param input Archive bytes, path, URL, stream, or blob to open.
+ * @param options Format hints, safety profile, limits, and cancellation
+ * signal forwarded to bytefold.
+ * @returns A live `ArchiveReader` for advanced inspection flows.
  */
 export const open = async (input, options = {}) => {
     const runtime = await loadRuntimeBindings();
     return runtime.openArchive(input, toArchiveOpenOptions(options));
 };
 /**
- * Detects archive format and exposes bytefold detection metadata.
+ * Detects an archive format without extracting or listing its contents.
+ *
+ * This is the lightest-weight way to confirm the container and compression
+ * layers before choosing a follow-up operation.
+ *
+ * @param input Archive bytes, path, URL, stream, or blob to inspect.
+ * @param options Format hints and parse controls applied during detection.
+ * @returns The resolved archive format and any bytefold detection metadata.
  */
 export const detect = async (input, options = {}) => {
     const reader = await open(input, options);
@@ -34,7 +51,15 @@ export const detect = async (input, options = {}) => {
     }
 };
 /**
- * Lists archive entries without extracting to disk.
+ * Lists archive entries without extracting anything to disk.
+ *
+ * Each entry is projected into a JSON-safe summary so CLI and API callers can
+ * inspect paths, sizes, and link metadata before deciding to extract.
+ *
+ * @param input Archive bytes, path, URL, stream, or blob to inspect.
+ * @param options Format hints and parse controls applied while reading the
+ * archive directory.
+ * @returns Archive metadata plus the entry summaries visible to callers.
  */
 export const list = async (input, options = {}) => {
     const reader = await open(input, options);
@@ -61,7 +86,15 @@ export const list = async (input, options = {}) => {
     }
 };
 /**
- * Runs bytefold audit checks for the selected safety profile.
+ * Audits an archive against the selected bytefold safety profile.
+ *
+ * Use this before extraction when you need a report of unsafe paths, link
+ * entries, or format-specific concerns without writing files to disk.
+ *
+ * @param input Archive bytes, path, URL, stream, or blob to audit.
+ * @param options Safety profile, limits, and format hints used during the
+ * audit pass.
+ * @returns The bytefold audit report for the requested profile.
  */
 export const audit = async (input, options = {}) => {
     const reader = await open(input, options);
@@ -73,7 +106,20 @@ export const audit = async (input, options = {}) => {
     }
 };
 /**
- * Writes a normalized deterministic archive when supported by the format.
+ * Rewrites an archive into its normalized deterministic representation.
+ *
+ * Normalization is available only when the opened archive reader exposes
+ * bytefold normalization support. Unsupported formats throw
+ * `DIRARCHIVER_NORMALIZE_UNSUPPORTED`.
+ *
+ * @param input Archive bytes, path, URL, stream, or blob to normalize.
+ * @param destination Output archive path that will receive the normalized
+ * bytes.
+ * @param options Format hints and normalization controls applied during the
+ * read and write pass.
+ * @returns The source format and bytefold normalization report.
+ * @throws {DirArchiverError} When the selected archive format cannot be
+ * normalized by the active runtime.
  */
 export const normalize = async (input, destination, options = {}) => {
     const reader = await open(input, options);
@@ -95,7 +141,18 @@ export const normalize = async (input, destination, options = {}) => {
     }
 };
 /**
- * Extracts entries to a destination directory with safety enforcement.
+ * Extracts an archive into a destination directory with safety enforcement.
+ *
+ * `extract()` defaults to `profile: 'strict'`. Under `strict` or `agent`, the
+ * archive is audited before bytes are written to disk and unsafe entries raise
+ * a `DirArchiverError` instead of being silently materialized.
+ *
+ * @param input Archive bytes, path, URL, stream, or blob to extract.
+ * @param destination Directory that will receive extracted files.
+ * @param options Extraction policy, safety profile, and resource limits.
+ * @returns A summary of what was extracted, skipped, and flagged.
+ * @throws {DirArchiverError} When audit checks fail, resource limits are
+ * exceeded, or unsupported entry types are encountered.
  */
 export const extract = async (input, destination, options = {}) => {
     var _a;
@@ -180,7 +237,19 @@ export const extract = async (input, destination, options = {}) => {
     }
 };
 /**
- * Writes an archive from a file or directory source.
+ * Writes an archive from a file or directory source path.
+ *
+ * Directory sources are traversed deterministically. When callers request a
+ * single-file compression codec such as `gz` for a directory source,
+ * `dir-archiver` wraps the directory in the corresponding tar-based container
+ * (`tar.gz`, `tar.zst`, and so on).
+ *
+ * @param source File or directory path to archive.
+ * @param destination Output archive path.
+ * @param options Format selection, traversal rules, and exclusion controls.
+ * @returns A summary of the emitted archive format and entry count.
+ * @throws {DirArchiverError} When the requested output format is unsupported by
+ * the active bytefold writer.
  */
 export const write = async (source, destination, options = {}) => {
     var _a, _b;