dir-archiver 2.2.0 → 3.0.1

package/dist/index.js

@@ -1,320 +1,18 @@
-'use strict';
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
+/**
+ * dir-archiver v3 API surface.
+ *
+ * v3 is a bytefold-backed orchestration layer that supports Node.js, Deno, and Bun.
+ */
+import { audit, detect, extract, list, normalize, open, write } from './core.js';
+export { audit, detect, extract, list, normalize, open, write };
+export { DirArchiverError } from './errors.js';
+const api = {
+    open,
+    detect,
+    list,
+    audit,
+    normalize,
+    extract,
+    write
 };
-const path = __importStar(require("path"));
-const fs = __importStar(require("fs"));
-const archiver_1 = __importDefault(require("archiver"));
-class DirArchiver {
-    /**
-     * The constructor.
-     * @param directoryPath - the path of the folder to archive.
-     * @param zipPath - The path of the zip file to create.
-     * @param includeBaseDirectory - Includes a base directory at the root of the archive. For example, if the root folder of your project is named "your-project", setting includeBaseDirectory to true will create an archive that includes this base directory. If this option is set to false the archive created will unzip its content to the current directory.
-     * @param excludes - The name of the files and foldes to exclude.
-     */
-    constructor(directoryPath, zipPath, includeBaseDirectory = false, excludes = [], followSymlinks = false) {
-        this.directoryPath = path.resolve(directoryPath);
-        this.zipPath = path.resolve(zipPath);
-        this.includeBaseDirectory = includeBaseDirectory;
-        this.followSymlinks = followSymlinks;
-        this.baseDirectory = path.basename(this.directoryPath);
-        this.visitedDirectories = new Set();
-        this.caseInsensitiveExcludes = process.platform === 'win32';
-        // Contains the excluded files and folders.
-        this.excludedPaths = new Set();
-        this.excludedNames = new Set();
-        for (const excludeRaw of excludes) {
-            if (typeof excludeRaw !== 'string') {
-                continue;
-            }
-            const trimmedRaw = excludeRaw.trim();
-            if (trimmedRaw.length === 0) {
-                continue;
-            }
-            let normalizedExclude = path.normalize(trimmedRaw.replace(/\\/g, path.sep));
-            if (normalizedExclude === '.' || normalizedExclude === path.sep) {
-                continue;
-            }
-            if (path.isAbsolute(normalizedExclude)) {
-                const relativeCandidate = path.relative(this.directoryPath, normalizedExclude);
-                const isInsideSource = relativeCandidate.length > 0
-                    && !relativeCandidate.startsWith('..')
-                    && !path.isAbsolute(relativeCandidate);
-                if (isInsideSource) {
-                    normalizedExclude = path.normalize(relativeCandidate);
-                }
-            }
-            if (normalizedExclude.length === 0) {
-                continue;
-            }
-            const hasSeparator = normalizedExclude.includes('/')
-                || normalizedExclude.includes('\\')
-                || normalizedExclude.includes(path.sep);
-            const trimmedExclude = normalizedExclude.replace(/[\\/]+$/g, '');
-            if (trimmedExclude.length === 0 || trimmedExclude === '.') {
-                continue;
-            }
-            const normalizedValue = this.normalizeExcludeValue(trimmedExclude);
-            this.excludedPaths.add(normalizedValue);
-            if (!hasSeparator) {
-                this.excludedNames.add(normalizedValue);
-            }
-        }
-        const relativeZipPath = path.relative(this.directoryPath, this.zipPath);
-        const isZipInsideSource = relativeZipPath.length > 0
-            && !relativeZipPath.startsWith('..')
-            && !path.isAbsolute(relativeZipPath);
-        if (isZipInsideSource) {
-            const normalizedZipPath = path.normalize(relativeZipPath);
-            this.excludedPaths.add(this.normalizeExcludeValue(normalizedZipPath));
-        }
-    }
-    /**
-     * Recursively traverse the directory tree and append the files to the archive.
-     * @param directoryPath - The path of the directory being looped through.
-     */
-    traverseDirectoryTree(directoryPath, archive) {
-        const directoriesToVisit = [directoryPath];
-        while (directoriesToVisit.length > 0) {
-            const nextDirectory = directoriesToVisit.pop();
-            if (!nextDirectory) {
-                continue;
-            }
-            if (this.followSymlinks) {
-                try {
-                    const realPath = fs.realpathSync(nextDirectory);
-                    if (this.visitedDirectories.has(realPath)) {
-                        continue;
-                    }
-                    this.visitedDirectories.add(realPath);
-                }
-                catch {
-                    continue;
-                }
-            }
-            const resolvedDirectoryPath = path.resolve(nextDirectory);
-            const entries = fs.readdirSync(resolvedDirectoryPath, { withFileTypes: true });
-            entries.sort((firstEntry, secondEntry) => {
-                if (firstEntry.name < secondEntry.name) {
-                    return -1;
-                }
-                if (firstEntry.name > secondEntry.name) {
-                    return 1;
-                }
-                return 0;
-            });
-            for (const entry of entries) {
-                const currentPath = path.join(resolvedDirectoryPath, entry.name);
-                if (currentPath === this.zipPath) {
-                    continue;
-                }
-                const relativePath = path.relative(this.directoryPath, currentPath);
-                const normalizedRelativePath = path.normalize(relativePath);
-                const archiveRelativePath = normalizedRelativePath.replace(/\\/g, '/');
-                const baseName = path.basename(normalizedRelativePath);
-                const normalizedPathValue = this.normalizeExcludeValue(normalizedRelativePath);
-                const normalizedNameValue = this.normalizeExcludeValue(baseName);
-                if (this.excludedPaths.has(normalizedPathValue) || this.excludedNames.has(normalizedNameValue)) {
-                    continue;
-                }
-                if (entry.isFile()) {
-                    if (this.includeBaseDirectory) {
-                        archive.file(currentPath, {
-                            name: path.posix.join(this.baseDirectory, archiveRelativePath)
-                        });
-                    }
-                    else {
-                        archive.file(currentPath, {
-                            name: archiveRelativePath
-                        });
-                    }
-                }
-                else if (entry.isDirectory()) {
-                    directoriesToVisit.push(currentPath);
-                }
-                else if (entry.isSymbolicLink()) {
-                    if (!this.followSymlinks) {
-                        continue;
-                    }
-                    let stats;
-                    try {
-                        stats = fs.statSync(currentPath);
-                    }
-                    catch {
-                        continue;
-                    }
-                    if (stats.isFile()) {
-                        if (this.includeBaseDirectory) {
-                            archive.file(currentPath, {
-                                name: path.posix.join(this.baseDirectory, archiveRelativePath)
-                            });
-                        }
-                        else {
-                            archive.file(currentPath, {
-                                name: archiveRelativePath
-                            });
-                        }
-                    }
-                    else if (stats.isDirectory()) {
-                        directoriesToVisit.push(currentPath);
-                    }
-                }
-            }
-        }
-    }
-    prettyBytes(bytes) {
-        if (bytes > 1000 && bytes < 1000000) {
-            const kiloBytes = Math.round(((bytes / 1000) + Number.EPSILON) * 100) / 100;
-            return `${kiloBytes} KB`;
-        }
-        if (bytes > 1000000 && bytes < 1000000000) {
-            const megaBytes = Math.round(((bytes / 1000000) + Number.EPSILON) * 100) / 100;
-            return `${megaBytes} MB`;
-        }
-        if (bytes > 1000000000) {
-            const gigaBytes = Math.round(((bytes / 1000000000) + Number.EPSILON) * 100) / 100;
-            return `${gigaBytes} GB`;
-        }
-        return `${bytes} bytes`;
-    }
-    normalizeExcludeValue(value) {
-        return this.caseInsensitiveExcludes ? value.toLowerCase() : value;
-    }
-    createZip() {
-        return new Promise((resolve, reject) => {
-            let output = null;
-            let archive = null;
-            let settled = false;
-            const safeResolve = (value) => {
-                if (settled) {
-                    return;
-                }
-                settled = true;
-                resolve(value);
-            };
-            const safeReject = (err) => {
-                if (settled) {
-                    return;
-                }
-                settled = true;
-                try {
-                    if (archive) {
-                        archive.abort();
-                    }
-                }
-                catch {
-                    // Ignore abort errors.
-                }
-                try {
-                    if (output) {
-                        output.destroy();
-                    }
-                }
-                catch {
-                    // Ignore destroy errors.
-                }
-                try {
-                    if (fs.existsSync(this.zipPath)) {
-                        fs.unlinkSync(this.zipPath);
-                    }
-                }
-                catch {
-                    // Ignore cleanup errors.
-                }
-                const normalizedError = err instanceof Error ? err : new Error(String(err));
-                reject(normalizedError);
-            };
-            // Remove the destination zip if it exists.
-            // see : https://github.com/Ismail-elkorchi/dir-archiver/issues/5
-            try {
-                if (fs.existsSync(this.zipPath)) {
-                    fs.unlinkSync(this.zipPath);
-                }
-            }
-            catch (err) {
-                safeReject(err);
-                return;
-            }
-            // Create a file to stream archive data to.
-            output = fs.createWriteStream(this.zipPath);
-            archive = (0, archiver_1.default)('zip', {
-                zlib: { level: 9 }
-            });
-            // Catch warnings during archiving.
-            archive.on('warning', (err) => {
-                if (err.code === 'ENOENT') {
-                    // log warning
-                    console.log(err);
-                }
-                else {
-                    safeReject(err);
-                }
-            });
-            // Catch errors during archiving.
-            archive.on('error', (err) => {
-                safeReject(err);
-            });
-            output.on('error', (err) => {
-                safeReject(err);
-            });
-            // Listen for all archive data to be written.
-            output.on('close', () => {
-                if (settled) {
-                    return;
-                }
-                console.log(`Created ${this.zipPath} of ${this.prettyBytes(archive.pointer())}`);
-                safeResolve(this.zipPath);
-            });
-            // Pipe archive data to the file.
-            archive.pipe(output);
-            // Recursively traverse the directory tree and append the files to the archive.
-            this.visitedDirectories.clear();
-            try {
-                this.traverseDirectoryTree(this.directoryPath, archive);
-            }
-            catch (err) {
-                safeReject(err);
-                return;
-            }
-            // Finalize the archive.
-            void Promise.resolve(archive.finalize()).catch((err) => {
-                safeReject(err);
-            });
-        });
-    }
-}
-module.exports = DirArchiver;
+export default api;

