@agiledigital/pingone-aic-script-tester 0.1.0

package/dist/src/protocol.d.ts

@@ -0,0 +1,62 @@
+/** JSON values the runner protocol can carry (job globals and completion values). */
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * Machine-readable job outcomes. These are different bugs; the harness must
+ * not collapse them into one string.
+ *
+ * - `ok` — compiled and ran
+ * - `compile_error` — failed to compile
+ * - `runtime_error` — threw at runtime
+ * - `timeout` — instruction observer fired (`Error("Interrupt.")`)
+ * - `protocol_error` — the job itself was malformed
+ */
+export type JobOutcome = "ok" | "compile_error" | "runtime_error" | "timeout" | "protocol_error";
+export interface JobRequest {
+    /** Correlates the response. Generated if omitted. */
+    id?: string;
+    source: string;
+    /** Author's file path; becomes Rhino's source name (not `<eval>`). */
+    sourceName?: string;
+    /** Rhino language version. Default 0 (`VERSION_DEFAULT`). */
+    languageVersion?: number | string;
+    /**
+     * Per-job timeout in milliseconds. `0` means no timeout (AM's default).
+     * Omitted uses the runner's harness default (10s) so a runaway cannot hang
+     * the process.
+     */
+    timeoutMs?: number;
+    /** JSON values placed in ENGINE_SCOPE Bindings before eval. */
+    globals?: {
+        [key: string]: JsonValue;
+    };
+    /**
+     * Java class allow-list for this job, as a script context's `allowLists`
+     * entries (exact names, or a trailing `*` meaning prefix). Supplying one
+     * installs AM's class shutter; omitting it leaves every Java name resolvable,
+     * which is the pre-shutter behaviour.
+     */
+    classAllowList?: string[];
+    /** Evaluated first, so author line numbers on `source` stay intact. */
+    preamble?: string;
+    preambleName?: string;
+    /** Return this global after evaluation instead of Rhino's completion value. */
+    resultGlobal?: string;
+}
+export interface JobError {
+    class: string;
+    message: string | null;
+    sourceName: string | null;
+    line: number;
+    column: number;
+    lineSource: string | null;
+}
+export interface JobResponse {
+    id: string;
+    outcome: JobOutcome;
+    valueKind: string;
+    value: JsonValue;
+    error: JobError | null;
+}
+export declare function parseJobResponse(raw: unknown, line: string): JobResponse;

package/dist/src/protocol.js

