dir-archiver 3.0.0 → 3.0.1

package/CHANGELOG.md

@@ -0,0 +1,94 @@
+# Changes to Dir Archiver
+
+### Unreleased
+
+* No entries yet.
+
+### 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,74 @@
----
-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`.
+Archive orchestration for detect/list/audit/extract/normalize/write flows across Node, Deno, and Bun.
 
-## Install
+## What it is
 
-### npm
+`dir-archiver` provides one API surface for archive operations with explicit safety profiles and stable error codes.
 
-```sh
-npm install dir-archiver
-```
-
-### 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
+## Options reference
 
-- `open(input, options)`
-- `detect(input, options)`
-- `list(input, options)`
-- `audit(input, options)`
-- `extract(input, destination, options)`
-- `normalize(input, destination, options)`
-- `write(source, destination, options)`
+- [Options reference](https://github.com/Ismail-elkorchi/dir-archiver/blob/main/docs/reference/options.md)
+- [CLI reference](https://github.com/Ismail-elkorchi/dir-archiver/blob/main/docs/reference/cli.md)
+- [10-minute tutorial: bundle a plugin directory](https://github.com/Ismail-elkorchi/dir-archiver/blob/main/docs/tutorial/bundle-a-plugin.md)
 
-Format surface matches bytefold `ArchiveFormat` support.  
-Directory + single-file codec requests are normalized to `tar.<codec>` (`gz`, `bz2`, `xz`, `zst`, `br`).
+## When not to use
 
-## CLI
+- 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.
 
-```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
-```
+## When to use
 
-Exit codes:
+- 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.
 
-- `0` success
-- `1` operational failure
-- `2` usage/validation failure
+## Compatibility
 
-## Security model
+- Module system: ESM-only.
+- Runtimes: Node `>=24`, current Deno, current Bun.
+- CLI and API contracts are documented in `CONTRACT.md`.
 
-- 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`.
+## Links
 
