@hachej/boring-files 0.0.0-stage → 0.2.1

package/dist/git.js

@@ -0,0 +1,205 @@
+import git from 'isomorphic-git';
+import { posix } from 'node:path';
+export class GitOperationError extends Error {
+    effects;
+    constructor(message, effects, options) {
+        super(message, options);
+        this.effects = effects;
+        this.name = 'GitOperationError';
+    }
+}
+function name(value, label) {
+    if (typeof value !== 'string' || !value || /[\x00-\x1f\x7f]/.test(value))
+        throw new TypeError(`Invalid Git ${label}`);
+    return value;
+}
+/** check-ref-format rules, so a name can never resolve outside refs/ or the repository. */
+function refname(value) {
+    name(value, 'reference');
+    if (value.startsWith('-') || value.startsWith('/') || value.endsWith('/') || value.endsWith('.') || value === '@' || value.includes('//')
+        || value.includes('..') || value.includes('@{') || /[ ~^:?*[\\]/.test(value)
+        || value.split('/').some(part => part.startsWith('.') || part.endsWith('.lock')))
+        throw new TypeError('Invalid Git reference');
+    return value;
+}
+function filepath(value) {
+    name(value, 'path');
+    if (value.startsWith('/') || value.includes('\\') || value.split('/').some(part => part === '..' || part.toLowerCase() === '.git'))
+        throw new TypeError('Git paths must stay in the selected worktree');
+    return value;
+}
+/** Borrow one filesystem and share this instance across callers. Raw filesystem writers do not take this queue. */
+export function createGitRepository(options) {
+    const { fs, authorize } = options;
+    const directory = name(options.directory, 'directory');
+    if (!directory.startsWith('/') || posix.normalize(directory) !== directory)
+        throw new TypeError('Git directory must be an absolute normalized path');
+    const author = { ...options.author };
+    const repo = { fs, dir: directory };
+    const limits = { files: 100, bytes: 1024 * 1024, ...options.diffLimits };
+    if (![limits.files, limits.bytes].every(value => Number.isSafeInteger(value) && value > 0))
+        throw new TypeError('Git diff limits must be positive safe integers');
+    let pending = Promise.resolve();
+    function run(operation, mutation, signal, execute) {
+        const result = pending.then(async () => {
+            let started = false;
+            try {
+                if (signal?.aborted)
+                    throw new Error('Git operation aborted before execution');
+                if (await authorize(operation) !== true)
+                    throw new Error('Git repository authorization denied');
+                if (signal?.aborted)
+                    throw new Error('Git operation aborted before execution');
+                started = true;
+                const value = await execute();
+                if (signal?.aborted)
+                    throw new Error('Git operation aborted after execution');
+                if (await authorize(operation) !== true)
+                    throw new Error('Git repository authorization changed during execution');
+                if (signal?.aborted)
+                    throw new Error('Git operation aborted after execution');
+                return value;
+            }
+            catch (cause) {
+                const effects = started && mutation ? 'possible' : 'none';
+                throw new GitOperationError(`${cause instanceof Error ? cause.message : String(cause)}${effects === 'possible' ? '; prior Git effects may remain' : ''}`, effects, { cause });
+            }
+        });
+        pending = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    function tree(view) {
+        switch (view.kind) {
+            case 'tree': return git.TREE({ ref: refname(view.ref) });
+            case 'index': return git.STAGE();
+            case 'worktree': return git.WORKDIR({ refresh: false });
+        }
+    }
+    return Object.freeze({
+        fs, directory,
+        init: (signal) => run('init', true, signal, () => git.init({ ...repo, defaultBranch: 'main' })),
+        status: (signal) => run('status', false, signal, () => git.statusMatrix({ ...repo, refresh: false })),
+        add: (path, signal) => {
+            const selected = filepath(path);
+            return run('add', true, signal, () => git.add({ ...repo, filepath: selected }));
+        },
+        remove: (path, signal) => {
+            const selected = filepath(path);
+            return run('remove', true, signal, () => git.remove({ ...repo, filepath: selected }));
+        },
+        commit: (message, signal) => {
+            if (typeof message !== 'string' || !message.trim() || message.includes('\0'))
+                throw new TypeError('Invalid Git message');
+            const selected = message;
+            return run('commit', true, signal, () => git.commit({ ...repo, author, message: selected }));
+        },
+        log: (signal) => run('log', false, signal, () => git.log({ ...repo, depth: 20 })),
+        branches: (signal) => run('branches', false, signal, () => git.listBranches(repo)),
+        branch: (ref, signal) => {
+            const selected = refname(ref);
+            return run('branch', true, signal, () => git.branch({ ...repo, ref: selected }));
+        },
+        checkout: (ref, signal) => {
+            const selected = refname(ref);
+            return run('checkout', true, signal, () => git.checkout({ ...repo, ref: selected }));
+        },
+        diff: (before, after, signal) => {
+            const trees = [tree(before), tree(after)];
+            return run('diff', false, signal, async () => {
+                const changes = [];
+                let bytes = 0;
+                async function version(entry) {
+                    if (!entry)
+                        return null;
+                    if (await entry.type() !== 'blob')
+                        throw new Error('Git diff supports blob entries only');
+                    const oid = await entry.oid();
+                    const content = await entry.content() ?? (await git.readBlob({ ...repo, oid })).blob;
+                    const copied = Uint8Array.from(content);
+                    bytes += copied.length;
+                    if (bytes > limits.bytes)
+                        throw new Error('Git diff byte limit exceeded');
+                    return { oid, mode: await entry.mode(), bytes: copied };
+                }
+                await git.walk({ ...repo, trees, iterate: async (walk, children) => {
+                        for (const child of children)
+                            await walk(child);
+                        return [];
+                    }, map: async (path, entries) => {
+                        if (path === '.git')
+                            return null;
+                        if (signal?.aborted)
+                            throw new Error('Git diff aborted');
+                        let left = entries[0] ?? null, right = entries[1] ?? null;
+                        if (left && await left.type() === 'tree')
+                            left = null;
+                        if (right && await right.type() === 'tree')
+                            right = null;
+                        if (!left && !right)
+                            return;
+                        if (left && right && await left.oid() === await right.oid() && await left.mode() === await right.mode())
+                            return;
+                        if (changes.length >= limits.files)
+                            throw new Error('Git diff file limit exceeded');
+                        const change = { path, before: await version(left), after: await version(right) };
+                        changes.push(change);
+                    } });
+                return changes.sort((left, right) => left.path.localeCompare(right.path));
+            });
+        },
+    });
+}
+const ERRNO = { not_found: 'ENOENT', not_directory: 'ENOTDIR', is_directory: 'EISDIR', permission_denied: 'EACCES', not_supported: 'ENOSYS', aborted: 'EINTR' };
+const failure = (message, code, cause) => Object.assign(new Error(message, cause === undefined ? undefined : { cause }), { code });
+/**
+ * isomorphic-git I/O over a Pi `FileSystem` (an `ExecutionEnv`'s files): every read and write goes through that environment, so its
+ * confinement (for example the AWS adapter's folder and symbolic link checks) also confines Git. No second checkout, no native Git.
+ * Modes are not part of Pi's file contract: files read as 0o100644. Symbolic links are refused (`ENOSYS`): Git fails on a worktree
+ * that contains one rather than following it.
+ */
+export function createEnvGitFs(filesystem, context) {
+    const value = (result) => {
+        if (result.ok)
+            return result.value;
+        throw failure(result.error.message, ERRNO[result.error.code] ?? 'EIO', result.error);
+    };
+    const unsupported = (what) => { throw failure(`${what}: symbolic links are not supported on this workspace`, 'ENOSYS'); };
+    // Racy-clean guard, as in the virtual Git fs: isomorphic-git compares whole seconds, so a same-size edit in the second of its `add`
+    // looks clean. The reported inode folds in the millisecond mtime, and is unique per call while the file is fresh.
+    let fresh = 0;
+    const stat = (info) => {
+        const racy = Date.now() - info.mtimeMs < 1000;
+        return {
+            type: info.kind === 'directory' ? 'dir' : info.kind, mode: info.kind === 'directory' ? 0o40000 : info.kind === 'symlink' ? 0o120000 : 0o100644,
+            size: info.size, mtimeMs: info.mtimeMs, ctimeMs: info.mtimeMs, uid: 0, gid: 0, dev: 0,
+            ino: racy ? 0x80000000 + (++fresh % 0x7fffffff) : Math.floor(info.mtimeMs) % 0x80000000,
+            isFile: () => info.kind === 'file', isDirectory: () => info.kind === 'directory', isSymbolicLink: () => info.kind === 'symlink',
+        };
+    };
+    return { promises: {
+            readFile: async (path, options) => {
+                const bytes = value(await filesystem.readBinaryFile(path, context));
+                return (typeof options === 'string' ? options : options?.encoding) ? new TextDecoder().decode(bytes) : bytes;
+            },
+            writeFile: async (path, bytes) => { value(await filesystem.writeFile(path, typeof bytes === 'string' ? bytes : Uint8Array.from(bytes), context)); },
+            unlink: async (path) => {
+                if (value(await filesystem.fileInfo(path, context)).kind === 'directory')
+                    throw failure(`EISDIR: ${path}`, 'EISDIR');
+                value(await filesystem.remove(path, { recursive: false }, context));
+            },
+            readdir: async (path) => value(await filesystem.listDir(path, context)).map(entry => entry.name),
+            mkdir: async (path) => { value(await filesystem.createDir(path, { recursive: true }, context)); },
+            rmdir: async (path) => {
+                if (value(await filesystem.fileInfo(path, context)).kind !== 'directory')
+                    throw failure(`ENOTDIR: ${path}`, 'ENOTDIR');
+                if (value(await filesystem.listDir(path, context)).length)
+                    throw failure(`ENOTEMPTY: ${path}`, 'ENOTEMPTY');
+                value(await filesystem.remove(path, { recursive: true }, context));
+            },
+            stat: async (path) => stat(value(await filesystem.fileInfo(value(await filesystem.canonicalPath(path, context)), context))),
+            lstat: async (path) => stat(value(await filesystem.fileInfo(path, context))),
+            readlink: async (path) => unsupported(`readlink ${path}`),
+            symlink: async (_target, path) => unsupported(`symlink ${path}`),
+            chmod: async () => { },
+        } };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type * from './contracts.js';
+export type * from './client.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1 @@
+export {};

package/dist/journal.d.ts

@@ -0,0 +1,83 @@
+import type { CommittedChange, NonEmpty, ResourceRef } from './contracts.js';
+import type { SqliteConnection } from './sqlite.js';
+/**
+ * Operation tables of the workspace journal: who asked for which operation, the digest of
+ * its arguments, its evidence reference and the changes it committed. Rows are plain strings; callers turn them into references.
+ * Every method is synchronous and runs in the caller's transaction (open one with `connection.transaction`), except the methods
+ * of `WorkspaceJournal` that say they commit on their own.
+ */
+export interface OperationKey {
+    readonly scope: string;
+    readonly principal: string;
+    readonly initiator: string;
+    readonly operation: string;
+}
+export interface StoredChange {
+    readonly kind: 'create' | 'replace' | 'delete';
+    readonly path: string;
+    readonly before: string | null;
+    readonly after: string | null;
+}
+export interface StoredOperation {
+    readonly digest: string;
+    readonly evidence: string;
+    readonly changes: readonly StoredChange[];
+}
+export interface OperationJournal {
+    /** Create the operation tables when missing. */
+    readonly install: () => void;
+    readonly operation: (key: OperationKey) => StoredOperation | undefined;
+    readonly record: (key: OperationKey, operation: StoredOperation) => void;
+}
+export declare function createOperationJournal(db: SqliteConnection): OperationJournal;
+/** Stored rows as committed changes, with the same shape checks the receipt parser applies. */
+export declare function committedChanges(changes: readonly StoredChange[], ref: (path: string, revision: string) => ResourceRef): NonEmpty<CommittedChange>;
+export interface StoredVersion {
+    readonly revision: string;
+    readonly bytes: Uint8Array;
+    readonly mediaType: string;
+    /** When this revision was saved, in milliseconds since the epoch. Kept the first time the revision is retained. */
+    readonly savedAt?: number;
+    /**
+     * Who produced the revision: `publish` (a conditional write), `agent` (a Pi `write` or `edit`, recorded by `provider.record`: it
+     * has no receipt) or `observed` (retained as found: `keep`, or the replaced revision of a write). Default `publish`.
+     */
+    readonly source?: HistorySource;
+}
+export type HistorySource = 'publish' | 'agent' | 'observed';
+/**
+ * The operation journal plus what a workspace needs beyond receipts: an intent row written before an operation's first effect
+ * (an intent without a completion is an operation of unknown outcome), and the last versions of each file when there is no Git.
+ * Receipts and intents are scoped per operation key; history is scoped per `scope` argument and path.
+ */
+export interface WorkspaceJournal extends OperationJournal {
+    /** The intent of an operation that has begun and neither completed nor been cancelled. */
+    readonly intent: (key: OperationKey) => {
+        readonly digest: string;
+    } | undefined;
+    /** Commits on its own. */
+    readonly begin: (key: OperationKey, digest: string) => void;
+    /** Commits on its own: the operation is known not to have taken effect. */
+    readonly cancel: (key: OperationKey) => void;
+    /** Commits on its own: the receipt, the end of the intent and the new versions together. */
+    readonly complete: (key: OperationKey, operation: StoredOperation, versions: {
+        readonly scope: string;
+        readonly path: string;
+        readonly version: StoredVersion;
+    }[]) => void;
+    /** Commits on its own. Keeps the newest `historyLimit` revisions of the file. */
+    readonly remember: (scope: string, path: string, version: StoredVersion) => void;
+    readonly version: (scope: string, path: string, revision: string) => StoredVersion | undefined;
+    /** Retained revisions of a file, newest first. */
+    readonly revisions: (scope: string, path: string) => string[];
+    /** Retained revisions of a file with their save times, newest first. A time of 0 is unknown (kept before times were recorded). */
+    readonly saves: (scope: string, path: string) => {
+        readonly revision: string;
+        readonly savedAt: number;
+        readonly source: HistorySource;
+    }[];
+}
+export declare function createWorkspaceJournal(db: SqliteConnection, options?: {
+    readonly historyLimit?: number;
+}): WorkspaceJournal;
+//# sourceMappingURL=journal.d.ts.map

package/dist/journal.js

@@ -0,0 +1,124 @@
+import { registerJournalConnection } from './sqlite-batch.js';
+const keyValues = (key) => [key.scope, key.principal, key.initiator, key.operation];
+function text(value) {
+    if (typeof value !== 'string')
+        throw new Error('Invalid stored journal value');
+    return value;
+}
+function nullableText(value) {
+    return value === null ? null : text(value);
+}
+export function createOperationJournal(db) {
+    return {
+        install: () => db.exec(`
+      CREATE TABLE IF NOT EXISTS boring_operations (
+        scope TEXT NOT NULL, principal TEXT NOT NULL, initiator TEXT NOT NULL, operation TEXT NOT NULL,
+        digest TEXT NOT NULL, evidence TEXT NOT NULL,
+        PRIMARY KEY (scope, principal, initiator, operation)
+      ) STRICT;
+      CREATE TABLE IF NOT EXISTS boring_changes (
+        scope TEXT NOT NULL, principal TEXT NOT NULL, initiator TEXT NOT NULL, operation TEXT NOT NULL,
+        ordinal INTEGER NOT NULL, path TEXT NOT NULL, kind TEXT NOT NULL,
+        before_revision TEXT, after_revision TEXT,
+        PRIMARY KEY (scope, principal, initiator, operation, ordinal)
+      ) STRICT;
+    `),
+        operation: key => {
+            const values = keyValues(key);
+            const row = db.get('SELECT digest, evidence FROM boring_operations WHERE scope = ? AND principal = ? AND initiator = ? AND operation = ?', ...values);
+            if (!row)
+                return undefined;
+            const changes = db.all('SELECT * FROM boring_changes WHERE scope = ? AND principal = ? AND initiator = ? AND operation = ? ORDER BY ordinal', ...values).map((item) => {
+                const kind = text(item.kind);
+                if (kind !== 'create' && kind !== 'replace' && kind !== 'delete')
+                    throw new Error('Invalid stored publication change');
+                return { kind, path: text(item.path), before: nullableText(item.before_revision), after: nullableText(item.after_revision) };
+            });
+            return { digest: text(row.digest), evidence: text(row.evidence), changes };
+        },
+        record: (key, operation) => {
+            const values = keyValues(key);
+            db.run('INSERT INTO boring_operations VALUES (?, ?, ?, ?, ?, ?)', ...values, operation.digest, operation.evidence);
+            operation.changes.forEach((item, index) => db.run('INSERT INTO boring_changes VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)', ...values, index, item.path, item.kind, item.before, item.after));
+        },
+    };
+}
+/** Stored rows as committed changes, with the same shape checks the receipt parser applies. */
+export function committedChanges(changes, ref) {
+    const mapped = changes.map((item) => {
+        if (item.kind === 'create' && item.before === null && item.after !== null)
+            return { kind: 'create', before: null, after: ref(item.path, item.after) };
+        if (item.kind === 'delete' && item.after === null && item.before !== null)
+            return { kind: 'delete', before: ref(item.path, item.before), after: null };
+        if (item.kind === 'replace' && item.before !== null && item.after !== null)
+            return { kind: 'replace', before: ref(item.path, item.before), after: ref(item.path, item.after) };
+        throw new Error('Invalid stored publication change');
+    });
+    const [first, ...rest] = mapped;
+    if (first === undefined)
+        throw new Error('Stored operation has no changes');
+    return [first, ...rest];
+}
+const historySource = (value) => value === 'agent' || value === 'observed' ? value : 'publish';
+export function createWorkspaceJournal(db, options = {}) {
+    const limit = options.historyLimit ?? 20;
+    if (!Number.isSafeInteger(limit) || limit < 1)
+        throw new RangeError('The history limit must be a positive integer');
+    const operations = createOperationJournal(db);
+    db.transaction('write', () => {
+        operations.install();
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS boring_intents (
+        scope TEXT NOT NULL, principal TEXT NOT NULL, initiator TEXT NOT NULL, operation TEXT NOT NULL,
+        digest TEXT NOT NULL,
+        PRIMARY KEY (scope, principal, initiator, operation)
+      ) STRICT;
+      CREATE TABLE IF NOT EXISTS boring_history (
+        scope TEXT NOT NULL, path TEXT NOT NULL, revision TEXT NOT NULL, sequence INTEGER NOT NULL,
+        bytes BLOB NOT NULL, media_type TEXT NOT NULL, saved_at INTEGER NOT NULL DEFAULT 0, source TEXT NOT NULL DEFAULT 'publish',
+        PRIMARY KEY (scope, path, revision)
+      ) STRICT;
+    `);
+        // A journal created before save times were recorded gets the column; its old rows read as unknown (0).
+        if (!db.all("SELECT name FROM pragma_table_info('boring_history')").some(column => column.name === 'saved_at'))
+            db.exec('ALTER TABLE boring_history ADD COLUMN saved_at INTEGER NOT NULL DEFAULT 0');
+        // A journal created before history recorded who wrote each revision: its old rows were all conditional writes.
+        if (!db.all("SELECT name FROM pragma_table_info('boring_history')").some(column => column.name === 'source'))
+            db.exec("ALTER TABLE boring_history ADD COLUMN source TEXT NOT NULL DEFAULT 'publish'");
+    });
+    const remember = (scope, path, version) => {
+        const last = db.get('SELECT COALESCE(MAX(sequence), 0) AS last FROM boring_history WHERE scope = ? AND path = ?', scope, path);
+        const sequence = Number(last?.last ?? 0) + 1;
+        // A revision found again (`observed`) keeps the writer it was first recorded with; a new write of the same bytes names its writer.
+        db.run("INSERT INTO boring_history (scope, path, revision, sequence, bytes, media_type, saved_at, source) VALUES (?, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT(scope, path, revision) DO UPDATE SET sequence = excluded.sequence, bytes = excluded.bytes, media_type = excluded.media_type, saved_at = CASE WHEN boring_history.saved_at = 0 THEN excluded.saved_at ELSE boring_history.saved_at END, source = CASE WHEN excluded.source = 'observed' THEN boring_history.source ELSE excluded.source END", scope, path, version.revision, sequence, version.bytes, version.mediaType, version.savedAt ?? 0, historySource(version.source));
+        db.run('DELETE FROM boring_history WHERE scope = ? AND path = ? AND revision NOT IN (SELECT revision FROM boring_history WHERE scope = ? AND path = ? ORDER BY sequence DESC LIMIT ?)', scope, path, scope, path, limit);
+    };
+    const journal = {
+        ...operations,
+        intent: key => {
+            const row = db.get('SELECT digest FROM boring_intents WHERE scope = ? AND principal = ? AND initiator = ? AND operation = ?', ...keyValues(key));
+            return row ? { digest: text(row.digest) } : undefined;
+        },
+        begin: (key, digest) => db.transaction('write', () => { db.run('INSERT INTO boring_intents VALUES (?, ?, ?, ?, ?)', ...keyValues(key), digest); }),
+        cancel: key => db.transaction('write', () => { db.run('DELETE FROM boring_intents WHERE scope = ? AND principal = ? AND initiator = ? AND operation = ?', ...keyValues(key)); }),
+        complete: (key, operation, versions) => db.transaction('write', () => {
+            operations.record(key, operation);
+            db.run('DELETE FROM boring_intents WHERE scope = ? AND principal = ? AND initiator = ? AND operation = ?', ...keyValues(key));
+            for (const item of versions)
+                remember(item.scope, item.path, item.version);
+        }),
+        remember: (scope, path, version) => db.transaction('write', () => { remember(scope, path, version); }),
+        version: (scope, path, revision) => {
+            const row = db.get('SELECT bytes, media_type FROM boring_history WHERE scope = ? AND path = ? AND revision = ?', scope, path, revision);
+            if (!row)
+                return undefined;
+            if (!(row.bytes instanceof Uint8Array))
+                throw new Error('Invalid stored bytes');
+            return { revision, bytes: Uint8Array.from(row.bytes), mediaType: text(row.media_type) };
+        },
+        revisions: (scope, path) => db.all('SELECT revision FROM boring_history WHERE scope = ? AND path = ? ORDER BY sequence DESC', scope, path).map(row => text(row.revision)),
+        saves: (scope, path) => db.all('SELECT revision, saved_at, source FROM boring_history WHERE scope = ? AND path = ? ORDER BY sequence DESC', scope, path).map(row => ({ revision: text(row.revision), savedAt: Number(row.saved_at), source: historySource(row.source) })),
+    };
+    registerJournalConnection(journal, db);
+    return journal;
+}

package/dist/node-http.d.ts

@@ -0,0 +1,23 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/** Reads at most `maxBytes` of the body. Returns `undefined` when the body is larger (answer 413) or the client went away. */
+export declare function readBody(incoming: IncomingMessage, maxBytes?: number): Promise<Uint8Array | undefined>;
+export interface WebRequestOptions {
+    /** Aborts the web request, for example when the Node response closes. */
+    readonly signal?: AbortSignal;
+    /** Largest accepted body (default 16 MiB). */
+    readonly maxBytes?: number;
+}
+/** The web `Request` for an incoming Node request, or `undefined` when its body is over `maxBytes` or unreadable. */
+export declare function webRequest(incoming: IncomingMessage, url: string | URL, { signal, maxBytes }?: WebRequestOptions): Promise<Request | undefined>;
+export interface SendWebResponseOptions {
+    /** Stops sending (the web body is cancelled), in addition to the Node response closing. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Write a web `Response` to a Node response: status and headers first (flushed immediately; multiple `set-cookie` values kept),
+ * then the body chunk by chunk, waiting for `drain` whenever `write()` returns false. When the client disconnects or `signal`
+ * aborts, the web body is cancelled and this resolves. A body that fails mid-stream destroys the connection, so the client
+ * sees a truncated response rather than a clean end, and the error is rethrown.
+ */
+export declare function sendWebResponse(response: Response, outgoing: ServerResponse, { signal }?: SendWebResponseOptions): Promise<void>;
+//# sourceMappingURL=node-http.d.ts.map

package/dist/node-http.js

@@ -0,0 +1,102 @@
+const DEFAULT_MAX_BYTES = 16 * 1024 * 1024;
+/** Reads at most `maxBytes` of the body. Returns `undefined` when the body is larger (answer 413) or the client went away. */
+export async function readBody(incoming, maxBytes = DEFAULT_MAX_BYTES) {
+    const chunks = [];
+    let size = 0;
+    try {
+        for await (const chunk of incoming) {
+            size += chunk.length;
+            if (size > maxBytes) {
+                incoming.resume();
+                return undefined;
+            }
+            chunks.push(chunk);
+        }
+    }
+    catch {
+        return undefined;
+    }
+    const body = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        body.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return body;
+}
+/** The web `Request` for an incoming Node request, or `undefined` when its body is over `maxBytes` or unreadable. */
+export async function webRequest(incoming, url, { signal, maxBytes = DEFAULT_MAX_BYTES } = {}) {
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(incoming.headers)) {
+        if (value === undefined)
+            continue;
+        for (const item of Array.isArray(value) ? value : [value])
+            headers.append(name, item);
+    }
+    const init = { method: incoming.method ?? 'GET', headers, ...(signal ? { signal } : {}) };
+    if (init.method === 'GET' || init.method === 'HEAD')
+        return new Request(url, init);
+    const body = await readBody(incoming, maxBytes);
+    return body === undefined ? undefined : new Request(url, { ...init, body: body });
+}
+/**
+ * Write a web `Response` to a Node response: status and headers first (flushed immediately; multiple `set-cookie` values kept),
+ * then the body chunk by chunk, waiting for `drain` whenever `write()` returns false. When the client disconnects or `signal`
+ * aborts, the web body is cancelled and this resolves. A body that fails mid-stream destroys the connection, so the client
+ * sees a truncated response rather than a clean end, and the error is rethrown.
+ */
+export async function sendWebResponse(response, outgoing, { signal } = {}) {
+    const headers = {};
+    response.headers.forEach((value, name) => { if (name !== 'set-cookie')
+        headers[name] = value; });
+    const cookies = response.headers.getSetCookie();
+    if (cookies.length)
+        headers['set-cookie'] = cookies;
+    outgoing.writeHead(response.status, headers);
+    outgoing.flushHeaders();
+    if (!response.body) {
+        outgoing.end();
+        return;
+    }
+    const reader = response.body.getReader();
+    let gone = false;
+    const stop = () => { gone = true; void reader.cancel().catch(() => { }); };
+    const closed = () => { if (!outgoing.writableFinished)
+        stop(); };
+    if (signal?.aborted)
+        stop();
+    signal?.addEventListener('abort', stop, { once: true });
+    outgoing.on('close', closed);
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done || gone || outgoing.destroyed)
+                break;
+            if (!outgoing.write(value)) {
+                await new Promise(resolve => {
+                    const go = () => { outgoing.off('drain', go); outgoing.off('close', go); signal?.removeEventListener('abort', go); resolve(); };
+                    outgoing.on('drain', go);
+                    outgoing.on('close', go);
+                    signal?.addEventListener('abort', go, { once: true });
+                });
+            }
+        }
+    }
+    catch (error) {
+        if (gone || outgoing.destroyed)
+            return;
+        outgoing.destroy(error instanceof Error ? error : new Error(String(error)));
+        throw error;
+    }
+    finally {
+        signal?.removeEventListener('abort', stop);
+        outgoing.off('close', closed);
+    }
+    if (gone) {
+        if (!outgoing.destroyed)
+            outgoing.destroy();
+        return;
+    }
+    if (!outgoing.destroyed)
+        outgoing.end();
+}

package/dist/platform.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Environment-sensitive browser capabilities, in one place. Browsers expose `crypto.randomUUID`, `crypto.subtle`,
+ * `navigator.clipboard` and `navigator.share` only in secure contexts (HTTPS, localhost); a page served over plain HTTP on a
+ * private network gets none of them. Every browser-reachable package and the studio import these instead of the raw APIs,
+ * and `npm run check` (scripts/check-platform-apis.mjs) fails when browser-reachable source uses a raw one.
+ */
+/** A version 4 UUID; falls back to `crypto.getRandomValues`, which every context has. */
+export declare function randomUUID(): string;
+/**
+ * Puts `text` on the clipboard: the async Clipboard API where present, otherwise a hidden-textarea `execCommand('copy')`
+ * (works over plain HTTP). Resolves `false` when neither worked, so the caller can show the text for a manual copy.
+ */
+export declare function copyToClipboard(text: string): Promise<boolean>;
+/** SHA-256 of `bytes`; without `crypto.subtle` it uses the portable standard (FIPS 180-4) implementation below, with identical output. */
+export declare function sha256(bytes: Uint8Array<ArrayBuffer>): Promise<Uint8Array>;
+/** SHA-1 of `bytes` (a content identifier, not a security boundary): `crypto.subtle` where present, otherwise the portable implementation below. */
+export declare function sha1(bytes: Uint8Array<ArrayBuffer>): Promise<Uint8Array>;
+/** Exported for the equivalence check only; use `sha1`. */
+export declare function sha1Portable(bytes: Uint8Array): Uint8Array;
+/** Exported for the equivalence check only; use `sha256`. */
+export declare function sha256Portable(bytes: Uint8Array): Uint8Array;
+//# sourceMappingURL=platform.d.ts.map