@@ -0,0 +1,68 @@
+const OUTCOMES = new Set([
+    "ok",
+    "compile_error",
+    "runtime_error",
+    "timeout",
+    "protocol_error",
+]);
+export function parseJobResponse(raw, line) {
+    if (!isRecord(raw)) {
+        throw new Error(`rhino-local: runner response is not an object: ${line}`);
+    }
+    if (typeof raw.id !== "string" || raw.id.length === 0) {
+        throw new Error(`rhino-local: runner response has no id: ${line}`);
+    }
+    if (typeof raw.outcome !== "string" || !OUTCOMES.has(raw.outcome)) {
+        throw new Error(`rhino-local: runner response has unknown outcome: ${line}`);
+    }
+    if (typeof raw.valueKind !== "string") {
+        throw new Error(`rhino-local: runner response is missing valueKind: ${line}`);
+    }
+    return {
+        id: raw.id,
+        outcome: raw.outcome,
+        valueKind: raw.valueKind,
+        value: raw.value,
+        error: parseJobError(raw.error),
+    };
+}
+function parseJobError(raw) {
+    if (raw === null || raw === undefined) {
+        return null;
+    }
+    if (!isRecord(raw)) {
+        throw new Error("rhino-local: runner error is not an object");
+    }
+    if (typeof raw.class !== "string") {
+        throw new Error("rhino-local: runner error is missing class");
+    }
+    return {
+        class: raw.class,
+        message: optionalString(raw.message),
+        sourceName: optionalString(raw.sourceName),
+        line: optionalNumber(raw.line, -1),
+        column: optionalNumber(raw.column, -1),
+        lineSource: optionalString(raw.lineSource),
+    };
+}
+function optionalString(raw) {
+    if (raw === null || raw === undefined) {
+        return null;
+    }
+    if (typeof raw !== "string") {
+        throw new Error("rhino-local: expected string or null");
+    }
+    return raw;
+}
+function optionalNumber(raw, fallback) {
+    if (raw === null || raw === undefined) {
+        return fallback;
+    }
+    if (typeof raw !== "number" || !Number.isFinite(raw)) {
+        throw new Error("rhino-local: expected finite number");
+    }
+    return raw;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/src/provider-module.d.ts

@@ -0,0 +1,11 @@
+import { type TenantProvider } from "./aic/provider.ts";
+/**
+ * Load a caller's tenant-provider module for a bin (`--provider-module`).
+ *
+ * A token callback lives in the consumer's code, and a bin is a separate
+ * process from the Vitest run that registered it, so the bins take the same
+ * module the consumer's `setupFiles` uses. Either shape works: a module whose
+ * default export is a `TenantProvider`, or one that calls
+ * `setTenantProvider()` when imported.
+ */
+export declare function loadProviderModule(path: string, cwd?: string): Promise<TenantProvider>;

package/dist/src/provider-module.js

@@ -0,0 +1,46 @@
+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 { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { configuredTenantProvider, setTenantProvider, TenantProviderError, } from "./aic/provider.js";
+/**
+ * Load a caller's tenant-provider module for a bin (`--provider-module`).
+ *
+ * A token callback lives in the consumer's code, and a bin is a separate
+ * process from the Vitest run that registered it, so the bins take the same
+ * module the consumer's `setupFiles` uses. Either shape works: a module whose
+ * default export is a `TenantProvider`, or one that calls
+ * `setTenantProvider()` when imported.
+ */
+export async function loadProviderModule(path, cwd = process.cwd()) {
+    const url = pathToFileURL(resolve(cwd, path)).href;
+    // Clear first, so the only provider that can be registered afterwards is
+    // one this module supplied: a module that supplies none must not leave an
+    // earlier registration — another tenant — in force.
+    setTenantProvider(undefined);
+    const loaded = (await import(__rewriteRelativeImportExtension(url)));
+    if (isTenantProvider(loaded.default)) {
+        setTenantProvider(loaded.default);
+        return loaded.default;
+    }
+    // An empty environment leaves only the registry to answer.
+    const registered = configuredTenantProvider({});
+    if (registered === undefined) {
+        throw new TenantProviderError(`${path} neither default-exports a TenantProvider nor calls setTenantProvider() ` +
+            "(a module that was already imported does not run again, so it cannot register twice)");
+    }
+    return registered;
+}
+function isTenantProvider(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const candidate = value;
+    return typeof candidate.describe === "function" && typeof candidate.getToken === "function";
+}

package/dist/src/runner.d.ts

@@ -0,0 +1,39 @@
+import { type JvmLane, type RunnerEnvironment } from "./jvm.ts";
+import { type JobRequest, type JobResponse } from "./protocol.ts";
+export declare class RhinoRunnerExitError extends Error {
+    readonly exitCode: number | null;
+    readonly signal: NodeJS.Signals | null;
+    readonly stderr: string;
+    constructor(exitCode: number | null, signal: NodeJS.Signals | null, stderr: string);
+}
+/**
+ * The host JVM and the AM image's JVM answered one job differently. This is
+ * the whole reason the `both` lane exists, so it fails the test rather than
+ * picking a winner.
+ */
+export declare class LaneDivergenceError extends Error {
+    readonly job: string;
+    readonly host: JobResponse;
+    readonly container: JobResponse;
+    constructor(job: string, host: JobResponse, container: JobResponse);
+}
+export interface SpawnRunnerOptions {
+    /** Default: `AIC_SCRIPT_TESTER_JVM`, else `host`. */
+    lane?: JvmLane;
+    /** Jar and compiled-class cache. Default: `AIC_SCRIPT_TESTER_CACHE`, else `~/.cache/aic-script-tester`. */
+    cache?: string;
+    spawnTimeoutMs?: number;
+}
+export declare class RhinoRunner {
+    #private;
+    readonly lane: JvmLane;
+    private constructor();
+    static spawn(options?: SpawnRunnerOptions): Promise<RhinoRunner>;
+    /** What the (primary) JVM reported at startup. */
+    get environment(): RunnerEnvironment;
+    eval(job: JobRequest): Promise<JobResponse>;
+    close(): Promise<void>;
+    /** Forcibly stop every JVM. Every pending eval rejects. Used by crash tests. */
+    kill(): Promise<void>;
+    get stderr(): string;
+}

package/dist/src/runner.js

@@ -0,0 +1,337 @@
+import { execFile, spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { isDeepStrictEqual, promisify } from "node:util";
+import { cacheDir, checkEnvironment, containerLaunch, ensureRhinoJar, ensureRunnerClasses, hostLaunch, laneFromEnv, parseEnvironment, } from "./jvm.js";
+import { parseJobResponse } from "./protocol.js";
+const execFileAsync = promisify(execFile);
+const READY = "rhino-local-runner ready";
+export class RhinoRunnerExitError extends Error {
+    exitCode;
+    signal;
+    stderr;
+    constructor(exitCode, signal, stderr) {
+        super(`rhino-local: JVM runner exited (code=${exitCode}, signal=${signal})` +
+            (stderr.trim() ? `: ${stderr.trim()}` : ""));
+        this.name = "RhinoRunnerExitError";
+        this.exitCode = exitCode;
+        this.signal = signal;
+        this.stderr = stderr;
+    }
+}
+/**
+ * The host JVM and the AM image's JVM answered one job differently. This is
+ * the whole reason the `both` lane exists, so it fails the test rather than
+ * picking a winner.
+ */
+export class LaneDivergenceError extends Error {
+    job;
+    host;
+    container;
+    constructor(job, host, container) {
+        super(`rhino-local: host and container JVMs disagree on ${job}\n` +
+            `  host:      ${JSON.stringify(withoutId(host))}\n` +
+            `  container: ${JSON.stringify(withoutId(container))}`);
+        this.name = "LaneDivergenceError";
+        this.job = job;
+        this.host = host;
+        this.container = container;
+    }
+}
+function withoutId(response) {
+    const { id: _id, ...rest } = response;
+    return rest;
+}
+/** One JVM speaking the line protocol. {@link RhinoRunner} holds one or two. */
+class JvmProcess {
+    lane;
+    containerName;
+    #child;
+    #pending = new Map();
+    #stdoutBuf = "";
+    #stderrBuf = "";
+    #closed = false;
+    #exit = null;
+    #exitWaiters = [];
+    environment;
+    constructor(lane, launch) {
+        this.lane = lane;
+        this.containerName = launch.containerName;
+        const child = spawn(launch.command, launch.args, {
+            env: launch.env,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        this.#child = child;
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => this.#onStdout(chunk));
+        child.stderr.on("data", (chunk) => {
+            this.#stderrBuf += chunk;
+        });
+        child.stdin.on("error", () => {
+            // EPIPE after a crash is reported via the exit handler.
+        });
+        child.on("error", (error) => {
+            this.#stderrBuf += `\n${error.message}`;
+        });
+        child.on("exit", (code, signal) => {
+            this.#exit = { code, signal };
+            const error = new RhinoRunnerExitError(code, signal, this.#stderrBuf);
+            for (const [id, pending] of this.#pending) {
+                this.#pending.delete(id);
+                pending.reject(error);
+            }
+            for (const waiter of this.#exitWaiters) {
+                waiter();
+            }
+            this.#exitWaiters = [];
+        });
+    }
+    get stderr() {
+        return this.#stderrBuf;
+    }
+    async waitUntilReady(timeoutMs) {
+        const started = Date.now();
+        for (;;) {
+            const at = this.#stderrBuf.indexOf(READY);
+            const end = at === -1 ? -1 : this.#stderrBuf.indexOf("\n", at);
+            if (end !== -1) {
+                const env = parseEnvironment(this.#stderrBuf.slice(at, end));
+                checkEnvironment(env, this.lane);
+                this.environment = env;
+                return;
+            }
+            if (this.#exit) {
+                throw new RhinoRunnerExitError(this.#exit.code, this.#exit.signal, this.#stderrBuf);
+            }
+            if (Date.now() - started > timeoutMs) {
+                await this.kill();
+                throw new Error(`rhino-local: ${this.lane} runner did not become ready within ${timeoutMs}ms: ${this.#stderrBuf}`);
+            }
+            await sleep(25);
+        }
+    }
+    send(id, payload) {
+        if (this.#closed || this.#exit) {
+            return Promise.reject(this.#exit
+                ? new RhinoRunnerExitError(this.#exit.code, this.#exit.signal, this.#stderrBuf)
+                : new Error("rhino-local: runner is closed"));
+        }
+        return new Promise((resolve, reject) => {
+            this.#pending.set(id, { resolve, reject });
+            const ok = this.#child.stdin.write(`${JSON.stringify(payload)}\n`);
+            if (!ok) {
+                this.#child.stdin.once("error", reject);
+            }
+        });
+    }
+    async close() {
+        if (this.#exit) {
+            await this.#removeContainer();
+            return;
+        }
+        if (this.#closed) {
+            await this.#waitForExit();
+            await this.#removeContainer();
+            return;
+        }
+        this.#closed = true;
+        try {
+            this.#child.stdin.end();
+        }
+        catch {
+            // already closed
+        }
+        const exited = await Promise.race([
+            this.#waitForExit().then(() => true),
+            sleep(5_000).then(() => false),
+        ]);
+        if (!exited) {
+            this.#child.kill("SIGTERM");
+            const exitedAfterTerm = await Promise.race([
+                this.#waitForExit().then(() => true),
+                sleep(2_000).then(() => false),
+            ]);
+            if (!exitedAfterTerm) {
+                this.#child.kill("SIGKILL");
+                await this.#waitForExit();
+            }
+        }
+        for (const [id, pending] of this.#pending) {
+            this.#pending.delete(id);
+            pending.reject(new Error("rhino-local: runner closed with job still pending"));
+        }
+        await this.#removeContainer();
+    }
+    async kill() {
+        this.#closed = true;
+        this.#child.kill("SIGKILL");
+        await Promise.race([this.#waitForExit(), sleep(2_000)]);
+        await this.#removeContainer();
+    }
+    #onStdout(chunk) {
+        this.#stdoutBuf += chunk;
+        let nl = this.#stdoutBuf.indexOf("\n");
+        while (nl !== -1) {
+            const line = this.#stdoutBuf.slice(0, nl);
+            this.#stdoutBuf = this.#stdoutBuf.slice(nl + 1);
+            if (line.length > 0) {
+                this.#dispatch(line);
+            }
+            nl = this.#stdoutBuf.indexOf("\n");
+        }
+    }
+    #dispatch(line) {
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch (error) {
+            const first = this.#pending.entries().next().value;
+            if (first) {
+                this.#pending.delete(first[0]);
+                first[1].reject(new Error(`rhino-local: unparseable runner stdout: ${line} (${String(error)})`));
+            }
+            return;
+        }
+        let response;
+        try {
+            response = parseJobResponse(parsed, line);
+        }
+        catch (error) {
+            const first = this.#pending.entries().next().value;
+            if (first) {
+                this.#pending.delete(first[0]);
+                first[1].reject(error instanceof Error ? error : new Error(String(error)));
+            }
+            return;
+        }
+        const pending = this.#pending.get(response.id);
+        if (!pending) {
+            return;
+        }
+        this.#pending.delete(response.id);
+        pending.resolve(response);
+    }
+    #waitForExit() {
+        if (this.#exit) {
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            this.#exitWaiters.push(resolve);
+        });
+    }
+    async #removeContainer() {
+        if (this.containerName === undefined) {
+            return;
+        }
+        try {
+            await execFileAsync("docker", ["rm", "-f", this.containerName], { timeout: 10_000 });
+        }
+        catch {
+            // already removed via --rm, or never created
+        }
+    }
+}
+export class RhinoRunner {
+    lane;
+    #primary;
+    #shadow;
+    constructor(lane, primary, shadow) {
+        this.lane = lane;
+        this.#primary = primary;
+        this.#shadow = shadow;
+    }
+    static async spawn(options = {}) {
+        const lane = options.lane ?? laneFromEnv();
+        const cache = options.cache ?? cacheDir();
+        const jar = await ensureRhinoJar(cache);
+        const classes = await ensureRunnerClasses(jar, { cache });
+        const spawnTimeoutMs = options.spawnTimeoutMs ?? 60_000;
+        const processes = [];
+        try {
+            if (lane === "host" || lane === "both") {
+                processes.push(new JvmProcess("host", hostLaunch(classes, jar)));
+            }
+            if (lane === "container" || lane === "both") {
+                processes.push(new JvmProcess("container", containerLaunch(classes, jar)));
+            }
+            await Promise.all(processes.map((p) => p.waitUntilReady(spawnTimeoutMs)));
+        }
+        catch (error) {
+            await Promise.all(processes.map((p) => p.kill()));
+            throw error;
+        }
+        const [primary, shadow] = processes;
+        if (primary === undefined) {
+            throw new Error("rhino-local: no runner lane selected");
+        }
+        return new RhinoRunner(lane, primary, shadow);
+    }
+    /** What the (primary) JVM reported at startup. */
+    get environment() {
+        const env = this.#primary.environment;
+        if (env === undefined) {
+            throw new Error("rhino-local: runner environment read before ready");
+        }
+        return env;
+    }
+    async eval(job) {
+        const id = job.id ?? randomUUID();
+        const payload = { id, source: job.source };
+        if (job.sourceName !== undefined) {
+            payload.sourceName = job.sourceName;
+        }
+        if (job.languageVersion !== undefined) {
+            payload.languageVersion = job.languageVersion;
+        }
+        if (job.timeoutMs !== undefined) {
+            payload.timeoutMs = job.timeoutMs;
+        }
+        if (job.globals !== undefined) {
+            payload.globals = job.globals;
+        }
+        if (job.preamble !== undefined) {
+            payload.preamble = job.preamble;
+        }
+        if (job.preambleName !== undefined) {
+            payload.preambleName = job.preambleName;
+        }
+        if (job.classAllowList !== undefined) {
+            payload.classAllowList = job.classAllowList;
+        }
+        if (job.resultGlobal !== undefined) {
+            payload.resultGlobal = job.resultGlobal;
+        }
+        if (this.#shadow === undefined) {
+            return this.#primary.send(id, payload);
+        }
+        const [host, container] = await Promise.all([
+            this.#primary.send(id, payload),
+            this.#shadow.send(id, payload),
+        ]);
+        if (!isDeepStrictEqual(withoutId(host), withoutId(container))) {
+            throw new LaneDivergenceError(job.sourceName ?? id, host, container);
+        }
+        return host;
+    }
+    async close() {
+        await Promise.all(this.#processes().map((p) => p.close()));
+    }
+    /** Forcibly stop every JVM. Every pending eval rejects. Used by crash tests. */
+    async kill() {
+        await Promise.all(this.#processes().map((p) => p.kill()));
+    }
+    get stderr() {
+        return this.#processes()
+            .map((p) => p.stderr)
+            .join("");
+    }
+    #processes() {
+        return this.#shadow === undefined ? [this.#primary] : [this.#primary, this.#shadow];
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}

package/dist/src/schema.d.ts

@@ -0,0 +1,48 @@
+/** Contexts-endpoint binding metadata (`docs/api/bindings/*.json`). */
+export declare const JS_TYPES: readonly ["string", "number", "boolean", "object", "array", "unknown", "void"];
+export type JsType = (typeof JS_TYPES)[number];
+export interface Parameter {
+    name: string;
+    javaScriptType: JsType;
+}
+export interface MethodElement {
+    elementType: "method";
+    name: string;
+    parameters: Parameter[];
+    returnType: JsType;
+}
+export interface FieldElement {
+    elementType: "field";
+    name: string;
+    javaScriptType: JsType;
+    elements: Element[];
+}
+export type Element = MethodElement | FieldElement;
+export interface Binding {
+    name: string;
+    javaScriptType: JsType;
+    elements: Element[];
+}
+export interface ContextsDocument {
+    _id: string;
+    bindings: Binding[];
+}
+export type BindingKind = "scalar" | "opaque" | "object";
+export declare function classifyBinding(binding: Binding): BindingKind;
+export interface MethodMember {
+    kind: "method";
+    name: string;
+    overloads: MethodElement[];
+}
+export interface FieldMember {
+    kind: "field";
+    name: string;
+    javaScriptType: JsType;
+    elements: Element[];
+}
+export type Member = MethodMember | FieldMember;
+/** Group overloads of the same name; preserve first-seen member order. */
+export declare function membersOf(elements: Element[]): Member[];
+export declare function uniqueOverloads(overloads: MethodElement[]): MethodElement[];
+export declare function overloadKey(overload: MethodElement): string;
+export declare function overloadLabel(overload: MethodElement): string;