@shardflux/sdk 0.6.2 → 0.8.0

package/dist/tar.js

@@ -0,0 +1,150 @@
+/**
+ * A small tar writer for build uploads of folders (contracts §24.2: uncompressed ustar/pax, extracted by the host's
+ * static tool). Pure: no Node imports, so the browser bundle can carry it.
+ *
+ * The bytes equal CPython's `tarfile.open(mode="w", format=tarfile.PAX_FORMAT)` with every member added by hand (the
+ * Python SDK's writer), so both SDKs upload the same bytes for the same folder and a template built from either has the
+ * same recipe_sha256:
+ * - a pax `x` header (`././@PaxHeader`) precedes a member whose name or link target is non-ASCII or longer than 100
+ *   characters (`path`, `linkpath` records), or whose size does not fit the 11 octal digits (`size`);
+ * - the ustar header then holds the name encoded as ASCII with `?` for each non-ASCII code point, truncated to 100 bytes;
+ * - the archive ends with two zero blocks and is padded to a multiple of 10240 bytes (tarfile's RECORDSIZE).
+ */
+export const TAR_BLOCK = 512;
+export const TAR_RECORD_SIZE = 20 * TAR_BLOCK;
+const TYPEFLAG = { file: 0x30, dir: 0x35, symlink: 0x32 };
+const utf8 = new TextEncoder();
+function isAscii(s) {
+    for (let i = 0; i < s.length; i += 1)
+        if (s.charCodeAt(i) > 0x7f)
+            return false;
+    return true;
+}
+/** Python's `s.encode("ascii", "replace")`: one `?` per non-ASCII code point (not per UTF-16 unit). */
+function asciiReplace(s) {
+    const out = [];
+    for (const ch of s)
+        out.push(ch.codePointAt(0) > 0x7f ? 0x3f : ch.charCodeAt(0));
+    return Uint8Array.from(out);
+}
+/** tarfile's stn(): the bytes truncated to `length` and NUL-padded. */
+function putString(buf, offset, length, bytes) {
+    buf.set(bytes.subarray(0, length), offset);
+}
+/** tarfile's itn() for the POSIX range: `%0*o` with digits-1 digits and a NUL. */
+function putOctal(buf, offset, digits, value) {
+    const text = `${value.toString(8).padStart(digits - 1, '0')}\0`;
+    buf.set(utf8.encode(text), offset);
+}
+/** Python's len(str): code points. */
+function codePoints(s) {
+    return Array.from(s).length;
+}
+/** tarfile's _create_header(info, USTAR_FORMAT, "ascii", "replace"). */
+function ustarHeader(info) {
+    const h = new Uint8Array(TAR_BLOCK);
+    putString(h, 0, 100, asciiReplace(info.name));
+    putOctal(h, 100, 8, info.mode & 0o7777);
+    putOctal(h, 108, 8, info.uid);
+    putOctal(h, 116, 8, info.gid);
+    putOctal(h, 124, 12, info.size);
+    putOctal(h, 136, 12, info.mtime);
+    h.fill(0x20, 148, 156);
+    h[156] = info.type;
+    putString(h, 157, 100, asciiReplace(info.linkname));
+    h.set(utf8.encode('ustar\x0000'), 257);
+    putString(h, 265, 32, asciiReplace(info.uname));
+    putString(h, 297, 32, asciiReplace(info.gname));
+    // devmajor, devminor and prefix stay NUL (tarfile writes empty strings for non-device members).
+    let sum = 0;
+    for (const b of h)
+        sum += b;
+    h.set(utf8.encode(`${sum.toString(8).padStart(6, '0')}\0`), 148);
+    return h;
+}
+/** Zero padding after `size` bytes of member data. */
+export function tarPadding(size) {
+    const rest = size % TAR_BLOCK;
+    return new Uint8Array(rest === 0 ? 0 : TAR_BLOCK - rest);
+}
+/** tarfile's pax record: "%d %s=%s\n" where the length counts itself. */
+function paxRecord(keyword, value) {
+    const kv = utf8.encode(`${keyword}=${value}\n`);
+    const l = kv.length + 1; // + ' '
+    let p = 0;
+    for (;;) {
+        const n = l + String(p).length;
+        if (n === p)
+            break;
+        p = n;
+    }
+    const head = utf8.encode(`${p} `);
+    const out = new Uint8Array(head.length + kv.length);
+    out.set(head, 0);
+    out.set(kv, head.length);
+    return out;
+}
+/**
+ * The header block(s) of one member: an optional pax extended header with its records, then the ustar header.
+ * Member data (a file's bytes) follows, then tarPadding(size).
+ */
+export function tarHeader(entry) {
+    const name = entry.type === 'dir' && !entry.path.endsWith('/') ? `${entry.path}/` : entry.path;
+    const info = {
+        name,
+        mode: entry.mode,
+        uid: entry.uid ?? 0,
+        gid: entry.gid ?? 0,
+        size: entry.type === 'file' ? entry.size : 0,
+        mtime: entry.mtime ?? 0,
+        type: TYPEFLAG[entry.type],
+        linkname: entry.linkname ?? '',
+        uname: entry.uname ?? '',
+        gname: entry.gname ?? '',
+    };
+    const records = [];
+    for (const [field, keyword, length] of [
+        ['name', 'path', 100],
+        ['linkname', 'linkpath', 100],
+        ['uname', 'uname', 32],
+        ['gname', 'gname', 32],
+    ]) {
+        const value = info[field];
+        if (!isAscii(value) || codePoints(value) > length)
+            records.push(paxRecord(keyword, value));
+    }
+    for (const [field, digits] of [
+        ['uid', 8],
+        ['gid', 8],
+        ['size', 12],
+        ['mtime', 12],
+    ]) {
+        const value = info[field];
+        if (!(value >= 0 && value < 8 ** (digits - 1))) {
+            records.push(paxRecord(field, String(value)));
+            info[field] = 0;
+        }
+    }
+    const header = ustarHeader(info);
+    if (records.length === 0)
+        return header;
+    const total = records.reduce((n, r) => n + r.length, 0);
+    const payload = new Uint8Array(total + tarPadding(total).length);
+    let at = 0;
+    for (const r of records) {
+        payload.set(r, at);
+        at += r.length;
+    }
+    const pax = ustarHeader({ name: '././@PaxHeader', mode: 0, uid: 0, gid: 0, size: total, mtime: 0, type: 0x78, linkname: '', uname: '', gname: '' });
+    const out = new Uint8Array(pax.length + payload.length + header.length);
+    out.set(pax, 0);
+    out.set(payload, pax.length);
+    out.set(header, pax.length + payload.length);
+    return out;
+}
+/** The end of an archive written so far (`offset` bytes): two zero blocks, then zeros up to a multiple of 10240. */
+export function tarEnd(offset) {
+    const end = offset + 2 * TAR_BLOCK;
+    const rest = end % TAR_RECORD_SIZE;
+    return new Uint8Array(2 * TAR_BLOCK + (rest === 0 ? 0 : TAR_RECORD_SIZE - rest));
+}