package/dist/runtime/bun.d.ts

@@ -0,0 +1,2 @@
+import type { RuntimeBindings } from './types.js';
+export declare const loadBunBindings: () => Promise<RuntimeBindings>;

package/dist/runtime/bun.js

@@ -0,0 +1,17 @@
+let bunBindingsPromise;
+export const loadBunBindings = async () => {
+    bunBindingsPromise !== null && bunBindingsPromise !== void 0 ? bunBindingsPromise : (bunBindingsPromise = import('@ismail-elkorchi/bytefold/bun')
+        .then((moduleExports) => {
+        const openArchive = moduleExports.openArchive;
+        const createArchiveWriter = moduleExports.createArchiveWriter;
+        if (typeof openArchive !== 'function' || typeof createArchiveWriter !== 'function') {
+            throw new Error('Bytefold bun runtime exports are unavailable.');
+        }
+        return {
+            runtime: 'bun',
+            openArchive,
+            createArchiveWriter
+        };
+    }));
+    return bunBindingsPromise;
+};

package/dist/runtime/deno.d.ts

@@ -0,0 +1,2 @@
+import type { RuntimeBindings } from './types.js';
+export declare const loadDenoBindings: () => Promise<RuntimeBindings>;

package/dist/runtime/deno.js

@@ -0,0 +1,17 @@
+let denoBindingsPromise;
+export const loadDenoBindings = async () => {
+    denoBindingsPromise !== null && denoBindingsPromise !== void 0 ? denoBindingsPromise : (denoBindingsPromise = import('@ismail-elkorchi/bytefold/deno')
+        .then((moduleExports) => {
+        const openArchive = moduleExports.openArchive;
+        const createArchiveWriter = moduleExports.createArchiveWriter;
+        if (typeof openArchive !== 'function' || typeof createArchiveWriter !== 'function') {
+            throw new Error('Bytefold deno runtime exports are unavailable.');
+        }
+        return {
+            runtime: 'deno',
+            openArchive,
+            createArchiveWriter
+        };
+    }));
+    return denoBindingsPromise;
+};

