dir-archiver 2.2.0 → 3.0.0

package/README.md

@@ -1,125 +1,88 @@
-[![npm][npm-image]][npm-url] [![license][license-image]][license-url]
-[![changelog][changelog-image]][changelog-url]
+---
+role: overview
+audience: users
+source_of_truth: README.md
+update_triggers:
+  - public API changes
+  - CLI contract changes
+  - runtime support changes
+---
 
-# Dir Archiver
-Compress a whole directory (including subdirectories) into a zip file, with options to exclude specific files or directories.
+# dir-archiver
 
-# Installation
+`dir-archiver` v3 is a bytefold-backed archive orchestration layer for Node.js, Deno, and Bun.  
+ESM-only. Safety profiles: `compat | strict | agent`.
 
-```sh
-$ npm install dir-archiver
-```
-
-Requires Node.js >=18.
-
-# Usage
-
-## API
+## Install
 
-Quick start (async/await):
+### npm
 
-```javascript
-const DirArchiver = require('dir-archiver');
+```sh
+npm install dir-archiver
+```
 
-const archive = new DirArchiver(
-  './my-project',
-  './my-project.zip',
-  true,
-  ['node_modules', 'dist', 'nested/secret.txt'],
-  false
-);
+### JSR
 
-await archive.createZip();
+```sh
+deno add jsr:@ismail-elkorchi/dir-archiver
 ```
 
-Signature:
+## Quickstart (API)
 
 ```ts
-new DirArchiver(
-  directoryPath: string,
-  zipPath: string,
-  includeBaseDirectory?: boolean,
-  excludes?: string[],
-  followSymlinks?: boolean
-)
-```
-
-Parameters:
-- `directoryPath`: Root folder to archive (must exist).
-- `zipPath`: Destination zip file path (parent directory must exist).
-- `includeBaseDirectory`: When true, the archive contains the source folder as the top-level directory.
-- `excludes`: Names or relative paths to skip. Names without path separators match anywhere; use a relative path
-  (for example, `nested/file.txt`) to target a specific entry. Trailing slashes can target directories (for example, `cache/`).
-  Windows-style backslashes are accepted and normalized. Absolute paths inside the source tree are accepted and converted
-  to relative excludes. Matching is case-insensitive on Windows.
-- `followSymlinks`: Follow symlinks when traversing directories. Default: `false`.
+import { write, detect, list, extract } from 'dir-archiver';
 
-`createZip()` returns a Promise that resolves with the zip path when the archive is finalized and rejects on failure.
-Zip entries always use forward slashes, regardless of OS, and are added in deterministic order.
+await write('./project', './project.zip', {
+  format: 'zip',
+  includeBaseDirectory: true,
+  profile: 'strict'
+});
 
-## Command Line Interface
+const detected = await detect('./project.zip');
+const listed = await list('./project.zip');
+await extract('./project.zip', './out', { profile: 'strict' });
 
-```sh
-Usage: dir-archiver --src <path-to-directory> --dest <path-to-file>.zip --includebasedir true|false --exclude folder-name file-name.extension
-
-Options:
-  --src             The path of the folder to archive.                            [string][required]
-  --dest            The path of the zip file to create.                           [string][required]
-  --includebasedir  Includes a base directory at the root of the archive.
-                    For example, if the root folder of your project is named
-                    "your-project", setting this option 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.                               [bool]
-  --followsymlinks  Follow symlinks when traversing directories.                              [bool]
-  --exclude         A list with the names of the files and folders to exclude. Names without
-                    path separators match anywhere; use a relative path to target a specific
-                    entry. Windows-style backslashes are accepted and normalized.           [array]
+console.log(detected.format, listed.entries.length);
 ```
 
-Inline values are supported for flags (for example, `--includebasedir=true` or `--exclude=cache`).
-
-# CLI examples
+## Public operations
 
-```sh
-# Basic
-dir-archiver --src ./my-project --dest ./my-project.zip
+- `open(input, options)`
+- `detect(input, options)`
+- `list(input, options)`
+- `audit(input, options)`
+- `extract(input, destination, options)`
+- `normalize(input, destination, options)`
+- `write(source, destination, options)`
 
-# Include base directory and exclude node_modules anywhere
-dir-archiver --src ./my-project --dest ./my-project.zip --includebasedir=true --exclude node_modules
+Format surface matches bytefold `ArchiveFormat` support.  
+Directory + single-file codec requests are normalized to `tar.<codec>` (`gz`, `bz2`, `xz`, `zst`, `br`).
 
