@formio/uag-sdk 0.0.0-stage → 2.0.0-rc.1

package/loader.js

@@ -0,0 +1,223 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const { ENGINE_API_VERSION, definitionProblems } = require('./define');
+const { EngineConfigError, redact } = require('./errors');
+const { checkName, checkType, checkUnique, isPackageName } = require('./instances');
+const { missingSetting, resolveSettings, secretValues, settingVariable } = require('./settings');
+
+/**
+ * Finding, configuring and creating engine instances. The UAG, `uag-eval` and
+ * the engine server all load engines here, so one configuration means the same
+ * engines in each.
+ */
+
+/**
+ * The directories whose `node_modules` engine packages are looked up in: the
+ * host's own installation and each directory above it (where Node finds the
+ * host's own dependencies, so engines installed beside the host are found),
+ * then each absolute directory in `UAG_ENGINE_PATH`, without the directories
+ * above it. Never the working directory, `NODE_PATH` or Node's global folders.
+ */
+function enginePaths(root, env = process.env) {
+    const extra = String(env.UAG_ENGINE_PATH || '').split(path.delimiter).map((dir) => dir.trim()).filter(Boolean);
+    for (const dir of extra) {
+        if (!path.isAbsolute(dir)) {
+            throw new EngineConfigError(`UAG_ENGINE_PATH must list absolute directories; "${dir}" is relative.`);
+        }
+    }
+    const host = [];
+    for (let dir = root && path.resolve(root); dir; ) {
+        // As Node does, never look for node_modules/node_modules.
+        if (path.basename(dir) !== 'node_modules') host.push(dir);
+        const parent = path.dirname(dir);
+        dir = parent === dir ? undefined : parent;
+    }
+    return [...host, ...extra];
+}
+
+/** The packages a type name may come from, in order. */
+function packageCandidates(type) {
+    return isPackageName(type) ? [type] : [`@formio/uag-${type}`, `uag-engine-${type}`];
+}
+
+/** Whether `file` is `dir` or inside it. */
+function isInside(file, dir) {
+    const relative = path.relative(dir, file);
+    return relative === '' || (!!relative && !relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+/**
+ * Find `name` in `<dir>/node_modules` of the first of `paths` that has it, and
+ * nowhere else: not in the directories above, `NODE_PATH` or Node's global
+ * folders, which `require.resolve` would also search. Returns its entry file
+ * and package.json, or undefined when no path has it.
+ */
+function findPackage(name, paths) {
+    for (const dir of paths) {
+        const packageDir = path.join(dir, 'node_modules', ...name.split('/'));
+        const manifest = path.join(packageDir, 'package.json');
+        if (!fs.existsSync(manifest)) continue;
+        let json;
+        try {
+            json = JSON.parse(fs.readFileSync(manifest, 'utf8'));
+        }
+        catch (err) {
+            throw new EngineConfigError(`The package "${name}" has an unreadable package.json (${manifest}): ${err && err.message}`);
+        }
+        let entry;
+        try {
+            entry = require.resolve(name, { paths: [dir] });
+        }
+        catch (err) {
+            throw new EngineConfigError(`The package "${name}" (${packageDir}) has no entry point that require() can load: ${err && (err.code || err.message)}.`);
+        }
+        // A broken package must not fall through to a copy found elsewhere.
+        // Real paths, so a linked workspace package is still its own.
+        if (!isInside(fs.realpathSync(entry), fs.realpathSync(packageDir))) {
+            throw new EngineConfigError(`The package "${name}" in ${packageDir} resolved to ${entry}, outside it; it was not loaded.`);
+        }
+        return { entry, json };
+    }
+    return undefined;
+}
+
+/** The message of anything thrown, including a string. */
+function errorText(err) {
+    return err && typeof err === 'object' && 'message' in err ? String(err.message) : String(err);
+}
+
+/** Check a definition, from this SDK, another copy of it, or none. */
+function checkDefinition(definition, source, apiVersion) {
+    const problems = definitionProblems(definition);
+    if (problems.length) {
+        throw new EngineConfigError(`${source} is not a UAG engine: it does not export a valid engine type definition (${problems.join('; ')}).`);
+    }
+    if (definition.apiVersion !== apiVersion) {
+        throw new EngineConfigError(
+            `${source} (engine type "${definition.type}") was built for engine API version ${definition.apiVersion}; ` +
+            `this server supports version ${apiVersion}.`
+        );
+    }
+    return definition;
+}
+
+/**
+ * The definition for an instance's type: a definition given directly, a type in
+ * `types` (built-in, or passed by the embedding application), then the packages
+ * `@formio/uag-<type>` and `uag-engine-<type>`, or the package named.
+ * Returns the package's name and version when it came from one.
+ */
+function resolveType(type, { types = {}, paths = [], apiVersion = ENGINE_API_VERSION } = {}) {
+    if (type && typeof type === 'object') {
+        return { definition: checkDefinition(type, 'The engine type given in configuration', apiVersion) };
+    }
+    checkType(type);
+    if (!isPackageName(type) && Object.prototype.hasOwnProperty.call(types, type)) {
+        return { definition: checkDefinition(types[type], `The built-in engine type "${type}"`, apiVersion) };
+    }
+    const candidates = packageCandidates(type);
+    for (const candidate of candidates) {
+        const found = findPackage(candidate, paths);
+        if (!found) continue;
+        const { entry, json: pkg } = found;
+        let exported;
+        try {
+            exported = require(entry);
+        }
+        catch (err) {
+            throw new EngineConfigError(`The package "${candidate}" failed to load: ${errorText(err)}`);
+        }
+        const definition = exported && exported.__esModule && exported.default ? exported.default : exported;
+        return {
+            definition: checkDefinition(definition, `The package "${candidate}"`, apiVersion),
+            package: candidate,
+            ...(pkg.version && { version: pkg.version })
+        };
+    }
+    const known = Object.keys(types);
+    throw new EngineConfigError(
+        `No engine type "${type}" is installed. Looked for ${candidates.map((name) => `"${name}"`).join(' and ')}. ` +
+        `Install one (npm install ${candidates[0]}), or add a directory that contains it to UAG_ENGINE_PATH.` +
+        (known.length ? ` Types available without installing: ${known.join(', ')}.` : '')
+    );
+}
+
+/** Refuse two instance settings that would read the same `UAG_ENGINE_*` variable. */
+function checkVariables(resolved) {
+    const owners = new Map();
+    for (const { name, definition } of resolved) {
+        for (const key of Object.keys(definition.settings || {})) {
+            const variable = settingVariable(name, key);
+            const owner = owners.get(variable);
+            if (owner && owner.name !== name) {
+                throw new EngineConfigError(
+                    `The engines "${owner.name}" and "${name}" would both read ${variable} (for ${owner.key} and ${key}). Rename one of them.`
+                );
+            }
+            owners.set(variable, { name, key });
+        }
+    }
+}
+
+/**
+ * Create one engine from its definition, for an instance name and options.
+ * Errors name the instance and its type, and never contain a secret setting.
+ */
+async function createEngine(definition, { name, options = {}, env = process.env, config = {} }) {
+    const label = `The "${name}" engine (type "${definition.type}")`;
+    const settings = resolveSettings(definition, name, options, env);
+    const secrets = secretValues(definition, settings, options);
+    let engine;
+    try {
+        engine = await definition.create({
+            name,
+            settings,
+            options,
+            config,
+            requireSetting: (key) => {
+                if (settings[key] === undefined) throw missingSetting(definition, name, key);
+                return settings[key];
+            },
+        });
+    }
+    catch (err) {
+        const message = redact(errorText(err), secrets);
+        throw new EngineConfigError(err instanceof EngineConfigError || (err && err.name === 'EngineConfigError') ? message : `${label} failed to start: ${message}`);
+    }
+    if (!engine || typeof engine !== 'object') {
+        throw new EngineConfigError(`${label} did not create an engine.`);
+    }
+    if (engine.name !== name) {
+        throw new EngineConfigError(`${label} created an engine named ${JSON.stringify(engine.name)}; it must use the instance name.`);
+    }
+    if (!definition.kinds.includes(engine.kind)) {
+        throw new EngineConfigError(`${label} created a ${JSON.stringify(engine.kind)} engine; its type declares ${definition.kinds.join(' and ')}.`);
+    }
+    return engine;
+}
+
+/**
+ * Load the given instances (from `parseInstances` or `engineInstances`): resolve
+ * each type, resolve its settings, and create the engine. Returns
+ * `{ engine, type, package, version }` for each, in order, ready for
+ * `Formflow.engineRegistry`. Any problem stops loading with the instance named.
+ */
+async function loadEngines(instances, { types = {}, paths = [], env = process.env, config = {}, apiVersion = ENGINE_API_VERSION } = {}) {
+    const resolved = instances.map((instance) => {
+        const found = resolveType(instance.type, { types, paths, apiVersion });
+        const name = instance.name || found.definition.type;
+        checkName(name);
+        return { ...found, name, options: instance.options || {} };
+    });
+    checkUnique(resolved);
+    checkVariables(resolved);
+    const loaded = [];
+    for (const { definition, name, options, package: pkg, version } of resolved) {
+        const engine = await createEngine(definition, { name, options, env, config });
+        loaded.push({ engine, type: definition.type, ...(pkg && { package: pkg }), ...(version && { version }) });
+    }
+    return loaded;
+}
+
+module.exports = { enginePaths, packageCandidates, resolveType, createEngine, loadEngines };

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@formio/uag-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.0-rc.1",
+  "description": "Build engine packages for the Form.io Universal Agent Gateway (UAG): the engine contract, defineEngine, settings and instance resolution, the engine loader, and a conformance check.",
+  "keywords": [
+    "formio",
+    "uag",
+    "universal-agent-gateway",
+    "ai",
+    "agents",
+    "engine",
+    "sdk"
+  ],
+  "license": "MIT",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./loader": {
+      "types": "./loader.d.ts",
+      "default": "./loader.js"
+    },
+    "./conformance": {
+      "types": "./conformance.d.ts",
+      "default": "./conformance.js"
+    },
+    "./protocol": {
+      "types": "./protocol.d.ts",
+      "default": "./protocol.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "*.js",
+    "*.d.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "mocha"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/formio/uag.git",
+    "directory": "packages/engine-sdk"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "chai": "^6.3.0",
+    "mocha": "^12.0.3"
+  }
+}

