@qvac/harness 0.0.0 → 0.1.1

package/dist-lib/lib/tools/exec/adapters/python/create-effect.js

@@ -0,0 +1,290 @@
+import { IMAGE_INPUT, OFFICE_READ, PDF_READ, isEscaped, parseInputs, parseOutputs, parsePackages, stripCommentsAndDocstrings, unwrapPythonSource } from "./python-adapter.js";
+const ARTIFACT_OUTPUT = /\.(docx|xlsx|pptx|pdf)$/i;
+const CREATE_PACKAGES = new Map([
+    ['python-docx', '1.2.0'],
+    ['openpyxl', '3.1.5'],
+    ['python-pptx', '1.0.2'],
+    ['fpdf2', '2.8.8'],
+    ['pillow', null]
+]);
+const PACKAGE_SPEC = /^([A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?)(?:==([0-9A-Za-z.]+))?$/;
+const IMPORT_ROOTS = new Set(['docx', 'openpyxl', 'pptx', 'fpdf', 'datetime']);
+const BUILDER_ROOTS = new Set(['docx', 'openpyxl', 'pptx', 'fpdf']);
+const IMPORT_FROM = /^\s*from\s+([A-Za-z]\w*(?:\.[A-Za-z]\w*)*)\s+import\s+[A-Za-z]\w*(?:\s+as\s+[A-Za-z]\w*)?(?:\s*,\s*[A-Za-z]\w*(?:\s+as\s+[A-Za-z]\w*)?)*\s*$/;
+const ALLOWED_BUILTINS = new Set([
+    'True',
+    'False',
+    'None',
+    'Ellipsis',
+    'NotImplemented',
+    'Exception',
+    'ValueError',
+    'KeyError',
+    'IndexError',
+    'TypeError',
+    'RuntimeError',
+    'abs',
+    'all',
+    'any',
+    'bool',
+    'dict',
+    'divmod',
+    'enumerate',
+    'filter',
+    'float',
+    'int',
+    'len',
+    'list',
+    'map',
+    'max',
+    'min',
+    'pow',
+    'print',
+    'range',
+    'reversed',
+    'round',
+    'set',
+    'sorted',
+    'str',
+    'sum',
+    'tuple',
+    'zip'
+]);
+const PYTHON_BUILTINS = new Set(`ArithmeticError AssertionError AttributeError BaseException BaseExceptionGroup
+   BlockingIOError BrokenPipeError BufferError BytesWarning ChildProcessError
+   ConnectionAbortedError ConnectionError ConnectionRefusedError ConnectionResetError
+   DeprecationWarning EOFError Ellipsis EncodingWarning EnvironmentError Exception
+   ExceptionGroup False FileExistsError FileNotFoundError FloatingPointError
+   FutureWarning GeneratorExit IOError ImportError ImportWarning IndentationError
+   IndexError InterruptedError IsADirectoryError KeyError KeyboardInterrupt
+   LookupError MemoryError ModuleNotFoundError NameError None NotADirectoryError
+   NotImplemented NotImplementedError OSError OverflowError PendingDeprecationWarning
+   PermissionError ProcessLookupError PythonFinalizationError RecursionError
+   ReferenceError ResourceWarning RuntimeError RuntimeWarning StopAsyncIteration
+   StopIteration SyntaxError SyntaxWarning SystemError SystemExit TabError
+   TimeoutError True TypeError UnboundLocalError UnicodeDecodeError
+   UnicodeEncodeError UnicodeError UnicodeTranslateError UnicodeWarning UserWarning
+   ValueError Warning ZeroDivisionError abs aiter all anext any ascii bin bool
+   breakpoint bytearray bytes callable chr classmethod compile complex copyright
+   credits delattr dict dir divmod enumerate eval exec execfile exit filter float
+   format frozenset getattr globals hasattr hash help hex id input int isinstance
+   issubclass iter len license list locals map max memoryview min next object oct
+   open ord pow print property quit range reload repr reversed round set setattr
+   slice sorted staticmethod str sum super tuple type unicode vars zip`.split(/\s+/));
+const DENIED_TOKENS = new Set([
+    'os',
+    'sys',
+    'js',
+    'pyodide',
+    'micropip',
+    'builtins',
+    'importlib',
+    'inspect',
+    'ctypes',
+    'subprocess',
+    'platform',
+    'shutil',
+    'pathlib',
+    'glob',
+    'tempfile',
+    'gc',
+    'socket',
+    'requests',
+    'urllib',
+    'http',
+    'ssl',
+    'ftplib',
+    'smtplib',
+    'webbrowser',
+    'pickle',
+    'marshal',
+    'base64',
+    'codecs',
+    'io',
+    'threading',
+    'asyncio',
+    'async',
+    'await',
+    'format_map',
+    'vformat'
+]);
+const INTROSPECTION_TOKEN = /^(?:gi|cr|ag|f|tb|im|func)_/;
+function isFStringPrefix(code) {
+    const prefix = /[A-Za-z]{1,3}$/.exec(code)?.[0] ?? '';
+    return prefix.length <= 2 && /f/i.test(prefix);
+}
+export function splitPythonSource(source) {
+    let code = '';
+    let text = '';
+    let i = 0;
+    while (i < source.length) {
+        const ch = source[i];
+        if (ch === '#') {
+            while (i < source.length && source[i] !== '\n') {
+                text += source[i];
+                i++;
+            }
+            continue;
+        }
+        const triple = source.startsWith('"""', i) ? '"""' : source.startsWith("'''", i) ? "'''" : null;
+        const quote = triple ?? (ch === '"' || ch === "'" ? ch : null);
+        if (quote) {
+            const fstring = isFStringPrefix(code);
+            const end = scanLiteral(source, i + quote.length, quote, fstring);
+            if (!end)
+                return null;
+            code += '""';
+            text += end.text;
+            code += end.code;
+            i = end.index;
+            continue;
+        }
+        code += ch;
+        i++;
+    }
+    return { code, text };
+}
+function scanLiteral(source, start, quote, fstring) {
+    let text = '';
+    let code = '';
+    let i = start;
+    while (i < source.length) {
+        if (source.startsWith(quote, i) && !isEscaped(source, i)) {
+            return { index: i + quote.length, text, code };
+        }
+        const ch = source[i];
+        if (fstring && (ch === '{' || ch === '}')) {
+            if (source[i + 1] === ch) {
+                text += ch + ch;
+                i += 2;
+                continue;
+            }
+            if (ch === '}')
+                return null;
+            const interior = scanInterpolation(source, i + 1);
+            if (!interior)
+                return null;
+            code += ` ${interior.code} `;
+            text += interior.text;
+            i = interior.index;
+            continue;
+        }
+        text += ch;
+        i++;
+    }
+    return null;
+}
+function scanInterpolation(source, start) {
+    let code = '';
+    let text = '';
+    let depth = 1;
+    let nested = null;
+    let i = start;
+    while (i < source.length) {
+        const ch = source[i];
+        if (nested) {
+            if (ch === nested && !isEscaped(source, i))
+                nested = null;
+            else
+                text += ch;
+            i++;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            nested = ch;
+            i++;
+            continue;
+        }
+        if (ch === '{')
+            depth++;
+        if (ch === '}') {
+            depth--;
+            if (depth === 0)
+                return { index: i + 1, text, code };
+        }
+        code += ch;
+        i++;
+    }
+    return null;
+}
+function isKeywordArgument(code, start, length) {
+    const before = code.slice(0, start).trimEnd();
+    const last = before[before.length - 1];
+    if (last !== '(' && last !== ',')
+        return false;
+    const after = code.slice(start + length).trimStart();
+    return after.startsWith('=') && after[1] !== '=';
+}
+function lintCreateSource(source) {
+    const halves = splitPythonSource(source);
+    if (!halves)
+        return 'write';
+    if (halves.text.includes('__'))
+        return 'write';
+    if (/\\(?:x[0-9A-Fa-f]|u[0-9A-Fa-f]|U[0-9A-Fa-f]|N\{|[0-7])/.test(halves.text))
+        return 'write';
+    if (/[^\x20-\x7e\t\r\n\f]/.test(halves.code))
+        return 'write';
+    let builder = false;
+    for (const line of halves.code.split('\n')) {
+        for (const statement of line.split(';')) {
+            if (!/\b(?:from|import)\b/.test(statement))
+                continue;
+            const match = IMPORT_FROM.exec(statement);
+            if (!match)
+                return 'write';
+            const root = match[1].split('.')[0];
+            if (!IMPORT_ROOTS.has(root))
+                return 'write';
+            if (BUILDER_ROOTS.has(root))
+                builder = true;
+        }
+    }
+    if (!builder)
+        return 'write';
+    for (const match of halves.code.matchAll(/[A-Za-z_]\w*/g)) {
+        const token = match[0];
+        if (token.includes('__') || DENIED_TOKENS.has(token) || INTROSPECTION_TOKEN.test(token)) {
+            return 'write';
+        }
+        if (isKeywordArgument(halves.code, match.index, token.length))
+            continue;
+        if (PYTHON_BUILTINS.has(token) && !ALLOWED_BUILTINS.has(token))
+            return 'write';
+    }
+    const openers = stripCommentsAndDocstrings(source);
+    const reads = [new RegExp(OFFICE_READ.source), new RegExp(PDF_READ.source)];
+    if (reads.some((pattern) => pattern.test(openers)))
+        return 'write';
+    return 'read';
+}
+export function pythonCreateEffect(args) {
+    const outputs = parseOutputs(args.outputs);
+    if (!Array.isArray(outputs) || outputs.length === 0)
+        return 'write';
+    if (!outputs.every((name) => ARTIFACT_OUTPUT.test(name)))
+        return 'write';
+    const packages = parsePackages(args.packages);
+    if (packages && 'error' in packages)
+        return 'write';
+    for (const spec of packages ?? []) {
+        const match = PACKAGE_SPEC.exec(spec);
+        if (!match)
+            return 'write';
+        const name = match[1].toLowerCase().replace(/[_.]+/g, '-');
+        if (!CREATE_PACKAGES.has(name))
+            return 'write';
+        if (CREATE_PACKAGES.get(name) !== (match[2] ?? null))
+            return 'write';
+    }
+    const inputs = parseInputs(args.inputs);
+    if (inputs && 'error' in inputs)
+        return 'write';
+    if ((inputs ?? []).some((input) => !IMAGE_INPUT.test(input.path)))
+        return 'write';
+    const command = String(args.command ?? '');
+    const source = unwrapPythonSource(command) ?? command;
+    if (!source.trim())
+        return 'write';
+    return lintCreateSource(source);
+}

package/dist-lib/lib/tools/exec/adapters/python/loader.d.ts

@@ -0,0 +1,11 @@
+import process from 'process';
+import type { LoadPyodideFn } from './run-session.ts';
+type NodeShapedProcess = typeof process & {
+    binding(name: string): Record<string, unknown>;
+};
+export declare function nodeShapedProcess(base: typeof process): NodeShapedProcess;
+export declare function pyodideLoadOptions(): {
+    packageCacheDir: string;
+} | undefined;
+export declare const defaultLoad: LoadPyodideFn;
+export {};

package/dist-lib/lib/tools/exec/adapters/python/loader.js

@@ -0,0 +1,94 @@
+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 b4a from 'b4a';
+import { constants as fsConstants } from 'fs';
+import process from 'process';
+import { seedPackageCache } from "./wheels.js";
+class B4aTextDecoder {
+    encoding;
+    constructor(label = 'utf-8') {
+        const normalized = String(label).toLowerCase();
+        if (normalized.includes('16'))
+            this.encoding = 'utf16le';
+        else if (/latin1|iso-8859|ascii/.test(normalized))
+            this.encoding = 'latin1';
+        else
+            this.encoding = 'utf8';
+    }
+    decode(input) {
+        if (input === undefined)
+            return '';
+        const view = input instanceof ArrayBuffer
+            ? new Uint8Array(input)
+            : new Uint8Array(input.buffer, input.byteOffset, input.byteLength);
+        return b4a.toString(view, this.encoding);
+    }
+}
+class B4aTextEncoder {
+    encode(input = '') {
+        return new Uint8Array(b4a.from(String(input), 'utf8'));
+    }
+}
+export function nodeShapedProcess(base) {
+    return new Proxy(base, {
+        get(target, prop) {
+            if (prop === 'versions')
+                return { ...target.versions, node: '22.0.0' };
+            if (prop === 'binding') {
+                return (name) => (name === 'constants' ? { fs: fsConstants } : {});
+            }
+            if (prop === 'getuid')
+                return () => 0;
+            return Reflect.get(target, prop);
+        }
+    });
+}
+async function shapeBareGlobals() {
+    const g = globalThis;
+    if (!g.fetch) {
+        const bareFetch = await import('bare-fetch');
+        g.fetch = bareFetch.default;
+        g.Request = bareFetch.Request;
+        g.Response = bareFetch.Response;
+        g.Headers = bareFetch.Headers;
+    }
+    if (!g.AbortController) {
+        const { AbortController, AbortSignal } = await import('bare-abort-controller');
+        g.AbortController = AbortController;
+        g.AbortSignal = AbortSignal;
+    }
+    if (!g.TextDecoder)
+        g.TextDecoder = B4aTextDecoder;
+    if (!g.TextEncoder)
+        g.TextEncoder = B4aTextEncoder;
+    if (!g.process)
+        g.process = nodeShapedProcess(process);
+    if (!g.performance) {
+        const origin = Date.now();
+        g.performance = { now: () => Date.now() - origin, timeOrigin: origin };
+    }
+}
+export function pyodideLoadOptions() {
+    const cacheDir = process.env.QVAC_PYODIDE_CACHE_DIR;
+    if (!cacheDir)
+        return undefined;
+    return { packageCacheDir: cacheDir };
+}
+export const defaultLoad = async () => {
+    if (typeof globalThis.Bare !== 'undefined')
+        await shapeBareGlobals();
+    const moduleName = 'pyodide';
+    const { loadPyodide } = (await import(__rewriteRelativeImportExtension(moduleName)));
+    const options = pyodideLoadOptions();
+    if (options) {
+        seedPackageCache(options.packageCacheDir);
+        return (await loadPyodide(options));
+    }
+    return (await loadPyodide());
+};

package/dist-lib/lib/tools/exec/adapters/python/memfs.d.ts

@@ -0,0 +1,47 @@
+type Fs = {
+    mkdirTree(path: string): void;
+    chdir(path: string): void;
+    writeFile(path: string, data: Uint8Array): void;
+    readFile(path: string, opts: {
+        encoding: 'binary';
+    }): Uint8Array;
+    analyzePath(path: string): {
+        exists: boolean;
+    };
+    readdir(path: string): string[];
+    stat(path: string): {
+        mode: number;
+        size: number;
+    };
+    lstat(path: string): {
+        mode: number;
+    };
+    isDir(mode: number): boolean;
+    isLink(mode: number): boolean;
+    unlink(path: string): void;
+    rmdir(path: string): void;
+};
+export type Scratch = {
+    readonly dir: string;
+    readonly cwd: string;
+    [Symbol.dispose](): void;
+};
+type InputFile = {
+    readonly path: string;
+    readonly bytes: Uint8Array;
+};
+export declare function nextScratchDir(fs: Pick<Fs, 'analyzePath'>): string;
+export declare function stageInputFiles(fs: Fs, dir: string, inputs: readonly InputFile[]): void;
+export declare function collectOutputs(fs: Fs, dir: string, names: readonly string[]): {
+    files: Map<string, Uint8Array>;
+    missing: string[];
+    rejected: {
+        name: string;
+        reason: string;
+    }[];
+};
+export declare function removeScratch(fs: Fs, dir: string, previousCwd: string): void;
+export declare function openScratch(fs: Fs & {
+    cwd(): string;
+}, workdir?: string): Scratch;
+export {};

package/dist-lib/lib/tools/exec/adapters/python/memfs.js

@@ -0,0 +1,85 @@
+import { hlog } from "../../../../log.js";
+import { MAX_OUTPUT_FILE_BYTES, MAX_OUTPUT_TOTAL_BYTES } from "./output-policy.js";
+let runCounter = 0;
+function filePath(dir, name) {
+    return `${dir}/${name}`;
+}
+export function nextScratchDir(fs) {
+    let candidate = `/tmp/qvac-exec-${++runCounter}`;
+    while (fs.analyzePath(candidate).exists)
+        candidate = `/tmp/qvac-exec-${++runCounter}`;
+    return candidate;
+}
+export function stageInputFiles(fs, dir, inputs) {
+    fs.mkdirTree(dir);
+    for (const input of inputs)
+        fs.writeFile(filePath(dir, input.path), input.bytes);
+}
+function isRegularFile(fs, path) {
+    const mode = fs.lstat(path).mode;
+    return !fs.isDir(mode) && !fs.isLink(mode);
+}
+export function collectOutputs(fs, dir, names) {
+    const files = new Map();
+    const missing = [];
+    const rejected = [];
+    let total = 0;
+    for (const name of names) {
+        const path = filePath(dir, name);
+        if (fs.analyzePath(path).exists && isRegularFile(fs, path)) {
+            const size = fs.stat(path).size;
+            if (size > MAX_OUTPUT_FILE_BYTES) {
+                rejected.push({ name, reason: 'file exceeds maximum output size' });
+                continue;
+            }
+            if (total + size > MAX_OUTPUT_TOTAL_BYTES) {
+                rejected.push({ name, reason: 'outputs exceed maximum total size' });
+                continue;
+            }
+            files.set(name, new Uint8Array(fs.readFile(path, { encoding: 'binary' })));
+            total += size;
+        }
+        else {
+            missing.push(name);
+        }
+    }
+    return { files, missing, rejected };
+}
+function removeTree(fs, dir) {
+    for (const name of fs.readdir(dir)) {
+        if (name === '.' || name === '..')
+            continue;
+        const path = filePath(dir, name);
+        const mode = fs.lstat(path).mode;
+        if (fs.isDir(mode) && !fs.isLink(mode))
+            removeTree(fs, path);
+        else
+            fs.unlink(path);
+    }
+    fs.rmdir(dir);
+}
+export function removeScratch(fs, dir, previousCwd) {
+    try {
+        fs.chdir(previousCwd);
+        removeTree(fs, dir);
+    }
+    catch (error) {
+        hlog('python: scratch cleanup failed', {
+            dir,
+            err: error instanceof Error ? error.message : String(error)
+        });
+    }
+}
+export function openScratch(fs, workdir) {
+    const dir = nextScratchDir(fs);
+    const cwd = workdir ? `${dir}/${workdir}` : dir;
+    const previousCwd = fs.cwd();
+    fs.mkdirTree(cwd);
+    return {
+        dir,
+        cwd,
+        [Symbol.dispose]() {
+            removeScratch(fs, dir, previousCwd);
+        }
+    };
+}

package/dist-lib/lib/tools/exec/adapters/python/output-policy.d.ts

@@ -0,0 +1,13 @@
+export declare const MAX_OUTPUT_FILE_BYTES: number;
+export declare const MAX_OUTPUT_TOTAL_BYTES: number;
+export declare const RUN_OUTPUT_BUDGET_BYTES: number;
+export declare const MAX_OUTPUTS = 8;
+export declare const MAX_INPUTS = 24;
+export declare const MAX_INPUT_TOTAL_BYTES: number;
+export declare function checkFileName(name: string): string | null;
+export declare function checkOutputName(name: string): string | null;
+export declare function checkOutputBytes(name: string, bytes: Uint8Array, runningTotal: number): {
+    mimeType: string;
+} | {
+    error: string;
+};

package/dist-lib/lib/tools/exec/adapters/python/output-policy.js

@@ -0,0 +1,129 @@
+export const MAX_OUTPUT_FILE_BYTES = 25 * 1024 * 1024;
+export const MAX_OUTPUT_TOTAL_BYTES = 50 * 1024 * 1024;
+export const RUN_OUTPUT_BUDGET_BYTES = 150 * 1024 * 1024;
+export const MAX_OUTPUTS = 8;
+export const MAX_INPUTS = 24;
+export const MAX_INPUT_TOTAL_BYTES = 50 * 1024 * 1024;
+const MAX_FILE_NAME_LENGTH = 255;
+const MIME_TYPES = {
+    pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+    docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    pdf: 'application/pdf',
+    png: 'image/png',
+    jpeg: 'image/jpeg',
+    jpg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    csv: 'text/csv',
+    json: 'application/json',
+    txt: 'text/plain',
+    md: 'text/markdown',
+    zip: 'application/zip'
+};
+const DENIED_EXTENSIONS = new Set([
+    'pptm',
+    'docm',
+    'xlsm',
+    'command',
+    'sh',
+    'py',
+    'app',
+    'dmg',
+    'scpt',
+    'jar'
+]);
+function extensionOf(name) {
+    return name.slice(name.lastIndexOf('.') + 1).toLowerCase();
+}
+function isKnownExtension(extension) {
+    return extension in MIME_TYPES || DENIED_EXTENSIONS.has(extension);
+}
+function matches(bytes, signature) {
+    if (bytes.length < signature.length)
+        return false;
+    return signature.every((byte, index) => bytes[index] === byte);
+}
+function hasExpectedSignature(extension, bytes) {
+    if (extension === 'pptx' || extension === 'docx' || extension === 'xlsx' || extension === 'zip') {
+        return matches(bytes, [0x50, 0x4b, 0x03, 0x04]);
+    }
+    if (extension === 'pdf')
+        return matches(bytes, [0x25, 0x50, 0x44, 0x46, 0x2d]);
+    if (extension === 'png')
+        return matches(bytes, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+    if (extension === 'jpeg' || extension === 'jpg')
+        return matches(bytes, [0xff, 0xd8, 0xff]);
+    if (extension === 'gif') {
+        return (matches(bytes, [0x47, 0x49, 0x46, 0x38, 0x37, 0x61]) ||
+            matches(bytes, [0x47, 0x49, 0x46, 0x38, 0x39, 0x61]));
+    }
+    if (extension === 'webp') {
+        return (matches(bytes, [0x52, 0x49, 0x46, 0x46]) && matches(bytes.slice(8), [0x57, 0x45, 0x42, 0x50]));
+    }
+    return !bytes.includes(0);
+}
+export function checkFileName(name) {
+    if (!name)
+        return 'file name must not be empty';
+    if (/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/.test(name)) {
+        return 'file name must not contain control characters';
+    }
+    if (/[\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/.test(name)) {
+        return 'file name must not contain bidi characters';
+    }
+    if (/[\u200b-\u200d\u2060\ufeff]/.test(name)) {
+        return 'file name must not contain invisible characters';
+    }
+    if (name.includes('/') || name.includes('\\')) {
+        return 'file name must not contain path separators';
+    }
+    if (name.includes('..'))
+        return 'file name must not contain double dots';
+    if (name.startsWith('.'))
+        return 'file name must not start with a dot';
+    if (name.endsWith('.') || name.endsWith(' ')) {
+        return 'file name must not end with a dot or space';
+    }
+    const segments = name.split('.');
+    if (segments.slice(1, -1).some((segment) => isKnownExtension(segment.toLowerCase()))) {
+        return 'file name must have at most one extension';
+    }
+    if (name.length > MAX_FILE_NAME_LENGTH)
+        return 'file name must be 255 characters or fewer';
+    return null;
+}
+const SUPERSEDED = { ppt: 'pptx', doc: 'docx', xls: 'xlsx' };
+export function checkOutputName(name) {
+    const nameError = checkFileName(name);
+    if (nameError)
+        return nameError;
+    const extension = extensionOf(name);
+    const mimeType = MIME_TYPES[extension];
+    if (DENIED_EXTENSIONS.has(extension) || !mimeType) {
+        const saw = extension && extension !== name.toLowerCase()
+            ? `".${extension}" is not an allowed output type`
+            : `"${name}" has no file extension`;
+        const instead = SUPERSEDED[extension];
+        const fix = instead ? ` — this runtime writes the current format, so name it ".${instead}"` : '';
+        return `${saw}${fix}. Allowed: ${Object.keys(MIME_TYPES)
+            .map((e) => `.${e}`)
+            .join(', ')}`;
+    }
+    return null;
+}
+export function checkOutputBytes(name, bytes, runningTotal) {
+    const nameError = checkOutputName(name);
+    if (nameError)
+        return { error: nameError };
+    const extension = extensionOf(name);
+    const mimeType = MIME_TYPES[extension];
+    if (!hasExpectedSignature(extension, bytes))
+        return { error: 'file bytes do not match file type' };
+    if (bytes.length > MAX_OUTPUT_FILE_BYTES)
+        return { error: 'file exceeds maximum output size' };
+    if (runningTotal + bytes.length > MAX_OUTPUT_TOTAL_BYTES) {
+        return { error: 'outputs exceed maximum total size' };
+    }
+    return { mimeType };
+}

package/dist-lib/lib/tools/exec/adapters/python/pyodide.d.ts

@@ -0,0 +1,19 @@
+import type { AbortSignal as BareAbortSignal } from 'bare-abort-controller';
+import { pyodideLoadOptions } from './loader.ts';
+import { type LoadPyodideFn, type PyodideLike, type PythonRunResult } from './run-session.ts';
+export { pyodideLoadOptions };
+export type { LoadPyodideFn, PyodideLike, PythonRunResult };
+export type RunPythonOptions = {
+    readonly timeoutMs?: number;
+    readonly maxOutputChars?: number;
+    readonly signal?: BareAbortSignal;
+    readonly packages?: readonly string[];
+    readonly inputs?: readonly {
+        readonly path: string;
+        readonly bytes: Uint8Array;
+    }[];
+    readonly outputs?: readonly string[];
+    readonly workdir?: string;
+    readonly loadPyodide?: LoadPyodideFn;
+};
+export declare function runPython(code: string, options?: RunPythonOptions): Promise<PythonRunResult>;