folderview 0.0.0-stage → 0.2.1

package/dist/server.js

@@ -0,0 +1,482 @@
+// The HTTP server: the page, the folder API, git, search, review comments and live-reload events.
+import http from 'node:http';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import crypto from 'node:crypto';
+import { NOISE, RAW_TYPES, inside, isHidden, list, serveRaw, toRel } from './files.js';
+import { excluder, parseRules } from './glob.js';
+import { writeZip, ZIP_LIMITS } from './zip.js';
+import { Git } from './git.js';
+import { FileIndex } from './search.js';
+import { Review, agentPrompt } from './review.js';
+import { watchTree } from './watch.js';
+const here = path.dirname(fileURLToPath(import.meta.url));
+const clientDir = path.resolve(here, 'client');
+const version = readVersion();
+const STATIC = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.woff2': 'font/woff2',
+    '.woff': 'font/woff',
+    '.ttf': 'font/ttf',
+};
+export async function start(opts) {
+    const root = path.resolve(opts.root);
+    const scope = {
+        root,
+        hidden: new Set(['.git', ...(opts.hide ?? [])]),
+        hideSecrets: !opts.showSecrets,
+        excluded: excluder(parseRules(opts.exclude ?? [])),
+    };
+    const git = opts.git ? await Git.open(root) : undefined;
+    const base = opts.base ?? '/';
+    const token = opts.token ?? '';
+    const maxFile = (opts.maxFileMb ?? 5) * 1048576;
+    const index = new FileIndex(scope, git, (opts.maxFileMb ?? 5) * 1048576);
+    const review = new Review(path.resolve(root, opts.reviewDir), root);
+    const reviewRel = toRel(scope, review.jsonPath);
+    const author = opts.author || (git && (await git.userName())) || os.userInfo().username || 'reviewer';
+    const visible = (rel) => !rel.split('/').some((p) => isHidden(scope, p)) && !scope.excluded(rel);
+    // ── live events ──
+    const clients = new Set();
+    const broadcast = (type, data) => {
+        const msg = `event: ${type}\ndata: ${JSON.stringify(data)}\n\n`;
+        for (const c of clients)
+            c.write(msg);
+    };
+    let status;
+    // the review notes are ours, not the project's: keep them out of the changes
+    const reviewPrefix = reviewRel.startsWith('..') ? '' : toRel(scope, review.dir) + '/';
+    const gitStatus = () => (status ??= git
+        ? git.status().then((s) => ({
+            ...s,
+            changes: s.changes.filter((c) => (!reviewPrefix || !c.path.startsWith(reviewPrefix)) && visible(c.path)),
+            ignored: s.ignored.filter((i) => visible(i.replace(/\/$/, ''))),
+        }))
+        : Promise.reject(new Error('not a git repository')));
+    const stopWatch = opts.watch
+        ? watchTree(root, git ? path.join(git.top, '.git') : undefined, (b) => {
+            if (b.git)
+                status = undefined;
+            if (b.folders.length || b.files.length)
+                index.invalidate();
+            broadcast('change', b);
+        })
+        : () => undefined;
+    review.onChange(() => {
+        broadcast('comments', { count: review.all().length });
+        opts.onReviewChange?.(review.all().filter((c) => c.status === 'open').length, review.all().length);
+    });
+    review.watch();
+    const ping = setInterval(() => {
+        for (const c of clients)
+            c.write(': ping\n\n');
+    }, 25_000);
+    ping.unref();
+    const allowed = allowedHosts(opts);
+    const server = http.createServer((req, res) => {
+        handle(req, res).catch((err) => {
+            if (!res.headersSent)
+                json(res, 500, { error: err instanceof Error ? err.message : String(err) });
+            else
+                res.end();
+        });
+    });
+    async function handle(req, res) {
+        // DNS rebinding: a page on another site that resolves its name to this machine is refused
+        const host = (req.headers.host ?? '').replace(/:\d+$/, '').replace(/^\[|\]$/g, '').toLowerCase();
+        if (!allowed(host))
+            return json(res, 403, { error: `Host "${host}" is not allowed. Start with --allow-host ${host} to allow it.` });
+        const url = new URL(req.url ?? '/', 'http://x');
+        // served under a path (behind a proxy): everything lives below it
+        if (base !== '/') {
+            if (url.pathname === base.slice(0, -1))
+                return void res.writeHead(301, { location: base + url.search }).end();
+            if (!url.pathname.startsWith(base))
+                return json(res, 404, { error: 'not found' });
+        }
+        const p = '/' + url.pathname.slice(base.length);
+        // a token: once in the address (it becomes a cookie), as a bearer header, or the cookie
+        if (token) {
+            const given = url.searchParams.get('token') ?? bearer(req) ?? cookie(req, 'folderview_token') ?? '';
+            if (!same(given, token)) {
+                if (p === '/' || p === '/index.html')
+                    return void res.writeHead(401, { 'content-type': 'text/html; charset=utf-8' }).end(LOCKED);
+                return json(res, 401, { error: 'This folderview needs its token: open the link with ?token=… once.' });
+            }
+            if (url.searchParams.has('token')) {
+                // keep it as a cookie and take it out of the address bar
+                url.searchParams.delete('token');
+                res.setHeader('set-cookie', `folderview_token=${encodeURIComponent(token)}; Path=${base}; HttpOnly; SameSite=Strict; Max-Age=31536000`);
+                if (p === '/' || p === '/index.html')
+                    return void res.writeHead(302, { location: base + (url.search || '') }).end();
+            }
+        }
+        const q = (k) => url.searchParams.get(k) ?? '';
+        const method = req.method ?? 'GET';
+        if (method !== 'GET' && method !== 'HEAD') {
+            // writes come only from this page: a JSON body and our own origin
+            const origin = req.headers.origin;
+            if (origin && new URL(origin).host !== req.headers.host)
+                return json(res, 403, { error: 'Cross-origin write refused' });
+            if (opts.readOnly)
+                return json(res, 403, { error: 'This folderview is read-only' });
+        }
+        if (p === '/' || p === '/index.html')
+            return sendStatic(res, path.join(clientDir, 'index.html'));
+        if (p.startsWith('/assets/')) {
+            const abs = path.resolve(clientDir, '.' + p);
+            if (!abs.startsWith(clientDir + path.sep))
+                return json(res, 404, { error: 'not found' });
+            return sendStatic(res, abs);
+        }
+        if (p.startsWith('/raw/')) {
+            const rel = decodeURIComponent(p.slice(5));
+            if (q('download') === '1')
+                res.setHeader('content-disposition', disposition(path.basename(rel)));
+            return serveRaw(scope, rel, req, res, q('as') === 'page');
+        }
+        if (p === '/api/zip')
+            return zipFolder(q('p'), res);
+        if (p === '/api/info') {
+            return json(res, 200, {
+                name: opts.title || path.basename(root) || root,
+                // the home folder as ~, so a shared screen or screenshot doesn't show the user's account name
+                root: root.startsWith(os.homedir()) ? '~' + root.slice(os.homedir().length) : root,
+                version,
+                git: !!git,
+                gitPrefix: git?.prefix ?? '',
+                author,
+                readOnly: opts.readOnly,
+                review: {
+                    json: reviewRel,
+                    md: toRel(scope, review.mdPath),
+                    dir: opts.reviewLabel ?? opts.reviewDir,
+                    prompt: agentPrompt(toRel(scope, review.mdPath), reviewRel),
+                },
+                hostname: os.hostname(),
+                maxFile,
+                token: !!token,
+            });
+        }
+        if (p === '/api/list') {
+            const entries = list(scope, q('p'));
+            return entries ? json(res, 200, { entries }) : json(res, 404, { error: 'No such folder' });
+        }
+        if (p === '/api/stat') {
+            const abs = inside(scope, q('p'));
+            if (!abs || !fs.existsSync(abs))
+                return json(res, 404, { error: 'not found' });
+            const st = fs.statSync(abs);
+            return json(res, 200, { type: st.isDirectory() ? 'folder' : 'file', size: st.size, mtime: st.mtimeMs });
+        }
+        if (p === '/api/files')
+            return json(res, 200, { files: await index.files() });
+        if (p === '/api/search') {
+            if (!q('q'))
+                return json(res, 400, { error: 'Nothing to search for' });
+            const result = await index.search({
+                q: q('q'),
+                scope: q('scope'),
+                regex: q('regex') === '1',
+                caseSensitive: q('case') === '1',
+                word: q('word') === '1',
+                include: q('include'),
+            });
+            // the review notes would match every word that was commented on: leave them out
+            if (reviewPrefix)
+                result.files = result.files.filter((f) => !f.path.startsWith(reviewPrefix));
+            return json(res, 200, result);
+        }
+        if (p.startsWith('/api/git/')) {
+            if (!git)
+                return json(res, 404, { error: 'Not a git repository' });
+            const rel = q('p');
+            if (p !== '/api/git/status' && inside(scope, rel) === undefined)
+                return json(res, 404, { error: 'not found' });
+            switch (p) {
+                case '/api/git/status':
+                    return json(res, 200, await gitStatus());
+                case '/api/git/diff':
+                    return text(res, await git.diff(rel));
+                case '/api/git/show': {
+                    const rev = q('rev') || 'HEAD';
+                    if (!isRev(rev))
+                        return json(res, 400, { error: 'bad revision' });
+                    return text(res, await git.show(rel, rev));
+                }
+                case '/api/git/raw': {
+                    const rev = q('rev') || 'HEAD';
+                    if (!isRev(rev))
+                        return json(res, 400, { error: 'bad revision' });
+                    const buf = await git.showRaw(rel, rev);
+                    const ext = path.extname(rel).slice(1).toLowerCase();
+                    res.writeHead(200, { 'content-type': RAW_TYPES[ext] ?? 'application/octet-stream', 'cache-control': 'no-store', 'content-security-policy': "default-src 'none'; style-src 'unsafe-inline'", 'x-content-type-options': 'nosniff' });
+                    return void res.end(buf);
+                }
+                case '/api/git/log':
+                    {
+                        // a page of the file's commits, and whether there are more
+                        const all = await git.log(rel, 31, Math.max(0, Number(q('skip')) || 0));
+                        return json(res, 200, { commits: all.slice(0, 30), more: all.length > 30 });
+                    }
+                case '/api/git/history':
+                    return json(res, 200, await git.history(Math.max(0, Number(q('skip')) || 0), 50, q('q').trim().slice(0, 200)));
+                case '/api/git/commit-info': {
+                    const h = q('h');
+                    if (!isRev(h))
+                        return json(res, 400, { error: 'bad revision' });
+                    const info = await git.commitInfo(h);
+                    info.files = info.files.filter((f) => visible(f.path) && (!reviewPrefix || !f.path.startsWith(reviewPrefix)));
+                    return json(res, 200, info);
+                }
+                case '/api/git/commit-diff': {
+                    const h = q('h');
+                    const from = q('from');
+                    if (!isRev(h))
+                        return json(res, 400, { error: 'bad revision' });
+                    if (from && inside(scope, from) === undefined)
+                        return json(res, 404, { error: 'not found' });
+                    return text(res, await git.commitFileDiff(h, rel, from || undefined));
+                }
+                case '/api/git/commit': {
+                    const h = q('h');
+                    if (!isRev(h))
+                        return json(res, 400, { error: 'bad revision' });
+                    return text(res, await git.commitDiff(rel, h));
+                }
+            }
+            return json(res, 404, { error: 'not found' });
+        }
+        if (p === '/api/review.md') {
+            return text(res, fs.existsSync(review.mdPath) ? fs.readFileSync(review.mdPath, 'utf8') : 'No comments yet.\n', 'text/markdown; charset=utf-8');
+        }
+        if (p === '/api/comments' && method === 'GET')
+            return json(res, 200, { comments: review.all() });
+        const img = /^\/api\/comments\/([0-9a-f]+)\/image\.png$/.exec(p);
+        if (img) {
+            const abs = review.imagePath(img[1] ?? '');
+            if (!abs)
+                return json(res, 404, { error: 'not found' });
+            res.writeHead(200, { 'content-type': 'image/png', 'cache-control': 'no-store', 'x-content-type-options': 'nosniff' });
+            return void fs.createReadStream(abs).pipe(res);
+        }
+        if (p === '/api/comments' && method === 'POST') {
+            const b = await body(req, 16_000_000);
+            const rel = str(b['path']);
+            if (inside(scope, rel) === undefined)
+                return json(res, 400, { error: 'No such file' });
+            if (!str(b['body']).trim())
+                return json(res, 400, { error: 'The comment is empty' });
+            const line = num(b['line']), endLine = num(b['endLine']);
+            const c = review.add({
+                path: rel,
+                body: str(b['body']),
+                author: str(b['author']) || author,
+                ...(line ? { line } : {}),
+                ...(endLine ? { endLine } : {}),
+                ...imageMarks(b),
+                ...(git ? { commit: (await gitStatus().catch(() => undefined))?.head ?? '' } : {}),
+            });
+            return json(res, 201, c);
+        }
+        if (p === '/api/comments' && method === 'DELETE' && q('resolved') === '1')
+            return json(res, 200, { removed: review.clearResolved() });
+        const m = /^\/api\/comments\/([0-9a-f]+)(\/replies)?$/.exec(p);
+        if (m) {
+            const id = m[1] ?? '';
+            if (m[2] && method === 'POST') {
+                const b = await body(req);
+                const c = review.reply(id, str(b['author']) || author, str(b['body']));
+                return c ? json(res, 200, c) : json(res, 404, { error: 'not found' });
+            }
+            if (method === 'PATCH') {
+                const b = await body(req);
+                const s = str(b['status']);
+                const patch = {};
+                if (typeof b['body'] === 'string')
+                    patch.body = b['body'];
+                if (s === 'open' || s === 'resolved')
+                    patch.status = s;
+                const c = review.update(id, patch);
+                return c ? json(res, 200, c) : json(res, 404, { error: 'not found' });
+            }
+            if (method === 'DELETE')
+                return review.remove(id) ? json(res, 200, { ok: true }) : json(res, 404, { error: 'not found' });
+        }
+        if (p === '/api/events') {
+            res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-store', connection: 'keep-alive' });
+            res.write(`event: hello\ndata: {"watch":${opts.watch}}\n\n`);
+            clients.add(res);
+            req.on('close', () => clients.delete(res));
+            return;
+        }
+        json(res, 404, { error: 'not found' });
+    }
+    /** a folder as a zip: what the listing shows (no hidden, excluded or noise folders), within the zip limits */
+    async function zipFolder(rel, res) {
+        const abs = inside(scope, rel);
+        if (!abs || !fs.existsSync(abs) || !fs.statSync(abs).isDirectory())
+            return json(res, 404, { error: 'No such folder' });
+        const name = rel ? path.basename(abs) : path.basename(root) || 'folder';
+        const files = [];
+        let bytes = 0;
+        const stack = [rel];
+        while (stack.length) {
+            const dir = stack.pop() ?? '';
+            for (const e of list(scope, dir) ?? []) {
+                const child = dir ? dir + '/' + e.name : e.name;
+                if (e.type === 'folder') {
+                    if (!NOISE.has(e.name))
+                        stack.push(child);
+                    continue;
+                }
+                bytes += e.size;
+                files.push({ abs: path.join(root, child), name: path.posix.join(name, rel ? child.slice(rel.length + 1) : child) });
+            }
+            if (files.length > ZIP_LIMITS.files || bytes > ZIP_LIMITS.bytes)
+                return json(res, 413, { error: `Too big to zip here (${files.length.toLocaleString()} files, ${Math.round(bytes / 1048576)} MB so far)` });
+        }
+        files.sort((a, b) => a.name.localeCompare(b.name));
+        res.writeHead(200, { 'content-type': 'application/zip', 'content-disposition': disposition(name + '.zip'), 'cache-control': 'no-store' });
+        await writeZip(res, files);
+        res.end();
+    }
+    const port = await listen(server, opts.port, opts.host);
+    return {
+        server,
+        port,
+        close: async () => {
+            stopWatch();
+            review.close();
+            clearInterval(ping);
+            for (const c of clients)
+                c.end();
+            await new Promise((r) => server.close(() => r()));
+        },
+    };
+}
+/** listen on the port, or the next free one */
+function listen(server, port, host, tries = 20) {
+    return new Promise((resolve, reject) => {
+        const onError = (err) => {
+            server.off('listening', onListening);
+            if (err.code === 'EADDRINUSE' && tries > 1 && port !== 0)
+                resolve(listen(server, port + 1, host, tries - 1));
+            else
+                reject(err);
+        };
+        const onListening = () => {
+            server.off('error', onError);
+            const a = server.address();
+            resolve(typeof a === 'object' && a ? a.port : port);
+        };
+        server.once('error', onError);
+        server.once('listening', onListening);
+        server.listen(port, host);
+    });
+}
+const LOCKED = '<!doctype html><meta name="viewport" content="width=device-width"><title>folderview</title><body style="font:16px system-ui;padding:2em;max-width:36em;margin:auto"><h1>🔒 This folderview needs its token</h1><p>Open the link you were given (it ends in <code>?token=…</code>). It is kept as a cookie, so you only need it once.</p>';
+const bearer = (req) => /^Bearer (.+)$/i.exec(String(req.headers.authorization ?? ''))?.[1];
+const cookie = (req, name) => {
+    for (const part of String(req.headers.cookie ?? '').split(';')) {
+        const [k, ...v] = part.trim().split('=');
+        if (k === name)
+            return decodeURIComponent(v.join('='));
+    }
+    return undefined;
+};
+function same(a, b) {
+    const x = crypto.createHash('sha256').update(a).digest();
+    const y = crypto.createHash('sha256').update(b).digest();
+    return crypto.timingSafeEqual(x, y);
+}
+const disposition = (name) => `attachment; filename="${name.replace(/[^\x20-\x7e]|["\\]/g, '_')}"; filename*=UTF-8''${encodeURIComponent(name)}`;
+function allowedHosts(opts) {
+    const names = new Set(['localhost', os.hostname().toLowerCase(), ...opts.allowHosts.map((h) => h.toLowerCase())]);
+    if (opts.host !== '0.0.0.0' && opts.host !== '::')
+        names.add(opts.host.toLowerCase());
+    return (h) => names.has(h) ||
+        h.endsWith('.localhost') ||
+        /^\d{1,3}(\.\d{1,3}){3}$/.test(h) || // an IP address can't be rebound
+        h.includes(':') || // IPv6 literal
+        opts.allowHosts.includes('*');
+}
+function isRev(r) {
+    return /^[0-9a-f]{4,40}$/i.test(r) || /^HEAD(~\d{1,4}|\^)?$/.test(r);
+}
+function sendStatic(res, abs) {
+    fs.readFile(abs, (err, buf) => {
+        if (err)
+            return json(res, 404, { error: 'not found' });
+        res.writeHead(200, { 'content-type': STATIC[path.extname(abs)] ?? 'application/octet-stream', 'cache-control': 'no-store' }).end(buf);
+    });
+}
+function json(res, code, data) {
+    res.writeHead(code, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' }).end(JSON.stringify(data));
+}
+function text(res, body, type = 'text/plain; charset=utf-8') {
+    res.writeHead(200, { 'content-type': type, 'cache-control': 'no-store' }).end(body);
+}
+/** an image comment's marks: the area, the strokes, and the marked-up picture (a PNG data URL) */
+function imageMarks(b) {
+    const out = {};
+    const a = b['area'];
+    if (a && typeof a === 'object' && !Array.isArray(a)) {
+        const r = Object.fromEntries(Object.entries(a));
+        const n = (k) => (typeof r[k] === 'number' && Number.isFinite(r[k]) && Number(r[k]) >= 0 ? Math.round(Number(r[k])) : undefined);
+        const [x, y, w, h] = [n('x'), n('y'), n('w'), n('h')];
+        if (x !== undefined && y !== undefined && w && h)
+            out.area = { x, y, w, h };
+    }
+    const s = b['strokes'];
+    if (Array.isArray(s)) {
+        let budget = 20_000;
+        const strokes = s
+            .filter((st) => Array.isArray(st))
+            .map((st) => st.filter((v) => typeof v === 'number' && v >= 0 && v <= 1).map((v) => Math.round(v * 10000) / 10000))
+            .filter((st) => st.length >= 2 && st.length % 2 === 0 && (budget -= st.length) >= 0);
+        if (strokes.length)
+            out.strokes = strokes;
+    }
+    const snap = typeof b['snapshot'] === 'string' ? /^data:image\/png;base64,([A-Za-z0-9+/=]+)$/.exec(b['snapshot']) : null;
+    if (snap && out.strokes) {
+        const buf = Buffer.from(snap[1] ?? '', 'base64');
+        // a PNG, and nothing else
+        if (buf.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])))
+            out.snapshot = buf;
+    }
+    return out;
+}
+async function body(req, max = 1_000_000) {
+    if (!String(req.headers['content-type'] ?? '').includes('application/json'))
+        throw new Error('Send JSON');
+    const chunks = [];
+    let size = 0;
+    for await (const c of req) {
+        const b = Buffer.isBuffer(c) ? c : Buffer.from(String(c));
+        size += b.length;
+        if (size > max)
+            throw new Error('Too large');
+        chunks.push(b);
+    }
+    const data = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}');
+    if (!data || typeof data !== 'object' || Array.isArray(data))
+        throw new Error('Send a JSON object');
+    return Object.fromEntries(Object.entries(data));
+}
+const str = (v) => (typeof v === 'string' ? v : '');
+const num = (v) => (typeof v === 'number' && Number.isInteger(v) && v > 0 ? v : undefined);
+function readVersion() {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.resolve(here, '..', 'package.json'), 'utf8'));
+        return pkg && typeof pkg === 'object' && 'version' in pkg ? String(pkg.version) : '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}