package/protocol.d.ts

@@ -0,0 +1,45 @@
+import type { DecisionQuestion, DecisionResponse, DecisionState, ExtractResponse, FieldSpec, ToolDefinition } from './contract';
+
+/** The remote engine protocol version this SDK speaks. */
+export declare const PROTOCOL_VERSION: 1;
+
+/** The header that carries a scoped token, on research extracts only. */
+export declare const SCOPED_TOKEN_HEADER: 'x-uag-scoped-token';
+
+/** The optional header that carries the Agent API request id, on decide and extract. */
+export declare const REQUEST_ID_HEADER: 'x-request-id';
+
+/** A request id that is safe to send and log (up to 128 of `[A-Za-z0-9._:-]`), or undefined. */
+export declare function safeRequestId(value: unknown): string | undefined;
+
+/** A message in another protocol version, or of the wrong shape. */
+export declare class ProtocolError extends Error {
+    status: number;
+    constructor(message: string, status?: number);
+}
+
+/** One engine an engine server hosts, as `GET /v1/engines` describes it. */
+export type RemoteEngineDescription = {
+    name: string;
+    kind: 'decision' | 'agent';
+    model: string;
+    maxOptions?: number;
+    toolUse?: boolean;
+};
+
+export type RemoteExtractRequest = {
+    instructions: string;
+    state: DecisionState;
+    fields: FieldSpec[];
+    schema: Record<string, any>;
+    tools?: ToolDefinition[];
+    maxIterations?: number;
+};
+
+export declare function checkVersion(body: unknown, side?: 'request' | 'response'): void;
+export declare function checkDecideRequest(body: unknown): { state: DecisionState; questions: Record<string, DecisionQuestion> };
+export declare function checkExtractRequest(body: unknown): RemoteExtractRequest;
+export declare function checkDescription(body: unknown): RemoteEngineDescription[];
+export declare function checkDecisionResponse(body: unknown): DecisionResponse;
+export declare function checkExtractResponse(body: unknown): ExtractResponse;
+export declare function errorBody(message: string, expose?: boolean): { protocol: 1; error: string; expose: boolean };

