@formio/uag 2.0.0-rc.7 → 2.0.0-rc.8

package/README.md

@@ -243,7 +243,7 @@ Engines run inside the UAG, or on an [engine server](./packages/engine-server) (
 | You run | You need |
 |---|---|
 | MCP and conversation forms (including a form's chat, `{form}/agent/chat`), on Form.io Open Source or a hosted project | Nothing |
-| MCP and conversation forms, on a self-hosted Form.io Enterprise project | A Form.io license in `LICENSE_KEY` (development hostnames such as `localhost` excepted) |
+| MCP and conversation forms, on a self-hosted Form.io Enterprise project | A Form.io license that includes the UAG, in `LICENSE_KEY` (development hostnames such as `localhost` excepted) |
 | Agentic workflows and Agentic Formflow (the Agent API's `extract`, `decide` and `generate`, the **Agent: Run task** action, the `agent_decide` and `agent_provide` tools, `uag-eval`) on a self-hosted project, Open Source or Enterprise | A Form.io license that includes the UAG, in `LICENSE_KEY` |
 | The same on a project on Form.io's hosted service (`https://*.form.io`) | Nothing, as the project runs under Form.io's license; except `uag-eval`, which runs offline and needs `LICENSE_KEY` |
 | The UAG's own database (`MONGO`), and with it remote MCP sign-in (`MCP_OAUTH`), on any project | A Form.io license that includes the UAG, unless the project and the database are both on development hosts (`localhost`, `*.localhost`, `lvh.me`, `*.local`) |
@@ -253,7 +253,8 @@ A hosted project needs a license after all when the UAG weakens the proof that i
 
 ## Extending the UAG
 
-- **Modules** add MCP tools, override the built-in tools and their response templates, add form actions (the UAG runs a module's own actions; Form.io runs its own), and ship a project template of forms and resources that the UAG installs. Mount one over `/app/module` in the container, or name it in `UAG_MODULE` for the `uag` command. See [Modules](https://ai.form.io/developers/modules), [`module/Readme.md`](./module/Readme.md) and the [Claude Desktop example](./demo/samples/custom-module).
+- **Modules** add MCP tools, override the built-in tools and their response templates, add form actions (the UAG runs a module's own actions; Form.io runs its own), and ship a project template of forms and resources that the UAG installs. A module can also add routes on every form, formio.js components (served in the UAG's `/uag-js/uag.use.js`), plugins, and settings of its own. Mount one over `/app/module` in the container, or name it in `UAG_MODULE` for the `uag` command. See [Modules](https://ai.form.io/developers/modules), [`module/Readme.md`](./module/Readme.md) and the [Claude Desktop example](./demo/samples/custom-module).
+- **Plugins** add capabilities of a known type, such as converters that read more file types and the document processes an AI Document runs. List them in a module, or in a plugins file: the one `UAG_PLUGINS` names, or in the image, one per folder under `/app/plugins`, where add-ons such as `formio/uag-documents` put theirs. Plugins and modules are trusted code: they run in the UAG process. See [Plugins](https://ai.form.io/developers/plugins) and [AI Document](https://ai.form.io/developers/ai-document).
 - **Node.js.** Embed the UAG in an Express application, or run it with `npx uag`:
 
 ```js
@@ -319,10 +320,11 @@ The full table, with the Agent API's errors: [Troubleshooting](https://ai.form.i
 | Package | Version | Works with UAG | What it is |
 |---|---|---|---|
 | [`@formio/uag`](https://www.npmjs.com/package/@formio/uag), image [`formio/uag`](https://hub.docker.com/r/formio/uag) | 2.x | — | The UAG. The image includes every official engine. |
-| `@formio/uag-jev`, `-claude`, `-openai`, `-grok`, `-gemini` | 2.x | ≥ 2.0.0 | The [engines](./engines), versioned independently of the UAG. |
+| `@formio/uag-jev`, `-claude`, `-openai`, `-grok`, `-gemini` | 2.x | ≥ 2.0.0 | The [engines](./engines), released with the UAG at the same version. |
 | [`@formio/uag-sdk`](./packages/engine-sdk) | 2.x | ≥ 2.0.0 | Engine contract version 1, remote engine protocol version 1. |
 | [`@formio/uag-engines`](./packages/engine-server), image `formio/uag-engines` | 2.x | ≥ 2.0.0 | The engine server. |
-| [`@formio/uag-js`](./packages/uag-js) | 2.x | ≥ 2.0.0 | The formio.js module: saves `uag` forms through the UAG, adds Agent Input, and renders forms as a chat. Runs in the browser. |
+| [`@formio/uag-js`](./packages/uag-js) | 2.x | ≥ 2.0.0 | The formio.js module: saves `uag` forms through the UAG, adds Agent Input, and renders forms as a chat. Runs in the browser; the UAG also serves it at `/uag-js/`. |
+| [`@formio/uag-extras`](https://github.com/formio/uag-extras), image `formio/uag-documents` | 1.x | ≥ 2.0.0-rc.7 | Versioned on its own: the AI Document module, document plugins and converters (`npm install @formio/uag-extras@^1`). The image is an add-on that runs beside `formio/uag` and fills its plugins folder (`formio/uag-documents:1`): see [AI Document](https://ai.form.io/developers/ai-document#run-it-with-docker). |
 | `@formio/uag-claude` | 1.3.x | 1.12.0 – 1.13.x | The retired Claude integration (against 2.0, only its direct commands). Security fixes only; see [MIGRATING-2.0.md](./MIGRATING-2.0.md). |
 
 `@formio/uag-claude` 2.x is the Claude *engine*, not the 1.x integration; pin `@formio/uag-claude@^1` if you still install the integration. Upgrading from 1.x: [MIGRATING-2.0.md](./MIGRATING-2.0.md).
@@ -335,6 +337,6 @@ The developer documentation is published at [ai.form.io/developers](https://ai.f
 |---|---|---|
 | **Start here** | [How the UAG works](https://ai.form.io/developers) · [Agentic Coding Plugin](https://ai.form.io/developers/agentic-coding) · [Quickstart](https://ai.form.io/developers/quickstart) | [Demo site](./demo/README.md) |
 | **Concepts** | [Concepts](https://ai.form.io/developers/concepts) · [Form properties](https://ai.form.io/developers/form-properties) | |
-| **Build** | [MCP tools](https://ai.form.io/developers/mcp-tools) · [Agent API](https://ai.form.io/developers/agent-api) · [Workflows](https://ai.form.io/developers/workflows) · [JavaScript (formio.js)](https://ai.form.io/developers/renderer) · [Chat widget](https://ai.form.io/developers/chat) · [Connect Claude](https://ai.form.io/developers/connect-claude) | [`@formio/uag-js`](./packages/uag-js/README.md) · [Claude Desktop module](./demo/samples/custom-module/Readme.md) |
-| **Extend** | [Node.js API](https://ai.form.io/developers/node-api) · [Modules](https://ai.form.io/developers/modules) · [Engines](https://ai.form.io/developers/engines) · [Engine SDK](https://ai.form.io/developers/engine-sdk) · [Engine server](https://ai.form.io/developers/engine-server) | [Modules](./module/Readme.md) · [Response templates](./demo/samples/custom-module/module/templates/Readme.md) · [Engines](./engines) · [Engine SDK](./packages/engine-sdk/README.md) · [Engine server](./packages/engine-server/README.md) · [Engine setups](./demo/samples/engines/Readme.md) |
+| **Build** | [MCP tools](https://ai.form.io/developers/mcp-tools) · [Agent API](https://ai.form.io/developers/agent-api) · [Workflows](https://ai.form.io/developers/workflows) · [JavaScript (formio.js)](https://ai.form.io/developers/renderer) · [Chat widget](https://ai.form.io/developers/chat) · [AI Document](https://ai.form.io/developers/ai-document) · [Connect Claude](https://ai.form.io/developers/connect-claude) | [`@formio/uag-js`](./packages/uag-js/README.md) · [Claude Desktop module](./demo/samples/custom-module/Readme.md) |
+| **Extend** | [Node.js API](https://ai.form.io/developers/node-api) · [Modules](https://ai.form.io/developers/modules) · [Plugins](https://ai.form.io/developers/plugins) · [Engines](https://ai.form.io/developers/engines) · [Engine SDK](https://ai.form.io/developers/engine-sdk) · [Engine server](https://ai.form.io/developers/engine-server) | [Modules](./module/Readme.md) · [Response templates](./demo/samples/custom-module/module/templates/Readme.md) · [Engines](./engines) · [Engine SDK](./packages/engine-sdk/README.md) · [Engine server](./packages/engine-server/README.md) · [Engine setups](./demo/samples/engines/Readme.md) |
 | **Operate** | [Security](https://ai.form.io/developers/security) · [Deployment](https://ai.form.io/developers/deployment) · [Evaluation](https://ai.form.io/developers/evaluation) · [Troubleshooting](https://ai.form.io/developers/troubleshooting) | [Docker Hub](./DOCKERHUB.md) · [Migrating to 2.0](./MIGRATING-2.0.md) · [Security policy](./SECURITY.md) · [End-to-end tests](./test/e2e/Readme.md) |

package/bin/uag.js

@@ -12,7 +12,7 @@
  * Engines are found among the installed packages, so a custom image holds only
  * the engines it installs:
  *
- *   npm install @formio/uag @formio/uag-claude
+ *   npm install @formio/uag@rc @formio/uag-claude@rc
  *   UAG_ENGINES=claude CLAUDE_API_KEY=... npx uag
  */
 // Before anything else, so a module that reads the environment sees .env too.
@@ -42,7 +42,8 @@ async function start(uagModule) {
     // A module may be exported as a promise (an async module).
     const resolved = await uagModule;
     if (resolved) server.use(resolved);
-    // Then the plugins file: UAG_PLUGINS, or the image's /app/plugins/index.mjs.
+    // Then the plugins files: UAG_PLUGINS, or the image's /app/plugins (its
+    // index.mjs, or each add-on's folder under it).
     await usePluginFiles(server);
     const app = Express();
     // Behind a reverse proxy, its forwarded headers give the public URL (TRUST_PROXY).
@@ -52,11 +53,49 @@ async function start(uagModule) {
     // names; a misconfigured engine stops startup with its name in the error.
     app.use(await server.router());
     const port = process.env.PORT || 3200;
-    await new Promise((resolve) => app.listen(port, resolve));
+    const listener = await new Promise((resolve) => {
+        const started = app.listen(port, () => resolve(started));
+    });
+    stopOnSignals(server, listener);
     console.log(`Form.io UAG server running on port ${port}`);
     console.log(`Visit http://localhost:${port} to access the application`);
 }
 
+/**
+ * On SIGTERM or SIGINT, stop taking connections and destroy the server, which
+ * calls each module's `close` and each plugin's, then exit. A shutdown that
+ * takes longer than `timeoutMs` exits with 1.
+ */
+function stopOnSignals(server, listener, { signals = ['SIGTERM', 'SIGINT'], exit = (code) => process.exit(code), on = process, timeoutMs = 10000 } = {}) {
+    let stopping = false;
+    const stop = async (signal) => {
+        if (stopping) return;
+        stopping = true;
+        console.log(`Received ${signal}: stopping the UAG.`);
+        const timer = setTimeout(() => {
+            console.error(`The UAG did not stop within ${timeoutMs} ms.`);
+            exit(1);
+        }, timeoutMs);
+        if (timer.unref) timer.unref();
+        if (listener) listener.close();
+        let code = 0;
+        try {
+            await server.destroy();
+        }
+        catch (error) {
+            console.error('Failed to stop the UAG cleanly:', error);
+            code = 1;
+        }
+        clearTimeout(timer);
+        exit(code);
+    };
+    // Not once: a repeated signal (a terminal's Ctrl-C reaches the restarted
+    // process twice, from the terminal and from its parent) must not fall back
+    // to Node's default handler and end the shutdown early.
+    for (const signal of signals) on.on(signal, () => stop(signal));
+    return stop;
+}
+
 function fail(error) {
     console.error('Failed to start server:', error);
     process.exit(1);
@@ -74,4 +113,4 @@ if (require.main === module) {
     }
 }
 
-module.exports = { start, fail };
+module.exports = { start, fail, stopOnSignals };

package/lib/documents/converters.d.ts

@@ -12,7 +12,9 @@ export declare const textConverter: Converter;
  * decoded). A PNG is decoded whole, in memory and synchronously, so its pixel
  * count is checked from its header first: a small, highly compressed file can
  * describe an image far larger than its size suggests. JPEGs are embedded
- * without being decoded. A converter setting, `maxPixels`, changes it.
+ * without being decoded. The converter's `maxPixels` setting changes it
+ * (config.plugins.settings.converter['image-pdf'].maxPixels, or
+ * DOCUMENTS_MAX_IMAGE_PIXELS).
  */
 export declare const MAX_IMAGE_PIXELS = 50000000;
 /** A PNG's width and height, from its IHDR header; undefined when it has none. */

package/lib/documents/converters.js

@@ -91,7 +91,9 @@ const PAGE = { width: 595.28, height: 841.89, margin: 36 };
  * decoded). A PNG is decoded whole, in memory and synchronously, so its pixel
  * count is checked from its header first: a small, highly compressed file can
  * describe an image far larger than its size suggests. JPEGs are embedded
- * without being decoded. A converter setting, `maxPixels`, changes it.
+ * without being decoded. The converter's `maxPixels` setting changes it
+ * (config.plugins.settings.converter['image-pdf'].maxPixels, or
+ * DOCUMENTS_MAX_IMAGE_PIXELS).
  */
 exports.MAX_IMAGE_PIXELS = 50000000;
 /** A PNG's width and height, from its IHDR header; undefined when it has none. */
@@ -110,6 +112,14 @@ exports.imagePdfConverter = {
     apiVersion: 1,
     accepts: [{ type: mime_1.MIME.png, ext: ['.png'] }, { type: mime_1.MIME.jpeg, ext: ['.jpg', '.jpeg'] }],
     produces: ['pdf'],
+    settings: {
+        maxPixels: {
+            type: 'number',
+            env: 'DOCUMENTS_MAX_IMAGE_PIXELS',
+            default: exports.MAX_IMAGE_PIXELS,
+            description: 'The largest PNG, in pixels (width × height), converted; a larger one is refused before it is decoded.'
+        }
+    },
     async convert(input, options) {
         options.signal.throwIfAborted();
         if (input.type === mime_1.MIME.png) {

package/lib/index.d.ts

@@ -108,7 +108,7 @@ export * from './tools';
 export * from './documents';
 export * from './modules';
 export { sanitizeMarkdown } from './markdown';
-export { usePluginFiles, pluginsFile, DEFAULT_PLUGINS_FILE } from './pluginFiles';
+export { usePluginFiles, pluginFiles, pluginFilesIn, DEFAULT_PLUGINS_DIR } from './pluginFiles';
 export * from './router';
 export * from './template';
 export { sanitizeRichText, isRichText, RICH_TEXT_TAGS, RICH_TEXT_RULE } from './richText';

package/lib/index.js

@@ -17,7 +17,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UAGFormInterface = exports.UAGProjectInterface = exports.RICH_TEXT_RULE = exports.RICH_TEXT_TAGS = exports.isRichText = exports.sanitizeRichText = exports.DEFAULT_PLUGINS_FILE = exports.pluginsFile = exports.usePluginFiles = exports.sanitizeMarkdown = exports.UAGServer = void 0;
+exports.UAGFormInterface = exports.UAGProjectInterface = exports.RICH_TEXT_RULE = exports.RICH_TEXT_TAGS = exports.isRichText = exports.sanitizeRichText = exports.DEFAULT_PLUGINS_DIR = exports.pluginFilesIn = exports.pluginFiles = exports.usePluginFiles = exports.sanitizeMarkdown = exports.UAGServer = void 0;
 exports.assertSingleCore = assertSingleCore;
 exports.assertNodeSnapshotDisabled = assertNodeSnapshotDisabled;
 const appserver_1 = require("@formio/appserver");
@@ -424,8 +424,9 @@ var markdown_1 = require("./markdown");
 Object.defineProperty(exports, "sanitizeMarkdown", { enumerable: true, get: function () { return markdown_1.sanitizeMarkdown; } });
 var pluginFiles_1 = require("./pluginFiles");
 Object.defineProperty(exports, "usePluginFiles", { enumerable: true, get: function () { return pluginFiles_1.usePluginFiles; } });
-Object.defineProperty(exports, "pluginsFile", { enumerable: true, get: function () { return pluginFiles_1.pluginsFile; } });
-Object.defineProperty(exports, "DEFAULT_PLUGINS_FILE", { enumerable: true, get: function () { return pluginFiles_1.DEFAULT_PLUGINS_FILE; } });
+Object.defineProperty(exports, "pluginFiles", { enumerable: true, get: function () { return pluginFiles_1.pluginFiles; } });
+Object.defineProperty(exports, "pluginFilesIn", { enumerable: true, get: function () { return pluginFiles_1.pluginFilesIn; } });
+Object.defineProperty(exports, "DEFAULT_PLUGINS_DIR", { enumerable: true, get: function () { return pluginFiles_1.DEFAULT_PLUGINS_DIR; } });
 __exportStar(require("./router"), exports);
 __exportStar(require("./template"), exports);
 var richText_1 = require("./richText");

package/lib/pluginFiles.d.ts

@@ -1,16 +1,28 @@
 import type { UAGServer } from './index';
-/** Where the curated image keeps its plugins file. */
-export declare const DEFAULT_PLUGINS_FILE = "/app/plugins/index.mjs";
+/** The image's plugins folder: add-ons are mounted in folders under it. */
+export declare const DEFAULT_PLUGINS_DIR = "/app/plugins";
 /**
- * The plugins file to load: UAG_PLUGINS (a path, or "off"), or else the
- * image's default when it exists. Undefined when there is none.
+ * The plugins files a path holds, in load order:
+ * - a file: that file;
+ * - a folder with an `index.mjs`: that file alone (one plugins folder);
+ * - any other folder: the `index.mjs` of each folder directly in it, in
+ *   name order (one per add-on), skipping folders whose name starts with
+ *   "." and `node_modules`.
  */
-export declare function pluginsFile(env?: Record<string, string | undefined>, defaultFile?: string): string | undefined;
+export declare function pluginFilesIn(target: string): string[];
 /**
- * Load the plugins file, if any, and use it, named by its path in error
- * messages. Its default export is a plugin or a list of plugins; or a module
- * (an extra, with its plugins), or a list mixing modules and
- * plugins, each module used in turn. Plugins are trusted code: they run in
- * the UAG process.
+ * The plugins files to load: those UAG_PLUGINS names (a file, a folder, or
+ * "off"), or else those in the image's plugins folder when it exists.
  */
-export declare function usePluginFiles(server: Pick<UAGServer, 'use'>, env?: Record<string, string | undefined>, defaultFile?: string): Promise<string | undefined>;
+export declare function pluginFiles(env?: Record<string, string | undefined>, defaultDir?: string): string[];
+/**
+ * Load the plugins files, if any, and use each in turn, named by its path in
+ * error messages. A file's default export is a plugin or a list of plugins;
+ * or a module (an extra, with its plugins), or a list mixing modules and
+ * plugins, each module used in turn. Several files merge as several modules
+ * do: a module used again by name is used once, and two files that register
+ * the same plugin, plugin type, route or component stop startup, naming both.
+ * Plugins are trusted code: they run in the UAG process. Returns the files
+ * loaded.
+ */
+export declare function usePluginFiles(server: Pick<UAGServer, 'use'>, env?: Record<string, string | undefined>, defaultDir?: string): Promise<string[]>;

package/lib/pluginFiles.js

@@ -3,26 +3,59 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_PLUGINS_FILE = void 0;
-exports.pluginsFile = pluginsFile;
+exports.DEFAULT_PLUGINS_DIR = void 0;
+exports.pluginFilesIn = pluginFilesIn;
+exports.pluginFiles = pluginFiles;
 exports.usePluginFiles = usePluginFiles;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const url_1 = require("url");
 const appserver_1 = require("@formio/appserver");
-/** Where the curated image keeps its plugins file. */
-exports.DEFAULT_PLUGINS_FILE = '/app/plugins/index.mjs';
+/** The image's plugins folder: add-ons are mounted in folders under it. */
+exports.DEFAULT_PLUGINS_DIR = '/app/plugins';
+/** The file that makes a folder one plugins folder. */
+const INDEX = 'index.mjs';
+const isDirectory = (target) => {
+    try {
+        return fs_1.default.statSync(target).isDirectory();
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * The plugins files a path holds, in load order:
+ * - a file: that file;
+ * - a folder with an `index.mjs`: that file alone (one plugins folder);
+ * - any other folder: the `index.mjs` of each folder directly in it, in
+ *   name order (one per add-on), skipping folders whose name starts with
+ *   "." and `node_modules`.
+ */
+function pluginFilesIn(target) {
+    if (!isDirectory(target))
+        return [target];
+    const own = path_1.default.join(target, INDEX);
+    if (fs_1.default.existsSync(own))
+        return [own];
+    return fs_1.default.readdirSync(target, { withFileTypes: true })
+        .filter((entry) => !entry.name.startsWith('.') && entry.name !== 'node_modules')
+        .filter((entry) => entry.isDirectory() || (entry.isSymbolicLink() && isDirectory(path_1.default.join(target, entry.name))))
+        .map((entry) => entry.name)
+        .sort()
+        .map((name) => path_1.default.join(target, name, INDEX))
+        .filter((file) => fs_1.default.existsSync(file));
+}
 /**
- * The plugins file to load: UAG_PLUGINS (a path, or "off"), or else the
- * image's default when it exists. Undefined when there is none.
+ * The plugins files to load: those UAG_PLUGINS names (a file, a folder, or
+ * "off"), or else those in the image's plugins folder when it exists.
  */
-function pluginsFile(env = process.env, defaultFile = exports.DEFAULT_PLUGINS_FILE) {
+function pluginFiles(env = process.env, defaultDir = exports.DEFAULT_PLUGINS_DIR) {
     const setting = String(env.UAG_PLUGINS || '').trim();
     if (setting.toLowerCase() === 'off')
-        return undefined;
+        return [];
     if (setting)
-        return path_1.default.resolve(setting);
-    return fs_1.default.existsSync(defaultFile) ? defaultFile : undefined;
+        return pluginFilesIn(path_1.default.resolve(setting));
+    return fs_1.default.existsSync(defaultDir) ? pluginFilesIn(defaultDir) : [];
 }
 /** A real dynamic import(), kept one after compilation to CommonJS. */
 const dynamicImport = new Function('specifier', 'return import(specifier)');
@@ -36,27 +69,33 @@ const dynamicImport = new Function('specifier', 'return import(specifier)');
 const MODULE_KEYS = ['uag', 'routes', 'components', 'initialize', 'plugins', 'pluginTypes', 'config', 'formRoutes', 'actions', 'hooks', 'providers', 'processors'];
 const isModule = (entry) => !!entry && typeof entry === 'object' && !Array.isArray(entry) && typeof entry.type !== 'string'
     && (MODULE_KEYS.some((key) => key in entry) || typeof entry.settings === 'function');
-/**
- * Load the plugins file, if any, and use it, named by its path in error
- * messages. Its default export is a plugin or a list of plugins; or a module
- * (an extra, with its plugins), or a list mixing modules and
- * plugins, each module used in turn. Plugins are trusted code: they run in
- * the UAG process.
- */
-async function usePluginFiles(server, env = process.env, defaultFile = exports.DEFAULT_PLUGINS_FILE) {
-    const file = pluginsFile(env, defaultFile);
-    if (!file)
-        return undefined;
+/** Use one plugins file, named by its path in error messages. */
+async function usePluginFile(server, file) {
     const exported = (await dynamicImport((0, url_1.pathToFileURL)(file).href))?.default;
     const entries = [].concat(exported ?? []);
     if (entries.some(isModule)) {
         const plugins = entries.filter((entry) => !isModule(entry));
         server.use([...entries.filter(isModule), ...(plugins.length ? [{ plugins }] : [])], file);
         console.log(`[formio-uag] Plugins and modules loaded from ${file}.`);
-        return file;
+        return;
     }
     const plugins = await (0, appserver_1.loadPluginFile)(file);
     server.use({ plugins }, file);
     console.log(`[formio-uag] Plugins loaded from ${file}.`);
-    return file;
+}
+/**
+ * Load the plugins files, if any, and use each in turn, named by its path in
+ * error messages. A file's default export is a plugin or a list of plugins;
+ * or a module (an extra, with its plugins), or a list mixing modules and
+ * plugins, each module used in turn. Several files merge as several modules
+ * do: a module used again by name is used once, and two files that register
+ * the same plugin, plugin type, route or component stop startup, naming both.
+ * Plugins are trusted code: they run in the UAG process. Returns the files
+ * loaded.
+ */
+async function usePluginFiles(server, env = process.env, defaultDir = exports.DEFAULT_PLUGINS_DIR) {
+    const files = pluginFiles(env, defaultDir);
+    for (const file of files)
+        await usePluginFile(server, file);
+    return files;
 }

package/lib/testing.js

@@ -48,9 +48,10 @@ function testForm(definition, options = {}) {
                 }
                 return bytes;
             }
-            if (options.files)
-                return options.files(value, readOptions);
-            throw new Error('testForm reads base64 (data: URL) files only: give createTestModuleApi or mountModuleRoutes a "files" function for others.');
+            const files = options.files || this?.files;
+            if (files)
+                return files(value, readOptions);
+            throw new Error('testForm reads base64 (data: URL) files only: give testForm, createTestModuleApi or mountModuleRoutes a "files" function for others.');
         }
     };
     return form;
@@ -96,6 +97,10 @@ function settingsOf(module, options) {
         throw new Error(`Module ${module.name}: "settings" returned a promise; it must return the settings themselves (no async)`);
     return Object.freeze({ ...(settings || {}) });
 }
+/** The form, reading stored values that are not base64 through `files` unless it has its own. */
+function withFiles(form, files) {
+    return files && form && typeof form === 'object' && !form.files ? { ...form, files } : form;
+}
 /** The UAG's module API for a module, in a test. */
 async function createTestModuleApi(module, options = {}) {
     const loaded = loadedOf(module, settingsOf(module, options));
@@ -121,6 +126,11 @@ async function createTestModuleApi(module, options = {}) {
     if (options.plugins?.length)
         registry.add(options.plugins, 'test');
     await registry.initialize({ server: {} });
+    if (options.files) {
+        // A form without its own "files" function reads other stored values through this one.
+        const read = api.files.read;
+        api.files.read = (form, value, auth, readOptions) => read(withFiles(form, options.files), value, auth, readOptions);
+    }
     return api;
 }
 /**
@@ -155,7 +165,7 @@ async function mountModuleRoutes(module, options) {
     };
     const router = (0, appserver_1.moduleFormRouter)({}, loaded, api, host);
     const withForm = (req, res, next) => {
-        req.form = options.form;
+        req.form = withFiles(options.form, options.files);
         req.auth = options.auth || testAuth();
         next();
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formio/uag",
-  "version": "2.0.0-rc.7",
+  "version": "2.0.0-rc.8",
   "mcpName": "io.form/formio-uag",
   "description": "The Form.io Universal Agent Gateway (UAG).",
   "main": "lib/index.js",
@@ -45,9 +45,9 @@
   "author": "Form.io Developers",
   "license": "MIT",
   "dependencies": {
-    "@formio/appserver": "^2.26.0",
+    "@formio/appserver": "^2.26.1",
     "@formio/core": "2.9.0",
-    "@formio/uag-sdk": "^2.0.0-rc.7",
+    "@formio/uag-sdk": "^2.0.0-rc.8",
     "@modelcontextprotocol/sdk": "1.32.2",
     "cors": "^2.8.6",
     "debug": "^4.4.3",