package/dist/watch.js

@@ -0,0 +1,69 @@
+// Live reload: watches the folder and tells open pages which folders changed (and when git's state may have).
+import fs from 'node:fs';
+import path from 'node:path';
+import { NOISE } from './files.js';
+export function watchTree(root, gitDir, onBatch) {
+    let folders = new Set(), files = new Set(), git = false;
+    let timer;
+    const flush = () => {
+        timer = undefined;
+        const b = { folders: [...folders], files: [...files], git };
+        folders = new Set();
+        files = new Set();
+        git = false;
+        onBatch(b);
+    };
+    const bump = () => {
+        timer ??= setTimeout(flush, 250);
+    };
+    const closers = [];
+    try {
+        const w = fs.watch(root, { recursive: true }, (_event, name) => {
+            if (!name)
+                return bump();
+            const rel = String(name).split(path.sep).join('/');
+            const parts = rel.split('/');
+            if (parts[0] === '.git') {
+                // the index, HEAD and refs say git's view moved; objects and logs are noise
+                if (/^\.git\/(index|HEAD|refs\/|packed-refs|MERGE_HEAD)/.test(rel)) {
+                    git = true;
+                    bump();
+                }
+                return;
+            }
+            if (parts.some((p) => NOISE.has(p)))
+                return;
+            files.add(rel);
+            folders.add(parts.slice(0, -1).join('/'));
+            git = true; // a working-tree edit changes git status too
+            bump();
+        });
+        w.on('error', () => undefined);
+        closers.push(() => w.close());
+    }
+    catch {
+        // recursive watching isn't available here: no live reload, the page still works on refresh
+    }
+    // a served subfolder of a repo: .git is elsewhere, watch it on its own
+    if (gitDir && !gitDir.startsWith(root + path.sep)) {
+        try {
+            const w = fs.watch(gitDir, (_e, name) => {
+                if (name && /^(index|HEAD|packed-refs)$/.test(String(name))) {
+                    git = true;
+                    bump();
+                }
+            });
+            w.on('error', () => undefined);
+            closers.push(() => w.close());
+        }
+        catch {
+            // fine without it
+        }
+    }
+    return () => {
+        for (const c of closers)
+            c();
+        if (timer)
+            clearTimeout(timer);
+    };
+}

