dir-archiver 3.0.0 → 3.0.2

package/dist/errors.d.ts

@@ -1,25 +1,69 @@
 /**
- * Stable dir-archiver error codes.
+ * Stable machine-readable error codes emitted by `dir-archiver`.
+ *
+ * - `DIRARCHIVER_INVALID_SOURCE`: input bytes or paths could not be read.
+ * - `DIRARCHIVER_INVALID_DESTINATION`: destination path or parent directory is
+ * invalid for the requested operation.
+ * - `DIRARCHIVER_PATH_TRAVERSAL`: strict extraction rejected a traversal or
+ * absolute-path entry.
+ * - `DIRARCHIVER_UNSUPPORTED_ENTRY`: the archive contains an entry type or
+ * feature that `dir-archiver` does not support safely.
+ * - `DIRARCHIVER_RESOURCE_LIMIT`: extraction exceeded configured byte limits.
+ * - `DIRARCHIVER_RUNTIME_UNSUPPORTED`: the current runtime cannot satisfy a
+ * required bytefold capability.
+ * - `DIRARCHIVER_NORMALIZE_UNSUPPORTED`: normalization is unavailable for the
+ * selected format/runtime pair.
+ * - `DIRARCHIVER_USAGE`: CLI invocation is missing required flags or uses
+ * unsupported values.
  */
 export type DirArchiverErrorCode = 'DIRARCHIVER_INVALID_SOURCE' | 'DIRARCHIVER_INVALID_DESTINATION' | 'DIRARCHIVER_PATH_TRAVERSAL' | 'DIRARCHIVER_UNSUPPORTED_ENTRY' | 'DIRARCHIVER_RESOURCE_LIMIT' | 'DIRARCHIVER_RUNTIME_UNSUPPORTED' | 'DIRARCHIVER_NORMALIZE_UNSUPPORTED' | 'DIRARCHIVER_USAGE';
+/**
+ * Stable JSON payload emitted by `DirArchiverError.toJSON()`.
+ *
+ * This is the machine-readable error shape used by the CLI `--json` surface and
+ * by API consumers that persist `DirArchiverError` objects to logs or reports.
+ */
+export interface DirArchiverErrorJson {
+    /** Schema version for the serialized error payload. */
+    schemaVersion: '1';
+    /** Stable error class name used in serialized output. */
+    name: 'DirArchiverError';
+    /** Stable machine-readable error code. */
+    code: DirArchiverErrorCode;
+    /** Human-readable summary of the failure. */
+    message: string;
+    /** Optional remediation hint when the error carries one. */
+    hint?: string;
+    /** Optional structured context for logs and diagnostics. */
+    context?: Record<string, unknown>;
+}
 /**
  * Structured error contract for dir-archiver v3.
  */
 export declare class DirArchiverError extends Error {
+    /** Stable machine-readable error code. */
     readonly code: DirArchiverErrorCode;
+    /** Optional operator-facing hint for remediation. */
     readonly hint: string | undefined;
+    /** Optional structured context for logs, JSON output, or diagnostics. */
     readonly context: Record<string, unknown> | undefined;
+    /**
+     * Creates a structured error value safe for CLI and API consumers.
+     *
+     * @param code Stable machine-readable error code.
+     * @param message Human-readable summary of the failure.
+     * @param options Optional hint, structured context, and nested cause.
+     */
     constructor(code: DirArchiverErrorCode, message: string, options?: {
         hint?: string | undefined;
         context?: Record<string, unknown> | undefined;
         cause?: unknown;
     });
-    toJSON(): {
-        schemaVersion: '1';
-        name: 'DirArchiverError';
-        code: DirArchiverErrorCode;
-        message: string;
-        hint?: string;
-        context?: Record<string, unknown>;
-    };
+    /**
+     * Serializes the error into the stable JSON shape used by the CLI.
+     *
+     * The returned object always includes `schemaVersion`, `name`, `code`, and
+     * `message`. Optional `hint` and `context` keys are omitted when unset.
+     */
+    toJSON(): DirArchiverErrorJson;
 }

