@entrinsik/vite-plugin-informer 2.7.0 → 2.11.0

package/src/dev-streams.js

@@ -0,0 +1,660 @@
+import { randomUUID } from 'node:crypto';
+import { extname } from 'node:path';
+
+/**
+ * Dev-mode app streams (I5-12979) — the local stand-in for the production
+ * harness's staged uploads/downloads:
+ *
+ *   - production stages bytes in Redis (the updown resource store) behind
+ *     /apps/{id}/view/_uploads and /view/_downloads; here an in-memory store behind the
+ *     same-origin /_uploads and /_downloads the origin-mode client uses
+ *   - production's `uploads`/`downloads` bag services move bytes host-side
+ *     (COPY FROM STDIN, pg-query-stream); dev has no pg client, only the
+ *     `_sql` proxy `query()` rides on, so copyInto() is emulated as batched
+ *     parameterized INSERTs, a bytea query() parameter becomes a `\x…` hex
+ *     string (Postgres' text-format bytea input), and fromQuery() reads rows
+ *     through query() and encodes them locally
+ *
+ * The protocol, geometry rules, error statuses (412 + missing chunks, 409
+ * incomplete, 413 over the cap) and handle shapes mirror
+ * modules/app/lib/app-streams.js so an app that works here works deployed.
+ * The emulation gaps (no extractText, INSERT vs COPY semantics) are named in
+ * the errors and docs rather than papered over.
+ */
+
+const MB = 1024 * 1024;
+
+export const LIMITS = Object.freeze({
+    maxUploadBytes: 100 * MB,
+    ttlSeconds: 60 * 60,
+    maxInlineBytes: 10 * MB,
+    maxChunkBytes: 8 * MB,
+    maxStreamsPerUser: 32,
+    maxStagedBytesPerUser: 512 * MB
+});
+
+export const DEFAULT_CHUNK_BYTES = 4 * MB;
+
+const MIME = {
+    '.csv': 'text/csv', '.json': 'application/json', '.jsonl': 'application/x-ndjson', '.txt': 'text/plain',
+    '.html': 'text/html', '.xml': 'application/xml', '.pdf': 'application/pdf', '.png': 'image/png',
+    '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.svg': 'image/svg+xml', '.zip': 'application/zip',
+    '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
+};
+
+export function mimeFor(filename) {
+    return MIME[extname(filename || '').toLowerCase()] || null;
+}
+
+export function defaultContentType(format) {
+    return { csv: 'text/csv', json: 'application/json', jsonl: 'application/x-ndjson' }[format] || null;
+}
+
+/** An Error with the HTTP status (and optional data) the prod boom would carry. */
+export function httpError(status, message, data) {
+    const err = new Error(message);
+    err.statusCode = status;
+    if (data !== undefined) err.data = data;
+    return err;
+}
+
+// ---------------------------------------------------------------------------
+// Store
+// ---------------------------------------------------------------------------
+
+/**
+ * In-memory stream store. Uploads hold indexed chunks; downloads hold an
+ * append-only buffer list. Expiry is enforced lazily on access.
+ */
+export function createStreamStore(limits = LIMITS) {
+    const items = new Map();
+
+    function sweep(now = Date.now()) {
+        for (const [id, item] of items) {
+            if (item.expiresAt <= now) items.delete(id);
+        }
+    }
+
+    function touch(item) {
+        item.expiresAt = Date.now() + limits.ttlSeconds * 1000;
+        return item;
+    }
+
+    function create(type, props) {
+        const item = touch({
+            id: randomUUID(),
+            type,
+            filename: props.filename || null,
+            fingerprint: props.fingerprint || null,
+            contentType: props.contentType || null,
+            size: props.size || 0,
+            // What this stream counts for while it is staged: an upload's
+            // declared size, a download's ceiling until sealed (see reserve).
+            reserved: props.reserved || props.size || 0,
+            chunkSize: props.chunkSize || null,
+            chunks: props.chunks || 0,
+            complete: Boolean(props.complete),
+            chunkData: new Map(),
+            parts: [],
+            createdAt: Date.now()
+        });
+        items.set(item.id, item);
+        return item;
+    }
+
+    function get(type, id) {
+        sweep();
+        const item = items.get(id);
+        return item && item.type === type ? item : null;
+    }
+
+    function bytes(item) {
+        if (item.type === 'upload') {
+            const ordered = [];
+            for (let n = 1; n <= item.chunks; n++) ordered.push(item.chunkData.get(n) || Buffer.alloc(0));
+            return Buffer.concat(ordered);
+        }
+        return Buffer.concat(item.parts);
+    }
+
+    function remove(id) {
+        return items.delete(id);
+    }
+
+    /**
+     * The prod per-user staging ledger (app-streams.js#reserveStream). Dev has
+     * a single user, so everything in the store is their share: too many
+     * staged streams is 429, too many reserved bytes is 413, same data. Like
+     * prod, an open download is counted at the ceiling its meter allows until
+     * seal() trades that for what it actually wrote — so an author meets the
+     * same 413 here as deployed, rather than only after they ship.
+     */
+    function reserve(size = 0) {
+        sweep();
+        const staged = [...items.values()];
+        if (staged.length >= limits.maxStreamsPerUser) {
+            throw httpError(429, `You already have ${staged.length} streams staged for this app; end, discard or download them before starting another`, { maxStreamsPerUser: limits.maxStreamsPerUser });
+        }
+        const bytes = staged.reduce((sum, item) => sum + (item.reserved || 0), 0);
+        if (bytes + size > limits.maxStagedBytesPerUser) {
+            throw httpError(413, `Staging ${size} more bytes would exceed the ${limits.maxStagedBytesPerUser} byte limit for your streams in this app (${bytes} already staged)`, { maxStagedBytesPerUser: limits.maxStagedBytesPerUser, stagedBytes: bytes });
+        }
+    }
+
+    /** Seal a download: complete, and holding only the bytes it wrote. */
+    function seal(item) {
+        item.complete = true;
+        item.reserved = item.size;
+        return touch(item);
+    }
+
+    return { create, get, bytes, remove, reserve, seal, sweep, touch, items, limits };
+}
+
+/** Guest-facing handle: never the store item itself. */
+export function toHandle(item, extra = {}) {
+    return {
+        __appStream: item.type,
+        id: item.id,
+        filename: item.filename,
+        contentType: item.contentType,
+        fingerprint: item.fingerprint || null,
+        size: item.size,
+        expiresAt: new Date(item.expiresAt).toISOString(),
+        ...extra
+    };
+}
+
+export function isStreamRef(value, type) {
+    return Boolean(value) && typeof value === 'object' && value.__appStream === type && typeof value.id === 'string';
+}
+
+// ---------------------------------------------------------------------------
+// Chunked upload protocol (mirrors app-streams.js)
+// ---------------------------------------------------------------------------
+
+export function createUpload(store, { filename, contentType, size, chunkSize, fingerprint }) {
+    const { limits } = store;
+    if (typeof filename !== 'string' || !filename || /[\\/\x00-\x1F]/.test(filename)) {
+        throw httpError(400, 'filename is required and may not contain path separators or control characters');
+    }
+    if (!Number.isInteger(size) || size < 0) throw httpError(400, 'size must be a non-negative integer');
+    if (size > limits.maxUploadBytes) {
+        throw httpError(413, `Upload exceeds the ${limits.maxUploadBytes} byte limit`, { maxUploadBytes: limits.maxUploadBytes });
+    }
+    const effective = Math.min(Math.max(1, chunkSize || DEFAULT_CHUNK_BYTES), limits.maxChunkBytes);
+    const chunks = Math.ceil(size / effective);
+    store.reserve(size);
+    return store.create('upload', {
+        filename,
+        contentType: contentType || mimeFor(filename) || 'application/octet-stream',
+        size,
+        fingerprint: fingerprint || null,
+        chunkSize: effective,
+        chunks,
+        complete: chunks === 0
+    });
+}
+
+export function expectedChunkBytes(item, n) {
+    return n < item.chunks ? item.chunkSize : item.size - item.chunkSize * (item.chunks - 1);
+}
+
+export function writeUploadChunk(store, item, n, contents) {
+    if (!Number.isInteger(n) || n < 1 || n > item.chunks) {
+        throw httpError(422, `Chunk ${n} is outside the expected range 1..${item.chunks}`);
+    }
+    if (item.complete) throw httpError(409, 'Upload is already complete');
+    const expected = expectedChunkBytes(item, n);
+    if (contents.length !== expected) {
+        throw httpError(422, `Chunk ${n}: expected ${expected} bytes, received ${contents.length}`);
+    }
+    item.chunkData.set(n, Buffer.from(contents));
+    store.touch(item);
+}
+
+export function missingChunks(item) {
+    const received = [...item.chunkData.keys()].sort((a, b) => a - b);
+    const missing = [];
+    for (let n = 1; n <= item.chunks; n++) if (!item.chunkData.has(n)) missing.push(n);
+    return { received, missing };
+}
+
+export function completeUpload(store, item) {
+    if (item.complete) return item;
+    const { missing } = missingChunks(item);
+    if (missing.length) {
+        throw httpError(412, `Upload is missing ${missing.length} chunk(s)`, { missing: missing.slice(0, 50) });
+    }
+    item.complete = true;
+    store.touch(item);
+    return item;
+}
+
+// ---------------------------------------------------------------------------
+// Encoders / parsers (no dependencies — the plugin ships with dotenv + yaml only)
+// ---------------------------------------------------------------------------
+
+function csvCell(value, delimiter) {
+    if (value === null || value === undefined) return '';
+    const s = typeof value === 'object' ? JSON.stringify(value) : String(value);
+    return /["\r\n]/.test(s) || s.includes(delimiter) ? `"${s.replace(/"/g, '""')}"` : s;
+}
+
+/** Rows → CSV text. Header from opts.columns or the first row's keys. */
+export function encodeRows(rows, { format = 'csv', columns, header = true, delimiter = ',' } = {}) {
+    if (format === 'json') {
+        return JSON.stringify(columns && columns.length ? rows.map(r => Object.fromEntries(columns.map(c => [c, r[c]]))) : rows);
+    }
+    if (format === 'jsonl') {
+        return rows.map(r => `${JSON.stringify(r)}\n`).join('');
+    }
+    if (format !== 'csv') throw httpError(400, `Unknown stream format "${format}" (expected csv, json or jsonl)`);
+    if (!rows.length && !(columns && columns.length)) return '';
+    const cols = columns && columns.length ? columns : Object.keys(rows[0]);
+    const cell = v => csvCell(v, delimiter);
+    const lines = [];
+    if (header) lines.push(cols.map(cell).join(delimiter));
+    for (const r of rows) lines.push(cols.map(c => cell(r[c])).join(delimiter));
+    return `${lines.join('\n')}\n`;
+}
+
+/**
+ * RFC 4180-ish CSV parser: quoted fields, doubled quotes, CRLF/LF, custom
+ * delimiter. Returns string[][] (no header handling — callers decide).
+ */
+export function parseCsv(text, { delimiter = ',', quote = '"' } = {}) {
+    const rows = [];
+    let row = [];
+    let field = '';
+    let quoted = false;
+    let i = 0;
+    while (i < text.length) {
+        const ch = text[i];
+        if (quoted) {
+            if (ch === quote) {
+                if (text[i + 1] === quote) { field += quote; i += 2; continue; }
+                quoted = false; i++; continue;
+            }
+            field += ch; i++; continue;
+        }
+        if (ch === quote) { quoted = true; i++; continue; }
+        if (ch === delimiter) { row.push(field); field = ''; i++; continue; }
+        if (ch === '\r') { i++; continue; }
+        if (ch === '\n') { row.push(field); rows.push(row); row = []; field = ''; i++; continue; }
+        field += ch; i++;
+    }
+    if (field.length || row.length) { row.push(field); rows.push(row); }
+    return rows;
+}
+
+/** Postgres text-format bytea literal for a Buffer: '\x' + hex. */
+export function byteaLiteral(buf) {
+    return `\\x${Buffer.from(buf).toString('hex')}`;
+}
+
+// ---------------------------------------------------------------------------
+// Bag services
+// ---------------------------------------------------------------------------
+
+const IDENT_RE = /^[A-Za-z_][A-Za-z0-9_$]*$/;
+
+function quoteIdent(ident, what) {
+    if (typeof ident !== 'string' || !ident) throw httpError(400, `copyInto: ${what} is required`);
+    const parts = ident.split('.');
+    if (parts.length > 2 || parts.some(p => !IDENT_RE.test(p))) throw httpError(400, `copyInto: invalid ${what} "${ident}"`);
+    return parts.map(p => `"${p.replace(/"/g, '""')}"`).join('.');
+}
+
+/**
+ * Build the per-invocation `uploads` / `downloads` services plus the query()
+ * parameter resolver and the finalize hook — the dev twin of
+ * app-streams.js#createStreamsHostFn.
+ *
+ * @param {Object} p
+ * @param {Object} p.store - createStreamStore()
+ * @param {Function|null} p.query - the invocation's query(sql, params) (null when no dev workspace)
+ * @param {string} [p.base=''] - URL prefix for download.url ('' on the dev origin)
+ */
+export function createStreamServices({ store, query, base = '' }) {
+    const { limits } = store;
+    const pending = new Set(); // downloads created and not yet ended/discarded
+
+    function requireQuery(what) {
+        if (!query) throw httpError(400, `${what} needs a dev workspace (INFORMER_DEV_WORKSPACE) — run: npx informer-workspace init`);
+        return query;
+    }
+
+    function ownedUpload(id) {
+        const item = store.get('upload', id);
+        if (!item) throw httpError(404, 'Not Found');
+        if (!item.complete) throw httpError(409, 'Upload is not complete yet');
+        return item;
+    }
+
+    function ownedDownload(id) {
+        const item = store.get('download', id);
+        if (!item) throw httpError(404, 'Not Found');
+        return item;
+    }
+
+    // Not yet sealed: writing past end() is a 409 in prod, as a chunk PUT on a
+    // completed upload is.
+    function writableDownload(id) {
+        const item = ownedDownload(id);
+        if (item.complete) throw httpError(409, 'Download is already complete');
+        return item;
+    }
+
+    /** Seal a download by id — what respond(download) and end() both do. */
+    async function endDownload(id) {
+        const item = ownedDownload(id);
+        pending.delete(id);
+        store.seal(item);
+        return item;
+    }
+
+    function inline(item) {
+        if (item.size > limits.maxInlineBytes) {
+            throw httpError(413, `Upload is ${item.size} bytes; inline reads are capped at ${limits.maxInlineBytes}. Use copyInto() or pass the upload as a query() parameter instead.`, { maxInlineBytes: limits.maxInlineBytes });
+        }
+        return store.bytes(item);
+    }
+
+    async function copyInto(item, table, opts = {}) {
+        const q = requireQuery('copyInto()');
+        const format = opts.format || 'csv';
+        if (!['csv', 'text'].includes(format)) throw httpError(400, `copyInto: unsupported format "${format}" (expected csv or text)`);
+        const target = quoteIdent(table, 'table');
+        const text = store.bytes(item).toString('utf8');
+        let rows = format === 'csv'
+            ? parseCsv(text, { delimiter: opts.delimiter || ',', quote: opts.quote || '"' })
+            : text.split(/\r?\n/).filter(l => l.length).map(l => l.split(opts.delimiter || '\t'));
+        let columns = Array.isArray(opts.columns) && opts.columns.length ? opts.columns : null;
+        if (format === 'csv' && opts.header !== false) {
+            const header = rows.shift() || [];
+            if (!columns) columns = header;
+        }
+        if (!columns) throw httpError(400, 'copyInto (dev): provide `columns` or a CSV header row so the emulated INSERT knows the target columns');
+        rows = rows.filter(r => r.length > 1 || (r.length === 1 && r[0] !== ''));
+        const nullToken = opts.null !== undefined ? String(opts.null) : (format === 'csv' ? '' : '\\N');
+        const cols = columns.map(c => quoteIdent(c, 'column')).join(', ');
+        // Production COPY is one atomic statement; this emulation is a loop of
+        // INSERTs, so validate every row up front — otherwise a bad row halfway
+        // through leaves a partially populated table only dev ever sees.
+        const headerOffset = (format === 'csv' && opts.header !== false) ? 2 : 1;
+        rows.forEach((r, idx) => {
+            if (r.length !== columns.length) {
+                throw httpError(422, `copyInto: row ${idx + headerOffset} has ${r.length} fields, expected ${columns.length}`);
+            }
+        });
+        const BATCH = 500;
+        let rowCount = 0;
+        for (let i = 0; i < rows.length; i += BATCH) {
+            const batch = rows.slice(i, i + BATCH);
+            const params = [];
+            const values = batch.map(r => {
+                return `(${r.map(v => { params.push(v === nullToken ? null : v); return `$${params.length}`; }).join(', ')})`;
+            });
+            await q(`INSERT INTO ${target} (${cols}) VALUES ${values.join(', ')}`, params);
+            rowCount += batch.length;
+        }
+        return { rowCount };
+    }
+
+    const uploads = {
+        async get(id) {
+            const item = ownedUpload(id);
+            return {
+                ...toHandle(item),
+                text: async (encoding) => {
+                    if (encoding !== undefined && encoding !== null && !Buffer.isEncoding(encoding)) throw httpError(422, `Unknown text encoding "${encoding}"`);
+                    return inline(item).toString(encoding || 'utf8');
+                },
+                json: async () => {
+                    const text = inline(item).toString('utf8');
+                    try {
+                        return JSON.parse(text);
+                    } catch (err) {
+                        throw httpError(422, `Upload is not valid JSON: ${err.message}`);
+                    }
+                },
+                base64: async () => inline(item).toString('base64'),
+                extractText: async () => { throw httpError(501, 'upload.extractText() is not available in dev — the platform text extractor runs on the Informer server; test it against a deployed app'); },
+                copyInto: async (table, opts) => await copyInto(item, table, opts || {}),
+                discard: async () => { store.remove(item.id); return true; }
+            };
+        }
+    };
+
+    function downloadHandle(item) {
+        const url = `${base}/_downloads/${encodeURIComponent(item.id)}${item.filename ? `/${encodeURIComponent(item.filename)}` : ''}`;
+        const handle = {
+            ...toHandle(item, { url }),
+            async write(chunk) {
+                writableDownload(item.id);
+                const buf = toBytes(chunk);
+                item.parts.push(buf);
+                item.size += buf.length;
+                return true;
+            },
+            async writeRows(rows, opts = {}) {
+                writableDownload(item.id);
+                const format = opts.format || 'csv';
+                if (!item.contentType) item.contentType = defaultContentType(format);
+                // One header per download, emitted with the first row — like the
+                // streaming encoder in prod. An empty page emits nothing and must
+                // not count as the first, or the header would never appear.
+                const out = encodeRows(rows, { ...opts, format, header: !item.rowsStarted && opts.header !== false });
+                if (out) {
+                    item.rowsStarted = true;
+                    await handle.write(out);
+                }
+                return rows.length;
+            },
+            async fromQuery(sql, params, opts = {}) {
+                const q = requireQuery('fromQuery()');
+                writableDownload(item.id);
+                const rows = await q(sql, params || []);
+                const format = opts.format || 'csv';
+                if (!item.contentType) item.contentType = defaultContentType(format);
+                await handle.write(encodeRows(rows, { ...opts, format }));
+                return { rowCount: rows.length };
+            },
+            async end() {
+                return downloadHandle(await endDownload(item.id));
+            },
+            async discard() {
+                pending.delete(item.id);
+                store.remove(item.id);
+                return true;
+            }
+        };
+        return handle;
+    }
+
+    const downloads = {
+        async create({ filename, contentType } = {}) {
+            // No size to declare yet: reserve the ceiling the write path holds
+            // this download to, as prod does, and let endDownload() true it up.
+            store.reserve(limits.maxUploadBytes);
+            const item = store.create('download', { filename, contentType: contentType || mimeFor(filename), reserved: limits.maxUploadBytes });
+            pending.add(item.id);
+            return downloadHandle(item);
+        }
+    };
+
+    /** Swap upload references in query() params for `\x…` bytea literals (memoized per invocation). */
+    const resolved = new Map();
+    async function resolveQueryParams(params) {
+        if (!Array.isArray(params) || !params.some(p => isStreamRef(p, 'upload'))) return params;
+        return params.map(p => {
+            if (!isStreamRef(p, 'upload')) return p;
+            if (!resolved.has(p.id)) resolved.set(p.id, byteaLiteral(store.bytes(ownedUpload(p.id))));
+            return resolved.get(p.id);
+        });
+    }
+
+    /** Seal every download the handler created and neither ended nor discarded. */
+    async function finalize() {
+        for (const id of [...pending]) {
+            const item = store.get('download', id);
+            pending.delete(id);
+            if (item) store.seal(item);
+        }
+    }
+
+    return { uploads, downloads, resolveQueryParams, endDownload, finalize };
+}
+
+// What a guest hands write(): a string or bytes. Anything else is a 422 in
+// prod, not a TypeError from Buffer.from.
+function toBytes(chunk) {
+    if (typeof chunk === 'string') return Buffer.from(chunk, 'utf8');
+    if (ArrayBuffer.isView(chunk)) return Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength);
+    if (chunk instanceof ArrayBuffer || Array.isArray(chunk)) return Buffer.from(chunk);
+    throw httpError(422, `write() expects a string or bytes, got ${chunk === null ? 'null' : typeof chunk}`);
+}
+
+// ---------------------------------------------------------------------------
+// Serving
+// ---------------------------------------------------------------------------
+
+export function contentDisposition(filename, inline = false) {
+    const type = inline ? 'inline' : 'attachment';
+    if (!filename) return type;
+    const ascii = filename.replace(/["\\\r\n]/g, '_').replace(/[^\x20-\x7e]/g, '_');
+    return `${type}; filename="${ascii}"; filename*=UTF-8''${encodeURIComponent(filename)}`;
+}
+
+// MIRROR of app-streams.js (pinned by test/streams-parity.test.js): only types
+// a browser renders inertly may go out inline; everything else is forced to
+// attachment and pinned shut with a CSP, so an author sees the same
+// disposition here that the deployed app will apply.
+export const INLINE_SAFE_TYPE_RE = /^(?:text\/(?:plain|csv|tab-separated-values|markdown)|application\/(?:json|x-ndjson|pdf)|image\/(?:png|jpeg|gif|webp|bmp|avif)|(?:audio|video)\/[\w.+-]+)(?:\s*;.*)?$/;
+
+export const SCRIPTABLE_CSP = [
+    `default-src 'none'`,
+    `script-src 'none'`,
+    `style-src 'unsafe-inline'`,
+    `img-src data:`,
+    `base-uri 'none'`,
+    `frame-ancestors 'none'`,
+    `sandbox`
+].join('; ');
+
+export function isInlineSafeType(contentType) {
+    return INLINE_SAFE_TYPE_RE.test(String(contentType || '').trim().toLowerCase());
+}
+
+/** Write a completed download to a Node response. Single-use unless `keep`. */
+export function serveDownload(store, item, res, { keep = false, inline = false } = {}) {
+    const body = store.bytes(item);
+    const contentType = item.contentType || mimeFor(item.filename) || 'application/octet-stream';
+    const inlineSafe = isInlineSafeType(contentType);
+    res.statusCode = 200;
+    res.setHeader('Content-Type', contentType);
+    res.setHeader('Content-Disposition', contentDisposition(item.filename, inline && inlineSafe));
+    res.setHeader('Content-Length', String(body.length));
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+    res.setHeader('Cache-Control', 'no-store');
+    if (!inlineSafe) {
+        res.setHeader('Content-Security-Policy', SCRIPTABLE_CSP);
+        res.setHeader('Referrer-Policy', 'no-referrer');
+    }
+    res.end(body);
+    if (!keep) store.remove(item.id);
+}
+
+// ---------------------------------------------------------------------------
+// Middleware: /_uploads and /_downloads on the dev origin
+// ---------------------------------------------------------------------------
+
+function sendJson(res, status, body) {
+    res.statusCode = status;
+    res.setHeader('Content-Type', 'application/json');
+    res.end(body === undefined ? '' : JSON.stringify(body));
+}
+
+function sendError(res, err) {
+    const status = err.statusCode || 500;
+    const payload = { statusCode: status, message: err.message };
+    if (err.data !== undefined) payload.data = err.data;
+    sendJson(res, status, payload);
+}
+
+async function readBody(req) {
+    const chunks = [];
+    for await (const chunk of req) chunks.push(chunk);
+    return Buffer.concat(chunks);
+}
+
+function uploadSummary(item) {
+    const { received, missing } = missingChunks(item);
+    return toHandle(item, { chunkSize: item.chunkSize, chunks: item.chunks, complete: item.complete, received, missing });
+}
+
+/**
+ * Connect middleware for the upload protocol. Mount at '/_uploads' — the
+ * mount prefix is already stripped from req.url by the time it runs.
+ */
+export function createUploadsMiddleware(store) {
+    return async function uploadsMiddleware(req, res, next) {
+        try {
+            const url = new URL(req.url, 'http://dev.local');
+            const parts = url.pathname.split('/').filter(Boolean);
+            const method = req.method.toUpperCase();
+
+            if (parts.length === 0 && method === 'POST') {
+                let payload;
+                try { payload = JSON.parse((await readBody(req)).toString('utf8') || '{}'); } catch { throw httpError(400, 'Invalid JSON body'); }
+                const item = createUpload(store, payload);
+                res.setHeader('Location', `/_uploads/${item.id}`);
+                return sendJson(res, 201, uploadSummary(item));
+            }
+            if (parts.length === 0) return next();
+
+            const item = store.get('upload', parts[0]);
+            if (!item) throw httpError(404, 'Not Found');
+
+            if (parts.length === 1 && method === 'GET') return sendJson(res, 200, uploadSummary(item));
+            if (parts.length === 1 && method === 'DELETE') { store.remove(item.id); res.statusCode = 204; return res.end(); }
+            if (parts.length === 2 && parts[1] === '_complete' && method === 'POST') {
+                completeUpload(store, item);
+                return sendJson(res, 200, uploadSummary(item));
+            }
+            if (parts.length === 2 && method === 'PUT') {
+                const n = parseInt(parts[1], 10);
+                if (!Number.isInteger(n) || n < 1) throw httpError(400, 'Chunk number must be a positive integer');
+                const body = await readBody(req);
+                if (body.length > store.limits.maxChunkBytes) throw httpError(413, `Chunk exceeds the ${store.limits.maxChunkBytes} byte limit`);
+                writeUploadChunk(store, item, n, body);
+                res.statusCode = 204;
+                return res.end();
+            }
+            return next();
+        } catch (err) {
+            return sendError(res, err);
+        }
+    };
+}
+
+/** Connect middleware for GET /_downloads/{id}/{filename?}?keep&inline. */
+export function createDownloadsMiddleware(store) {
+    return function downloadsMiddleware(req, res, next) {
+        try {
+            if (req.method.toUpperCase() !== 'GET') return next();
+            const url = new URL(req.url, 'http://dev.local');
+            const [id] = url.pathname.split('/').filter(Boolean);
+            if (!id) return next();
+            const item = store.get('download', id);
+            if (!item || !item.complete) throw httpError(404, 'Not Found');
+            return serveDownload(store, item, res, {
+                keep: url.searchParams.get('keep') === 'true',
+                inline: url.searchParams.get('inline') === 'true'
+            });
+        } catch (err) {
+            return sendError(res, err);
+        }
+    };
+}

package/src/env.js

@@ -1,5 +1,5 @@
 import dotenv from 'dotenv';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { resolve, dirname, parse as parsePath } from 'node:path';
 
 /**
@@ -71,6 +71,22 @@ export function envWritePath({ mode, cwd } = {}) {
     return resolve(dir, useMode ? `.env.${mode}` : '.env');
 }
 
+/**
+ * A variable as defined in the app's OWN env file (the one envWritePath
+ * names), ignoring the shell and any parent .env loadEnv walked up to. Null
+ * when the file is missing or leaves the variable unset or empty.
+ *
+ * @param {string} name
+ * @param {{ mode?: string, cwd?: string }} options
+ * @returns {string|null}
+ */
+export function localEnvValue(name, { mode, cwd } = {}) {
+    const path = envWritePath({ mode, cwd });
+    if (!existsSync(path)) return null;
+    const value = dotenv.parse(readFileSync(path, 'utf8'))[name];
+    return value ? value : null;
+}
+
 /**
  * Parse --mode <name> from a process.argv array.
  *