package/dist/zip.js

@@ -0,0 +1,100 @@
+// A folder as a .zip, streamed: each file deflated (or stored, when that's smaller), no dependencies.
+// Plain ZIP (not ZIP64): up to 65,535 files and under 4 GB, which is checked before anything is sent.
+import fs from 'node:fs';
+import path from 'node:path';
+import zlib from 'node:zlib';
+const TABLE = (() => {
+    const t = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        t[n] = c >>> 0;
+    }
+    return t;
+})();
+export function crc32(buf) {
+    const native = zlib.crc32;
+    if (native)
+        return native(buf) >>> 0;
+    let c = 0xffffffff;
+    for (const b of buf)
+        c = (TABLE[(c ^ b) & 0xff] ?? 0) ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+export const ZIP_LIMITS = { files: 65_535, bytes: 2 * 1024 * 1024 * 1024 };
+function dosTime(d) {
+    const time = (d.getHours() << 11) | (d.getMinutes() << 5) | Math.floor(d.getSeconds() / 2);
+    const date = (Math.max(0, d.getFullYear() - 1980) << 9) | ((d.getMonth() + 1) << 5) | d.getDate();
+    return [time, date];
+}
+/** Write a zip of the given files (absolute path → name inside the zip) to out. */
+export async function writeZip(out, files) {
+    const central = [];
+    let offset = 0;
+    const write = (b) => new Promise((resolve, reject) => {
+        offset += b.length;
+        if (out.write(b))
+            resolve();
+        else {
+            out.once('drain', resolve);
+            out.once('error', reject);
+        }
+    });
+    for (const f of files) {
+        let data, st;
+        try {
+            st = await fs.promises.stat(f.abs);
+            data = await fs.promises.readFile(f.abs);
+        }
+        catch {
+            continue; // gone since it was listed
+        }
+        const crc = crc32(data);
+        const deflated = zlib.deflateRawSync(data, { level: 6 });
+        const store = deflated.length >= data.length;
+        const body = store ? data : deflated;
+        const name = Buffer.from(f.name, 'utf8');
+        const [time, date] = dosTime(st.mtime);
+        const local = Buffer.alloc(30);
+        local.writeUInt32LE(0x04034b50, 0);
+        local.writeUInt16LE(20, 4);
+        local.writeUInt16LE(0x0800, 6); // names are UTF-8
+        local.writeUInt16LE(store ? 0 : 8, 8);
+        local.writeUInt16LE(time, 10);
+        local.writeUInt16LE(date, 12);
+        local.writeUInt32LE(crc, 14);
+        local.writeUInt32LE(body.length, 18);
+        local.writeUInt32LE(data.length, 22);
+        local.writeUInt16LE(name.length, 26);
+        const at = offset;
+        await write(Buffer.concat([local, name]));
+        await write(body);
+        const cen = Buffer.alloc(46);
+        cen.writeUInt32LE(0x02014b50, 0);
+        cen.writeUInt16LE(20, 4);
+        cen.writeUInt16LE(20, 6);
+        cen.writeUInt16LE(0x0800, 8);
+        cen.writeUInt16LE(store ? 0 : 8, 10);
+        cen.writeUInt16LE(time, 12);
+        cen.writeUInt16LE(date, 14);
+        cen.writeUInt32LE(crc, 16);
+        cen.writeUInt32LE(body.length, 20);
+        cen.writeUInt32LE(data.length, 24);
+        cen.writeUInt16LE(name.length, 28);
+        cen.writeUInt32LE(at, 42);
+        central.push(Buffer.concat([cen, name]));
+    }
+    const start = offset;
+    const dir = Buffer.concat(central);
+    await write(dir);
+    const end = Buffer.alloc(22);
+    end.writeUInt32LE(0x06054b50, 0);
+    end.writeUInt16LE(central.length, 8);
+    end.writeUInt16LE(central.length, 10);
+    end.writeUInt32LE(dir.length, 12);
+    end.writeUInt32LE(start, 16);
+    await write(end);
+}
+/** A zip-safe name for a root-relative path inside a folder being zipped. */
+export const entryName = (folderName, rel) => path.posix.join(folderName, rel);