package/protocol.js

@@ -0,0 +1,189 @@
+'use strict';
+const { ENGINE_NAME } = require('./define');
+
+/**
+ * The remote engine protocol, version 1: JSON over HTTP between the UAG's
+ * `remote` engine type and an engine server.
+ *
+ *   GET  /v1/engines                 -> { protocol, engines: [{ name, kind, model, maxOptions?, toolUse? }] }
+ *   POST /v1/engines/:name/decide    { protocol, state, questions }  -> { protocol, model, answers, usage? }
+ *   POST /v1/engines/:name/extract   { protocol, instructions, state, fields, schema, tools?, maxIterations? }
+ *                                    -> { protocol, model, values, toolCalls?, usage? }
+ *   Authorization: Bearer <engine server key>
+ *   X-UAG-Scoped-Token: <scoped token>        research extracts only
+ *   X-Request-Id: <request id>                optional, on decide and extract
+ *   errors: { protocol, error, expose }       with a 4xx or 5xx status
+ *
+ * The version is in both the path and the body: the path routes future
+ * versions side by side, and the body catches a proxy that mixes them up.
+ *
+ * The request id is the Agent API request's, and the engine server sends it on
+ * with research's calls to the UAG's `/mcp`, so logs can group every leg of a
+ * run. Neither side sends or logs one that is not a short token (`safeRequestId`).
+ */
+const PROTOCOL_VERSION = 1;
+const SCOPED_TOKEN_HEADER = 'x-uag-scoped-token';
+const REQUEST_ID_HEADER = 'x-request-id';
+const REQUEST_ID = /^[A-Za-z0-9._:-]{1,128}$/;
+
+/** A request id that is safe to send and log: up to 128 letters, digits, `.`, `_`, `:` or `-`. Anything else is undefined. */
+function safeRequestId(value) {
+    return typeof value === 'string' && REQUEST_ID.test(value) ? value : undefined;
+}
+
+/** A message that breaks the protocol: the wrong version, or the wrong shape. */
+class ProtocolError extends Error {
+    constructor(message, status = 400) {
+        super(message);
+        this.name = 'ProtocolError';
+        this.status = status;
+    }
+}
+
+const isObject = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+
+function check(condition, message, status) {
+    if (!condition) throw new ProtocolError(message, status);
+}
+
+/** Refuse a message in another protocol version, naming both versions. */
+function checkVersion(body, side = 'request') {
+    check(isObject(body), `The ${side} is not a JSON object.`);
+    const version = body.protocol;
+    if (version !== PROTOCOL_VERSION) {
+        throw new ProtocolError(
+            `This side speaks remote engine protocol ${PROTOCOL_VERSION}; the ${side} used ${version === undefined ? 'no version' : `protocol ${JSON.stringify(version)}`}.`,
+            400
+        );
+    }
+}
+
+function checkState(state) {
+    check(isObject(state) && isObject(state.input) && typeof state.today === 'string', '"state" must be an object with "input" and "today".');
+}
+
+/** A decide request, as an engine server receives it. */
+function checkDecideRequest(body) {
+    checkVersion(body);
+    checkState(body.state);
+    check(isObject(body.questions), '"questions" must be an object.');
+    for (const [id, question] of Object.entries(body.questions)) {
+        check(isObject(question) && ['choice', 'score', 'noul'].includes(question.type) && typeof question.instructions === 'string',
+            `The question "${id}" is not a choice, score or noul question.`);
+    }
+    return { state: body.state, questions: body.questions };
+}
+
+/** An extract request, as an engine server receives it. */
+function checkExtractRequest(body) {
+    checkVersion(body);
+    checkState(body.state);
+    check(typeof body.instructions === 'string', '"instructions" must be a string.');
+    check(Array.isArray(body.fields) && body.fields.every((field) => isObject(field) && typeof field.path === 'string'), '"fields" must be a list of fields with paths.');
+    check(isObject(body.schema), '"schema" must be an object.');
+    const request = { instructions: body.instructions, state: body.state, fields: body.fields, schema: body.schema };
+    if (body.tools !== undefined) {
+        check(Array.isArray(body.tools) && body.tools.every((tool) => isObject(tool) && typeof tool.name === 'string' && typeof tool.description === 'string' && isObject(tool.inputSchema)),
+            '"tools" must be a list of tool definitions.');
+        check(Number.isInteger(body.maxIterations) && body.maxIterations > 0, '"maxIterations" must be a positive whole number with "tools".');
+        Object.assign(request, { tools: body.tools, maxIterations: body.maxIterations });
+    }
+    return request;
+}
+
+/** A describe response, as the UAG receives it. */
+function checkDescription(body) {
+    checkVersion(body, 'response');
+    check(Array.isArray(body.engines), '"engines" must be a list.');
+    return body.engines.map((engine) => {
+        check(isObject(engine) && typeof engine.name === 'string' && ENGINE_NAME.test(engine.name), 'Each engine needs a valid name.');
+        check(['decision', 'agent'].includes(engine.kind), `The engine "${engine.name}" must be a decision or an agent engine.`);
+        check(typeof engine.model === 'string' && engine.model, `The engine "${engine.name}" does not name its model.`);
+        if (engine.kind === 'decision') {
+            check(Number.isInteger(engine.maxOptions) && engine.maxOptions >= 2, `The decision engine "${engine.name}" needs maxOptions.`);
+        }
+        return {
+            name: engine.name,
+            kind: engine.kind,
+            model: engine.model,
+            ...(engine.kind === 'decision' && { maxOptions: engine.maxOptions }),
+            ...(engine.kind === 'agent' && { toolUse: engine.toolUse === true }),
+        };
+    });
+}
+
+/** A token count: a whole number, or null when not reported. */
+function tokenCount(value, key) {
+    if (value === undefined || value === null) return null;
+    check(Number.isInteger(value) && value >= 0, `"usage.${key}" must be a whole number or null.`);
+    return value;
+}
+
+function checkUsage(usage) {
+    if (usage === undefined) return undefined;
+    check(isObject(usage), '"usage" must be an object.');
+    return { inputTokens: tokenCount(usage.inputTokens, 'inputTokens'), outputTokens: tokenCount(usage.outputTokens, 'outputTokens') };
+}
+
+const isProbability = (value) => typeof value === 'number' && value >= 0 && value <= 1;
+
+/** One answer's shape (which options and levels were asked is the UAG's to check). */
+function checkAnswer(id, answer) {
+    const where = `The answer to "${id}"`;
+    check(isObject(answer) && ['choice', 'score', 'noul'].includes(answer.type), `${where} must be a choice, score or noul answer.`);
+    if (answer.type === 'noul') {
+        check(isProbability(answer.probability), `${where} needs a probability from 0 to 1.`);
+        return;
+    }
+    check(isObject(answer.probabilities) && Object.values(answer.probabilities).every(isProbability), `${where} needs probabilities from 0 to 1.`);
+    check(isProbability(answer.confidence), `${where} needs a confidence from 0 to 1.`);
+    if (answer.type === 'choice') check(typeof answer.choice === 'string', `${where} needs its choice.`);
+    else check(Number.isFinite(answer.score), `${where} needs its score.`);
+}
+
+/** A decide response, as the UAG receives it. */
+function checkDecisionResponse(body) {
+    checkVersion(body, 'response');
+    check(typeof body.model === 'string', 'The response does not name its model.');
+    check(isObject(body.answers), '"answers" must be an object.');
+    for (const [id, answer] of Object.entries(body.answers)) checkAnswer(id, answer);
+    const usage = checkUsage(body.usage);
+    return { model: body.model, answers: body.answers, ...(usage && { usage }) };
+}
+
+/** An extract response, as the UAG receives it. */
+function checkExtractResponse(body) {
+    checkVersion(body, 'response');
+    check(typeof body.model === 'string', 'The response does not name its model.');
+    check(isObject(body.values), '"values" must be an object.');
+    if (body.toolCalls !== undefined) {
+        check(Array.isArray(body.toolCalls) && body.toolCalls.every((call) => isObject(call) && typeof call.name === 'string'), '"toolCalls" must be a list of calls.');
+    }
+    const usage = checkUsage(body.usage);
+    return {
+        model: body.model,
+        values: body.values,
+        ...(body.toolCalls && { toolCalls: body.toolCalls.map((call) => ({ name: call.name, isError: call.isError === true })) }),
+        ...(usage && { usage }),
+    };
+}
+
+/** An error response body. `expose` says whether the message may be shown to API callers. */
+function errorBody(message, expose = false) {
+    return { protocol: PROTOCOL_VERSION, error: String(message), expose: expose === true };
+}
+
+module.exports = {
+    PROTOCOL_VERSION,
+    SCOPED_TOKEN_HEADER,
+    REQUEST_ID_HEADER,
+    safeRequestId,
+    ProtocolError,
+    checkVersion,
+    checkDecideRequest,
+    checkExtractRequest,
+    checkDescription,
+    checkDecisionResponse,
+    checkExtractResponse,
+    errorBody,
+};