-## Docs
+- [Docs index](https://github.com/Ismail-elkorchi/dir-archiver/blob/main/docs/index.md)
+- Reference:
+  - [Reference index](https://github.com/Ismail-elkorchi/dir-archiver/blob/main/docs/reference/index.md)
+  - [Contract](https://github.com/Ismail-elkorchi/dir-archiver/blob/main/CONTRACT.md)
+  - [Security policy](https://github.com/Ismail-elkorchi/dir-archiver/blob/main/SECURITY.md)
+- How-to:
+  - [How-to index](https://github.com/Ismail-elkorchi/dir-archiver/blob/main/docs/how-to/index.md)
+  - [Contributing](https://github.com/Ismail-elkorchi/dir-archiver/blob/main/CONTRIBUTING.md)
+- Explanation: [explanation index](https://github.com/Ismail-elkorchi/dir-archiver/blob/main/docs/explanation/index.md)
 
-- `docs/V3_CONTRACT.md`
-- `CHANGELOG.md`
-- `SECURITY.md`
+## Verification
+
+```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/types.d.ts

@@ -5,15 +5,38 @@ export type { ArchiveFormat, ArchiveLimits, ArchiveProfile };
  */
 export type DirArchiverInput = string | URL | Uint8Array | ArrayBuffer | ReadableStream<Uint8Array> | Blob;
 /**
- * Common options forwarded to bytefold open operations.
+ * Common options forwarded to bytefold archive-open operations.
+ *
+ * Used by `open()`, `detect()`, `list()`, and `audit()`.
  */
 export interface OpenOptions {
+    /**
+     * Explicit format override when callers already know archive type.
+     */
     format?: ArchiveOpenOptions['format'] | undefined;
+    /**
+     * Safety profile (`compat`, `strict`, `agent`) applied during reads/audits.
+     */
     profile?: ArchiveOpenOptions['profile'] | undefined;
+    /**
+     * Extra strictness toggle forwarded to bytefold parsing.
+     */
     isStrict?: ArchiveOpenOptions['isStrict'] | undefined;
+    /**
+     * Parser/resource limits enforced while opening or auditing archives.
+     */
     limits?: ArchiveOpenOptions['limits'] | undefined;
+    /**
+     * Abort signal for cancelling in-flight async operations.
+     */
     signal?: ArchiveOpenOptions['signal'] | undefined;
+    /**
+     * Password used for encrypted archives when supported by the runtime.
+     */
     password?: ArchiveOpenOptions['password'] | undefined;
+    /**
+     * Filename hint used for extension-based inference with non-path inputs.
+     */
     filename?: ArchiveOpenOptions['filename'] | undefined;
 }
 /**
@@ -42,6 +65,12 @@ export interface ListResult {
     detection: ArchiveDetectionReport | undefined;
     entries: ListEntry[];
 }
+/**
+ * Options for `audit()`.
+ *
+ * Alias of `OpenOptions` for stable API typing; CLI-only flags (for example
+ * `--json`) are not part of this programmatic surface.
+ */
 export type AuditOptions = OpenOptions;
 /**
  * Normalize operation options.
@@ -58,11 +87,27 @@ export interface NormalizeResult {
 }
 /**
  * Extraction options with explicit safety limits.
+ *
+ * `extract()` defaults to `profile: 'strict'` when no profile is supplied.
  */
 export interface ExtractOptions extends OpenOptions {
+    /**
+     * If `true`, symbolic-link entries are materialized on disk; otherwise they
+     * are skipped and counted in `ExtractResult.skippedEntries`.
+     */
     allowSymlinks?: boolean | undefined;
+    /**
+     * Reserved for forward compatibility. Hard-link entries are currently
+     * rejected with `DIRARCHIVER_UNSUPPORTED_ENTRY` regardless of this flag.
+     */
     allowHardlinks?: boolean | undefined;
+    /**
+     * Maximum bytes allowed for any single extracted file entry.
+     */
     maxEntryBytes?: number | undefined;
+    /**
+     * Maximum cumulative bytes allowed across all extracted file entries.
+     */
     maxTotalExtractedBytes?: number | undefined;
 }
 /**
@@ -80,11 +125,31 @@ export interface ExtractResult {
  * Archive writer options.
  */
 export interface WriteOptions {
+    /**
+     * Requested output format. If omitted, inferred from destination extension
+     * and falls back to `zip` when inference is not possible.
+     */
     format?: ArchiveFormat | undefined;
+    /**
+     * Includes the source directory name as a root folder in the archive when
+     * source is a directory.
+     */
     includeBaseDirectory?: boolean | undefined;
+    /**
+     * Follows symbolic links while walking directory sources for `write()`.
+     */
     followSymlinks?: boolean | undefined;
+    /**
+     * Glob-like exclusion patterns evaluated relative to the source root.
+     */
     exclude?: string[] | undefined;
+    /**
+     * Writer profile (`compat`, `strict`, `agent`) forwarded to bytefold.
+     */
     profile?: ArchiveProfile | undefined;
+    /**
+     * Optional writer limits passed through to bytefold operations.
+     */
     limits?: ArchiveLimits | undefined;
 }
 /**

package/docs/explanation/index.md

@@ -0,0 +1,5 @@
+# Explanation index
+
+Design and tradeoff notes:
+
+- [Profile behavior and tradeoffs](profiles.md)

package/docs/explanation/profiles.md

@@ -0,0 +1,21 @@
+# Profile behavior and tradeoffs
+
+Profiles configure safety posture for audit and extraction.
+
+## compat
+
+- Minimal guardrails.
+- Use only for trusted inputs or internal tooling.
+
+## strict
+
+- Blocks traversal, absolute paths, and unsafe entries.
+- Enforces explicit resource limits.
+
+## agent
+
+- Same safety posture as strict.
+- Adds additional audit assertions for automation pipelines.
+
+Profiles are passed through to bytefold, so bytefold updates may expand the
+checked conditions without changing the profile names.

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

@@ -1,21 +1,26 @@
 {
   "name": "@ismail-elkorchi/dir-archiver",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "license": "MIT",
   "exports": {
     ".": "./src/index.ts"
   },
   "imports": {
-    "@ismail-elkorchi/bytefold": "jsr:@ismail-elkorchi/bytefold@^0.7.2",
-    "@ismail-elkorchi/bytefold/node": "jsr:@ismail-elkorchi/bytefold/node@^0.7.2",
-    "@ismail-elkorchi/bytefold/deno": "jsr:@ismail-elkorchi/bytefold/deno@^0.7.2",
-    "@ismail-elkorchi/bytefold/bun": "jsr:@ismail-elkorchi/bytefold/bun@^0.7.2"
+    "@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"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dir-archiver",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "Bytefold-backed archive orchestration for directories/files across Node.js, Deno, and Bun.",
   "license": "MIT",
   "type": "module",
@@ -17,6 +17,13 @@
   },
   "files": [
     "LICENSE",
+    "README.md",
+    "CHANGELOG.md",
+    "CONTRACT.md",
+    "SECURITY.md",
+    "CONTRIBUTING.md",
+    "SUPPORT.md",
+    "docs",
     "dist",
     "jsr.json"
   ],
@@ -46,16 +53,20 @@
   "homepage": "https://github.com/Ismail-elkorchi/dir-archiver",
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "examples:run": "node ./examples/run-all.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "lint": "npm run typecheck && eslint . --max-warnings=0",
-    "test": "npm run build && node --test test/api-snapshot.test.mjs test/operations.test.mjs test/cli.test.mjs test/matrix-node.test.mjs",
+    "test": "npm run build && node --test test/api-snapshot.test.mjs test/operations.test.mjs test/cli.test.mjs test/cli-docs-drift.test.mjs test/matrix-node.test.mjs",
+    "check:fast": "npm run lint && npm run test && npm run examples:run",
     "test:security": "npm run build && node --test test/security.test.mjs",
-    "check": "node ./scripts/verify-runtime-versions.mjs && node ./scripts/workflow-policy-check.mjs && node ./scripts/esm-only-guard.mjs && node ./scripts/docs-policy-check.mjs && npm run lint && npm run test && npm run test:security && npm run test:runtimes",
+    "check": "node ./scripts/verify-runtime-versions.mjs && node ./scripts/workflow-policy-check.mjs && node ./scripts/esm-only-guard.mjs && node ./scripts/docs-policy-check.mjs && npm run lint && npm run test && npm run examples:run && npm run test:security && npm run test:runtimes",
+    "deps:fresh": "node ./scripts/direct-runtime-deps-freshness.mjs",
     "test:deno": "npm run build && deno run --allow-read --allow-write --allow-env --allow-sys test/deno-smoke.mjs",
     "test:bun": "npm run build && bun test/bun-smoke.mjs",
     "test:runtimes": "npm run test:deno && npm run test:bun && npm run test:runtimes:fingerprints",
     "test:runtimes:fingerprints": "npm run build && node ./scripts/compare-runtime-fingerprints.mjs",
     "jsr:score": "node ./scripts/jsr-score-gate.mjs",
+    "release:audit": "node ./scripts/release-audit.mjs",
     "test:downstream:released": "npm run test",
     "test:downstream:main": "npm install --no-save github:Ismail-elkorchi/bytefold#main github:Ismail-elkorchi/argv-flags#main && npm run test",
     "jsr:dry": "deno publish --dry-run --allow-dirty --sloppy-imports",
@@ -65,16 +76,16 @@
     "node": ">=24"
   },
   "dependencies": {
-    "@ismail-elkorchi/bytefold": "^0.7.2",
-    "argv-flags": "^1.0.3"
+    "@ismail-elkorchi/bytefold": "^0.8.1",
+    "argv-flags": "^1.0.4"
   },
   "devDependencies": {
-    "@eslint/js": "^9.39.2",
-    "@types/node": "^20.11.0",
-    "@typescript-eslint/eslint-plugin": "^8.54.0",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^25.3.2",
+    "@typescript-eslint/eslint-plugin": "^8.56.1",
     "@typescript-eslint/parser": "^8.54.0",
-    "eslint": "^9.39.2",
-    "globals": "^17.2.0",
+    "eslint": "^10.0.2",
+    "globals": "^17.3.0",
     "typescript": "^5.3.3",
     "yauzl": "^3.2.0"
   }