@agiledigital/pingone-aic-script-tester 0.1.0

package/dist/src/harness/lease.js

@@ -0,0 +1,286 @@
+import { judge } from "../case/index.js";
+import { runCase } from "../bindings/index.js";
+import { ledgerToManaged, localIdmHandle } from "./idm.js";
+import { describeResidue, findResidue } from "./residue.js";
+import { applyInputsAndEsv, caseWithGiven, mergeChannels, normaliseWire, parseInputs, toGiven, } from "./spec.js";
+import { carryGiven, submittedCallbacks } from "./step.js";
+/**
+ * One test's run, assembled lazily.
+ *
+ * Deliberately NOT a thenable. A builder that is also a promise invites an
+ * `await` halfway through the chain, after which `.check()` is appending to a
+ * run that has already settled — a bug that reads as working code. Making
+ * `.expect()` the only terminal turns that whole class into a type error.
+ */
+export class RunBuilder {
+    #lease;
+    #testName;
+    #rawInput;
+    #override = {};
+    #checks = [];
+    #steps = [];
+    constructor(lease, testName, rawInput) {
+        this.#lease = lease;
+        this.#testName = testName;
+        this.#rawInput = rawInput;
+    }
+    state(state) {
+        this.#override = { ...this.#override, state: mergeState(this.#override.state, state) };
+        return this;
+    }
+    esv(esv) {
+        this.#override = { ...this.#override, esv: { ...this.#override.esv, ...esv } };
+        return this;
+    }
+    headers(headers) {
+        this.#override = { ...this.#override, headers: { ...this.#override.headers, ...headers } };
+        return this;
+    }
+    params(params) {
+        this.#override = { ...this.#override, params: { ...this.#override.params, ...params } };
+        return this;
+    }
+    session(session) {
+        this.#override = { ...this.#override, session: { ...this.#override.session, ...session } };
+        return this;
+    }
+    /**
+     * Declare one suspended pass: what the script must send, what the client
+     * sends back, and what must be true of the world in between.
+     *
+     * Passes run in declaration order and the terminal `.expect()` judges the
+     * one after the last step, so a two-callback journey is two `.step()` calls
+     * and one `.expect()`. A step whose expectations fail aborts the chain
+     * rather than replying anyway: every later pass is seeded from this one, so
+     * continuing would report a cascade of failures that all trace back here.
+     */
+    step(spec) {
+        this.#steps.push(spec);
+        return this;
+    }
+    /** The same, for a chain built from data. */
+    steps(specs) {
+        for (const spec of specs) {
+            this.#steps.push(spec);
+        }
+        return this;
+    }
+    /** Assert against each lane's IDM store and response. Fail by throwing. */
+    check(fn) {
+        this.#checks.push(fn);
+        return this;
+    }
+    /** The only terminal. */
+    async expect(expected) {
+        return this.#lease.execute(this.#testName, this.#rawInput, this.#override, expected, this.#checks, this.#steps);
+    }
+}
+export class Lease {
+    #spec;
+    #options;
+    /** Everything the harness created, in creation order. */
+    #suiteLedger = [];
+    #testLedger = [];
+    constructor(spec, options) {
+        this.#spec = spec;
+        this.#options = options;
+    }
+    /** Suite-scoped fixtures, created once before the first test. */
+    open() {
+        this.#suiteLedger = [];
+        for (const fixture of Object.values(this.#spec.fixtures ?? {})) {
+            this.#suiteLedger.push(fixture);
+        }
+    }
+    fixtures = {
+        create: (type, record) => {
+            for (const one of Array.isArray(record) ? record : [record]) {
+                this.#testLedger.push({ type, record: one });
+            }
+            return Promise.resolve();
+        },
+    };
+    run(input) {
+        return new RunBuilder(this, this.#options.testName?.() ?? this.#spec.name, input);
+    }
+    /**
+     * Drained after every test. The per-test ledger goes; the suite's stays
+     * until close(). Clearing only at teardown would let test 3 see test 1's
+     * records, which is the cross-test interference this design exists to
+     * remove.
+     */
+    async endTest() {
+        try {
+            await this.#options.lane?.endTest();
+        }
+        finally {
+            this.#testLedger = [];
+        }
+    }
+    /** Suite teardown: drop what the suite created, alongside the journey. */
+    close() {
+        this.#testLedger = [];
+        this.#suiteLedger = [];
+        return Promise.resolve();
+    }
+    ledger() {
+        return [...this.#suiteLedger, ...this.#testLedger];
+    }
+    async execute(testName, rawInput, override, expected, checks, steps = []) {
+        const input = parseInputs(this.#spec, rawInput);
+        const draft = mergeChannels(this.#spec.always, override);
+        if (this.#spec.beforeRun !== undefined) {
+            await this.#spec.beforeRun({
+                input: input,
+                request: draft,
+                fixtures: this.fixtures,
+            });
+        }
+        applyInputsAndEsv(draft, input);
+        const ledger = this.ledger();
+        let given = toGiven(draft, {
+            managed: ledgerToManaged(ledger),
+            ...(this.#options.realm === undefined
+                ? {}
+                : { realm: this.#options.realm }),
+        }, this.#options.realm);
+        if (steps.length > 0 && given.callbacks === undefined) {
+            // Declaring a step says the script suspends, and a script that suspends
+            // reads `callbacks` to tell its first pass from its later ones. AM's
+            // first pass carries an empty list, so seed one rather than leaving the
+            // binding unseeded and failing on a read the chain guarantees.
+            given = { ...given, callbacks: [] };
+        }
+        const stepResults = [];
+        for (const [index, step] of steps.entries()) {
+            given = await this.#runStep(testName, index, step, given, input, stepResults);
+        }
+        const kase = caseWithGiven(this.#spec, testName, given, expected);
+        const effects = await runCase(this.#options.runner, kase, {
+            ...(this.#options.timeoutMs !== undefined ? { timeoutMs: this.#options.timeoutMs } : {}),
+        });
+        const verdict = judge(kase, effects.effects);
+        const store = cloneStore(effects.effects.managedStore);
+        const idm = localIdmHandle(store ?? {}, () => undefined);
+        try {
+            for (const check of checks) {
+                await check(idm, { input, effects: effects.effects });
+            }
+        }
+        finally {
+            if (this.#spec.cleanup !== undefined) {
+                await this.#spec.cleanup(idm, { input: input });
+            }
+        }
+        // The store is diffed AFTER cleanup ran, which is the only ordering that
+        // tests the cleanup rather than the script.
+        if (this.#options.allowResidue !== true) {
+            const residue = findResidue(store, ledger);
+            if (residue.length > 0) {
+                throw new Error(`rhino-local: ${kase.name}\n  ${describeResidue(residue)}`);
+            }
+        }
+        const result = {
+            kase,
+            effects: effects.effects,
+            verdict,
+            fixtures: ledger,
+            steps: stepResults,
+        };
+        if (this.#options.lane !== undefined) {
+            const conformance = await this.#options.lane.run({
+                result,
+                source: this.#spec.script,
+                hooks: this.#laneHooks(input, checks, steps),
+            });
+            result.conformance = conformance;
+        }
+        return result;
+    }
+    /**
+     * Run one suspended pass and return the seed for the next.
+     *
+     * The step's `check` is handed the run's own store rather than a copy, so a
+     * record it deletes really is gone from the pass that follows. A copy would
+     * let a cleanup written between two halves of a journey look like it worked
+     * while the next pass still saw the record.
+     */
+    async #runStep(testName, index, step, given, input, results) {
+        const kase = caseWithGiven(this.#spec, `${testName} [step ${index + 1}]`, given, {
+            ...(step.expect ?? {}),
+            outcome: null,
+        });
+        const run = await runCase(this.#options.runner, kase, {
+            ...(this.#options.timeoutMs !== undefined ? { timeoutMs: this.#options.timeoutMs } : {}),
+        });
+        const verdict = judge(kase, run.effects);
+        if (!verdict.pass) {
+            throw new Error(`rhino-local: ${kase.name}\n${verdict.summary}`);
+        }
+        const context = {
+            input,
+            step: index + 1,
+            callbacks: run.effects.callbacks,
+            effects: run.effects,
+        };
+        if (step.check !== undefined) {
+            if (run.effects.managedStore === undefined) {
+                run.effects.managedStore = {};
+            }
+            await step.check(localIdmHandle(run.effects.managedStore, () => undefined), context);
+        }
+        const replies = typeof step.reply === "function" ? step.reply(context) : step.reply;
+        const submitted = submittedCallbacks(run.effects.callbacks, replies, kase.name);
+        results.push({ kase, effects: run.effects, verdict, submitted });
+        return carryGiven(given, run.effects, submitted);
+    }
+    #laneHooks(input, checks, steps) {
+        const cleanup = this.#spec.cleanup;
+        return {
+            stepChecks: steps.map((step, index) => {
+                const check = step.check;
+                return check === undefined
+                    ? undefined
+                    : (idm, effects) => check(idm, {
+                        input,
+                        step: index + 1,
+                        callbacks: effects.callbacks,
+                        effects,
+                    });
+            }),
+            finalChecks: checks.map((check) => (idm, effects) => check(idm, { input, effects })),
+            ...(cleanup === undefined
+                ? {}
+                : {
+                    cleanup: (idm) => cleanup(idm, {
+                        input: input,
+                    }),
+                }),
+        };
+    }
+}
+export function defineSuite(spec) {
+    if (spec.outcomes.length === 0) {
+        throw new Error(`rhino-local: suite ${JSON.stringify(spec.name)} must declare its outcomes — a tenant answers an undeclared outcome with a bare 401 and no callback`);
+    }
+    return {
+        spec,
+        lease: (options) => new Lease(spec, options),
+    };
+}
+/** A managed record the suite creates once, for the whole file. */
+export function managed(type, record) {
+    return { type, record };
+}
+function mergeState(a, b) {
+    return {
+        shared: { ...(a?.shared ?? {}), ...(b?.shared ?? {}) },
+        transient: { ...(a?.transient ?? {}), ...(b?.transient ?? {}) },
+    };
+}
+function cloneStore(store) {
+    return store === undefined
+        ? undefined
+        : JSON.parse(JSON.stringify(store));
+}
+export { normaliseWire };

package/dist/src/harness/residue.d.ts

@@ -0,0 +1,23 @@
+import type { JsonObject } from "../case/types.ts";
+import type { FixtureSpec } from "./types.ts";
+export interface ResidueEntry {
+    resource: string;
+    reason: "created-by-script" | "mutated-by-script";
+}
+/**
+ * Identify records that survived a test which the harness did not create.
+ *
+ * This is the check that stops `cleanup()` rotting. A cleanup function nobody
+ * verifies drifts the moment the script grows a new write, and on a tenant the
+ * drift is invisible — the harness cannot see a record it has no id for. The
+ * local lane can: it owns the whole store, so the residue is simply what is
+ * left over after removing everything the ledger accounts for.
+ *
+ * Compared against the **store**, not the recorded call log. Matching
+ * `create` calls to `delete` calls checks intent, and would call a test clean
+ * when its cleanup deleted a different id than the one the script wrote. It
+ * would also miss a script that mutated a record it never created, which
+ * leaves the tenant just as dirty as an extra row does.
+ */
+export declare function findResidue(store: Record<string, JsonObject[]> | undefined, ledger: readonly FixtureSpec[]): ResidueEntry[];
+export declare function describeResidue(entries: readonly ResidueEntry[]): string;

package/dist/src/harness/residue.js

@@ -0,0 +1,73 @@
+/**
+ * Identify records that survived a test which the harness did not create.
+ *
+ * This is the check that stops `cleanup()` rotting. A cleanup function nobody
+ * verifies drifts the moment the script grows a new write, and on a tenant the
+ * drift is invisible — the harness cannot see a record it has no id for. The
+ * local lane can: it owns the whole store, so the residue is simply what is
+ * left over after removing everything the ledger accounts for.
+ *
+ * Compared against the **store**, not the recorded call log. Matching
+ * `create` calls to `delete` calls checks intent, and would call a test clean
+ * when its cleanup deleted a different id than the one the script wrote. It
+ * would also miss a script that mutated a record it never created, which
+ * leaves the tenant just as dirty as an extra row does.
+ */
+export function findResidue(store, ledger) {
+    if (store === undefined) {
+        return [];
+    }
+    const accounted = new Map();
+    for (const fixture of ledger) {
+        const id = recordId(fixture.record);
+        if (id !== undefined) {
+            accounted.set(`${fixture.type}/${id}`, fixture.record);
+        }
+    }
+    const residue = [];
+    for (const [collection, rows] of Object.entries(store)) {
+        for (const row of rows) {
+            const id = recordId(row);
+            const resource = id === undefined ? collection : `${collection}/${id}`;
+            const seeded = id === undefined ? undefined : accounted.get(resource);
+            if (seeded === undefined) {
+                residue.push({ resource, reason: "created-by-script" });
+                continue;
+            }
+            if (!sameRecord(seeded, row)) {
+                residue.push({ resource, reason: "mutated-by-script" });
+            }
+        }
+    }
+    return residue;
+}
+export function describeResidue(entries) {
+    if (entries.length === 0) {
+        return "";
+    }
+    const lines = entries.map((entry) => `    ${entry.resource}  (${entry.reason.replace(/-/g, " ")})`);
+    const count = entries.length === 1 ? "1 record" : `${entries.length} records`;
+    return [
+        `${count} survived the test that the harness did not create:`,
+        ...lines,
+        "  Add them to the suite's cleanup(), or set allowResidue if deliberate.",
+        "  On the AIC lane this would leak permanently and invisibly.",
+    ].join("\n");
+}
+function recordId(record) {
+    const id = record._id;
+    return typeof id === "string" ? id : undefined;
+}
+/**
+ * The mock stores what the script wrote, which may carry fields the fixture
+ * never set (`_rev`, server defaults). Comparing only the keys the fixture
+ * declared keeps those from reading as mutations the script made.
+ */
+function sameRecord(seeded, stored) {
+    for (const [key, value] of Object.entries(seeded)) {
+        if (JSON.stringify(stored[key]) !== JSON.stringify(value)) {
+            return false;
+        }
+    }
+    return true;
+}

package/dist/src/harness/show-log.d.ts

@@ -0,0 +1,43 @@
+import { type FailureRecord } from "./failures.ts";
+export interface TxChoice {
+    id: string;
+    label: string;
+}
+export interface ShowLogIo {
+    readDump: () => Promise<FailureRecord[]>;
+    print: (text: string) => void;
+    error: (text: string) => void;
+    selectTests: (records: FailureRecord[]) => Promise<FailureRecord[]>;
+    selectIds: (record: FailureRecord, choices: TxChoice[]) => Promise<string[]>;
+    /** Every log event for `id` on the tenant a failure record names. */
+    readTransaction: (tenant: string, id: string) => Promise<unknown[]>;
+    openEditor: (editor: string, file: string) => Promise<void>;
+    writeView: (contents: string) => Promise<string>;
+    env: NodeJS.ProcessEnv;
+}
+export declare function txChoices(record: FailureRecord): TxChoice[];
+export declare function resolveLogsEditor(env: NodeJS.ProcessEnv): string | undefined;
+/**
+ * No tenant column: a tenant's name defaults to its hostname, and this list
+ * reaches stdout (and so CI logs) whether or not `--stdout` was asked for.
+ */
+export declare function formatFailureList(records: readonly FailureRecord[]): string;
+export declare function formatChoices(choices: readonly TxChoice[]): string;
+/**
+ * Empty input selects the first entry (newest test / the stem). `all` selects
+ * every entry. Invalid input returns undefined so the caller can re-prompt.
+ */
+export declare function parseSelection(input: string, count: number, empty?: "first" | "all"): number[] | undefined;
+export interface ShowLogOptions {
+    /**
+     * Print the log bodies instead of writing the view. Off by default: the
+     * bodies are tenant data, and the view is a 0600 file in the self-ignoring
+     * state directory, where a CI log is neither.
+     */
+    stdout?: boolean;
+}
+export declare function runShowLog(io: ShowLogIo, options?: ShowLogOptions): Promise<number>;
+export declare function createDefaultIo(options?: {
+    env?: NodeJS.ProcessEnv;
+    project?: string;
+}): ShowLogIo;

package/dist/src/harness/show-log.js

@@ -0,0 +1,253 @@
+import { spawn } from "node:child_process";
+import { chmod, writeFile } from "node:fs/promises";
+import { createInterface } from "node:readline/promises";
+import { checkTenantDescription, configuredTenantProvider, } from "../aic/provider.js";
+import { aicCliProvider, defaultAicIo } from "../aic/tenant.js";
+import { latestLogsPath, projectRoot } from "../project.js";
+import { readFailures, sortNewestFirst, } from "./failures.js";
+export function txChoices(record) {
+    if (record.passIds.length <= 1) {
+        return [{ id: record.stem, label: "whole chain" }];
+    }
+    return [
+        { id: record.stem, label: "whole chain" },
+        ...record.passIds.map((id, index) => ({
+            id,
+            label: `pass ${index + 1}`,
+        })),
+    ];
+}
+export function resolveLogsEditor(env) {
+    return nonEmpty(env.LOGS_EDITOR) ?? nonEmpty(env.EDITOR);
+}
+/**
+ * No tenant column: a tenant's name defaults to its hostname, and this list
+ * reaches stdout (and so CI logs) whether or not `--stdout` was asked for.
+ */
+export function formatFailureList(records) {
+    return records
+        .map((record, index) => {
+        const n = String(index + 1).padStart(String(records.length).length, " ");
+        return `${n}. ${record.timestamp}  ${record.testName}`;
+    })
+        .join("\n");
+}
+export function formatChoices(choices) {
+    return choices
+        .map((choice, index) => `${index + 1}. ${choice.id}  (${choice.label})`)
+        .join("\n");
+}
+/**
+ * Empty input selects the first entry (newest test / the stem). `all` selects
+ * every entry. Invalid input returns undefined so the caller can re-prompt.
+ */
+export function parseSelection(input, count, empty = "first") {
+    if (count < 1) {
+        return [];
+    }
+    const trimmed = input.trim().toLowerCase();
+    if (trimmed === "") {
+        return empty === "all" ? range(0, count) : [0];
+    }
+    if (trimmed === "all") {
+        return range(0, count);
+    }
+    const picked = [];
+    const seen = new Set();
+    for (const part of trimmed.split(",")) {
+        const piece = part.trim();
+        const span = /^(\d+)-(\d+)$/.exec(piece);
+        if (span !== null) {
+            const start = Number(span[1]);
+            const end = Number(span[2]);
+            if (!Number.isInteger(start) || !Number.isInteger(end) || start < 1 || end > count || start > end) {
+                return undefined;
+            }
+            for (let index = start - 1; index < end; index += 1) {
+                if (!seen.has(index)) {
+                    seen.add(index);
+                    picked.push(index);
+                }
+            }
+            continue;
+        }
+        const n = Number(piece);
+        if (!Number.isInteger(n) || n < 1 || n > count) {
+            return undefined;
+        }
+        const index = n - 1;
+        if (!seen.has(index)) {
+            seen.add(index);
+            picked.push(index);
+        }
+    }
+    return picked.length === 0 ? undefined : picked;
+}
+export async function runShowLog(io, options = {}) {
+    const records = sortNewestFirst(await io.readDump());
+    if (records.length === 0) {
+        io.print("no failed tests recorded. Run a test that hits the AIC lane first.");
+        return 0;
+    }
+    io.print(formatFailureList(records));
+    const onlyRecord = records[0];
+    const selected = records.length === 1 && onlyRecord !== undefined
+        ? [onlyRecord]
+        : await io.selectTests(records);
+    if (selected.length === 0) {
+        io.print("nothing selected");
+        return 0;
+    }
+    const chunks = [];
+    for (const record of selected) {
+        const choices = txChoices(record);
+        const onlyChoice = choices[0];
+        const ids = choices.length === 1 && onlyChoice !== undefined
+            ? [onlyChoice.id]
+            : await io.selectIds(record, choices);
+        for (const id of ids) {
+            let events;
+            try {
+                events = await io.readTransaction(record.tenant, id);
+            }
+            catch (error) {
+                io.error(error instanceof Error ? error.message : String(error));
+                return 1;
+            }
+            const body = JSON.stringify(events, null, 2);
+            chunks.push(ids.length === 1 && selected.length === 1
+                ? body
+                : `=== ${id} (${record.testName}) ===\n${body}`);
+        }
+    }
+    const text = `${chunks.join("\n\n")}\n`;
+    if (options.stdout === true) {
+        io.print(text);
+        return 0;
+    }
+    const viewPath = await io.writeView(text);
+    const editor = resolveLogsEditor(io.env);
+    if (editor === undefined) {
+        io.print(`wrote ${viewPath}\nSet LOGS_EDITOR or EDITOR to open it, or pass --stdout to print the logs instead.`);
+        return 0;
+    }
+    await io.openEditor(editor, viewPath);
+    return 0;
+}
+export function createDefaultIo(options = {}) {
+    const env = options.env ?? process.env;
+    const project = options.project ?? projectRoot(env);
+    const providers = new Map();
+    return {
+        env,
+        readDump: () => readFailures(),
+        print: (text) => {
+            process.stdout.write(`${text}\n`);
+        },
+        error: (text) => {
+            process.stderr.write(`${text}\n`);
+        },
+        async selectTests(records) {
+            process.stdout.write("\nSelect test (comma-separated, all) [1]: ");
+            const picked = await readSelection(records.length);
+            return picked.flatMap((index) => {
+                const record = records[index];
+                return record === undefined ? [] : [record];
+            });
+        },
+        async selectIds(record, choices) {
+            process.stdout.write(`\n${record.testName}\n${formatChoices(choices)}\n`);
+            process.stdout.write("Select transaction id(s) [1 = whole chain]: ");
+            const picked = await readSelection(choices.length);
+            return picked.flatMap((index) => {
+                const id = choices[index]?.id;
+                return id === undefined ? [] : [id];
+            });
+        },
+        async readTransaction(tenant, id) {
+            // One provider per tenant for the whole session, so an `aic` context is
+            // listed once rather than once per selected transaction.
+            let provider = providers.get(tenant);
+            if (provider === undefined) {
+                provider =
+                    configuredTenantProvider(env) ??
+                        aicCliProvider(defaultAicIo(project), { tenant, project });
+                providers.set(tenant, provider);
+            }
+            const { name } = checkTenantDescription(await provider.describe());
+            if (name !== tenant) {
+                throw new Error("show-log: this failure ran on a different tenant from the one the configured tenant provider serves");
+            }
+            if (provider.logs === undefined) {
+                throw new Error("show-log: the configured tenant provider cannot read logs. Give it logKeys (or set AIC_SCRIPT_TESTER_LOG_KEY_ID and AIC_SCRIPT_TESTER_LOG_KEY_SECRET).");
+            }
+            return provider.logs.transaction(id);
+        },
+        openEditor,
+        async writeView(contents) {
+            const path = latestLogsPath(env);
+            // 0600: this holds a live tenant's log bodies — hostnames, client ips,
+            // request headers. The directory is gitignored, but the file should not
+            // be world-readable either.
+            await writeFile(path, contents, { encoding: "utf8", mode: 0o600 });
+            await chmod(path, 0o600);
+            return path;
+        },
+    };
+}
+async function readSelection(count) {
+    if (process.stdin.isTTY !== true) {
+        throw new Error("show-log: need a terminal to select among multiple entries. Re-run from a tty.");
+    }
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await rl.question("");
+        const picked = parseSelection(answer, count);
+        if (picked === undefined) {
+            throw new Error(`show-log: could not parse ${JSON.stringify(answer)}`);
+        }
+        return picked;
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * `shell: true` is deliberate — `$EDITOR` is routinely a command line
+ * (`code -w`, `vim -p`), not a bare executable. But an args array WITH a shell
+ * is what Node deprecated in DEP0190, because the shell re-splits what was
+ * already separated. So build the one command string the shell will actually
+ * run, and quote the path ourselves.
+ */
+function openEditor(editor, file) {
+    const command = `${editor} ${shellQuote(file)}`;
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, { stdio: "inherit", shell: true });
+        child.on("error", reject);
+        child.on("exit", (code) => {
+            if (code === 0 || code === null) {
+                resolve();
+                return;
+            }
+            reject(new Error(`${editor} exited ${code}`));
+        });
+    });
+}
+function nonEmpty(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length === 0 ? undefined : trimmed;
+}
+function range(start, end) {
+    const out = [];
+    for (let index = start; index < end; index += 1) {
+        out.push(index);
+    }
+    return out;
+}
+/** Single-quote for a POSIX shell, closing and reopening around any quote. */
+function shellQuote(value) {
+    return `'${value.replaceAll("'", `'\\''`)}'`;
+}