dir-archiver 2.1.2 → 3.0.0

package/README.md

@@ -1,79 +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`.
+
+## Install
+
+### npm
 
 ```sh
-$ npm install dir-archiver
+npm install dir-archiver
 ```
 
-Requires Node.js >=14.
-
-# Usage
-
-## API
-
-```javascript
-// Require modules.
-var DirArchiver = require('dir-archiver');
-
-// Create an array with the files and directories to exclude.
-const excludes = ['directory_name', 'file.extension'];
-
-/**
- * Create a dir-archiver object. 
- * @param {string} directoryPath - The path of the folder to archive.
- * @param {string} zipPath - The path of the zip file to create.
- * @param {Boolean} 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 {array} excludes - A list with the names of the files and folders to exclude.
-*/
-var archive = new DirArchiver('path/to/directory', 'path/to/desination/zipfile.zip', true, excludes);
-
-// Create the zip file.
-archive.createZip().then(() => {
-  console.log('Archive ready');
-}).catch((err) => {
-  console.error(err);
-});
+### JSR
 
-// Or with async/await:
-// await archive.createZip();
+```sh
+deno add jsr:@ismail-elkorchi/dir-archiver
 ```
-## Command Line Interface
 
-```sh
-Usage: dir-archiver --src <path-to-directory> --dest <path-to-file>.zip --includebasedir true|false --exclude folder-name file-name.extention
-
-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]
-  --exclude         A list with the names of the files and folders to exclude.               [array]
+## Quickstart (API)
+
+```ts
+import { write, detect, list, extract } from 'dir-archiver';
+
+await write('./project', './project.zip', {
+  format: 'zip',
+  includeBaseDirectory: true,
+  profile: 'strict'
+});
+
+const detected = await detect('./project.zip');
+const listed = await list('./project.zip');
+await extract('./project.zip', './out', { profile: 'strict' });
+
+console.log(detected.format, listed.entries.length);
 ```
 
-# Testing
+## Public operations
+
+- `open(input, options)`
+- `detect(input, options)`
+- `list(input, options)`
+- `audit(input, options)`
+- `extract(input, destination, options)`
+- `normalize(input, destination, options)`
+- `write(source, destination, options)`
+
+Format surface matches bytefold `ArchiveFormat` support.  
+Directory + single-file codec requests are normalized to `tar.<codec>` (`gz`, `bz2`, `xz`, `zst`, `br`).
+
+## 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
 ```
 
+Exit codes:
+
+- `0` success
+- `1` operational failure
+- `2` usage/validation failure
+
+## 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.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+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;
+    }
+    const unreachable = command;
+    throw new Error(`Unhandled command: ${String(unreachable)}`);
+};
+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;