package/settings.js

@@ -0,0 +1,99 @@
+'use strict';
+const { EngineConfigError } = require('./errors');
+
+/** `apiKey` → `API_KEY`, `baseURL` → `BASE_URL`, `fast-lane` → `FAST_LANE`. */
+function upperSnake(name) {
+    return String(name)
+        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .replace(/([A-Z])([A-Z][a-z])/g, '$1_$2')
+        .replace(/-/g, '_')
+        .toUpperCase();
+}
+
+/** The instance's own variable for a setting: `UAG_ENGINE_<NAME>_<SETTING>`. */
+function settingVariable(instance, setting) {
+    return `UAG_ENGINE_${upperSnake(instance)}_${upperSnake(setting)}`;
+}
+
+/**
+ * The variables that set a setting, in the order they are read. `env` may be one
+ * name or a list: definitions not made with `defineEngine` are not normalised.
+ */
+function settingVariables(instance, setting, spec) {
+    return [settingVariable(instance, setting), ...[].concat(spec.env || [])];
+}
+
+function given(value) {
+    return value !== undefined && value !== null && value !== '';
+}
+
+function listNames(names) {
+    return names.length > 1 ? `${names.slice(0, -1).join(', ')} or ${names[names.length - 1]}` : names[0];
+}
+
+/** Coerce a value read from the environment (always a string) to the setting's type. */
+function coerce(value, spec, describe) {
+    const type = spec.type || 'string';
+    if (type === 'number') {
+        const number = typeof value === 'number' ? value : Number(String(value).trim());
+        if (String(value).trim() === '' || !Number.isFinite(number)) {
+            throw new EngineConfigError(`${describe()} must be a number${spec.secret ? '' : `, not ${JSON.stringify(value)}`}.`);
+        }
+        return number;
+    }
+    if (type === 'boolean') {
+        if (typeof value === 'boolean') return value;
+        const text = String(value).trim().toLowerCase();
+        if (['true', '1', 'yes'].includes(text)) return true;
+        if (['false', '0', 'no'].includes(text)) return false;
+        throw new EngineConfigError(`${describe()} must be true or false${spec.secret ? '' : `, not ${JSON.stringify(value)}`}.`);
+    }
+    return typeof value === 'string' ? value : String(value);
+}
+
+/**
+ * An instance's value for each setting its type declares, from the first of:
+ * the instance's options, `UAG_ENGINE_<NAME>_<SETTING>`, the type's own
+ * variables, and the default. A required setting with no value is an error
+ * naming the instance, the type, the setting and every variable that sets it.
+ */
+function resolveSettings(definition, name, options = {}, env = process.env) {
+    const settings = {};
+    for (const [key, spec] of Object.entries(definition.settings || {})) {
+        const describe = () => `The "${name}" engine's ${key} setting`;
+        let value = options[key];
+        if (!given(value)) {
+            const variable = settingVariables(name, key, spec).find((candidate) => given(env[candidate]));
+            value = variable ? env[variable] : spec.default;
+        }
+        if (!given(value)) {
+            if (spec.required) {
+                throw missingSetting(definition, name, key);
+            }
+            continue;
+        }
+        settings[key] = coerce(value, spec, describe);
+    }
+    return settings;
+}
+
+/** The error for a required setting with no value. */
+function missingSetting(definition, name, key) {
+    const spec = (definition.settings || {})[key] || {};
+    return new EngineConfigError(
+        `The "${name}" engine (type "${definition.type}") needs its ${key} setting: set ${listNames(settingVariables(name, key, spec))}.`
+    );
+}
+
+/** The resolved values of the settings a type marks secret. */
+function secretValues(definition, settings, options = {}) {
+    const secrets = [];
+    for (const [key, spec] of Object.entries(definition.settings || {})) {
+        if (!spec.secret) continue;
+        if (given(settings[key])) secrets.push(settings[key]);
+        if (given(options[key])) secrets.push(options[key]);
+    }
+    return secrets;
+}
+
+module.exports = { upperSnake, settingVariable, settingVariables, resolveSettings, missingSetting, secretValues };