@documonster/mcp 0.8.0-canary.sha.09791dab

package/dist/tools/archive-read.js

@@ -0,0 +1,315 @@
+/**
+ * `archive_read` — list or extract a ZIP/TAR archive.
+ *
+ * The entry point to most real work: documents arrive as email attachments and
+ * export bundles, and a model cannot open a binary container by itself. It is
+ * also where the security surface is widest, so three guards apply beyond the
+ * generic path sandbox:
+ *
+ * 1. **Traversal, including through existing links.** Entries are written one at
+ *    a time and every destination goes through `resolveInRoot`, so an entry name
+ *    with `..` is rejected *and* so is an entry whose path passes through a
+ *    symlink already sitting in the destination directory. Delegating to the
+ *    library's `extractTo` was not enough: it validates entry names against the
+ *    target directory but writes through a pre-existing `out/link -> /elsewhere`,
+ *    which was verified to escape the sandbox.
+ * 2. **Decompression bombs** — the archive file's own size is checked before it
+ *    is opened, and the declared uncompressed sizes before anything is written.
+ * 3. **Symlink and special entries** — never materialised. A `link ->
+ *    /etc/passwd` entry would otherwise leave a live escape hatch inside the
+ *    sandbox for a later tool to follow.
+ * 4. **Permissions** — extracted files get the process default rather than the
+ *    archive's mode bits, so an untrusted archive cannot produce something
+ *    executable or world-writable.
+ *
+ * Encryption is not reported when listing: `ArchiveEntryInfo` carries an
+ * `isEncrypted` flag at runtime but does not declare it, and this package reads
+ * only documented public surface. Encryption therefore surfaces as a failed
+ * extraction with a hint to pass `password`. (Worth declaring upstream.)
+ */
+import { copyFile, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { Archive, ArchiveFile } from "documonster/archive";
+import { z } from "zod";
+import { McpToolError, toolError } from "../errors.js";
+import { assertWritable, resolveInRoot, resolveOutputPath } from "../sandbox.js";
+import { ensureParent, exists, writeWithPolicy } from "./fs-helpers.js";
+import { formatBytes, textResult } from "./result.js";
+import { defineTool } from "./types.js";
+/** Entries listed in one call. */
+const MAX_LISTED = 300;
+/** Total uncompressed bytes allowed in one extraction (256 MiB). */
+const MAX_TOTAL_EXTRACTED = 256 * 1024 * 1024;
+/** Entry count allowed in one extraction. */
+const MAX_ENTRIES = 5_000;
+export const archiveReadTool = defineTool({
+    name: "archive_read",
+    group: "archive",
+    title: "List or extract an archive",
+    description: "List the contents of a .zip/.tar/.tar.gz, or extract entries to a directory. Start with action 'list' to see what is inside, then extract only what you need. Encrypted archives are supported with a password. Symlink entries are never created.",
+    inputSchema: {
+        path: z.string().min(1).describe("Archive path, relative to the server root."),
+        action: z
+            .enum(["list", "extract"])
+            .optional()
+            .describe("'list' (default) reports the entries; 'extract' writes them to `out`."),
+        out: z
+            .string()
+            .optional()
+            .describe("Destination directory for extract, relative to the server root. Created if missing."),
+        entries: z
+            .array(z.string())
+            .optional()
+            .describe('Extract only these entry paths, or glob-ish prefixes/suffixes such as "data/" or "*.xlsx". Omit to extract everything.'),
+        password: z.string().optional().describe("Password for an encrypted archive."),
+        overwrite: z
+            .boolean()
+            .optional()
+            .describe("Replace files that already exist in `out`. Defaults to false so an extraction cannot silently clobber a working directory."),
+        format: z
+            .enum(["zip", "tar"])
+            .optional()
+            .describe("Container format. Inferred from the extension when omitted.")
+    },
+    // destructiveHint: extraction replaces files that already exist at the
+    // destination, which a client should be able to warn about.
+    annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
+    // Listing is read-only and useful on a read-only server; extraction calls
+    // assertWritable before touching disk. MCP annotations cannot vary by action,
+    // so they conservatively describe the destructive branch.
+    mutates: false,
+    handler: async (args, context) => {
+        const { config } = context;
+        const archivePath = await resolveInRoot(config, args.path, { mustExist: true });
+        const action = args.action ?? "list";
+        // Before opening: the reader loads the container into memory, and a .tar.gz
+        // is inflated during that call, so a bomb must be refused on its on-disk
+        // size first — checking the declared entry sizes afterwards is too late.
+        const archiveBytes = (await stat(archivePath)).size;
+        if (archiveBytes > config.maxFileSize) {
+            throw toolError.tooLarge(`${args.path} is ${formatBytes(archiveBytes)}, over the ${formatBytes(config.maxFileSize)} limit`, "Ask the user to raise --max-file-size if this archive is genuinely needed.");
+        }
+        const archive = await open(archivePath, args.path, args.format, args.password);
+        const entries = await archive.getEntries();
+        if (action === "list") {
+            return textResult(config, describeEntries(args.path, entries));
+        }
+        assertWritable(config);
+        if (args.out === undefined) {
+            throw toolError.invalidInput("extract requires `out`", 'Pass a destination directory, e.g. out: "extracted".');
+        }
+        let selected = args.entries === undefined
+            ? entries
+            : entries.filter(entry => matches(entry.path, args.entries ?? []));
+        if (selected.length === 0) {
+            throw toolError.invalidInput(`no entries matched ${JSON.stringify(args.entries)}`, `The archive contains: ${entries
+                .slice(0, 20)
+                .map(entry => entry.path)
+                .join(", ")}`);
+        }
+        assertNoBomb(selected, config);
+        // ArchiveFile's format-neutral entry type loses ZIP's file/symlink bit.
+        // Recover it from the public streaming reader, or a ZIP symlink is exposed
+        // as an ordinary 11-byte file and would be written despite our "skip
+        // special entries" promise.
+        const special = inferFormat(archivePath) === "zip"
+            ? await zipSpecialEntries(archivePath, args.password)
+            : tarSpecialEntries(entries);
+        selected = selected.filter(entry => !special.has(entry.path));
+        // Validate the destination directory itself, even when no entry ends up
+        // being written: `out: "../elsewhere"` must fail rather than silently
+        // succeed on an archive that happens to contain only directories.
+        const target = await resolveOutputPath(config, args.out);
+        const warnings = [];
+        let written = 0;
+        let bytesWritten = 0;
+        // Validate every destination and overwrite decision before reading or
+        // writing the first byte. This prevents a late traversal entry from leaving
+        // earlier existing files replaced.
+        const destinations = new Map();
+        for (const entry of selected) {
+            if (entry.isDirectory) {
+                continue;
+            }
+            try {
+                const destination = await resolveOutputPath(config, path.posix.join(args.out, entry.path));
+                if (args.overwrite !== true && (await exists(destination))) {
+                    throw toolError.invalidInput(`extraction would overwrite ${path.posix.join(args.out, entry.path)}`, "Pass overwrite: true to replace existing files, or choose an empty destination. Nothing was written.");
+                }
+                destinations.set(entry.path, destination);
+            }
+            catch (cause) {
+                if (cause instanceof McpToolError && cause.code === "outside_root") {
+                    throw toolError.invalidInput(`extraction aborted: entry ${JSON.stringify(entry.path)} would be written outside the server root`, "Either the archive contains a traversal path, or the destination directory contains a symlink that leaves the sandbox. Nothing was written.");
+                }
+                throw cause;
+            }
+        }
+        // Decrypt/decompress every selected entry into a private staging directory
+        // before installing any output. A wrong password or corrupt late entry can
+        // then fail without leaving a half-extracted tree.
+        await ensureParent(target);
+        const staging = await mkdtemp(path.join(path.dirname(target), ".documonster-extract-"));
+        try {
+            for (const [stagingIndex, entry] of selected.entries()) {
+                if (entry.isDirectory) {
+                    continue;
+                }
+                let bytes;
+                try {
+                    bytes = await archive.readEntry(entry.path, args.password);
+                }
+                catch (cause) {
+                    const message = cause instanceof Error ? cause.message : String(cause);
+                    throw toolError.unsupported(`could not read entry ${JSON.stringify(entry.path)}: ${message}`, /password|encrypt|decrypt/i.test(message)
+                        ? "The archive is encrypted; pass `password`. Nothing was written."
+                        : "Nothing was written.", { cause });
+                }
+                if (bytes === null) {
+                    warnings.push(`${entry.path}: no data (skipped)`);
+                    destinations.delete(entry.path);
+                    continue;
+                }
+                // The numeric directory makes duplicate basenames (`a/x.txt`,
+                // `b/x.txt`) distinct in staging.
+                const staged = path.join(staging, String(stagingIndex), path.basename(entry.path));
+                await ensureParent(staged);
+                await writeFile(staged, bytes);
+                destinations.set(entry.path, `${destinations.get(entry.path)}\0${staged}`);
+                bytesWritten += bytes.byteLength;
+            }
+            for (const encoded of destinations.values()) {
+                const separator = encoded.indexOf("\0");
+                const destination = encoded.slice(0, separator);
+                const staged = encoded.slice(separator + 1);
+                await writeWithPolicy(destination, args.overwrite === true, temporary => copyFile(staged, temporary));
+                written += 1;
+            }
+        }
+        finally {
+            await rm(staging, { recursive: true, force: true });
+        }
+        const lines = [
+            `Extracted **${written}** entr${written === 1 ? "y" : "ies"} from ${args.path} to @output/${args.out}/`,
+            `- total written: ${formatBytes(bytesWritten)}`,
+            "- symlink and special entries were skipped, and file modes were not preserved",
+            "",
+            ...selected
+                .filter(entry => !entry.isDirectory)
+                .slice(0, MAX_LISTED)
+                .map(entry => `- \`@output/${path.posix.join(args.out ?? "", entry.path)}\` — ${formatBytes(entry.size)}`)
+        ];
+        if (selected.length > MAX_LISTED) {
+            lines.push(`- [${selected.length - MAX_LISTED} more not listed]`);
+        }
+        if (warnings.length > 0) {
+            lines.push("", "Warnings:", ...warnings.slice(0, 20).map(warning => `- ${warning}`));
+        }
+        lines.push("", "Inspect an extracted file with doc_inspect before reading it.");
+        return textResult(config, lines.join("\n"));
+    }
+});
+async function open(archivePath, displayPath, format, password) {
+    const resolvedFormat = format ?? inferFormat(archivePath);
+    try {
+        if (resolvedFormat === "tar") {
+            return await ArchiveFile.fromFile(archivePath, { format: "tar" });
+        }
+        return await ArchiveFile.fromFile(archivePath, password === undefined ? {} : { password });
+    }
+    catch (cause) {
+        throw toolError.unsupported(`could not open ${displayPath} as a ${resolvedFormat} archive`, "Run doc_inspect to confirm the container format, and pass `format` explicitly if the extension is misleading.", { cause });
+    }
+}
+/** `.tar` / `.tgz` / `.tar.gz` are tar; everything else is treated as zip. */
+function inferFormat(archivePath) {
+    const lower = archivePath.toLowerCase();
+    return lower.endsWith(".tar") || lower.endsWith(".tgz") || lower.endsWith(".tar.gz")
+        ? "tar"
+        : "zip";
+}
+/** Entry paths whose ZIP type is not a regular file or directory. */
+async function zipSpecialEntries(archivePath, password) {
+    const reader = Archive.unzip(new Uint8Array(await readFile(archivePath)), {
+        ...(password === undefined ? {} : { password })
+    });
+    const special = new Set();
+    for await (const entry of reader.entries()) {
+        if (entry.type !== "file" && entry.type !== "directory") {
+            special.add(entry.path);
+        }
+        entry.discard();
+    }
+    return special;
+}
+/** TAR exposes its special-entry type on the format-neutral info object. */
+function tarSpecialEntries(entries) {
+    return new Set(entries
+        .filter(entry => {
+        const type = entry.type;
+        return type !== undefined && type !== "file" && type !== "directory";
+    })
+        .map(entry => entry.path));
+}
+function describeEntries(displayPath, entries) {
+    const files = entries.filter(entry => !entry.isDirectory);
+    const lines = [
+        `# Archive: ${displayPath}`,
+        "",
+        `- entries: ${entries.length} (${files.length} file(s))`,
+        `- total uncompressed: ${formatBytes(totalSize(files))}`,
+        ""
+    ];
+    lines.push("| entry | size |", "| --- | --- |");
+    for (const entry of entries.slice(0, MAX_LISTED)) {
+        lines.push(`| \`${entry.path}${entry.isDirectory ? "/" : ""}\` | ${entry.isDirectory ? "—" : formatBytes(entry.size)} |`);
+    }
+    if (entries.length > MAX_LISTED) {
+        lines.push("", `[${entries.length - MAX_LISTED} more entries not listed]`);
+    }
+    lines.push("", 'Extract what you need with `action: "extract"` and an `out` directory.');
+    return lines.join("\n");
+}
+function totalSize(entries) {
+    return entries.reduce((sum, entry) => sum + (entry.isDirectory ? 0 : entry.size), 0);
+}
+/**
+ * Refuse a decompression bomb before writing anything.
+ *
+ * Sizes come from the archive's own directory, so a lying archive could still
+ * under-report; the per-entry check against `--max-file-size` limits the damage
+ * a single entry can do, and the total is what stops a thousand small ones.
+ */
+function assertNoBomb(entries, config) {
+    if (entries.length > MAX_ENTRIES) {
+        throw toolError.tooLarge(`the selection has ${entries.length} entries, over the ${MAX_ENTRIES} limit`, "Narrow the `entries` filter to the files you actually need.");
+    }
+    const total = totalSize(entries);
+    if (total > MAX_TOTAL_EXTRACTED) {
+        throw toolError.tooLarge(`extracting would write ${formatBytes(total)}, over the ${formatBytes(MAX_TOTAL_EXTRACTED)} limit`, "Narrow the `entries` filter.");
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory && entry.size > config.maxFileSize) {
+            throw toolError.tooLarge(`entry ${JSON.stringify(entry.path)} is ${formatBytes(entry.size)}, over the per-file limit of ${formatBytes(config.maxFileSize)}`, "Exclude it, or ask the user to raise --max-file-size.");
+        }
+    }
+}
+/**
+ * Match an entry against caller-supplied selectors.
+ *
+ * Supports exact paths, `dir/` prefixes and `*.ext` suffixes — the three shapes
+ * a model reaches for. Not a full glob, and deliberately so: a half-working
+ * glob is worse than a documented small set.
+ */
+function matches(entryPath, selectors) {
+    return selectors.some(selector => {
+        if (selector.startsWith("*.")) {
+            return entryPath.toLowerCase().endsWith(selector.slice(1).toLowerCase());
+        }
+        if (selector.endsWith("/")) {
+            return entryPath.startsWith(selector);
+        }
+        return entryPath === selector;
+    });
+}
+//# sourceMappingURL=archive-read.js.map