package/dist/runtime/index.d.ts

@@ -0,0 +1,2 @@
+import type { RuntimeBindings } from './types.js';
+export declare const loadRuntimeBindings: () => Promise<RuntimeBindings>;

package/dist/runtime/index.js

@@ -0,0 +1,33 @@
+import { DirArchiverError } from '../errors.js';
+import { loadBunBindings } from './bun.js';
+import { loadDenoBindings } from './deno.js';
+import { loadNodeBindings } from './node.js';
+const hasDenoGlobal = () => { var _a, _b; return typeof ((_b = (_a = globalThis.Deno) === null || _a === void 0 ? void 0 : _a.version) === null || _b === void 0 ? void 0 : _b.deno) === 'string'; };
+const hasBunGlobal = () => { var _a; return typeof ((_a = globalThis.Bun) === null || _a === void 0 ? void 0 : _a.version) === 'string'; };
+const hasNodeProcess = () => { var _a, _b; return typeof ((_b = (_a = globalThis.process) === null || _a === void 0 ? void 0 : _a.versions) === null || _b === void 0 ? void 0 : _b.node) === 'string'; };
+const detectRuntime = () => {
+    if (hasDenoGlobal()) {
+        return 'deno';
+    }
+    if (hasBunGlobal()) {
+        return 'bun';
+    }
+    if (hasNodeProcess()) {
+        return 'node';
+    }
+    throw new DirArchiverError('DIRARCHIVER_RUNTIME_UNSUPPORTED', 'Unsupported runtime. Expected Node.js, Deno, or Bun.');
+};
+let runtimeBindingsPromise;
+export const loadRuntimeBindings = async () => {
+    runtimeBindingsPromise !== null && runtimeBindingsPromise !== void 0 ? runtimeBindingsPromise : (runtimeBindingsPromise = (async () => {
+        const runtime = detectRuntime();
+        if (runtime === 'deno') {
+            return loadDenoBindings();
+        }
+        if (runtime === 'bun') {
+            return loadBunBindings();
+        }
+        return loadNodeBindings();
+    })());
+    return runtimeBindingsPromise;
+};

