@formio/uag-sdk 2.0.0-rc.8 → 2.0.0-rc.9

package/loader.d.ts

@@ -53,3 +53,15 @@ export declare function createEngine(definition: EngineTypeDefinition, options:
 
 /** Resolve, configure and create each instance. Any problem stops loading, with the instance named. */
 export declare function loadEngines(instances: EngineInstanceSpec[], options?: LoadOptions): Promise<LoadedEngine[]>;
+
+/** One instance planned but not created: what creating it takes, and how a failure to start reads. */
+export type PlannedEngine = Omit<LoadedEngine, 'engine'> & {
+    name: string;
+    kinds: ('decision' | 'agent')[];
+    definition: EngineTypeDefinition;
+    args: { name: string; settings: Record<string, any>; options: Record<string, any>; config: Record<string, any>; requireSetting(key: string): any };
+    failure(err: unknown): string;
+};
+
+/** Resolve and configure each instance without creating it, for a host that creates engines elsewhere. */
+export declare function planEngines(instances: EngineInstanceSpec[], options?: LoadOptions): PlannedEngine[];

package/loader.js

@@ -223,4 +223,50 @@ async function loadEngines(instances, { types = {}, paths = [], env = process.en
     return loaded;
 }
 
-module.exports = { enginePaths, packageCandidates, resolveType, createEngine, loadEngines };
+/**
+ * Plan the given instances without creating them: resolve each type and its
+ * settings, and describe how each is created and how a failure to start reads
+ * (with secrets left out). For a host that has engines created elsewhere, such
+ * as Agentic Formflow's `startEngines`, which creates and wraps them.
+ */
+function planEngines(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.name;
+        checkName(name);
+        return { ...found, name, options: instance.options || {} };
+    });
+    checkUnique(resolved);
+    checkVariables(resolved);
+    return resolved.map(({ definition, name, options, package: pkg, version }) => {
+        const label = `The "${name}" engine (type "${definition.name}")`;
+        const settings = resolveSettings(definition, name, options, env);
+        const secrets = secretValues(definition, settings, options);
+        return {
+            name,
+            type: definition.name,
+            title: definition.title,
+            kinds: [...definition.kinds],
+            ...(definition.version && { typeVersion: definition.version }),
+            ...(pkg && { package: pkg }),
+            ...(version && { version }),
+            definition,
+            args: {
+                name,
+                settings,
+                options,
+                config,
+                requireSetting: (key) => {
+                    if (settings[key] === undefined) throw missingSetting(definition, name, key);
+                    return settings[key];
+                },
+            },
+            failure: (err) => {
+                const message = redact(errorText(err), secrets);
+                return err instanceof EngineConfigError || (err && err.name === 'EngineConfigError') ? message : `${label} failed to start: ${message}`;
+            },
+        };
+    });
+}
+
+module.exports = { enginePaths, packageCandidates, resolveType, createEngine, loadEngines, planEngines };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formio/uag-sdk",
-  "version": "2.0.0-rc.8",
+  "version": "2.0.0-rc.9",
   "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",