@qvac/harness 0.4.0 → 0.5.0

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

@@ -1,5 +1,5 @@
-export type InterruptTimer = {
+export interface InterruptTimer {
     readonly interrupt: Uint8Array;
     disarm(): boolean;
-};
+}
 export declare function startInterruptTimer(ms: number): InterruptTimer;

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

@@ -15,12 +15,15 @@ class B4aTextDecoder {
     encoding;
     constructor(label = 'utf-8') {
         const normalized = String(label).toLowerCase();
-        if (normalized.includes('16'))
+        if (normalized.includes('16')) {
             this.encoding = 'utf16le';
-        else if (/latin1|iso-8859|ascii/.test(normalized))
+        }
+        else if (/latin1|iso-8859|ascii/.test(normalized)) {
             this.encoding = 'latin1';
-        else
+        }
+        else {
             this.encoding = 'utf8';
+        }
     }
     decode(input) {
         if (input === undefined)
@@ -39,13 +42,15 @@ class B4aTextEncoder {
 export function nodeShapedProcess(base) {
     return new Proxy(base, {
         get(target, prop) {
-            if (prop === 'versions')
+            if (prop === 'versions') {
                 return { ...target.versions, node: '22.0.0' };
+            }
             if (prop === 'binding') {
                 return (name) => (name === 'constants' ? { fs: fsConstants } : {});
             }
-            if (prop === 'getuid')
+            if (prop === 'getuid') {
                 return () => 0;
+            }
             return Reflect.get(target, prop);
         }
     });
@@ -64,12 +69,15 @@ async function shapeBareGlobals() {
         g.AbortController = AbortController;
         g.AbortSignal = AbortSignal;
     }
-    if (!g.TextDecoder)
+    if (!g.TextDecoder) {
         g.TextDecoder = B4aTextDecoder;
-    if (!g.TextEncoder)
+    }
+    if (!g.TextEncoder) {
         g.TextEncoder = B4aTextEncoder;
-    if (!g.process)
+    }
+    if (!g.process) {
         g.process = nodeShapedProcess(process);
+    }
     if (!g.performance) {
         const origin = Date.now();
         g.performance = { now: () => Date.now() - origin, timeOrigin: origin };
@@ -82,17 +90,20 @@ const silentStdio = {
 };
 export function pyodideLoadOptions() {
     const cacheDir = process.env.QVAC_PYODIDE_CACHE_DIR;
-    if (!cacheDir)
+    if (!cacheDir) {
         return { ...silentStdio };
+    }
     return { ...silentStdio, packageCacheDir: cacheDir };
 }
 export const defaultLoad = async () => {
-    if (typeof globalThis.Bare !== 'undefined')
+    if (typeof globalThis.Bare !== 'undefined') {
         await shapeBareGlobals();
+    }
     const moduleName = 'pyodide';
-    const { loadPyodide } = (await import(__rewriteRelativeImportExtension(moduleName)));
+    const { loadPyodide } = await import(__rewriteRelativeImportExtension(moduleName));
     const options = pyodideLoadOptions();
-    if (options.packageCacheDir)
+    if (options.packageCacheDir) {
         seedPackageCache(options.packageCacheDir);
+    }
     return (await loadPyodide(options));
 };

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

@@ -1,4 +1,4 @@
-type Fs = {
+interface Fs {
     mkdirTree(path: string): void;
     chdir(path: string): void;
     writeFile(path: string, data: Uint8Array): void;
@@ -20,28 +20,30 @@ type Fs = {
     isLink(mode: number): boolean;
     unlink(path: string): void;
     rmdir(path: string): void;
-};
-export type Scratch = {
+}
+interface CwdFs extends Fs {
+    cwd(): string;
+}
+export interface Scratch {
     readonly dir: string;
     readonly cwd: string;
     [Symbol.dispose](): void;
-};
-type InputFile = {
+}
+interface 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[]): {
+export interface CollectedOutputs {
     files: Map<string, Uint8Array>;
     missing: string[];
     rejected: {
         name: string;
         reason: string;
     }[];
-};
+}
+export declare function collectOutputs(fs: Fs, dir: string, names: readonly string[]): CollectedOutputs;
 export declare function removeScratch(fs: Fs, dir: string, previousCwd: string): void;
-export declare function openScratch(fs: Fs & {
-    cwd(): string;
-}, workdir?: string): Scratch;
+export declare function openScratch(fs: CwdFs, workdir?: string): Scratch;
 export {};

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

@@ -1,3 +1,4 @@
+import { errorMessage } from '../../../../guards.js';
 import { hlog } from '../../../../log.js';
 import { MAX_OUTPUT_FILE_BYTES, MAX_OUTPUT_TOTAL_BYTES } from './output-policy.js';
 let runCounter = 0;
@@ -6,14 +7,16 @@ function filePath(dir, name) {
 }
 export function nextScratchDir(fs) {
     let candidate = `/tmp/qvac-exec-${++runCounter}`;
-    while (fs.analyzePath(candidate).exists)
+    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)
+    for (const input of inputs) {
         fs.writeFile(filePath(dir, input.path), input.bytes);
+    }
 }
 function isRegularFile(fs, path) {
     const mode = fs.lstat(path).mode;
@@ -51,10 +54,12 @@ function removeTree(fs, dir) {
             continue;
         const path = filePath(dir, name);
         const mode = fs.lstat(path).mode;
-        if (fs.isDir(mode) && !fs.isLink(mode))
+        if (fs.isDir(mode) && !fs.isLink(mode)) {
             removeTree(fs, path);
-        else
+        }
+        else {
             fs.unlink(path);
+        }
     }
     fs.rmdir(dir);
 }
@@ -66,7 +71,7 @@ export function removeScratch(fs, dir, previousCwd) {
     catch (error) {
         hlog('python: scratch cleanup failed', {
             dir,
-            err: error instanceof Error ? error.message : String(error)
+            err: errorMessage(error)
         });
     }
 }

package/dist-lib/lib/tools/exec/adapters/python/net-shim.js

@@ -1,6 +1,8 @@
 export function pythonReachesNetwork() {
+    const wasm = WebAssembly;
     return (typeof globalThis.Bare !== 'undefined' &&
-        typeof WebAssembly.Suspending === 'function');
+        'Suspending' in wasm &&
+        typeof wasm.Suspending === 'function');
 }
 export const NET_SHIM = `
 def _qvac_install_net():

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

@@ -6,8 +6,10 @@ 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;
-} | {
+export interface ExecError {
     error: string;
-};
+}
+export interface AcceptedOutput {
+    mimeType: string;
+}
+export declare function checkOutputBytes(name: string, bytes: Uint8Array, runningTotal: number): AcceptedOutput | ExecError;

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

@@ -55,17 +55,21 @@ function hasExpectedSignature(extension, bytes) {
     if (extension === 'mp4' || extension === 'm4a') {
         return matches(bytes.slice(4), [0x66, 0x74, 0x79, 0x70]);
     }
-    if (extension === 'webm')
+    if (extension === 'webm') {
         return matches(bytes, [0x1a, 0x45, 0xdf, 0xa3]);
+    }
     if (extension === 'mp3') {
         return (matches(bytes, [0x49, 0x44, 0x33]) || (bytes[0] === 0xff && ((bytes[1] ?? 0) & 0xe0) === 0xe0));
     }
-    if (extension === 'pdf')
+    if (extension === 'pdf') {
         return matches(bytes, [0x25, 0x50, 0x44, 0x46, 0x2d]);
-    if (extension === 'png')
+    }
+    if (extension === 'png') {
         return matches(bytes, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
-    if (extension === 'jpeg' || extension === 'jpg')
+    }
+    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]));
@@ -92,8 +96,9 @@ export function checkFileName(name) {
     }
     if (name.includes('..'))
         return 'file name must not contain double dots';
-    if (name.startsWith('.'))
+    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';
     }
@@ -101,15 +106,17 @@ export function checkFileName(name) {
     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)
+    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)
+    if (nameError) {
         return nameError;
+    }
     const extension = extensionOf(name);
     const mimeType = MIME_TYPES[extension];
     if (DENIED_EXTENSIONS.has(extension) || !mimeType) {
@@ -126,14 +133,17 @@ export function checkOutputName(name) {
 }
 export function checkOutputBytes(name, bytes, runningTotal) {
     const nameError = checkOutputName(name);
-    if (nameError)
+    if (nameError) {
         return { error: nameError };
+    }
     const extension = extensionOf(name);
     const mimeType = MIME_TYPES[extension];
-    if (!hasExpectedSignature(extension, bytes))
+    if (!hasExpectedSignature(extension, bytes)) {
         return { error: 'file bytes do not match file type' };
-    if (bytes.length > MAX_OUTPUT_FILE_BYTES)
+    }
+    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' };
     }

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

@@ -3,7 +3,7 @@ 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 = {
+export interface RunPythonOptions {
     readonly timeoutMs?: number;
     readonly maxOutputChars?: number;
     readonly signal?: BareAbortSignal;
@@ -18,5 +18,5 @@ export type RunPythonOptions = {
     readonly network?: boolean;
     readonly hosts?: readonly string[];
     readonly askConnect?: (host: string) => Promise<boolean>;
-};
+}
 export declare function runPython(code: string, options?: RunPythonOptions): Promise<PythonRunResult>;

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

@@ -1,6 +1,7 @@
 import { AbortController } from 'bare-abort-controller';
 import process from 'process';
 import ScopeLock from 'scope-lock';
+import { errorMessage } from '../../../../guards.js';
 import { AbortedError, raceAbort } from '../../../../helpers/race-abort.js';
 import { hlog } from '../../../../log.js';
 import { MAX_OUTPUT_CHARS } from '../../runner.js';
@@ -24,7 +25,7 @@ function getPyodide(load) {
             .catch((error) => {
             cache.delete(load);
             hlog('python: interpreter boot failed', {
-                err: error instanceof Error ? error.message : String(error)
+                err: errorMessage(error)
             });
             throw error;
         });
@@ -43,8 +44,9 @@ async function runInProcess(load, spec, options) {
         await runLock.lock();
         try {
             const isCancelled = () => timedOut || options.signal?.aborted === true;
-            if (isCancelled())
+            if (isCancelled()) {
                 throw new AbortedError();
+            }
             const py = await getPyodide(load);
             const timer = startInterruptTimer(Math.max(0, deadline - Date.now()));
             py.setInterruptBuffer(timer.interrupt);
@@ -56,20 +58,23 @@ async function runInProcess(load, spec, options) {
                 });
             }
             finally {
-                if (timer.disarm())
+                if (timer.disarm()) {
                     timedOut = true;
+                }
             }
             if (outcome.evict) {
                 cache.delete(load);
                 hlog('python: interpreter evicted; next run boots fresh');
             }
-            if (timedOut)
+            if (timedOut) {
                 throw new Error(timeoutMessage);
+            }
             return outcome.result;
         }
         catch (error) {
-            if (isPyodideFatal(error))
+            if (isPyodideFatal(error)) {
                 cache.delete(load);
+            }
             throw error;
         }
         finally {
@@ -87,8 +92,9 @@ async function runInProcess(load, spec, options) {
         return await raceAbort(Promise.race([run, timeout]), options.signal);
     }
     finally {
-        if (timer)
+        if (timer) {
             clearTimeout(timer);
+        }
         stop.abort(undefined);
     }
 }
@@ -130,8 +136,9 @@ export async function runPython(code, options = {}) {
     }
     await runLock.lock();
     try {
-        if (options.signal?.aborted)
+        if (options.signal?.aborted) {
             throw new AbortedError();
+        }
         return await runPythonInWorker(spec, {
             timeoutMs,
             signal: options.signal,

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

@@ -1,14 +1,22 @@
+import type { ExecAttachment } from '../../runner.ts';
 import type { ExecutionAdapter } from '../adapter.ts';
 import { type ExecInput } from './attachments.ts';
-import { type LoadPyodideFn } from './pyodide.ts';
+import { type ExecError } from './output-policy.ts';
+import { type LoadPyodideFn, type PythonRunResult } from './pyodide.ts';
 export declare function isPythonLanguage(language: unknown): boolean;
 export declare function runsThroughPyodide(language: unknown, disablePyodide: boolean): boolean;
 export declare function unwrapPythonSource(command: string): string | null;
 export declare function withoutProgramDir(command: string): string;
 export declare function pipInstallTargets(command: string): string[] | null;
 export declare function pinned(spec: string): string;
-export declare function pipMessage(targets: readonly string[] | null, sandbox?: boolean): string;
-export declare function pipFromSourceHint(stderr: string, source: string, packages: readonly string[] | undefined, sandbox?: boolean): string | null;
+export declare function pipMessage(targets: readonly string[] | null, { sandbox }?: {
+    sandbox?: boolean | undefined;
+}): string;
+export interface PipFromSourceHintOptions {
+    readonly packages?: readonly string[] | undefined;
+    readonly sandbox?: boolean;
+}
+export declare function pipFromSourceHint(stderr: string, source: string, { packages, sandbox }?: PipFromSourceHintOptions): string | null;
 export declare function stringLiteralProgramHint(source: string): string | null;
 export declare function checkCollapsedCompound(source: string): string | null;
 export declare function mangledPptxApiHint(source: string): string | null;
@@ -25,29 +33,25 @@ export declare function rgbColorImportHint(stderr: string): string | null;
 export declare function checkPythonSource(command: string): string | null;
 export declare function syntaxErrorHint(stderr: string, source: string): string | null;
 export declare function checkPptxBuildSource(source: string, outputs: readonly string[] | undefined, packages?: readonly string[] | undefined): string | null;
+export declare function tripleQuoteAt(source: string, index: number): string | null;
 export declare function isEscaped(source: string, index: number): boolean;
 export declare function checkBareLengthArgs(source: string, packages?: readonly string[] | undefined): string | null;
 export declare function checkPdfBuildSource(source: string, outputs: readonly string[] | undefined, packages?: readonly string[] | undefined): string | null;
 export declare function stripCommentsAndDocstrings(source: string): string;
 export declare const PDF_READ: RegExp;
 export declare const OFFICE_READ: RegExp;
-export declare function checkUnstagedRead(source: string, inputs: readonly {
-    path: string;
-}[] | undefined): string | null;
+export declare function checkUnstagedRead(source: string, inputs: readonly Pick<ExecInput, 'path'>[] | undefined): string | null;
 export declare function missingFileHint(stderr: string): string | null;
-export declare function parsePackages(value: unknown): string[] | {
-    error: string;
-} | undefined;
-export declare function parseInputs(value: unknown): ExecInput[] | {
-    error: string;
-} | undefined;
-export declare function parseOutputs(value: unknown): string[] | {
-    error: string;
-} | undefined;
-export declare function parseWorkdir(value: unknown): string | {
-    error: string;
-} | undefined;
-export declare function missingModuleHint(stderr: string, packages: readonly string[] | undefined, sandbox?: boolean, network?: boolean): string | null;
+export declare function parsePackages(value: unknown): string[] | ExecError | undefined;
+export declare function parseInputs(value: unknown): ExecInput[] | ExecError | undefined;
+export declare function parseOutputs(value: unknown): string[] | ExecError | undefined;
+export declare function parseWorkdir(value: unknown): string | ExecError | undefined;
+export interface MissingModuleHintOptions {
+    readonly packages?: readonly string[] | undefined;
+    readonly sandbox?: boolean;
+    readonly network?: boolean;
+}
+export declare function missingModuleHint(stderr: string, { packages, sandbox, network }?: MissingModuleHintOptions): string | null;
 export declare function nonePlaceholderHint(stderr: string): string | null;
 export declare function slideShapesHint(stderr: string): string | null;
 export declare function shapeFontHint(stderr: string): string | null;
@@ -63,19 +67,22 @@ export declare function packageFetchFailedHint(stderr: string): string | null;
 export declare const IMAGE_INPUT: RegExp;
 export declare function pptxHasEmbeddedMedia(bytes: Uint8Array): boolean;
 export declare function softFailedDeckHint(stdout: string, exitCode: number, source: string): string | null;
-export declare function stagedImagesMissingFromDeck(result: {
-    exitCode: number;
-    files?: ReadonlyMap<string, Uint8Array>;
-}, inputs: readonly {
-    path: string;
-}[] | undefined, outputs: readonly string[] | undefined, source: string): string | null;
-export declare function checkStagedImagesUsed(source: string, inputs: readonly {
-    path: string;
-}[] | undefined, outputs: readonly string[] | undefined): string | null;
-export declare function checkTurnImagesStaged(source: string, inputs: readonly ExecInput[] | undefined, outputs: readonly string[] | undefined, turnImages: readonly {
-    path: string;
-}[] | undefined): string | null;
-export declare function deckDeliveredStop(attachments: readonly {
-    readonly fileName: string;
-}[] | undefined, exitCode: number, source?: string): string | null;
+export interface DeckImagesOptions {
+    readonly inputs: readonly {
+        path: string;
+    }[] | undefined;
+    readonly outputs: readonly string[] | undefined;
+    readonly source: string;
+}
+export declare function stagedImagesMissingFromDeck(result: Pick<PythonRunResult, 'exitCode' | 'files'>, { inputs, outputs, source }: DeckImagesOptions): string | null;
+export declare function checkStagedImagesUsed(source: string, inputs: readonly Pick<ExecInput, 'path'>[] | undefined, outputs: readonly string[] | undefined): string | null;
+export interface TurnImagesStagedOptions {
+    readonly inputs: readonly ExecInput[] | undefined;
+    readonly outputs: readonly string[] | undefined;
+    readonly turnImages: readonly {
+        path: string;
+    }[] | undefined;
+}
+export declare function checkTurnImagesStaged(source: string, { inputs, outputs, turnImages }: TurnImagesStagedOptions): string | null;
+export declare function deckDeliveredStop(attachments: readonly Pick<ExecAttachment, 'fileName'>[] | undefined, exitCode: number, source?: string): string | null;
 export declare function createPythonAdapter(disabled: boolean, loadPyodide?: LoadPyodideFn, network?: boolean): ExecutionAdapter;