package/dist/template-file.d.ts

@@ -0,0 +1,92 @@
+type Fs = typeof import('node:fs');
+type FsPromises = typeof import('node:fs/promises');
+type Path = typeof import('node:path');
+type Os = typeof import('node:os');
+type Crypto = typeof import('node:crypto');
+type Stream = {
+    Readable: typeof import('node:stream').Readable;
+};
+interface NodeModules {
+    fs: Fs;
+    fsp: FsPromises;
+    path: Path;
+    os: Os;
+    crypto: Crypto;
+    stream: Stream;
+}
+/** The Node modules this file needs, loaded once (throws outside Node). */
+export declare function nodeModules(): Promise<NodeModules>;
+/** A template file that cannot be read, parsed or packed (before any request is made). */
+export declare class TemplateFileError extends Error {
+    /** The template file or local path concerned, when there is one. */
+    readonly path: string | undefined;
+    constructor(message: string, path?: string);
+}
+/** Largest single upload (contracts §24.2: 5 GiB, one presigned PUT). */
+export declare const UPLOAD_BYTES_MAX = 5368709120;
+/** Most entries a folder tar may have (the host's extraction limit, §24.2). */
+export declare const TAR_ENTRIES_MAX = 200000;
+export declare const RECIPE_V2_SCHEMA = "shardflux.template-recipe.v2";
+/** Parses YAML text: the optional `yaml` package's parse() unless the caller passes its own. */
+export type YamlParser = (text: string) => unknown;
+/**
+ * The document of a template file: `.json` is JSON, anything else YAML (JSON is valid YAML too). YAML needs the
+ * optional `yaml` package (`npm install yaml`) or `parseYaml`; without either, a YAML file that is not valid JSON fails.
+ */
+export declare function parseTemplateText(text: string, fileName: string, parseYaml?: YamlParser): Promise<Record<string, unknown>>;
+/** The recipe v2 document: a mapping whose `schema` is recipe v2 (filled in when absent). */
+export declare function normalizeTemplateDocument(doc: unknown, where?: string): Record<string, unknown>;
+/** Reads and parses a template file (template.yaml or .json). */
+export declare function readTemplateFile(file: string, opts?: {
+    parseYaml?: YamlParser;
+}): Promise<Record<string, unknown>>;
+export interface PackedFile {
+    sha256: string;
+    size: number;
+    /** Tar members (folders), null for a file uploaded as it is. */
+    entries: number | null;
+}
+/** SHA-256 (lower-case hex) and size of a local file, streamed. */
+export declare function hashFile(file: string): Promise<{
+    sha256: string;
+    size: number;
+}>;
+/**
+ * Packs the folder `root` into `dest` as the reproducible tar (tar.ts; byte-identical to the Python SDK's): members in
+ * UTF-8 path order, mtime 0, uid/gid 0 without names, permission bits kept (symlinks 0777). Returns its sha256, size and
+ * member count.
+ */
+export declare function packDirectory(root: string, dest: string): Promise<PackedFile>;
+/** Refuses `target` when it resolves, after symlinks, outside `root` (an agent-facing server confines local reads). */
+export declare function assertInside(root: string, target: string, what: string): Promise<void>;
+/** One `from` entry resolved on the disk: what gets uploaded and how. */
+export interface LocalSource {
+    /** `from` as written. */
+    from: string;
+    /** The resolved local path. */
+    path: string;
+    kind: 'file' | 'tar';
+    /** The bytes to upload: the file itself, or the packed tar in a temporary directory. */
+    uploadPath: string;
+    sha256: string;
+    size: number;
+    entries: number | null;
+}
+/**
+ * Resolves `from` (relative to `baseDir`), checks it against `root` when given (after symlinks), and packs or hashes
+ * it. `kind` omitted: a folder is `tar`, a file is `file`. A folder with kind `file` is refused; a file with kind `tar`
+ * is a prepared (uncompressed) archive.
+ */
+export declare function resolveLocalSource(from: string, kind: 'file' | 'tar' | undefined, opts: {
+    baseDir: string;
+    root?: string | undefined;
+    tmpDir: () => Promise<string>;
+}): Promise<LocalSource>;
+/** A fetch body that streams a local file (replayable: each call opens it again). */
+export declare function fileBody(file: string): Promise<ReadableStream<Uint8Array>>;
+/** A private temporary directory, created on first use; `cleanup()` removes it. */
+export declare function tempDir(): {
+    get: () => Promise<string>;
+    cleanup: () => Promise<void>;
+};
+export {};

