@qvac/harness 0.4.0 → 0.6.0

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

@@ -1,5 +1,5 @@
 import type { ExecResult } from '../../runner.ts';
-export type PyodideLike = {
+export interface PyodideLike {
     runPython(code: string, options?: {
         filename?: string;
     }): unknown;
@@ -42,7 +42,7 @@ export type PyodideLike = {
         unlink(path: string): void;
         rmdir(path: string): void;
     };
-};
+}
 export type LoadPyodideFn = () => Promise<PyodideLike>;
 export type PythonRunResult = ExecResult & {
     files?: ReadonlyMap<string, Uint8Array>;
@@ -53,7 +53,7 @@ export type PythonRunResult = ExecResult & {
     }[];
     undeclared?: readonly string[];
 };
-export type RunSpec = {
+export interface RunSpec {
     readonly code: string;
     readonly packages?: readonly string[] | undefined;
     readonly inputs?: readonly {
@@ -66,15 +66,16 @@ export type RunSpec = {
     readonly installTimeoutMs: number;
     readonly network?: boolean | undefined;
     readonly hosts?: readonly string[] | undefined;
-};
-export type RunOutcome = {
+}
+export interface RunOutcome {
     readonly result: PythonRunResult;
     readonly evict: boolean;
-};
+}
 export declare function cap(text: string, limit: number): string;
 export declare function isPyodideFatal(error: unknown): boolean;
 export declare function repairDoubleEscapedSource(code: string, message: string): string | null;
-export declare function performRun(py: PyodideLike, spec: RunSpec, opts?: {
+export interface PerformRunOptions {
     readonly isCancelled?: () => boolean;
     readonly askConnect?: ((host: string) => Promise<boolean>) | undefined;
-}): Promise<RunOutcome>;
+}
+export declare function performRun(py: PyodideLike, spec: RunSpec, opts?: PerformRunOptions): Promise<RunOutcome>;

package/dist-lib/lib/tools/exec/adapters/python/run-session.js

@@ -1,3 +1,4 @@
+import { errorMessage } from '../../../../guards.js';
 import { AbortedError } from '../../../../helpers/race-abort.js';
 import { hlog } from '../../../../log.js';
 import { TRUNCATED_OUTPUT_SUFFIX } from '../../runner.js';
@@ -13,8 +14,9 @@ export function cap(text, limit) {
 export function isPyodideFatal(error) {
     if (typeof error !== 'object' || error === null)
         return false;
-    if ('pyodide_fatal_error' in error && error.pyodide_fatal_error === true)
+    if ('pyodide_fatal_error' in error && error.pyodide_fatal_error === true) {
         return true;
+    }
     return error instanceof Error && error.message.includes('and can no longer be used');
 }
 const DOUBLE_ESCAPED = /\\[nt"']/;
@@ -24,8 +26,9 @@ function unescapeSource(code) {
             return '\n';
         if (char === 't')
             return '\t';
-        if (char === 'r')
+        if (char === 'r') {
             return '\r';
+        }
         return char;
     });
 }
@@ -34,8 +37,9 @@ export function repairDoubleEscapedSource(code, message) {
         return null;
     if (code.includes('\n'))
         return null;
-    if (!DOUBLE_ESCAPED.test(code))
+    if (!DOUBLE_ESCAPED.test(code)) {
         return null;
+    }
     const repaired = unescapeSource(code);
     return repaired === code ? null : repaired;
 }
@@ -60,7 +64,7 @@ async function enter(py, code, access) {
         setConnectPolicy(null);
     }
 }
-async function attempt(py, code, output, maxOutputChars, access) {
+async function attempt(py, code, { output, maxOutputChars, access }) {
     try {
         await enter(py, code, access);
         return {
@@ -74,7 +78,7 @@ async function attempt(py, code, output, maxOutputChars, access) {
         };
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
+        const message = errorMessage(error);
         return {
             result: {
                 stdout: cap(output.stdout, maxOutputChars),
@@ -86,16 +90,19 @@ async function attempt(py, code, output, maxOutputChars, access) {
         };
     }
 }
-async function runOnce(py, code, output, maxOutputChars, access) {
-    const first = await attempt(py, code, output, maxOutputChars, access);
-    if (first.error === null)
+async function runOnce(py, code, opts) {
+    const first = await attempt(py, code, opts);
+    if (first.error === null) {
         return first;
+    }
     const repaired = repairDoubleEscapedSource(code, first.error);
-    if (repaired === null)
+    if (repaired === null) {
         return first;
-    const retry = await attempt(py, repaired, output, maxOutputChars, access);
-    if (retry.error !== null && retry.error.includes('SyntaxError'))
+    }
+    const retry = await attempt(py, repaired, opts);
+    if (retry.error !== null && retry.error.includes('SyntaxError')) {
         return first;
+    }
     return retry;
 }
 const FIT_DECKS = `
@@ -168,16 +175,18 @@ class InstallTimeoutError extends Error {
 }
 function installSource(py, packages) {
     const plan = planVendoredInstall(packages);
-    if (!plan)
+    if (!plan) {
         return `import micropip\nawait micropip.install(${JSON.stringify(packages)})`;
+    }
     const specs = [...stageVendoredWheels(py.FS, plan), ...plan.packages];
     hlog('python: installing from vendored wheels', { specs });
     return `import micropip\nawait micropip.install(${JSON.stringify(specs)}, deps=False)`;
 }
-async function installPackages(py, packages, timeoutMs, isCancelled) {
+async function installPackages(py, packages, { timeoutMs, isCancelled }) {
     await py.loadPackage('micropip');
-    if (isCancelled())
+    if (isCancelled()) {
         throw new AbortedError();
+    }
     const install = py.runPythonAsync(installSource(py, packages));
     let timer;
     const bound = new Promise((_, reject) => {
@@ -187,8 +196,9 @@ async function installPackages(py, packages, timeoutMs, isCancelled) {
         await Promise.race([install, bound]);
     }
     finally {
-        if (timer)
+        if (timer) {
             clearTimeout(timer);
+        }
     }
 }
 const DELIVERABLE = /\.(pptx|docx|xlsx|pdf|png|jpe?g|gif|webp|csv|json|txt|md|zip|mp4|webm|m4a|mp3)$/i;
@@ -204,15 +214,16 @@ function newDeliverables(before, after) {
     return [...after].filter((name) => !before.has(name) && DELIVERABLE.test(name));
 }
 function fitDecks(py, outputs) {
-    if (!outputs.some((name) => name.toLowerCase().endsWith('.pptx')))
+    if (!outputs.some((name) => name.toLowerCase().endsWith('.pptx'))) {
         return false;
+    }
     try {
         py.runPython(`${FIT_DECKS}\n_qvac_fit_decks(${JSON.stringify(outputs)})`);
         return false;
     }
     catch (error) {
         hlog('python: deck fit skipped', {
-            err: error instanceof Error ? error.message : String(error)
+            err: errorMessage(error)
         });
         return isPyodideFatal(error);
     }
@@ -225,20 +236,25 @@ export async function performRun(py, spec, opts = {}) {
     py.setStdout({ batched: (chunk) => (output.stdout += chunk + '\n') });
     py.setStderr({ batched: (chunk) => (output.stderr += chunk + '\n') });
     if (spec.packages?.length) {
-        if (isCancelled())
+        if (isCancelled()) {
             throw new AbortedError();
+        }
         hlog('python: installing packages', {
             packages: [...spec.packages],
             timeoutMs: spec.installTimeoutMs
         });
         try {
-            await installPackages(py, spec.packages, spec.installTimeoutMs, isCancelled);
+            await installPackages(py, spec.packages, {
+                timeoutMs: spec.installTimeoutMs,
+                isCancelled
+            });
             hlog('python: packages ready', { packages: [...spec.packages] });
         }
         catch (error) {
-            if (error instanceof AbortedError)
+            if (error instanceof AbortedError) {
                 throw error;
-            const message = error instanceof Error ? error.message : String(error);
+            }
+            const message = errorMessage(error);
             const timedOut = error instanceof InstallTimeoutError;
             const evict = timedOut || isPyodideFatal(error);
             hlog(timedOut ? 'python: package install timed out' : 'python: package install failed', {
@@ -254,14 +270,20 @@ export async function performRun(py, spec, opts = {}) {
         output.stdout = '';
         output.stderr = '';
     }
-    if (isCancelled())
+    if (isCancelled()) {
         throw new AbortedError();
+    }
     if (!spec.inputs?.length && !spec.outputs?.length && !spec.workdir) {
         const cwd = py.FS.cwd();
         const before = listFiles(py, cwd);
-        const { result, fatal } = await runOnce(py, spec.code, output, spec.maxOutputChars, access);
-        if (result.exitCode !== 0)
+        const { result, fatal } = await runOnce(py, spec.code, {
+            output,
+            maxOutputChars: spec.maxOutputChars,
+            access
+        });
+        if (result.exitCode !== 0) {
             return { result, evict: fatal };
+        }
         const undeclared = newDeliverables(before, listFiles(py, cwd));
         return { result: undeclared.length > 0 ? { ...result, undeclared } : result, evict: false };
     }
@@ -270,12 +292,18 @@ export async function performRun(py, spec, opts = {}) {
         py.FS.chdir(scratch.cwd);
         stageInputFiles(py.FS, scratch.cwd, spec.inputs ?? []);
         const before = listFiles(py, scratch.cwd);
-        const { result, fatal } = await runOnce(py, spec.code, output, spec.maxOutputChars, access);
+        const { result, fatal } = await runOnce(py, spec.code, {
+            output,
+            maxOutputChars: spec.maxOutputChars,
+            access
+        });
         let evict = fatal;
-        if (result.exitCode === 0)
+        if (result.exitCode === 0) {
             evict = fitDecks(py, spec.outputs ?? []);
-        if (evict)
+        }
+        if (evict) {
             return { result: { ...result, missing: spec.outputs ?? [] }, evict };
+        }
         const outputs = collectOutputs(py.FS, scratch.cwd, spec.outputs ?? []);
         const declared = new Set(spec.outputs ?? []);
         const undeclared = result.exitCode === 0
@@ -287,7 +315,7 @@ export async function performRun(py, spec, opts = {}) {
                 files: outputs.files,
                 missing: outputs.missing,
                 rejected: outputs.rejected,
-                ...(undeclared.length > 0 && { undeclared })
+                undeclared: undeclared.length > 0 ? undeclared : undefined
             },
             evict: false
         };

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

@@ -17,28 +17,26 @@ declare const ManifestSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type WheelManifest = z.infer<typeof ManifestSchema>;
-export type VendoredInstall = {
+export interface VendoredInstall {
     readonly wheels: readonly string[];
     readonly packages: readonly string[];
-};
-type WheelFs = {
+}
+interface WheelFs {
     mkdirTree(path: string): void;
     writeFile(path: string, data: Uint8Array): void;
     analyzePath(path: string): {
         exists: boolean;
     };
-};
+}
 export declare function wheelsDir(): string | undefined;
 export declare function vendoredManifest(dir?: string | undefined): WheelManifest | null;
 export declare function normalizeDistribution(name: string): string;
-export declare function vendoredSpec(distribution: string, opts?: {
+export interface VendoredOptions {
     readonly dir?: string | undefined;
     readonly manifest?: WheelManifest | null;
-}): string | null;
-export declare function planVendoredInstall(specs: readonly string[], opts?: {
-    readonly dir?: string | undefined;
-    readonly manifest?: WheelManifest | null;
-}): VendoredInstall | null;
+}
+export declare function vendoredSpec(distribution: string, opts?: VendoredOptions): string | null;
+export declare function planVendoredInstall(specs: readonly string[], opts?: VendoredOptions): VendoredInstall | null;
 export declare function stageVendoredWheels(target: WheelFs, install: VendoredInstall): string[];
 export declare function seedPackageCache(cacheDir: string, dir?: string | undefined): void;
 export {};

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

@@ -2,6 +2,7 @@ import fs from 'fs';
 import process from 'process';
 import { fileURLToPath } from 'url';
 import { z } from 'zod';
+import { errorMessage } from '../../../../guards.js';
 import { hlog } from '../../../../log.js';
 const ManifestSchema = z.object({
     pyodide: z.string(),
@@ -16,12 +17,14 @@ const ManifestSchema = z.object({
 const STAGE_DIR = '/qvac-wheels';
 export function wheelsDir() {
     const fromHost = process.env.QVAC_PYTHON_WHEELS_DIR;
-    if (fromHost)
+    if (fromHost) {
         return fromHost;
+    }
     const root = new URL('../../../../../', import.meta.url);
     const source = new URL(root.pathname.endsWith('/dist-lib/') ? '../wheels' : 'wheels', root);
-    if (source.href.includes('.bundle/'))
+    if (source.href.includes('.bundle/')) {
         return undefined;
+    }
     return fileURLToPath(source.href);
 }
 export function vendoredManifest(dir = wheelsDir()) {
@@ -38,7 +41,7 @@ export function vendoredManifest(dir = wheelsDir()) {
     catch (error) {
         hlog('python: vendored wheel manifest unusable', {
             file,
-            err: error instanceof Error ? error.message : String(error)
+            err: errorMessage(error)
         });
         return null;
     }
@@ -58,23 +61,26 @@ export function vendoredSpec(distribution, opts = {}) {
     const dir = opts.dir ?? wheelsDir();
     const manifest = opts.manifest === undefined ? vendoredManifest(dir) : opts.manifest;
     const entry = manifest?.packages[name];
-    if (!entry)
+    if (!entry) {
         return null;
+    }
     const spec = entry.version ? `${name}==${entry.version}` : name;
     return planVendoredInstall([spec], { dir, manifest }) ? spec : null;
 }
 export function planVendoredInstall(specs, opts = {}) {
     const dir = opts.dir ?? wheelsDir();
     const manifest = opts.manifest === undefined ? vendoredManifest(dir) : opts.manifest;
-    if (!manifest || !dir || specs.length === 0)
+    if (!manifest || !dir || specs.length === 0) {
         return null;
+    }
     const wheels = new Set();
     const packages = new Set();
     for (const spec of specs) {
         const { name, version } = parseSpec(spec);
         const entry = manifest.packages[name];
-        if (!entry || entry.version !== version)
+        if (!entry || entry.version !== version) {
             return null;
+        }
         for (const wheel of entry.pypi) {
             if (!fs.existsSync(`${dir}/${wheel}`)) {
                 hlog('python: vendored wheel missing, installing from PyPI instead', { wheel });
@@ -82,14 +88,16 @@ export function planVendoredInstall(specs, opts = {}) {
             }
             wheels.add(`${dir}/${wheel}`);
         }
-        for (const dependency of entry.pyodide)
+        for (const dependency of entry.pyodide) {
             packages.add(dependency);
+        }
     }
     return { wheels: [...wheels], packages: [...packages] };
 }
 export function stageVendoredWheels(target, install) {
-    if (install.wheels.length > 0)
+    if (install.wheels.length > 0) {
         target.mkdirTree(STAGE_DIR);
+    }
     return install.wheels.map((wheel) => {
         const staged = `${STAGE_DIR}/${wheel.slice(wheel.lastIndexOf('/') + 1)}`;
         if (!target.analyzePath(staged).exists) {
@@ -100,18 +108,21 @@ export function stageVendoredWheels(target, install) {
 }
 export function seedPackageCache(cacheDir, dir = wheelsDir()) {
     const manifest = vendoredManifest(dir);
-    if (!manifest || !dir)
+    if (!manifest || !dir) {
         return;
+    }
     fs.mkdirSync(cacheDir, { recursive: true });
     let seeded = 0;
     for (const [file, entry] of Object.entries(manifest.files)) {
-        if (entry.channel !== 'pyodide' || fs.existsSync(`${cacheDir}/${file}`))
+        if (entry.channel !== 'pyodide' || fs.existsSync(`${cacheDir}/${file}`)) {
             continue;
+        }
         if (!fs.existsSync(`${dir}/${file}`))
             continue;
         fs.copyFileSync(`${dir}/${file}`, `${cacheDir}/${file}`);
         seeded++;
     }
-    if (seeded > 0)
+    if (seeded > 0) {
         hlog('python: seeded package cache', { cacheDir, wheels: seeded });
+    }
 }

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

@@ -1,8 +1,9 @@
 import { type AbortSignal as BareAbortSignal } from 'bare-abort-controller';
 import type { PythonRunResult, RunSpec } from '../run-session.ts';
-export declare function runPythonInWorker(spec: RunSpec, opts: {
+export interface RunSpecOptions {
     readonly timeoutMs: number;
     readonly signal?: BareAbortSignal | undefined;
     readonly askConnect?: ((host: string) => Promise<boolean>) | undefined;
-}): Promise<PythonRunResult>;
+}
+export declare function runPythonInWorker(spec: RunSpec, opts: RunSpecOptions): Promise<PythonRunResult>;
 export declare function closePythonWorker(): Promise<void>;

package/dist-lib/lib/tools/exec/adapters/python/worker/client.js

@@ -20,17 +20,20 @@ function workerEntry() {
 async function readMessage(link) {
     for (;;) {
         const message = asWorkerMessage(await link.read());
-        if (message?.type !== 'log')
+        if (message?.type !== 'log') {
             return message;
+        }
         hlog(`python worker: ${message.message}`);
     }
 }
 async function awaitReady(link) {
     const message = await readMessage(link);
-    if (message?.type === 'ready')
+    if (message?.type === 'ready') {
         return;
-    if (message?.type === 'boot-error')
+    }
+    if (message?.type === 'boot-error') {
         throw new Error(`python worker: ${message.message}`);
+    }
     throw new Error('python worker sent an unexpected first message');
 }
 function boot() {
@@ -44,28 +47,33 @@ function boot() {
         nextId: 1
     };
     worker.ready.catch(() => {
-        if (active === worker)
+        if (active === worker) {
             active = null;
+        }
         link.kill();
     });
     return worker;
 }
 function destroy(worker) {
-    if (active === worker)
+    if (active === worker) {
         active = null;
+    }
     worker.link.kill();
 }
 async function drainAndReap(worker) {
-    if (active === worker)
+    if (active === worker) {
         active = null;
+    }
     const closed = readMessage(worker.link).then(() => 'message', () => 'closed');
     const timer = grace(SHUTDOWN_GRACE_MS);
     try {
         const settled = await Promise.race([closed, timer.expired]);
-        if (settled === 'closed')
+        if (settled === 'closed') {
             worker.link.reap();
-        else
+        }
+        else {
             worker.link.kill();
+        }
     }
     finally {
         timer.clear();
@@ -79,12 +87,14 @@ async function resultFor(worker, id, askConnect) {
         message = await readMessage(worker.link);
     }
     if (message?.type === 'result') {
-        if (message.id !== id)
+        if (message.id !== id) {
             throw new Error('python worker answered a different run');
+        }
         return { result: fromWireResult(message.result), evict: message.evict };
     }
-    if (message?.type === 'boot-error')
+    if (message?.type === 'boot-error') {
         throw new Error(`python worker: ${message.message}`);
+    }
     throw new Error('python worker sent an unexpected message');
 }
 function grace(ms) {
@@ -129,8 +139,9 @@ export async function runPythonInWorker(spec, opts) {
         const ask = opts.askConnect;
         const outcome = (async () => {
             await worker.ready;
-            if (cancelled)
+            if (cancelled) {
                 throw new AbortedError();
+            }
             sent = true;
             await worker.link.write({ type: 'run', id, spec });
             return resultFor(worker, id, ask && ((host) => raceAbort(ask(host), stop.signal)));
@@ -139,38 +150,40 @@ export async function runPythonInWorker(spec, opts) {
         const timeout = new Promise((resolve) => {
             timer = setTimeout(() => resolve('timeout'), opts.timeoutMs);
         });
+        const cancel = async () => {
+            cancelled = true;
+            stop.abort(undefined);
+            if (sent) {
+                await interrupt(worker, outcome);
+            }
+            else {
+                outcome.catch(noop);
+            }
+        };
         let first;
         try {
             first = await raceAbort(Promise.race([outcome, timeout]), opts.signal);
         }
         catch (error) {
             if (error instanceof AbortedError) {
-                cancelled = true;
-                stop.abort(undefined);
-                if (sent)
-                    await interrupt(worker, outcome);
-                else
-                    outcome.catch(() => { });
+                await cancel();
                 throw error;
             }
             destroy(worker);
             throw error;
         }
         finally {
-            if (timer)
+            if (timer) {
                 clearTimeout(timer);
+            }
         }
         if (first === 'timeout') {
-            cancelled = true;
-            stop.abort(undefined);
-            if (sent)
-                await interrupt(worker, outcome);
-            else
-                outcome.catch(() => { });
+            await cancel();
             throw new Error(`Command timed out after ${opts.timeoutMs}ms`);
         }
-        if (first.evict)
+        if (first.evict) {
             await drainAndReap(worker);
+        }
         return first.result;
     }
     finally {
@@ -179,8 +192,9 @@ export async function runPythonInWorker(spec, opts) {
 }
 export async function closePythonWorker() {
     const worker = active;
-    if (!worker)
+    if (!worker) {
         return;
+    }
     active = null;
     const timer = grace(SHUTDOWN_GRACE_MS);
     try {
@@ -199,3 +213,4 @@ export async function closePythonWorker() {
         timer.clear();
     }
 }
+function noop() { }