package/dist/errors.js

@@ -2,6 +2,13 @@
  * Structured error contract for dir-archiver v3.
  */
 export class DirArchiverError extends Error {
+    /**
+     * Creates a structured error value safe for CLI and API consumers.
+     *
+     * @param code Stable machine-readable error code.
+     * @param message Human-readable summary of the failure.
+     * @param options Optional hint, structured context, and nested cause.
+     */
     constructor(code, message, options = {}) {
         super(message);
         this.name = 'DirArchiverError';
@@ -12,6 +19,12 @@ export class DirArchiverError extends Error {
             this.cause = options.cause;
         }
     }
+    /**
+     * Serializes the error into the stable JSON shape used by the CLI.
+     *
+     * The returned object always includes `schemaVersion`, `name`, `code`, and
+     * `message`. Optional `hint` and `context` keys are omitted when unset.
+     */
     toJSON() {
         return {
             schemaVersion: '1',

package/dist/index.d.ts

@@ -1,19 +1,40 @@
 /**
- * dir-archiver v3 API surface.
+ * Deterministic directory archiving and extraction over zip, tar, and layered compression.
  *
- * v3 is a bytefold-backed orchestration layer that supports Node.js, Deno, and Bun.
+ * Supports Node.js, Deno, and Bun through one API surface backed by bytefold.
  */
 import { audit, detect, extract, list, normalize, open, write } from './core.js';
 export { audit, detect, extract, list, normalize, open, write };
 export { DirArchiverError } from './errors.js';
-export type { ArchiveFormat, ArchiveLimits, ArchiveProfile, CliUsageError, DetectResult, DirArchiverInput, ExtractOptions, ExtractResult, ListEntry, ListResult, NormalizeOptions, NormalizeResult, OpenOptions, SupportedCommandMap, WriteOptions, WriteResult } from './types.js';
-declare const api: {
-    open: (input: import("./types.js").DirArchiverInput, options?: import("./types.js").OpenOptions) => Promise<import("@ismail-elkorchi/bytefold").ArchiveReader>;
-    detect: (input: import("./types.js").DirArchiverInput, options?: import("./types.js").OpenOptions) => Promise<import("./types.js").DetectResult>;
-    list: (input: import("./types.js").DirArchiverInput, options?: import("./types.js").OpenOptions) => Promise<import("./types.js").ListResult>;
-    audit: (input: import("./types.js").DirArchiverInput, options?: import("./types.js").OpenOptions) => Promise<import("@ismail-elkorchi/bytefold").ArchiveAuditReport>;
-    normalize: (input: import("./types.js").DirArchiverInput, destination: string, options?: import("./types.js").NormalizeOptions) => Promise<import("./types.js").NormalizeResult>;
-    extract: (input: import("./types.js").DirArchiverInput, destination: string, options?: import("./types.js").ExtractOptions) => Promise<import("./types.js").ExtractResult>;
-    write: (source: string, destination: string, options?: import("./types.js").WriteOptions) => Promise<import("./types.js").WriteResult>;
-};
+export type { DirArchiverErrorCode, DirArchiverErrorJson } from './errors.js';
+export type { ArchiveFormat, ArchiveLimits, ArchiveDetectionReport, ArchiveIssue, ArchiveNormalizeReport, ArchiveProfile, CliUsageError, DetectResult, DirArchiverInput, ExtractOptions, ExtractResult, ListEntry, ListResult, NormalizeOptions, NormalizeResult, OpenOptions, SupportedCommandMap, WriteOptions, WriteResult } from './types.js';
+/**
+ * Namespace-style API contract mirrored by the default export.
+ *
+ * Consumers who prefer `import dirArchiver from "dir-archiver"` get the same
+ * operations and semantics as the named exports on this interface.
+ */
+export interface DirArchiverNamespace {
+    /** Open an archive reader after resolving format, limits, and runtime support. */
+    readonly open: typeof open;
+    /** Detect an archive format without extracting entries. */
+    readonly detect: typeof detect;
+    /** Project archive entries into a stable listing payload. */
+    readonly list: typeof list;
+    /** Audit an archive against the requested safety profile and limits. */
+    readonly audit: typeof audit;
+    /** Rewrite an archive into its normalized deterministic representation. */
+    readonly normalize: typeof normalize;
+    /** Extract an archive to disk with explicit safety and size controls. */
+    readonly extract: typeof extract;
+    /** Write a directory or file tree into an archive. */
+    readonly write: typeof write;
+}
+/**
+ * Namespace-style default export for consumers who prefer
+ * `import dirArchiver from "dir-archiver"`.
+ *
+ * It mirrors the named exports exactly and does not add extra behavior.
+ */
+declare const api: DirArchiverNamespace;
 export default api;

package/dist/index.js

@@ -1,11 +1,17 @@
 /**
- * dir-archiver v3 API surface.
+ * Deterministic directory archiving and extraction over zip, tar, and layered compression.
  *
- * v3 is a bytefold-backed orchestration layer that supports Node.js, Deno, and Bun.
+ * Supports Node.js, Deno, and Bun through one API surface backed by bytefold.
  */
 import { audit, detect, extract, list, normalize, open, write } from './core.js';
 export { audit, detect, extract, list, normalize, open, write };
 export { DirArchiverError } from './errors.js';
+/**
+ * Namespace-style default export for consumers who prefer
+ * `import dirArchiver from "dir-archiver"`.
+ *
+ * It mirrors the named exports exactly and does not add extra behavior.
+ */
 const api = {
     open,
     detect,

package/dist/types.d.ts

@@ -1,107 +1,210 @@
-import type { ArchiveDetectionReport, ArchiveFormat, ArchiveIssue, ArchiveLimits, ArchiveNormalizeReport, ArchiveOpenOptions, ArchiveProfile } from '@ismail-elkorchi/bytefold';
-export type { ArchiveFormat, ArchiveLimits, ArchiveProfile };
+import type { ArchiveFormat, ArchiveProfile } from '@ismail-elkorchi/bytefold';
+export type { ArchiveFormat, ArchiveProfile, } from '@ismail-elkorchi/bytefold';
+/** Resource limit configuration accepted by `open`, `audit`, and extraction flows. */
+export type ArchiveLimits = Record<string, unknown>;
+/** Issue shape emitted for archive read/normalize/extract failures. */
+export type ArchiveIssue = Record<string, unknown>;
+/** Public detection report shape aligned with runtime diagnostics payloads. */
+export type ArchiveDetectionReport = Record<string, unknown>;
+/** Public normalize report shape for deterministic archive rewrites. */
+export type ArchiveNormalizeReport = Record<string, unknown>;
 /**
  * Accepted input shapes for archive read operations.
+ *
+ * String paths and `URL` objects are the most common inputs, but callers can
+ * also supply raw bytes or web streams when the archive is already in memory.
  */
 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 {
-    format?: ArchiveOpenOptions['format'] | undefined;
-    profile?: ArchiveOpenOptions['profile'] | undefined;
-    isStrict?: ArchiveOpenOptions['isStrict'] | undefined;
-    limits?: ArchiveOpenOptions['limits'] | undefined;
-    signal?: ArchiveOpenOptions['signal'] | undefined;
-    password?: ArchiveOpenOptions['password'] | undefined;
-    filename?: ArchiveOpenOptions['filename'] | undefined;
+    /**
+     * Explicit format override when callers already know archive type.
+     */
+    format?: ArchiveFormat | 'auto' | undefined;
+    /**
+     * Safety profile (`compat`, `strict`, `agent`) applied during reads/audits.
+     */
+    profile?: ArchiveProfile | undefined;
+    /**
+     * Extra strictness toggle forwarded to bytefold parsing.
+     */
+    isStrict?: boolean | undefined;
+    /**
+     * Parser/resource limits enforced while opening or auditing archives.
+     */
+    limits?: ArchiveLimits | undefined;
+    /**
+     * Abort signal for cancelling in-flight async operations.
+     */
+    signal?: AbortSignal | undefined;
+    /**
+     * Password used for encrypted archives when supported by the runtime.
+     */
+    password?: string | undefined;
+    /**
+     * Filename hint used for extension-based inference with non-path inputs.
+     */
+    filename?: string | undefined;
 }
 /**
  * Format detection result.
  */
 export interface DetectResult {
+    /** Resolved archive format after detection. */
     format: ArchiveFormat;
+    /** Bytefold detection metadata, if the runtime produced it. */
     detection: ArchiveDetectionReport | undefined;
 }
 /**
  * Single archive entry projection used by list responses.
  */
 export interface ListEntry {
+    /** Entry format as exposed by the underlying reader. */
     format: ArchiveFormat;
+    /** Entry path inside the archive, normalized to forward slashes. */
     name: string;
+    /** Entry size encoded as a string for JSON-safe transport. */
     size: string;
+    /** Whether the entry materializes as a directory. */
     isDirectory: boolean;
+    /** Whether the entry is a symbolic link. */
     isSymlink: boolean;
+    /** Link target when the entry is a symbolic link. */
     linkName?: string | undefined;
 }
 /**
  * Archive listing response payload.
  */
 export interface ListResult {
+    /** Resolved archive format after detection/open completed. */
     format: ArchiveFormat;
+    /** Bytefold detection metadata used to choose `format`, when available. */
     detection: ArchiveDetectionReport | undefined;
+    /** Projected archive entries in archive iteration order. */
     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.
  */
 export interface NormalizeOptions extends OpenOptions {
+    /** Request deterministic normalization when the runtime supports the knob. */
     deterministic?: boolean | undefined;
 }
 /**
  * Normalize operation result payload.
  */
 export interface NormalizeResult {
+    /** Source archive format that was normalized. */
     format: ArchiveFormat;
+    /** Detailed normalization report from bytefold. */
     report: ArchiveNormalizeReport;
 }
 /**
  * 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;
 }
 /**
  * Extraction summary result.
  */
 export interface ExtractResult {
+    /** Source archive format that was extracted to disk. */
     format: ArchiveFormat;
+    /** Absolute destination directory path used for extraction. */
     destination: string;
+    /** Number of file entries written to disk. */
     extractedFiles: number;
+    /** Number of directory entries created on disk. */
     extractedDirectories: number;
+    /** Number of entries skipped due to policy, such as disallowed symlinks. */
     skippedEntries: number;
+    /** Audit issues collected before or during extraction. */
     issues: ArchiveIssue[];
 }
 /**
  * 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;
 }
 /**
  * Archive writer result payload.
  */
 export interface WriteResult {
+    /** Archive format emitted to the destination path. */
     format: ArchiveFormat;
+    /** Absolute source path that was archived. */
     source: string;
+    /** Absolute destination archive path that was written. */
     destination: string;
+    /** Number of archive entries written to the output archive. */
     entryCount: number;
+    /** Whether a directory source was wrapped in a tar-based single-file codec. */
     wrappedDirectoryCodec: boolean;
 }
 /**
  * Usage-error shape emitted by CLI parsing.
  */
 export interface CliUsageError {
+    /** Human-readable summary of the CLI validation failure. */
     message: string;
+    /** Individual issues returned by the command-line parser. */
     issues: readonly {
         code: string;
         message: string;
@@ -111,11 +214,18 @@ export interface CliUsageError {
  * Canonical command identifiers supported by the CLI contract.
  */
 export interface SupportedCommandMap {
+    /** Literal identifier for the `open` command. */
     open: 'open';
+    /** Literal identifier for the `detect` command. */
     detect: 'detect';
+    /** Literal identifier for the `list` command. */
     list: 'list';
+    /** Literal identifier for the `audit` command. */
     audit: 'audit';
+    /** Literal identifier for the `extract` command. */
     extract: 'extract';
+    /** Literal identifier for the `normalize` command. */
     normalize: 'normalize';
+    /** Literal identifier for the `write` command. */
     write: 'write';
 }

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/cli-json-and-exit-codes.md

@@ -0,0 +1,78 @@
+# How-to: use CLI JSON output and exit codes
+
+## Goal
+Drive `dir-archiver` from automation without scraping human-readable command
+output.
+
+## Prereqs
+- Node `>=24`
+- `npm install`
+- `npm run build`
+
+## Copy/paste
+```sh
+tmpdir="$(mktemp -d)"
+mkdir -p "$tmpdir/src"
+printf 'hello from dir-archiver\n' > "$tmpdir/src/hello.txt"
+
+node dist/cli.js write --source "$tmpdir/src" --output "$tmpdir/archive.zip" --json
+node dist/cli.js detect --input "$tmpdir/archive.zip" --json
+
+set +e
+node dist/cli.js extract --json
+usage_exit=$?
+set -e
+
+printf 'usage_exit=%s\n' "$usage_exit"
+rm -rf "$tmpdir"
+```
+
+## What you should see
+- `write` emits JSON on stdout with fields shaped like:
+
+```json
+{
+  "format": "zip",
+  "source": "/tmp/.../src",
+  "destination": "/tmp/.../archive.zip",
+  "entryCount": 1,
+  "wrappedDirectoryCodec": false
+}
+```
+
+- `detect` emits JSON on stdout with `format` plus a `detection` object.
+- The invalid `extract --json` invocation emits a usage payload on stdout shaped
+  like:
+
+```json
+{
+  "schemaVersion": "1",
+  "code": "DIRARCHIVER_USAGE",
+  "message": "Invalid CLI arguments.",
+  "issues": [
+    { "code": "REQUIRED", "message": "extract requires --input." },
+    { "code": "REQUIRED", "message": "extract requires --output." }
+  ]
+}
+```
+
+- `usage_exit=2` confirms the usage-error exit code.
+
+## Exit codes
+
+| Exit code | Meaning | Where to read details |
+| --- | --- | --- |
+| `0` | Command completed successfully. | stdout (`--json`) or normal console output |
+| `1` | Runtime failure or archive-policy failure. | stderr |
+| `2` | CLI usage or validation failure. | stdout with `--json`, stderr otherwise |
+
+## Common failure modes
+- Scripts scrape prose output instead of passing `--json`.
+- Exit codes `1` and `2` are collapsed into one generic failure bucket.
+- stdout and stderr are merged, which corrupts JSON parsing.
+- Commands are run before `npm run build`, so `dist/cli.js` is missing.
+
+## Related reference
+- [CLI reference](../reference/cli.md)
+- [Options reference](../reference/options.md)
+- [Contract](../../CONTRACT.md)

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

@@ -0,0 +1,54 @@
+# 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
+Runnable example file:
+
+```sh
+node examples/extract-untrusted.mjs
+```
+
+Equivalent API 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,
+});
+```
+
+## What you should see
+- The audit step succeeds before extraction starts.
+- The example intentionally sets a low extraction limit and reports
+  `DIRARCHIVER_RESOURCE_LIMIT`.
+
+## Common failure modes
+- `profile: "compat"` is used for hostile input, which weakens pre-extract
+  safety checks.
+- Limits are left unset, so decompression amplification can consume far more
+  disk than expected.
+- Callers treat file creation as success instead of checking the returned issues
+  and skipped-entry counts.
+
+## Related reference
+- [CLI reference](../reference/cli.md)
+- [Options reference](../reference/options.md)
+- [Contract](../../CONTRACT.md)

package/docs/how-to/index.md

@@ -0,0 +1,7 @@
+# How-to index
+
+Pick the guide that matches the job:
+
+- [Use CLI JSON output and exit codes](cli-json-and-exit-codes.md)
+- [Troubleshoot common failures](troubleshoot-common-failures.md)
+- [Extract untrusted archives safely](extract-untrusted.md)

package/docs/how-to/troubleshoot-common-failures.md

@@ -0,0 +1,78 @@
+# How-to: troubleshoot common failures
+
+## Goal
+Map common `dir-archiver` failures to the likely option or input problem
+without guessing from raw shell output.
+
+## Prereqs
+- Node `>=24`
+- `npm install`
+- `npm run build`
+
+## Copy/paste
+```sh
+tmpdir="$(mktemp -d)"
+mkdir -p "$tmpdir/src"
+printf 'hello world\n' > "$tmpdir/src/hello.txt"
+node dist/cli.js write --source "$tmpdir/src" --output "$tmpdir/archive.zip" --json >/dev/null
+
+set +e
+node dist/cli.js extract \
+  --input "$tmpdir/archive.zip" \
+  --output "$tmpdir/out" \
+  --max-entry-bytes 4 \
+  --json
+runtime_exit=$?
+
+node dist/cli.js extract --json
+usage_exit=$?
+set -e
+
+printf 'runtime_exit=%s\n' "$runtime_exit"
+printf 'usage_exit=%s\n' "$usage_exit"
+
+node dist/cli.js detect --input "$tmpdir/archive.zip" --json
+node dist/cli.js list --input "$tmpdir/archive.zip" --json
+rm -rf "$tmpdir"
+```
+
+## What you should see
+- The first `extract` fails with a `DirArchiverError` JSON payload on stderr
+  shaped like:
+
+```json
+{
+  "schemaVersion": "1",
+  "name": "DirArchiverError",
+  "code": "DIRARCHIVER_RESOURCE_LIMIT",
+  "message": "..."
+}
+```
+
+- `runtime_exit=1` confirms a runtime/archive-policy failure.
+- The second `extract --json` emits a `DIRARCHIVER_USAGE` payload on stdout and
+  `usage_exit=2`.
+- `detect` and `list` still succeed. Use them to inspect the archive before
+  trying a different `extract` policy or limit.
+
+## Quick diagnosis table
+
+| Symptom | Likely cause | First fix |
+| --- | --- | --- |
+| Exit `2` with `DIRARCHIVER_USAGE` | Missing or invalid command flags | Compare the command to the [CLI reference](../reference/cli.md). |
+| Exit `1` with `DIRARCHIVER_RESOURCE_LIMIT` | `maxEntryBytes` or `maxTotalExtractedBytes` is lower than the archive requires | Raise the limit or audit first to size the archive. |
+| Exit `1` with `DIRARCHIVER_PATH_TRAVERSAL` or `DIRARCHIVER_UNSUPPORTED_ENTRY` | Strict/agent safety checks rejected an entry path or link | Run `audit` or `list` first and keep `compat` only for trusted input. |
+| Raw `ENOENT` or a missing-path stack trace | The input or output path is wrong for the current working directory | Re-run with absolute paths or verify the file exists. |
+
+## Common failure modes
+- Missing input files or missing output directories.
+- Unsupported archive formats or encrypted inputs without the required
+  password/support.
+- Strict extraction rejecting traversal-style or link-based entries.
+- Treating an exit code alone as the diagnosis instead of reading the JSON
+  error `code`.
+
+## Related reference
+- [CLI reference](../reference/cli.md)
+- [Options reference](../reference/options.md)
+- [Contract](../../CONTRACT.md)