package/dist/tools/archive-read.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-read.js","sourceRoot":"","sources":["../../src/tools/archive-read.ts"],"names":[],"mappings":"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"}

package/dist/tools/archive-write.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `archive_write` — package files into an archive.
+ *
+ * Closes the loop that `archive_read` opens. A session that unpacked an archive,
+ * analysed it and produced several outputs needs to hand back one file, and a
+ * model cannot assemble a binary container itself. Small tool, high value.
+ */
+export declare const archiveWriteTool: import("./types.js").AnyToolDefinition;
+//# sourceMappingURL=archive-write.d.ts.map

package/dist/tools/archive-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-write.d.ts","sourceRoot":"","sources":["../../src/tools/archive-write.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAqBH,eAAO,MAAM,gBAAgB,wCA8H3B,CAAC"}

package/dist/tools/archive-write.js

@@ -0,0 +1,219 @@
+/**
+ * `archive_write` — package files into an archive.
+ *
+ * Closes the loop that `archive_read` opens. A session that unpacked an archive,
+ * analysed it and produced several outputs needs to hand back one file, and a
+ * model cannot assemble a binary container itself. Small tool, high value.
+ */
+import { readdir, stat } from "node:fs/promises";
+import path from "node:path";
+import { ArchiveFile } from "documonster/archive";
+import { z } from "zod";
+import { toolError } from "../errors.js";
+import { assertWritable, outputDisplay, resolveInRoot, resolveOutputPath } from "../sandbox.js";
+import { writeWithPolicy } from "./fs-helpers.js";
+import { formatBytes, textResult } from "./result.js";
+import { defineTool } from "./types.js";
+/** Files one archive may contain. */
+const MAX_FILES = 5_000;
+/** Total input bytes allowed in one archive (512 MiB). */
+const MAX_TOTAL_INPUT = 512 * 1024 * 1024;
+export const archiveWriteTool = defineTool({
+    name: "archive_write",
+    group: "archive",
+    title: "Create an archive",
+    description: "Package files and directories into a .zip or .tar. Use it to hand a set of produced documents back as one file. Directories are added recursively. Every input must be inside the server root.",
+    inputSchema: {
+        out: z
+            .string()
+            .min(1)
+            .describe("Archive path to create below --output-root. The result is returned as @output/<path>. The extension chooses .zip or .tar."),
+        entries: z
+            .array(z.object({
+            path: z
+                .string()
+                .min(1)
+                .describe("File or directory to add, relative to the server root."),
+            as: z
+                .string()
+                .optional()
+                .describe("Name inside the archive. For a directory this is the prefix. Defaults to the base name.")
+        }))
+            .min(1)
+            .describe("Files and directories to include."),
+        overwrite: z
+            .boolean()
+            .optional()
+            .describe("Replace the archive if it exists. Defaults to false.")
+    },
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false
+    },
+    mutates: true,
+    handler: async (args, context) => {
+        const { config } = context;
+        assertWritable(config);
+        const format = formatFor(args.out);
+        const target = await resolveOutputPath(config, args.out);
+        // Resolve and measure everything before creating the archive, so a bad
+        // entry fails before any file is written.
+        //
+        // Entry names are validated too: an archive is data we hand to someone else,
+        // and `as: "../../escape.txt"` would make this tool the *producer* of a Zip
+        // Slip payload. Neither the ZIP nor the TAR writer rejects it.
+        const resolvedEntries = await Promise.all(args.entries.map(async (entry) => {
+            const resolved = await resolveInRoot(config, entry.path, { mustExist: true });
+            const stats = await stat(resolved);
+            return {
+                resolved,
+                display: entry.path,
+                name: assertSafeEntryName(entry.as ?? path.basename(entry.path)),
+                isDirectory: stats.isDirectory(),
+                size: stats.isDirectory() ? 0 : stats.size
+            };
+        }));
+        await assertWithinBudget(resolvedEntries, config);
+        // Branch rather than holding a union: ArchiveFile is generic in its format,
+        // and `ArchiveFile<"zip"> | ArchiveFile<"tar">` collapses to `never` on any
+        // shared method because the `format` field conflicts.
+        try {
+            // "overwrite" is safe here only because the archive is built into a
+            // temporary sibling and renamed into place; the caller's `overwrite: false`
+            // was enforced above, and the rename is what makes the replacement atomic
+            // rather than a truncate-then-fill.
+            await writeWithPolicy(target, args.overwrite === true, async (temporary) => {
+                if (format === "tar") {
+                    const archive = new ArchiveFile({ format: "tar" });
+                    addAll(archive, resolvedEntries);
+                    await archive.writeToFile(temporary, { overwrite: "overwrite" });
+                }
+                else {
+                    const archive = new ArchiveFile();
+                    addAll(archive, resolvedEntries);
+                    await archive.writeToFile(temporary, { overwrite: "overwrite" });
+                }
+            });
+        }
+        catch (cause) {
+            throw toolError.unsupported(`could not write the archive: ${cause instanceof Error ? cause.message : String(cause)}`, undefined, { cause });
+        }
+        // Read it back and report the real entry list — "wrote 4 KB" says nothing
+        // about whether the archive contains what was intended.
+        const entries = format === "tar"
+            ? await (await ArchiveFile.fromFile(target, { format: "tar" })).getEntries()
+            : await (await ArchiveFile.fromFile(target)).getEntries();
+        const files = entries.filter(entry => !entry.isDirectory);
+        const size = (await stat(target)).size;
+        return textResult(config, [
+            `Created **${outputDisplay(args.out)}** (${format}, ${formatBytes(size)}) containing ${files.length} file(s).`,
+            "",
+            "| entry | size |",
+            "| --- | --- |",
+            ...entries
+                .slice(0, 200)
+                .map(entry => `| \`${entry.path}${entry.isDirectory ? "/" : ""}\` | ${entry.isDirectory ? "—" : formatBytes(entry.size)} |`),
+            ...(entries.length > 200 ? ["", `[${entries.length - 200} more not listed]`] : []),
+            "",
+            "Verified by reading the archive back."
+        ].join("\n"));
+    }
+});
+/**
+ * Reject an archive entry name that would escape on extraction.
+ *
+ * Absolute paths, `..` segments and Windows drive letters are all refused, and
+ * separators are normalised to the forward slashes an archive uses.
+ */
+function assertSafeEntryName(name) {
+    const normalised = name.replace(/\\/g, "/").replace(/^\/+/, "").trim();
+    if (normalised.length === 0) {
+        throw toolError.invalidInput("an entry name cannot be empty");
+    }
+    if (/^[a-zA-Z]:/.test(normalised)) {
+        throw toolError.invalidInput(`entry name ${JSON.stringify(name)} must not be an absolute Windows path`);
+    }
+    if (normalised.split("/").some(segment => segment === "..")) {
+        throw toolError.invalidInput(`entry name ${JSON.stringify(name)} must not contain ".."`, "Entry names are relative paths inside the archive. A `..` would make the archive unsafe for whoever extracts it.");
+    }
+    return normalised;
+}
+/** `.tar` is tar; `.zip` is zip; anything else is rejected by name. */
+function formatFor(out) {
+    const extension = path.extname(out).toLowerCase();
+    if (extension === ".tar") {
+        return "tar";
+    }
+    if (extension === ".zip") {
+        return "zip";
+    }
+    throw toolError.invalidInput(`cannot tell the archive format from ${JSON.stringify(out)}`, "Use a .zip or .tar extension. Compressed tarballs (.tar.gz) are not produced yet.");
+}
+/** Add every entry to an archive of either format. */
+function addAll(archive, entries) {
+    for (const entry of entries) {
+        if (entry.isDirectory) {
+            archive.addDirectory(entry.resolved, { prefix: entry.name });
+        }
+        else {
+            archive.addFile(entry.resolved, { name: entry.name });
+        }
+    }
+}
+/**
+ * Refuse an archive that would read too much.
+ *
+ * Directories are walked to measure them, because "add this directory" is how a
+ * caller accidentally packages a whole workspace.
+ */
+async function assertWithinBudget(entries, config) {
+    let total = 0;
+    let count = 0;
+    for (const entry of entries) {
+        if (entry.isDirectory) {
+            // The per-file cap applies inside a directory as well: "add this folder"
+            // is exactly how a caller accidentally packages one enormous file.
+            const walked = await measureDirectory(entry.resolved, config, entry.display);
+            total += walked.bytes;
+            count += walked.files;
+        }
+        else {
+            if (entry.size > config.maxFileSize) {
+                throw toolError.tooLarge(`${entry.display} is ${formatBytes(entry.size)}, over the per-file limit of ${formatBytes(config.maxFileSize)}`, "Exclude it, or ask the user to raise --max-file-size.");
+            }
+            total += entry.size;
+            count += 1;
+        }
+        if (count > MAX_FILES) {
+            throw toolError.tooLarge(`the selection contains more than ${MAX_FILES} files`, "Name specific files or a narrower directory.");
+        }
+        if (total > MAX_TOTAL_INPUT) {
+            throw toolError.tooLarge(`the selection totals more than ${formatBytes(MAX_TOTAL_INPUT)}`, "Name specific files or a narrower directory.");
+        }
+    }
+}
+async function measureDirectory(dir, config, display) {
+    let bytes = 0;
+    let files = 0;
+    const walk = async (current) => {
+        for (const item of await readdir(current, { withFileTypes: true })) {
+            const full = path.join(current, item.name);
+            if (item.isDirectory()) {
+                await walk(full);
+            }
+            else if (item.isFile()) {
+                const size = (await stat(full)).size;
+                if (size > config.maxFileSize) {
+                    throw toolError.tooLarge(`${display}/${path.relative(dir, full)} is ${formatBytes(size)}, over the per-file limit of ${formatBytes(config.maxFileSize)}`, "Name specific files instead of the whole directory, or ask the user to raise --max-file-size.");
+                }
+                files += 1;
+                bytes += size;
+            }
+        }
+    };
+    await walk(dir);
+    return { bytes, files };
+}
+//# sourceMappingURL=archive-write.js.map

package/dist/tools/archive-write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-write.js","sourceRoot":"","sources":["../../src/tools/archive-write.ts"],"names":[],"mappings":"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"}