package/dist/runtime/node.d.ts

@@ -0,0 +1,2 @@
+import type { RuntimeBindings } from './types.js';
+export declare const loadNodeBindings: () => Promise<RuntimeBindings>;

package/dist/runtime/node.js

@@ -0,0 +1,17 @@
+let nodeBindingsPromise;
+export const loadNodeBindings = async () => {
+    nodeBindingsPromise !== null && nodeBindingsPromise !== void 0 ? nodeBindingsPromise : (nodeBindingsPromise = import('@ismail-elkorchi/bytefold/node')
+        .then((moduleExports) => {
+        const openArchive = moduleExports.openArchive;
+        const createArchiveWriter = moduleExports.createArchiveWriter;
+        if (typeof openArchive !== 'function' || typeof createArchiveWriter !== 'function') {
+            throw new Error('Bytefold node runtime exports are unavailable.');
+        }
+        return {
+            runtime: 'node',
+            openArchive,
+            createArchiveWriter
+        };
+    }));
+    return nodeBindingsPromise;
+};

package/dist/runtime/types.d.ts

@@ -0,0 +1,11 @@
+import type { ArchiveFormat, ArchiveOpenOptions, ArchiveReader } from '@ismail-elkorchi/bytefold';
+export type RuntimeKind = 'node' | 'deno' | 'bun';
+export interface ArchiveWriterLike {
+    add: (name: string, source: Uint8Array | ArrayBuffer | ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>) => Promise<void>;
+    close: () => Promise<void>;
+}
+export interface RuntimeBindings {
+    runtime: RuntimeKind;
+    openArchive: (input: unknown, options?: ArchiveOpenOptions) => Promise<ArchiveReader>;
+    createArchiveWriter: (format: ArchiveFormat, writable: WritableStream<Uint8Array>, options?: unknown) => ArchiveWriterLike;
+}