package/dist/template-file.js

@@ -0,0 +1,326 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { tarEnd, tarHeader, tarPadding } from "./tar.js";
+let loaded;
+/** The Node modules this file needs, loaded once (throws outside Node). */
+export function nodeModules() {
+    if (typeof process === 'undefined' || typeof process.versions?.node !== 'string') {
+        return Promise.reject(new TemplateFileError('Building from local files needs Node.js (it reads the disk); send a recipe with uploads instead.'));
+    }
+    const modules = (loaded ??= Promise.all([
+        import(/* webpackIgnore: true */ /* @vite-ignore */ 'node:fs'),
+        import(/* webpackIgnore: true */ /* @vite-ignore */ 'node:fs/promises'),
+        import(/* webpackIgnore: true */ /* @vite-ignore */ 'node:path'),
+        import(/* webpackIgnore: true */ /* @vite-ignore */ 'node:os'),
+        import(/* webpackIgnore: true */ /* @vite-ignore */ 'node:crypto'),
+        import(/* webpackIgnore: true */ /* @vite-ignore */ 'node:stream'),
+    ]).then(([fs, fsp, path, os, crypto, stream]) => ({ fs, fsp, path, os, crypto, stream: { Readable: stream.Readable } })));
+    return modules;
+}
+/** A template file that cannot be read, parsed or packed (before any request is made). */
+export class TemplateFileError extends Error {
+    /** The template file or local path concerned, when there is one. */
+    path;
+    constructor(message, path) {
+        super(message);
+        this.name = 'TemplateFileError';
+        this.path = path;
+    }
+}
+/** Largest single upload (contracts §24.2: 5 GiB, one presigned PUT). */
+export const UPLOAD_BYTES_MAX = 5_368_709_120;
+/** Most entries a folder tar may have (the host's extraction limit, §24.2). */
+export const TAR_ENTRIES_MAX = 200_000;
+export const RECIPE_V2_SCHEMA = 'shardflux.template-recipe.v2';
+async function defaultYamlParser() {
+    const spec = 'yaml';
+    try {
+        const mod = (await import(__rewriteRelativeImportExtension(/* webpackIgnore: true */ /* @vite-ignore */ spec)));
+        const parse = mod.parse ?? mod.default?.parse;
+        return typeof parse === 'function' ? parse : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The document of a template file: `.json` is JSON, anything else YAML (JSON is valid YAML too). YAML needs the
+ * optional `yaml` package (`npm install yaml`) or `parseYaml`; without either, a YAML file that is not valid JSON fails.
+ */
+export async function parseTemplateText(text, fileName, parseYaml) {
+    let doc;
+    if (/\.json$/i.test(fileName)) {
+        try {
+            doc = JSON.parse(text);
+        }
+        catch (err) {
+            throw new TemplateFileError(`${fileName}: not valid JSON (${err instanceof Error ? err.message : String(err)})`, fileName);
+        }
+    }
+    else {
+        const parse = parseYaml ?? (await defaultYamlParser());
+        if (parse) {
+            try {
+                doc = parse(text);
+            }
+            catch (err) {
+                throw new TemplateFileError(`${fileName}: not valid YAML (${err instanceof Error ? (err.message.split('\n')[0] ?? err.message) : String(err)})`, fileName);
+            }
+        }
+        else {
+            try {
+                doc = JSON.parse(text);
+            }
+            catch {
+                throw new TemplateFileError(`${fileName}: reading YAML needs the "yaml" package (npm install yaml) or the parseYaml option`, fileName);
+            }
+        }
+    }
+    return normalizeTemplateDocument(doc, fileName);
+}
+/** The recipe v2 document: a mapping whose `schema` is recipe v2 (filled in when absent). */
+export function normalizeTemplateDocument(doc, where = 'the template') {
+    if (typeof doc !== 'object' || doc === null || Array.isArray(doc))
+        throw new TemplateFileError(`${where}: expected a mapping (the recipe v2 document), got ${doc === null ? 'null' : Array.isArray(doc) ? 'a list' : typeof doc}`, where);
+    const out = { ...doc };
+    if (out.schema === undefined)
+        out.schema = RECIPE_V2_SCHEMA;
+    else if (out.schema !== RECIPE_V2_SCHEMA)
+        throw new TemplateFileError(`${where}: schema must be ${RECIPE_V2_SCHEMA} (got ${JSON.stringify(out.schema)}); Dockerfile recipes (v1) are built with templates.builds.create`, where);
+    return out;
+}
+/** Reads and parses a template file (template.yaml or .json). */
+export async function readTemplateFile(file, opts = {}) {
+    const { fsp } = await nodeModules();
+    let text;
+    try {
+        text = await fsp.readFile(file, 'utf8');
+    }
+    catch (err) {
+        throw new TemplateFileError(`cannot read ${file} (${err.code ?? String(err)})`, file);
+    }
+    return parseTemplateText(text, file, opts.parseYaml);
+}
+/** SHA-256 (lower-case hex) and size of a local file, streamed. */
+export async function hashFile(file) {
+    const { fs, crypto } = await nodeModules();
+    const hash = crypto.createHash('sha256');
+    let size = 0;
+    for await (const chunk of fs.createReadStream(file)) {
+        const b = chunk;
+        size += b.length;
+        hash.update(b);
+    }
+    return { sha256: hash.digest('hex'), size };
+}
+const fatalUtf8 = new TextDecoder('utf-8', { fatal: true });
+/** Every directory, file and symlink below `root` (not following symlinks), sorted by UTF-8 path bytes. */
+async function walk(root) {
+    const { fsp, path } = await nodeModules();
+    const out = [];
+    const visit = async (dirAbs, prefix) => {
+        const names = await fsp.readdir(dirAbs, { encoding: 'buffer' });
+        for (const raw of names) {
+            let name;
+            try {
+                name = fatalUtf8.decode(raw);
+            }
+            catch {
+                throw new TemplateFileError(`${path.join(root, prefix)}: a name that is not UTF-8 cannot be uploaded (${raw.toString('hex')})`, dirAbs);
+            }
+            const rel = prefix ? `${prefix}/${name}` : name;
+            const abs = path.join(dirAbs, name);
+            const st = await fsp.lstat(abs);
+            let entry;
+            if (st.isDirectory())
+                entry = { path: rel, type: 'dir', mode: st.mode & 0o777, size: 0 };
+            else if (st.isFile())
+                entry = { path: rel, type: 'file', mode: st.mode & 0o777, size: st.size };
+            else if (st.isSymbolicLink()) {
+                const target = await fsp.readlink(abs);
+                checkSymlink(rel, target, abs);
+                entry = { path: rel, type: 'symlink', mode: 0o777, size: 0, linkname: target };
+            }
+            else {
+                const kind = st.isFIFO() ? 'a FIFO' : st.isSocket() ? 'a socket' : st.isCharacterDevice() || st.isBlockDevice() ? 'a device' : 'an unsupported file type';
+                throw new TemplateFileError(`${abs}: ${kind} cannot be uploaded (folders may hold files, directories and symlinks)`, abs);
+            }
+            out.push({ rel, key: Buffer.from(rel, 'utf8'), abs, entry });
+            if (out.length > TAR_ENTRIES_MAX)
+                throw new TemplateFileError(`${root}: more than ${TAR_ENTRIES_MAX} entries (the build host's limit for one folder)`, root);
+            if (entry.type === 'dir')
+                await visit(abs, rel);
+        }
+    };
+    await visit(root, '');
+    out.sort((a, b) => Buffer.compare(a.key, b.key));
+    return out;
+}
+/** The host refuses absolute symlink targets and targets that leave the extracted tree (§24.2); refuse them here. */
+function checkSymlink(rel, target, abs) {
+    if (target.startsWith('/'))
+        throw new TemplateFileError(`${abs}: symlink to an absolute path (${target}); the build host refuses it (use a relative target inside the folder)`, abs);
+    const parts = rel.split('/').slice(0, -1);
+    for (const p of target.split('/')) {
+        if (p === '' || p === '.')
+            continue;
+        if (p === '..') {
+            if (parts.length === 0)
+                throw new TemplateFileError(`${abs}: symlink leaves the folder (${target}); the build host refuses it`, abs);
+            parts.pop();
+        }
+        else
+            parts.push(p);
+    }
+}
+/**
+ * Packs the folder `root` into `dest` as the reproducible tar (tar.ts; byte-identical to the Python SDK's): members in
+ * UTF-8 path order, mtime 0, uid/gid 0 without names, permission bits kept (symlinks 0777). Returns its sha256, size and
+ * member count.
+ */
+export async function packDirectory(root, dest) {
+    const { fs, fsp, crypto } = await nodeModules();
+    const entries = await walk(root);
+    const hash = crypto.createHash('sha256');
+    const handle = await fsp.open(dest, 'w', 0o600);
+    let offset = 0;
+    const write = async (b) => {
+        if (b.length === 0)
+            return;
+        hash.update(b);
+        let done = 0;
+        while (done < b.length) {
+            const { bytesWritten } = await handle.write(b, done, b.length - done);
+            done += bytesWritten;
+        }
+        offset += b.length;
+    };
+    try {
+        for (const w of entries) {
+            await write(tarHeader(w.entry));
+            if (w.entry.type !== 'file')
+                continue;
+            let read = 0;
+            for await (const chunk of fs.createReadStream(w.abs)) {
+                const b = chunk;
+                read += b.length;
+                if (read > w.entry.size)
+                    break;
+                await write(b);
+            }
+            if (read !== w.entry.size)
+                throw new TemplateFileError(`${w.abs} changed while it was packed (${w.entry.size} bytes expected, ${read} read)`, w.abs);
+            await write(tarPadding(w.entry.size));
+        }
+        await write(tarEnd(offset));
+    }
+    finally {
+        await handle.close();
+    }
+    return { sha256: hash.digest('hex'), size: offset, entries: entries.length };
+}
+const COMPRESSED = [
+    { name: 'gzip', magic: [0x1f, 0x8b] },
+    { name: 'xz', magic: [0xfd, 0x37, 0x7a, 0x58, 0x5a, 0x00] },
+    { name: 'zstd', magic: [0x28, 0xb5, 0x2f, 0xfd] },
+];
+/** A prepared archive must be an uncompressed tar: the build host refuses gzip, xz and zstd (§24.2). */
+async function checkUncompressed(file) {
+    const { fsp } = await nodeModules();
+    const handle = await fsp.open(file, 'r');
+    try {
+        const head = Buffer.alloc(6);
+        const { bytesRead } = await handle.read(head, 0, 6, 0);
+        for (const c of COMPRESSED) {
+            if (bytesRead >= c.magic.length && c.magic.every((b, i) => head[i] === b))
+                throw new TemplateFileError(`${file}: a ${c.name}-compressed archive; the build host takes uncompressed tar only (or point "from" at the folder)`, file);
+        }
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Refuses `target` when it resolves, after symlinks, outside `root` (an agent-facing server confines local reads). */
+export async function assertInside(root, target, what) {
+    const { fsp, path } = await nodeModules();
+    let real;
+    let base;
+    try {
+        [real, base] = await Promise.all([fsp.realpath(target), fsp.realpath(root)]);
+    }
+    catch (err) {
+        throw new TemplateFileError(`${what}: cannot read ${target} (${err.code ?? String(err)})`, target);
+    }
+    const rel = path.relative(base, real);
+    if (rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel))
+        throw new TemplateFileError(`${what} resolves outside ${base}; only paths inside it may be read`, target);
+}
+/**
+ * Resolves `from` (relative to `baseDir`), checks it against `root` when given (after symlinks), and packs or hashes
+ * it. `kind` omitted: a folder is `tar`, a file is `file`. A folder with kind `file` is refused; a file with kind `tar`
+ * is a prepared (uncompressed) archive.
+ */
+export async function resolveLocalSource(from, kind, opts) {
+    const { fsp, path } = await nodeModules();
+    const resolved = path.resolve(opts.baseDir, from);
+    let st;
+    try {
+        st = await fsp.stat(resolved);
+    }
+    catch (err) {
+        throw new TemplateFileError(`from: ${from}: cannot read ${resolved} (${err.code ?? String(err)})`, resolved);
+    }
+    if (opts.root !== undefined)
+        await assertInside(opts.root, resolved, `from: ${from}`);
+    const effective = kind ?? (st.isDirectory() ? 'tar' : 'file');
+    if (st.isDirectory()) {
+        if (effective !== 'tar')
+            throw new TemplateFileError(`from: ${from} is a folder; a folder uploads as kind tar`, resolved);
+        const dest = path.join(await opts.tmpDir(), `${path.basename(resolved) || 'folder'}-${Math.random().toString(16).slice(2, 10)}.tar`);
+        const packed = await packDirectory(resolved, dest);
+        if (packed.size > UPLOAD_BYTES_MAX)
+            throw new TemplateFileError(`from: ${from} packs to ${packed.size} bytes; one upload is at most ${UPLOAD_BYTES_MAX} bytes (5 GiB)`, resolved);
+        return { from, path: resolved, kind: 'tar', uploadPath: dest, ...packed };
+    }
+    if (!st.isFile())
+        throw new TemplateFileError(`from: ${from} is neither a file nor a folder`, resolved);
+    if (st.size > UPLOAD_BYTES_MAX)
+        throw new TemplateFileError(`from: ${from} is ${st.size} bytes; one upload is at most ${UPLOAD_BYTES_MAX} bytes (5 GiB)`, resolved);
+    if (effective === 'tar')
+        await checkUncompressed(resolved);
+    const { sha256, size } = await hashFile(resolved);
+    return { from, path: resolved, kind: effective, uploadPath: resolved, sha256, size, entries: null };
+}
+/** A fetch body that streams a local file (replayable: each call opens it again). */
+export async function fileBody(file) {
+    const { fs, stream } = await nodeModules();
+    return stream.Readable.toWeb(fs.createReadStream(file));
+}
+/** A private temporary directory, created on first use; `cleanup()` removes it. */
+export function tempDir() {
+    let dir;
+    return {
+        get: async () => {
+            if (!dir) {
+                const { fsp, os, path } = await nodeModules();
+                dir = fsp.mkdtemp(path.join(os.tmpdir(), 'shardflux-template-'));
+            }
+            return dir;
+        },
+        cleanup: async () => {
+            if (!dir)
+                return;
+            const d = await dir.catch(() => null);
+            if (d === null)
+                return;
+            const { fsp } = await nodeModules();
+            await fsp.rm(d, { recursive: true, force: true });
+        },
+    };
+}