-# Exclude a specific path
-dir-archiver --src ./my-project --dest ./my-project.zip --exclude nested/secret.txt
-
-# Windows-style excludes (backslashes are normalized)
-dir-archiver --src . --dest archive.zip --exclude .\\nested\\skip.txt
-
-# Follow symlinks
-dir-archiver --src ./my-project --dest ./my-project.zip --followsymlinks=true
-```
-
-# Testing
+## CLI
 
 ```sh
-$ npm test
+dir-archiver write --source ./project --output ./project.zip --format zip --json
+dir-archiver detect --input ./project.zip --json
+dir-archiver list --input ./project.zip --json
+dir-archiver audit --input ./project.zip --profile agent --json
+dir-archiver extract --input ./project.zip --output ./out --profile strict --json
+dir-archiver normalize --input ./project.zip --output ./normalized.zip --json
 ```
 
-# Development
+Exit codes:
 
-```sh
-$ npm install
-$ npm run typecheck
-$ npm run build
-$ npm run lint
-```
+- `0` success
+- `1` operational failure
+- `2` usage/validation failure
 
-Linting runs TypeScript typechecking and ESLint. CI runs lint and tests on Node 18/20/22 across Linux, macOS, and Windows.
+## Security model
 
+- Archive extraction treats input as untrusted by default.
+- Traversal/absolute paths are blocked in strict/agent profiles.
+- See `SECURITY.md` and `docs/security-triage.md`.
 
+## Docs
 
-[changelog-image]: https://img.shields.io/badge/changelog-md-blue.svg?style=flat-square
-[changelog-url]: CHANGELOG.md
-[license-image]: https://img.shields.io/npm/l/dir-archiver.svg?style=flat-square
-[license-url]: LICENSE
-[npm-image]: https://img.shields.io/npm/v/dir-archiver.svg?style=flat-square
-[npm-url]: https://www.npmjs.com/package/dir-archiver
+- `docs/V3_CONTRACT.md`
+- `CHANGELOG.md`
+- `SECURITY.md`

package/dist/cli-args.d.ts

@@ -0,0 +1,24 @@
+import type { ArchiveFormat, ArchiveProfile } from './types.js';
+export type CliCommand = 'open' | 'detect' | 'list' | 'audit' | 'extract' | 'normalize' | 'write';
+export interface ParsedCliArgs {
+    ok: boolean;
+    issues: {
+        code: string;
+        message: string;
+    }[];
+    command: CliCommand | undefined;
+    input: string | undefined;
+    source: string | undefined;
+    output: string | undefined;
+    format: ArchiveFormat | undefined;
+    profile: ArchiveProfile;
+    json: boolean;
+    includeBaseDirectory: boolean;
+    followSymlinks: boolean;
+    exclude: string[];
+    allowSymlinks: boolean;
+    allowHardlinks: boolean;
+    maxEntryBytes: number | undefined;
+    maxTotalExtractedBytes: number | undefined;
+}
+export declare const parseCliArgs: (argv: readonly string[]) => Promise<ParsedCliArgs>;

package/dist/cli-args.js

@@ -0,0 +1,204 @@
+const SUPPORTED_COMMANDS = new Set(['open', 'detect', 'list', 'audit', 'extract', 'normalize', 'write']);
+const SUPPORTED_FORMATS = new Set([
+    'zip',
+    'tar',
+    'tgz',
+    'tar.gz',
+    'gz',
+    'bz2',
+    'tar.bz2',
+    'zst',
+    'tar.zst',
+    'br',
+    'tar.br',
+    'xz',
+    'tar.xz'
+]);
+const SUPPORTED_PROFILES = new Set(['compat', 'strict', 'agent']);
+const CLI_SCHEMA = {
+    source: {
+        type: 'string',
+        flags: ['--source', '--src']
+    },
+    input: {
+        type: 'string',
+        flags: ['--input', '-i']
+    },
+    output: {
+        type: 'string',
+        flags: ['--output', '--dest', '-o']
+    },
+    format: {
+        type: 'string',
+        flags: ['--format']
+    },
+    profile: {
+        type: 'string',
+        flags: ['--profile'],
+        default: 'strict'
+    },
+    json: {
+        type: 'boolean',
+        flags: ['--json'],
+        default: false
+    },
+    includeBaseDirectory: {
+        type: 'boolean',
+        flags: ['--include-base-directory', '--includebasedir'],
+        default: false
+    },
+    followSymlinks: {
+        type: 'boolean',
+        flags: ['--follow-symlinks', '--followsymlinks'],
+        default: false
+    },
+    exclude: {
+        type: 'array',
+        flags: ['--exclude'],
+        default: []
+    },
+    allowSymlinks: {
+        type: 'boolean',
+        flags: ['--allow-symlinks'],
+        default: false
+    },
+    allowHardlinks: {
+        type: 'boolean',
+        flags: ['--allow-hardlinks'],
+        default: false
+    },
+    maxEntryBytes: {
+        type: 'number',
+        flags: ['--max-entry-bytes']
+    },
+    maxTotalExtractedBytes: {
+        type: 'number',
+        flags: ['--max-total-extracted-bytes']
+    }
+};
+let parseArgsPromise;
+const loadParseArgs = () => {
+    parseArgsPromise !== null && parseArgsPromise !== void 0 ? parseArgsPromise : (parseArgsPromise = import('argv-flags').then((moduleExports) => moduleExports.default));
+    return parseArgsPromise;
+};
+export const parseCliArgs = async (argv) => {
+    const parseArgs = await loadParseArgs();
+    const parsed = parseArgs(CLI_SCHEMA, {
+        argv: [...argv]
+    });
+    const issues = parsed.issues.map((issue) => ({
+        code: issue.code,
+        message: issue.message
+    }));
+    const values = parsed.values;
+    const commandToken = parsed.rest[0];
+    const command = resolveCommand(commandToken, values, issues);
+    const profile = resolveProfile(values['profile'], issues);
+    const format = resolveFormat(values['format'], issues);
+    const source = toOptionalString(values['source']);
+    const input = toOptionalString(values['input']);
+    const output = toOptionalString(values['output']);
+    validateCommandRequirements(command, { source, input, output }, issues);
+    return {
+        ok: issues.length === 0,
+        issues,
+        command,
+        source,
+        input,
+        output,
+        format,
+        profile,
+        json: values['json'] === true,
+        includeBaseDirectory: values['includeBaseDirectory'] === true,
+        followSymlinks: values['followSymlinks'] === true,
+        exclude: toStringArray(values['exclude']),
+        allowSymlinks: values['allowSymlinks'] === true,
+        allowHardlinks: values['allowHardlinks'] === true,
+        maxEntryBytes: toOptionalNumber(values['maxEntryBytes']),
+        maxTotalExtractedBytes: toOptionalNumber(values['maxTotalExtractedBytes'])
+    };
+};
+const resolveCommand = (commandToken, values, issues) => {
+    if (typeof commandToken === 'string' && SUPPORTED_COMMANDS.has(commandToken)) {
+        return commandToken;
+    }
+    if (typeof commandToken === 'string' && commandToken.length > 0) {
+        issues.push({
+            code: 'USAGE',
+            message: `Unknown command "${commandToken}".`
+        });
+        return undefined;
+    }
+    const hasSource = typeof values['source'] === 'string';
+    const hasOutput = typeof values['output'] === 'string';
+    if (hasSource && hasOutput) {
+        return 'write';
+    }
+    issues.push({
+        code: 'USAGE',
+        message: 'Missing command.'
+    });
+    return undefined;
+};
+const resolveProfile = (value, issues) => {
+    const normalized = typeof value === 'string' ? value : 'strict';
+    if (!SUPPORTED_PROFILES.has(normalized)) {
+        issues.push({
+            code: 'INVALID_VALUE',
+            message: `Unsupported profile "${String(value)}".`
+        });
+        return 'strict';
+    }
+    return normalized;
+};
+const resolveFormat = (value, issues) => {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    if (!SUPPORTED_FORMATS.has(value)) {
+        issues.push({
+            code: 'INVALID_VALUE',
+            message: `Unsupported format "${value}".`
+        });
+        return undefined;
+    }
+    return value;
+};
+const validateCommandRequirements = (command, values, issues) => {
+    if (!command) {
+        return;
+    }
+    if (command === 'write') {
+        if (!values.source) {
+            issues.push({ code: 'REQUIRED', message: 'write requires --source/--src.' });
+        }
+        if (!values.output) {
+            issues.push({ code: 'REQUIRED', message: 'write requires --output/--dest.' });
+        }
+        return;
+    }
+    if (command === 'extract' || command === 'normalize') {
+        if (!values.input) {
+            issues.push({ code: 'REQUIRED', message: `${command} requires --input.` });
+        }
+        if (!values.output) {
+            issues.push({ code: 'REQUIRED', message: `${command} requires --output.` });
+        }
+        return;
+    }
+    if (!values.input) {
+        issues.push({ code: 'REQUIRED', message: `${command} requires --input.` });
+    }
+};
+const toOptionalString = (value) => {
+    return typeof value === 'string' ? value : undefined;
+};
+const toStringArray = (value) => {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((item) => typeof item === 'string');
+};
+const toOptionalNumber = (value) => {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+};

package/dist/cli.js

@@ -1,51 +1,136 @@
 #!/usr/bin/env node
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-const index_1 = __importDefault(require("./index"));
-const argv_flags_1 = __importDefault(require("argv-flags"));
-const parseBooleanFlag = (flag) => {
-    const rawValue = (0, argv_flags_1.default)(flag, 'string');
-    if (typeof rawValue === 'string' && rawValue.length > 0 && !rawValue.startsWith('-')) {
-        const normalized = rawValue.toLowerCase();
-        if (normalized === 'true') {
-            return true;
-        }
-        if (normalized === 'false') {
-            return false;
+import { audit, detect, extract, list, normalize, open, write } from './index.js';
+import { DirArchiverError } from './errors.js';
+import { parseCliArgs } from './cli-args.js';
+const usage = `Usage:
+  dir-archiver write --source <path> --output <archive> [--format <format>] [--include-base-directory] [--exclude <path>...]
+  dir-archiver detect --input <archive>
+  dir-archiver list --input <archive>
+  dir-archiver audit --input <archive> [--profile compat|strict|agent]
+  dir-archiver extract --input <archive> --output <directory> [--profile compat|strict|agent] [--max-entry-bytes <n>] [--max-total-extracted-bytes <n>]
+  dir-archiver normalize --input <archive> --output <archive> [--profile compat|strict|agent]
+
+Common options:
+  --format <format>                     zip|tar|tgz|tar.gz|gz|bz2|tar.bz2|zst|tar.zst|br|tar.br|xz|tar.xz
+  --profile <profile>                   compat|strict|agent
+  --json                                emit machine-readable JSON
+  --allow-symlinks                      enable symlink extraction
+  --allow-hardlinks                     enable hardlink extraction (currently unsupported)
+`;
+const run = async () => {
+    const parsed = await parseCliArgs(process.argv.slice(2));
+    const command = parsed.command;
+    if (!parsed.ok || !command) {
+        const payload = {
+            schemaVersion: '1',
+            code: 'DIRARCHIVER_USAGE',
+            message: 'Invalid CLI arguments.',
+            issues: parsed.issues
+        };
+        if (parsed.json) {
+            console.log(JSON.stringify(payload));
+        }
+        else {
+            console.error(usage);
+            for (const issue of parsed.issues) {
+                console.error(`- [${issue.code}] ${issue.message}`);
+            }
+        }
+        return 2;
+    }
+    const commonOptions = {
+        profile: parsed.profile,
+        ...(parsed.format ? { format: parsed.format } : {})
+    };
+    switch (command) {
+        case 'write': {
+            const result = await write(requireString(parsed.source, 'write requires --source/--src'), requireString(parsed.output, 'write requires --output/--dest'), {
+                ...commonOptions,
+                includeBaseDirectory: parsed.includeBaseDirectory,
+                followSymlinks: parsed.followSymlinks,
+                exclude: parsed.exclude
+            });
+            outputResult(parsed.json, result);
+            return 0;
+        }
+        case 'open': {
+            const reader = await open(requireString(parsed.input, 'open requires --input'), commonOptions);
+            outputResult(parsed.json, {
+                format: reader.format,
+                detection: reader.detection
+            });
+            return 0;
+        }
+        case 'detect': {
+            const result = await detect(requireString(parsed.input, 'detect requires --input'), commonOptions);
+            outputResult(parsed.json, result);
+            return 0;
+        }
+        case 'list': {
+            const result = await list(requireString(parsed.input, 'list requires --input'), commonOptions);
+            outputResult(parsed.json, result);
+            return 0;
+        }
+        case 'audit': {
+            const result = await audit(requireString(parsed.input, 'audit requires --input'), commonOptions);
+            outputResult(parsed.json, result);
+            return 0;
+        }
+        case 'extract': {
+            const result = await extract(requireString(parsed.input, 'extract requires --input'), requireString(parsed.output, 'extract requires --output'), {
+                ...commonOptions,
+                allowSymlinks: parsed.allowSymlinks,
+                allowHardlinks: parsed.allowHardlinks,
+                ...(typeof parsed.maxEntryBytes === 'number' ? { maxEntryBytes: parsed.maxEntryBytes } : {}),
+                ...(typeof parsed.maxTotalExtractedBytes === 'number'
+                    ? { maxTotalExtractedBytes: parsed.maxTotalExtractedBytes }
+                    : {})
+            });
+            outputResult(parsed.json, result);
+            return 0;
+        }
+        case 'normalize': {
+            const result = await normalize(requireString(parsed.input, 'normalize requires --input'), requireString(parsed.output, 'normalize requires --output'), {
+                ...commonOptions
+            });
+            outputResult(parsed.json, result);
+            return 0;
         }
+        default:
+            break;
     }
-    return (0, argv_flags_1.default)(flag, 'boolean') === true;
+    const unreachable = command;
+    throw new Error(`Unhandled command: ${String(unreachable)}`);
 };
-const directoryPath = (0, argv_flags_1.default)('--src', 'string');
-const zipPath = (0, argv_flags_1.default)('--dest', 'string');
-const includeBaseDirectory = parseBooleanFlag('--includebasedir');
-const followSymlinks = parseBooleanFlag('--followsymlinks');
-const excludeValues = (0, argv_flags_1.default)('--exclude', 'array');
-const excludes = Array.isArray(excludeValues) ? excludeValues : [];
-if (typeof directoryPath !== 'string' || typeof zipPath !== 'string') {
-    console.log(` Dir Archiver could not be executed. Some arguments are missing.
-
-    Options:
-      --src            The path of the folder to archive.                            [string][required]
-      --dest           The path of the zip file to create.                           [string][required]
-      --includebasedir Includes a base directory at the root of the archive.
-                       For example, if the root folder of your project is named
-                       "your-project", setting this option 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.                               [bool]
-      --followsymlinks Follow symlinks when traversing directories.                              [bool]
-      --exclude        A list with the names of the files and folders to exclude.               [array]`);
-    process.exitCode = 1;
-}
-else {
-    const archive = new index_1.default(directoryPath, zipPath, includeBaseDirectory, excludes, followSymlinks);
-    archive.createZip().catch((err) => {
-        const normalizedError = err instanceof Error ? err : new Error(String(err));
-        console.error(normalizedError);
+const outputResult = (asJson, payload) => {
+    if (asJson) {
+        console.log(JSON.stringify(payload));
+        return;
+    }
+    console.log(payload);
+};
+const requireString = (value, message) => {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new DirArchiverError('DIRARCHIVER_USAGE', message);
+    }
+    return value;
+};
+void run()
+    .then((exitCode) => {
+    process.exitCode = exitCode;
+})
+    .catch((error) => {
+    var _a;
+    if (error instanceof DirArchiverError) {
+        console.error(JSON.stringify(error.toJSON()));
         process.exitCode = 1;
-    });
-}
+        return;
+    }
+    if (error instanceof Error) {
+        console.error((_a = error.stack) !== null && _a !== void 0 ? _a : error.message);
+    }
+    else {
+        console.error(String(error));
+    }
+    process.exitCode = 1;
+});

package/dist/core.d.ts

@@ -0,0 +1,33 @@
+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.
+ */
+export declare const open: (input: DirArchiverInput, options?: OpenOptions) => Promise<ArchiveReader>;
+/**
+ * Detects archive format and exposes bytefold detection metadata.
+ */
+export declare const detect: (input: DirArchiverInput, options?: OpenOptions) => Promise<DetectResult>;
+/**
+ * Lists archive entries without extracting to disk.
+ */
+export declare const list: (input: DirArchiverInput, options?: OpenOptions) => Promise<ListResult>;
+/**
+ * Runs bytefold audit checks for the selected safety profile.
+ */
+export declare const audit: (input: DirArchiverInput, options?: OpenOptions) => Promise<ArchiveAuditReport>;
+/**
+ * Writes a normalized deterministic archive when supported by the format.
+ */
+export declare const normalize: (input: DirArchiverInput, destination: string, options?: NormalizeOptions) => Promise<NormalizeResult>;
+/**
+ * Extracts entries to a destination directory with safety enforcement.
+ */
+export declare const extract: (input: DirArchiverInput, destination: string, options?: ExtractOptions) => Promise<ExtractResult>;
+/**
+ * Writes an archive from a file or directory source.
+ */
+export declare const write: (source: string, destination: string, options?: WriteOptions) => Promise<WriteResult>;
+export declare const copyStreamToFile: (source: string, destination: string) => Promise<void>;
+export declare const pathExists: (value: string) => boolean;
+export declare const fileSize: (value: string) => number;