dir-archiver 3.0.0 → 3.0.2

package/docs/index.md

@@ -0,0 +1,23 @@
+# Documentation
+
+Use this map to pick the right doc quickly.
+
+## Tutorial
+- [Tutorial: bundle a plugin directory](tutorial/bundle-a-plugin.md)
+- [Tutorial: first archive flow](tutorial/first-archive-flow.md)
+
+## How-to
+- [Use CLI JSON output and exit codes](how-to/cli-json-and-exit-codes.md)
+- [Troubleshoot common failures](how-to/troubleshoot-common-failures.md)
+- [Extract untrusted archives safely](how-to/extract-untrusted.md)
+- [How-to index](how-to/index.md)
+
+## Reference
+- [CLI reference](reference/cli.md)
+- [Options reference](reference/options.md)
+- [Contract](reference/contract.md)
+- [Reference index](reference/index.md)
+
+## Explanation
+- [Explanation index](explanation/index.md)
+- [Profile behavior and tradeoffs](explanation/profiles.md)

package/docs/maintainers/ci-release-artifact.md

@@ -0,0 +1,39 @@
+# Maintainer 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
+node dist/cli.js write --source ./dist --output ./release.zip --include-base-directory --json
+node dist/cli.js 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`.
+
+## Common failure modes
+- `--json` is omitted, so CI jobs have to scrape human-readable output.
+- The destination extension does not match the intended format, so inference
+  chooses the wrong archive type.
+- `--include-base-directory` is skipped and extracted files do not land under a
+  stable root folder.
+
+## Related reference
+- [CLI reference](../reference/cli.md)
+- [Options reference](../reference/options.md)
+- [Contract](../reference/contract.md)

package/docs/maintainers/ci-usage.md

@@ -0,0 +1,41 @@
+# Maintainer 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
+node dist/cli.js normalize \
+  --input ./incoming.zip \
+  --output ./normalized.zip \
+  --profile strict \
+  --json
+```
+
+Audit gate:
+
+```sh
+node dist/cli.js 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.
+
+## Common failure modes
+- Exit code `2` is treated like an archive-safety failure instead of a CLI
+  usage mistake.
+- Pipelines skip `audit` and extract or normalize untrusted input blindly.
+- Jobs do not persist the JSON output, so later stages cannot inspect the exact
+  audit or normalize report.
+
+## Related reference
+- [CLI reference](../reference/cli.md)
+- [Options reference](../reference/options.md)
+- [Contract](../reference/contract.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/contract.md

@@ -0,0 +1,13 @@
+# Contract
+
+Goal: point API and CLI users to the stable behavior contract that backs the public surface.
+
+The full contract lives at the repo root so it can ship with npm and JSR artifacts alongside the package entrypoints.
+
+Use the root contract for:
+- CLI JSON output shape expectations
+- exit-code meanings
+- stability expectations for named commands and result payloads
+
+Primary contract:
+- [CONTRACT.md](../../CONTRACT.md)

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,55 @@
+# 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
+```sh
+tmpdir="$(mktemp -d)"
+mkdir -p "$tmpdir/plugin/src" "$tmpdir/plugin/node_modules/demo"
+printf 'export const pluginName = \"demo\";\n' > "$tmpdir/plugin/src/index.js"
+printf '{\"name\":\"demo\"}\n' > "$tmpdir/plugin/package.json"
+printf 'ignore me\n' > "$tmpdir/plugin/package-lock.json"
+printf 'ignore me\n' > "$tmpdir/plugin/node_modules/demo/index.js"
+
+node dist/cli.js write \
+  --source "$tmpdir/plugin" \
+  --output "$tmpdir/bundle.zip" \
+  --include-base-directory \
+  --exclude node_modules \
+  --exclude package-lock.json \
+  --json
+
+node dist/cli.js list --input "$tmpdir/bundle.zip" --json
+rm -rf "$tmpdir"
+```
+
+Runnable example file:
+
+```sh
+node examples/bundle-a-plugin.mjs
+```
+
+## What you should see
+- A ZIP file is created.
+- `write` reports `format: "zip"` and a stable `entryCount`.
+- `list` shows entries rooted under the plugin directory and does not include
+  `node_modules` or `package-lock.json`.
+
+## Common failure modes
+- The output extension is missing, so format inference falls back to the wrong
+  archive type.
+- `includeBaseDirectory` is omitted and extracted files scatter directly into
+  the destination root.
+- Exclude patterns miss local build artifacts, which leaks development files
+  into the distributable archive.
+
+## Related reference
+- [CLI reference](../reference/cli.md)
+- [Options reference](../reference/options.md)

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

@@ -0,0 +1,52 @@
+# 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
+```sh
+tmpdir="$(mktemp -d)"
+mkdir -p "$tmpdir/project"
+printf 'hello from tutorial\n' > "$tmpdir/project/hello.txt"
+
+node dist/cli.js write \
+  --source "$tmpdir/project" \
+  --output "$tmpdir/project.zip" \
+  --include-base-directory \
+  --json
+
+node dist/cli.js detect --input "$tmpdir/project.zip" --json
+
+node dist/cli.js extract \
+  --input "$tmpdir/project.zip" \
+  --output "$tmpdir/out" \
+  --profile strict \
+  --json
+
+find "$tmpdir/out" -maxdepth 3 -type f | sort
+rm -rf "$tmpdir"
+```
+
+## What you should see
+- `write` reports `format: "zip"` and `wrappedDirectoryCodec: false`.
+- `detect` reports `format: "zip"` plus a `detection` object.
+- `extract` reports at least one extracted file and one extracted directory.
+- `find` prints a path ending in `/project/hello.txt`.
+
+## Common failure modes
+- `--include-base-directory` is omitted and the extracted files land directly
+  in the destination root.
+- The output archive extension is missing or mismatched, so format inference is
+  not what you expected.
+- Extraction is run with `compat` on untrusted input, which weakens path and
+  entry checks.
+
+## Related reference
+- [CLI reference](../reference/cli.md)
+- [Options reference](../reference/options.md)
+- [Contract](../../CONTRACT.md)

package/jsr.json

@@ -1,21 +1,26 @@
 {
   "name": "@ismail-elkorchi/dir-archiver",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "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,7 +1,7 @@
 {
   "name": "dir-archiver",
-  "version": "3.0.0",
-  "description": "Bytefold-backed archive orchestration for directories/files across Node.js, Deno, and Bun.",
+  "version": "3.0.2",
+  "description": "Deterministic directory archiving and extraction over zip, tar, and layered compression.",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",
@@ -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,25 @@
   "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",
+    "docs:lint:jsr": "deno doc --lint --sloppy-imports src/index.ts",
+    "docs:test:jsr": "node ./scripts/jsr-docs-quality.mjs",
+    "docs:quality:jsr": "npm run docs:lint:jsr && npm run docs:test:jsr",
+    "release:notes:dry-run": "node ./scripts/release-notes.mjs --dry-run",
+    "changelog:update:dry-run": "node ./scripts/changelog-update.mjs --dry-run",
+    "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 docs:quality:jsr && 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 docs:quality:jsr && 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,17 +81,17 @@
     "node": ">=24"
   },
   "dependencies": {
-    "@ismail-elkorchi/bytefold": "^0.7.2",
-    "argv-flags": "^1.0.3"
+    "@ismail-elkorchi/bytefold": "^0.8.1",
+    "argv-flags": "^1.0.5"
   },
   "devDependencies": {
-    "@eslint/js": "^9.39.2",
-    "@types/node": "^20.11.0",
-    "@typescript-eslint/eslint-plugin": "^8.54.0",
-    "@typescript-eslint/parser": "^8.54.0",
-    "eslint": "^9.39.2",
-    "globals": "^17.2.0",
-    "typescript": "^5.3.3",
-    "yauzl": "^3.2.0"
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^25.9.3",
+    "@typescript-eslint/eslint-plugin": "^8.61.1",
+    "@typescript-eslint/parser": "^8.61.1",
+    "eslint": "^10.5.0",
+    "globals": "^17.6.0",
+    "typescript": "^6.0.3",
+    "yauzl": "^3.4.0"
   }
 }