dir-archiver 3.0.1 → 3.0.2

package/CHANGELOG.md

@@ -4,6 +4,12 @@
 
 * 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.

package/README.md

@@ -1,6 +1,8 @@
 # dir-archiver
 
-Archive orchestration for detect/list/audit/extract/normalize/write flows across Node, Deno, and Bun.
+Deterministic directory archiving and extraction over zip, tar, and layered compression.
+
+Supports Node.js, Deno, and Bun.
 
 ## What it is
 
@@ -29,12 +31,6 @@ await extract("./project.zip", "./out", { profile: "strict" });
 console.log(detected.format);
 ```
 
-## Options reference
-
-- [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)
-
 ## When not to use
 
 - You only need a low-level parser for a single format.
@@ -51,19 +47,13 @@ console.log(detected.format);
 
 - Module system: ESM-only.
 - Runtimes: Node `>=24`, current Deno, current Bun.
-- CLI and API contracts are documented in `CONTRACT.md`.
+- CLI and API contracts are documented in [Contract](https://github.com/Ismail-elkorchi/dir-archiver/blob/main/CONTRACT.md).
 
-## Links
+## Documentation
 
 - [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)
+- [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)
 
 ## Verification
 

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;

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,7 +1,18 @@
-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;
 /**
@@ -13,56 +24,67 @@ export interface OpenOptions {
     /**
      * Explicit format override when callers already know archive type.
      */
-    format?: ArchiveOpenOptions['format'] | undefined;
+    format?: ArchiveFormat | 'auto' | undefined;
     /**
      * Safety profile (`compat`, `strict`, `agent`) applied during reads/audits.
      */
-    profile?: ArchiveOpenOptions['profile'] | undefined;
+    profile?: ArchiveProfile | undefined;
     /**
      * Extra strictness toggle forwarded to bytefold parsing.
      */
-    isStrict?: ArchiveOpenOptions['isStrict'] | undefined;
+    isStrict?: boolean | undefined;
     /**
      * Parser/resource limits enforced while opening or auditing archives.
      */
-    limits?: ArchiveOpenOptions['limits'] | undefined;
+    limits?: ArchiveLimits | undefined;
     /**
      * Abort signal for cancelling in-flight async operations.
      */
-    signal?: ArchiveOpenOptions['signal'] | undefined;
+    signal?: AbortSignal | undefined;
     /**
      * Password used for encrypted archives when supported by the runtime.
      */
-    password?: ArchiveOpenOptions['password'] | undefined;
+    password?: string | undefined;
     /**
      * Filename hint used for extension-based inference with non-path inputs.
      */
-    filename?: ArchiveOpenOptions['filename'] | undefined;
+    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[];
 }
 /**
@@ -76,13 +98,16 @@ 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;
 }
 /**
@@ -114,11 +139,17 @@ export interface ExtractOptions extends OpenOptions {
  * 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[];
 }
 /**
@@ -156,17 +187,24 @@ export interface WriteOptions {
  * 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;
@@ -176,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/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

@@ -10,7 +10,13 @@ into a filesystem or resource-exhaustion risk.
 - `npm run build`
 
 ## Copy/paste
-Recommended pattern (audit first, then extract with limits):
+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";
@@ -29,29 +35,20 @@ await extract(input, "./out", {
 });
 ```
 
-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`.
+## 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

@@ -1,7 +1,7 @@
 # How-to index
 
-Task guides:
+Pick the guide that matches the job:
 
-- [Create CI release artifacts](ci-release-artifact.md)
+- [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)
-- [Use in CI pipelines](ci-usage.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)

package/docs/index.md

@@ -2,22 +2,21 @@
 
 Use this map to pick the right doc quickly.
 
-## Start here
+## Tutorial
 - [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)
+## 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)
-- [Use in CI pipelines](how-to/ci-usage.md)
+- [How-to index](how-to/index.md)
 
 ## Reference
-- [Contract](../CONTRACT.md)
 - [CLI reference](reference/cli.md)
 - [Options reference](reference/options.md)
+- [Contract](reference/contract.md)
 - [Reference index](reference/index.md)
-- [Security policy](../SECURITY.md)
 
 ## Explanation
 - [Explanation index](explanation/index.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/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

@@ -4,4 +4,4 @@ Use this page as the canonical reference entrypoint.
 
 - [CLI reference](cli.md)
 - [Options reference](options.md)
-- [Contract](../../CONTRACT.md)
+- [Contract](contract.md)

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

@@ -10,18 +10,24 @@ development files.
 - `npm run build`
 
 ## Copy/paste
-CLI-style command:
-
 ```sh
-dir-archiver write \
-  --includebasedir \
-  --src . \
-  --dest ../bundle.zip \
-  --exclude .git \
+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 \
-  --exclude package.json \
   --json
+
+node dist/cli.js list --input "$tmpdir/bundle.zip" --json
+rm -rf "$tmpdir"
 ```
 
 Runnable example file:
@@ -32,11 +38,18 @@ 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.
+- `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

@@ -9,25 +9,44 @@ Write an archive, detect its format, and extract it with strict safety defaults.
 - `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);
+```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
-- `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.
+- `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,6 +1,6 @@
 {
   "name": "@ismail-elkorchi/dir-archiver",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "license": "MIT",
   "exports": {
     ".": "./src/index.ts"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dir-archiver",
-  "version": "3.0.1",
-  "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",
@@ -56,10 +56,15 @@
     "examples:run": "node ./examples/run-all.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "lint": "npm run typecheck && eslint . --max-warnings=0",
+    "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 test && npm run examples:run",
+    "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 examples:run && 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",
@@ -77,16 +82,16 @@
   },
   "dependencies": {
     "@ismail-elkorchi/bytefold": "^0.8.1",
-    "argv-flags": "^1.0.4"
+    "argv-flags": "^1.0.5"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@types/node": "^25.3.2",
-    "@typescript-eslint/eslint-plugin": "^8.56.1",
-    "@typescript-eslint/parser": "^8.54.0",
-    "eslint": "^10.0.2",
-    "globals": "^17.3.0",
-    "typescript": "^5.3.3",
-    "yauzl": "^3.2.0"
+    "@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"
   }
 }

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

@@ -1,32 +0,0 @@
-# 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

@@ -1,34 +0,0 @@
-# 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.