package/dist/runtime/types.js

@@ -0,0 +1 @@
+export {};

package/dist/types.d.ts

@@ -0,0 +1,186 @@
+import type { ArchiveDetectionReport, ArchiveFormat, ArchiveIssue, ArchiveLimits, ArchiveNormalizeReport, ArchiveOpenOptions, ArchiveProfile } from '@ismail-elkorchi/bytefold';
+export type { ArchiveFormat, ArchiveLimits, ArchiveProfile };
+/**
+ * Accepted input shapes for archive read operations.
+ */
+export type DirArchiverInput = string | URL | Uint8Array | ArrayBuffer | ReadableStream<Uint8Array> | Blob;
+/**
+ * Common options forwarded to bytefold archive-open operations.
+ *
+ * Used by `open()`, `detect()`, `list()`, and `audit()`.
+ */
+export interface OpenOptions {
+    /**
+     * Explicit format override when callers already know archive type.
+     */
+    format?: ArchiveOpenOptions['format'] | undefined;
+    /**
+     * Safety profile (`compat`, `strict`, `agent`) applied during reads/audits.
+     */
+    profile?: ArchiveOpenOptions['profile'] | undefined;
+    /**
+     * Extra strictness toggle forwarded to bytefold parsing.
+     */
+    isStrict?: ArchiveOpenOptions['isStrict'] | undefined;
+    /**
+     * Parser/resource limits enforced while opening or auditing archives.
+     */
+    limits?: ArchiveOpenOptions['limits'] | undefined;
+    /**
+     * Abort signal for cancelling in-flight async operations.
+     */
+    signal?: ArchiveOpenOptions['signal'] | undefined;
+    /**
+     * Password used for encrypted archives when supported by the runtime.
+     */
+    password?: ArchiveOpenOptions['password'] | undefined;
+    /**
+     * Filename hint used for extension-based inference with non-path inputs.
+     */
+    filename?: ArchiveOpenOptions['filename'] | undefined;
+}
+/**
+ * Format detection result.
+ */
+export interface DetectResult {
+    format: ArchiveFormat;
+    detection: ArchiveDetectionReport | undefined;
+}
+/**
+ * Single archive entry projection used by list responses.
+ */
+export interface ListEntry {
+    format: ArchiveFormat;
+    name: string;
+    size: string;
+    isDirectory: boolean;
+    isSymlink: boolean;
+    linkName?: string | undefined;
+}
+/**
+ * Archive listing response payload.
+ */
+export interface ListResult {
+    format: ArchiveFormat;
+    detection: ArchiveDetectionReport | undefined;
+    entries: ListEntry[];
+}
+/**
+ * Options for `audit()`.
+ *
+ * Alias of `OpenOptions` for stable API typing; CLI-only flags (for example
+ * `--json`) are not part of this programmatic surface.
+ */
+export type AuditOptions = OpenOptions;
+/**
+ * Normalize operation options.
+ */
+export interface NormalizeOptions extends OpenOptions {
+    deterministic?: boolean | undefined;
+}
+/**
+ * Normalize operation result payload.
+ */
+export interface NormalizeResult {
+    format: ArchiveFormat;
+    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 {
+    format: ArchiveFormat;
+    destination: string;
+    extractedFiles: number;
+    extractedDirectories: number;
+    skippedEntries: number;
+    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 {
+    format: ArchiveFormat;
+    source: string;
+    destination: string;
+    entryCount: number;
+    wrappedDirectoryCodec: boolean;
+}
+/**
+ * Usage-error shape emitted by CLI parsing.
+ */
+export interface CliUsageError {
+    message: string;
+    issues: readonly {
+        code: string;
+        message: string;
+    }[];
+}
+/**
+ * Canonical command identifiers supported by the CLI contract.
+ */
+export interface SupportedCommandMap {
+    open: 'open';
+    detect: 'detect';
+    list: 'list';
+    audit: 'audit';
+    extract: 'extract';
+    normalize: 'normalize';
+    write: 'write';
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

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.