@formio/uag 2.0.0-rc.1 → 2.0.0-rc.10

package/lib/plugins.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toolPluginType = exports.enginePluginType = void 0;
+exports.listEngines = listEngines;
+exports.listTools = listTools;
+const uag_sdk_1 = require("@formio/uag-sdk");
+const tools_1 = require("./agent/tools");
+const engines_1 = require("./agent/engines");
+const version_1 = require("./version");
+/**
+ * Engines and MCP tools, listed in the plugin registry (phase 1). The UAG keeps
+ * loading them its own way (UAG_ENGINES, config.tools); the registry only lists
+ * them, so they appear in GET {project}/plugins. Settings values are never listed.
+ */
+exports.enginePluginType = {
+    type: 'engine',
+    title: 'Engine',
+    apiVersions: [1],
+    editForm: 'none',
+    // A misconfigured engine stops startup.
+    unavailable: 'error',
+    registration: 'internal',
+    stability: 'stable',
+    validate: (plugin) => uag_sdk_1.ENGINE_NAME.test(plugin.name) ? [] : [`engine name "${plugin.name}" must be lowercase letters, digits and "-", starting with a letter`],
+    manifest: (plugin) => ({
+        kinds: plugin.kinds,
+        accepts: plugin.accepts,
+        generate: plugin.generate,
+        instances: plugin.instances
+    })
+};
+exports.toolPluginType = {
+    type: 'tool',
+    title: 'MCP tool',
+    apiVersions: [1],
+    editForm: 'none',
+    unavailable: 'error',
+    registration: 'internal',
+    stability: 'stable',
+    validate: (plugin) => /^[A-Za-z][A-Za-z0-9_-]*$/.test(plugin.name) ? [] : [`tool name "${plugin.name}" must start with a letter and hold only letters, digits, "_" and "-"`],
+    manifest: (plugin) => ({ annotations: plugin.annotations ?? null })
+};
+const semver = (version) => (version && /^\d+\.\d+\.\d+/.test(version)) ? version : version_1.UAG_VERSION;
+/** List each loaded engine type: its instances, kinds, what agent instances read, and whether they generate. */
+function listEngines(registry, project) {
+    const engines = project.formflowEngines();
+    const entries = (0, engines_1.engineTypesOf)(engines).map((type) => {
+        const instances = type.instances.map((name) => engines.get(name)).filter(Boolean);
+        const agents = instances.filter((engine) => engine.kind === 'agent');
+        const accepts = [...new Set(agents.flatMap((engine) => Array.isArray(engine.accepts) ? engine.accepts : ['text']))];
+        return {
+            type: 'engine',
+            name: type.name,
+            title: type.title,
+            version: semver(type.version),
+            apiVersion: 1,
+            kinds: type.kinds,
+            accepts,
+            generate: agents.some((engine) => typeof engine.generate === 'function'),
+            instances: type.instances
+        };
+    });
+    registry.addType(exports.enginePluginType, '@formio/uag');
+    registry.add(entries, 'UAG_ENGINES', { server: true });
+}
+/**
+ * List every MCP tool the project serves (built-in, then config.tools). A name
+ * served twice is listed once, with a warning: listing never refuses what the
+ * tool loader allows.
+ */
+async function listTools(registry, project, log = console) {
+    const seen = new Set();
+    const entries = [];
+    for (const tool of await (0, tools_1.allTools)(project)) {
+        const name = String(tool.name);
+        if (seen.has(name)) {
+            log.warn(`[plugins] tool:${name} is defined more than once; it is listed once`);
+            continue;
+        }
+        seen.add(name);
+        entries.push({
+            type: 'tool',
+            name,
+            title: tool.title || name,
+            description: tool.description,
+            version: version_1.UAG_VERSION,
+            apiVersion: 1,
+            annotations: tool.annotations
+        });
+    }
+    registry.addType(exports.toolPluginType, '@formio/uag');
+    registry.add(entries, 'config.tools', { server: true });
+}

package/lib/richText.d.ts

@@ -0,0 +1,20 @@
+import type { Component } from '@formio/core';
+/**
+ * HTML for rich text fields (textareas with the CKEditor or Quill editor).
+ *
+ * What an agent engine writes into such a field is reduced to the markup the
+ * editors keep, because the engine's input can be steered (a document it reads
+ * is someone else's text), and the field is later rendered for reviewers. The
+ * HTML is parsed and written out again: allowed elements with their allowed
+ * attributes, text escaped, everything else dropped. An element that is not
+ * allowed is dropped and its children kept, except for elements whose content
+ * is never text to show (scripts, styles, frames, embedded documents).
+ */
+/** Allowed elements, each with the attributes it may keep. */
+export declare const RICH_TEXT_TAGS: Record<string, string[]>;
+/** Whether a component is a rich text field, whose value is HTML. */
+export declare function isRichText(component: Component | undefined): boolean;
+/** Reduce HTML to the markup rich text editors keep (RICH_TEXT_TAGS). */
+export declare function sanitizeRichText(html: string): string;
+/** The rule agents are given for a rich text field's value. */
+export declare const RICH_TEXT_RULE: string;

package/lib/richText.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RICH_TEXT_RULE = exports.RICH_TEXT_TAGS = void 0;
+exports.isRichText = isRichText;
+exports.sanitizeRichText = sanitizeRichText;
+const node_html_parser_1 = require("node-html-parser");
+/**
+ * HTML for rich text fields (textareas with the CKEditor or Quill editor).
+ *
+ * What an agent engine writes into such a field is reduced to the markup the
+ * editors keep, because the engine's input can be steered (a document it reads
+ * is someone else's text), and the field is later rendered for reviewers. The
+ * HTML is parsed and written out again: allowed elements with their allowed
+ * attributes, text escaped, everything else dropped. An element that is not
+ * allowed is dropped and its children kept, except for elements whose content
+ * is never text to show (scripts, styles, frames, embedded documents).
+ */
+/** Allowed elements, each with the attributes it may keep. */
+exports.RICH_TEXT_TAGS = {
+    p: [], br: [], hr: [],
+    strong: [], b: [], em: [], i: [], u: [], s: [], sub: [], sup: [], code: [], pre: [],
+    h1: [], h2: [], h3: [], h4: [], h5: [], h6: [],
+    ul: [], ol: [], li: [],
+    blockquote: [],
+    a: ['href'],
+    figure: [], table: [], thead: [], tbody: [], tfoot: [], tr: [],
+    th: ['colspan', 'rowspan'], td: ['colspan', 'rowspan']
+};
+/** Elements dropped with everything inside them. */
+const DROPPED_WITH_CONTENT = new Set(['script', 'style', 'noscript', 'template', 'iframe', 'frame', 'frameset', 'object', 'embed', 'svg', 'math', 'head', 'title', 'textarea', 'select']);
+const VOID = new Set(['br', 'hr']);
+/** Whether a component is a rich text field, whose value is HTML. */
+function isRichText(component) {
+    const editor = component?.editor;
+    return component?.type === 'textarea' && (editor === 'ckeditor' || editor === 'quill');
+}
+function escapeText(text) {
+    return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+function escapeAttribute(value) {
+    return escapeText(value).replace(/"/g, '&quot;');
+}
+/** Only links to web pages and mail addresses: never `javascript:`, `data:` or the like. */
+function safeHref(value) {
+    const href = String(value || '').replace(/[\u0000-\u001F\u007F\s]+/g, '');
+    return /^(https?:\/\/|mailto:)/i.test(href) ? String(value).trim() : null;
+}
+function attributesOf(element, allowed) {
+    let out = '';
+    for (const name of allowed) {
+        const raw = element.getAttribute(name);
+        if (raw === undefined || raw === null)
+            continue;
+        let value = raw;
+        if (name === 'href')
+            value = safeHref(raw);
+        if ((name === 'colspan' || name === 'rowspan'))
+            value = /^\d{1,3}$/.test(raw.trim()) ? raw.trim() : null;
+        if (value === null)
+            continue;
+        out += ` ${name}="${escapeAttribute(value)}"`;
+    }
+    return out;
+}
+function write(node) {
+    if (node.nodeType === node_html_parser_1.NodeType.TEXT_NODE) {
+        // `text` is the decoded text; it is escaped once, here.
+        return escapeText(node.text);
+    }
+    if (node.nodeType !== node_html_parser_1.NodeType.ELEMENT_NODE)
+        return '';
+    const element = node;
+    const children = () => element.childNodes.map(write).join('');
+    const tag = String(element.rawTagName || '').toLowerCase();
+    if (!tag)
+        return children();
+    if (DROPPED_WITH_CONTENT.has(tag))
+        return '';
+    const allowed = exports.RICH_TEXT_TAGS[tag];
+    if (!allowed)
+        return children();
+    const open = `<${tag}${attributesOf(element, allowed)}>`;
+    return VOID.has(tag) ? open : `${open}${children()}</${tag}>`;
+}
+/** Reduce HTML to the markup rich text editors keep (RICH_TEXT_TAGS). */
+function sanitizeRichText(html) {
+    const root = (0, node_html_parser_1.parse)(String(html ?? ''), {
+        comment: false,
+        lowerCaseTagName: true,
+        // Read as raw text, so their content is never parsed as markup; they are dropped.
+        blockTextElements: { script: true, style: true, noscript: true }
+    });
+    return root.childNodes.map(write).join('').trim();
+}
+/** The rule agents are given for a rich text field's value. */
+exports.RICH_TEXT_RULE = 'The value is HTML for a rich text editor. Use only these elements: ' +
+    Object.keys(exports.RICH_TEXT_TAGS).join(', ') +
+    ', with no attributes except href on a (http, https or mailto links only) and colspan and rowspan on td and th. ' +
+    'No other elements, styles, classes, images or scripts, which are removed. Write HTML, not Markdown, and do not wrap it in a code fence.';

package/lib/router.d.ts

@@ -1,3 +1,12 @@
 import { Router } from 'express';
 import { UAGProjectInterface } from './UAGProjectInterface';
+import type { ScopedTokenClaims } from './formflow';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Hold a scoped token to its tools whatever built the server: a project
+ * interface a module replaces may override buildMcpServer() and register tools
+ * without the scope it was given. Every tool the token does not list, and every
+ * tool not annotated read-only, is disabled, so it is neither listed nor run.
+ */
+export declare function restrictToScope(server: McpServer, scope: Pick<ScopedTokenClaims, 'tools'>): void;
 export declare function UAGRouter(project: UAGProjectInterface): Router;

package/lib/router.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.restrictToScope = restrictToScope;
 exports.UAGRouter = UAGRouter;
 const express_1 = require("express");
 const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
@@ -30,6 +31,22 @@ const handleResponseError = (error, res) => {
     res.status(500).json(createJsonRpcErrorResponse(-32603, "Internal Server Error"));
     return false;
 };
+/**
+ * Hold a scoped token to its tools whatever built the server: a project
+ * interface a module replaces may override buildMcpServer() and register tools
+ * without the scope it was given. Every tool the token does not list, and every
+ * tool not annotated read-only, is disabled, so it is neither listed nor run.
+ */
+function restrictToScope(server, scope) {
+    const allowed = new Set(scope.tools || []);
+    // The SDK keeps registered tools here; it has no public list of them.
+    const registered = server._registeredTools || {};
+    for (const [name, tool] of Object.entries(registered)) {
+        if (!allowed.has(name) || tool?.annotations?.readOnlyHint !== true) {
+            tool.disable?.();
+        }
+    }
+}
 /**
  * Build a per-request McpServer + transport (stateless mode) and tear both down
  * when the response closes. A fresh instance per request keeps concurrent requests
@@ -37,6 +54,8 @@ const handleResponseError = (error, res) => {
  */
 const connectMcpTransport = async (project, res, scope) => {
     const server = await project.buildMcpServer(scope);
+    if (scope)
+        restrictToScope(server, scope);
     const transport = new streamableHttp_js_1.StreamableHTTPServerTransport({
         sessionIdGenerator: undefined, // Use "undefined" to trigger stateless mode.
     });

package/lib/runner.d.ts

@@ -53,6 +53,8 @@ export type TaskRunOutcome = {
     }[];
     /** Whether the results were saved (nothing is saved when nothing changed). */
     saved: boolean;
+    /** Answers the form's validation refused, left out: path to the form's message. */
+    refused?: Record<string, string>;
     error?: string;
 };
 /**

package/lib/runner.js

@@ -268,8 +268,9 @@ class TaskRunner {
         const service = (0, formflow_1.formflow)(this.project);
         const load = async () => {
             const stored = await form.loadSubmission(job.submission, await act());
+            // Form.io answers a submission the caller may not read as missing, so say both.
             if (!stored)
-                throw new formflow_1.FormflowError(404, `Submission "${job.submission}" was not found.`);
+                throw new formflow_1.FormflowError(404, `Submission "${job.submission}" was not found, or the user the run acts as may not read it (give submitters Read Own access, or the action an agent role).`);
             return stored;
         };
         let stored = await load();
@@ -278,8 +279,14 @@ class TaskRunner {
             const engines = run.results.map((result) => ({ kind: result.kind, engine: result.engine ?? null, model: result.model ?? null }));
             const failed = run.failed.map((group) => group.error || 'no engine could answer').join('; ');
             const changed = Object.keys(run.written).length > 0 || run.cleared.length > 0;
+            const refused = run.refused || {};
+            if (Object.keys(refused).length) {
+                console.warn(`[formio-uag] Run task "${job.task}" left out answers the form refused for submission ${job.submission} of "${job.form}": ` +
+                    Object.entries(refused).map(([path, message]) => `${path} (${message})`).join('; '));
+            }
+            const left = Object.keys(refused).length ? { refused } : {};
             if (!changed) {
-                return { status: failed ? 'failed' : 'done', written: {}, cleared: [], engines, saved: false, ...(failed && { error: failed }) };
+                return { status: failed ? 'failed' : 'done', written: {}, cleared: [], engines, saved: false, ...left, ...(failed && { error: failed }) };
             }
             try {
                 // Only the task's fields changed; `modified` refuses the save if a person saved in the meantime.
@@ -291,7 +298,7 @@ class TaskRunner {
                     ...(job.caller ? { [exports.RUN_TASK_CALLER]: job.caller, [exports.RUN_TASK_IDENTITY]: job.identity } : { [exports.RUN_TASK_AS_USER]: true }),
                     [exports.RUN_TASK_CHAIN]: (job.chain || 0) + 1
                 });
-                return { status: failed ? 'failed' : 'done', written: run.written, cleared: run.cleared, engines, saved: true, ...(failed && { error: failed }) };
+                return { status: failed ? 'failed' : 'done', written: run.written, cleared: run.cleared, engines, saved: true, ...left, ...(failed && { error: failed }) };
             }
             catch (err) {
                 if (err?.name !== 'ConflictError' || attempt >= 2) {
@@ -313,6 +320,7 @@ function resultOf(outcome) {
         engines: outcome.engines,
         written: Object.keys(outcome.written),
         cleared: outcome.cleared,
+        ...(outcome.refused && { refused: Object.keys(outcome.refused) }),
         saved: outcome.saved,
         ...(outcome.error && { error: outcome.error })
     };

package/lib/runs.d.ts

@@ -1,89 +1,27 @@
-import { Collection, ObjectId } from 'mongodb';
+import { ObjectId } from 'mongodb';
 import type { ActingFor } from './identity';
+import { LEASE_MS, MAX_ATTEMPTS, RENEW_MS } from './formflow';
+import type { CoreNewTaskRun, CoreTaskRunRecord, CoreTaskRunStore, TaskRunStatus } from './formflow';
 /**
  * Run task records in the UAG's database (`uag-taskruns`): one per run, for
  * audit (Action Logs), and, for runs that act with an agent role, the queue
  * that lets a run survive a restart and be taken by one replica at a time.
  * A record never holds a token.
+ *
+ * The store is Agentic Formflow's (`useDatabase`); the UAG gives it the
+ * collection and its ids.
  */
-export type TaskRunStatus = 'pending' | 'running' | 'done' | 'failed';
-export type TaskRunRecord = {
-    _id: ObjectId;
-    project: string;
-    /** The form's id, and its name for the runner. */
-    form: string;
-    formName: string;
-    submission?: string;
-    /** The action's title, and the task it runs. */
-    action: string;
-    task: string;
-    answer: 'decisions' | 'task';
-    /** When it ran: before the save, or after it. */
-    handler: 'before' | 'after';
-    method: string;
-    /** Resumed after a restart (it acts with an agent role). */
-    durable: boolean;
+export type { TaskRunStatus };
+export type TaskRunRecord = CoreTaskRunRecord<ObjectId> & {
     actingFor: ActingFor;
-    /** The X-Request-Id of the request that started the run. */
-    requestId?: string;
-    agentRole?: string;
-    /** How many runner saves led to this run. */
-    chain?: number;
-    status: TaskRunStatus;
-    attempts: number;
-    owner?: string;
-    leaseUntil?: Date;
-    engines?: {
-        kind: string;
-        engine: string | null;
-        model: string | null;
-    }[];
-    written?: string[];
-    cleared?: string[];
-    saved?: boolean;
-    error?: string;
-    created: Date;
-    modified: Date;
-    started?: Date;
-    finished?: Date;
 };
-export type NewTaskRun = Omit<TaskRunRecord, '_id' | 'attempts' | 'created' | 'modified' | 'status'> & {
-    status?: TaskRunStatus;
+export type NewTaskRun = CoreNewTaskRun<ObjectId> & {
+    actingFor: ActingFor;
+};
+export type TaskRunStore = CoreTaskRunStore<ObjectId>;
+export { LEASE_MS, MAX_ATTEMPTS, RENEW_MS };
+/** The ids of the UAG's database: MongoDB ObjectIds. */
+export declare const OBJECT_IDS: {
+    create: () => ObjectId;
+    parse: (id: string) => ObjectId | null;
 };
-/** How long a replica holds a run before another may take it over, and how often it renews. */
-export declare const LEASE_MS: number;
-export declare const RENEW_MS: number;
-/** Attempts before a run that keeps losing its replica is given up. */
-export declare const MAX_ATTEMPTS = 3;
-export declare class TaskRunStore {
-    readonly collection: Collection<TaskRunRecord>;
-    readonly project?: string | undefined;
-    /** This replica, as the owner of the runs it holds. */
-    readonly owner: `${string}-${string}-${string}-${string}-${string}`;
-    /**
-     * `project` limits the durable runs this replica takes to its project's:
-     * UAGs of different projects may share one database.
-     */
-    constructor(collection: Collection<TaskRunRecord>, project?: string | undefined);
-    private get scope();
-    add(run: NewTaskRun): Promise<ObjectId>;
-    /**
-     * Take the oldest durable run that is pending, or whose holder's lease ran
-     * out, for this replica. Only one replica can take a run.
-     */
-    claim(now?: Date): Promise<TaskRunRecord | null>;
-    /** Fail the runs that lost their replica too many times. */
-    private giveUp;
-    /** Keep holding a run. False when another replica took it over. */
-    renew(id: ObjectId): Promise<boolean>;
-    /** Record how a run ended. Only the replica holding a durable run can. */
-    finish(id: ObjectId, result: Pick<TaskRunRecord, 'engines' | 'written' | 'cleared' | 'saved' | 'error'> & {
-        status: 'done' | 'failed';
-    }): Promise<void>;
-    get(id: string): Promise<TaskRunRecord | null>;
-    /** The project's records matching a filter, newest change first. */
-    list(filter: Record<string, any>, limit: number): Promise<{
-        items: TaskRunRecord[];
-        total: number;
-    }>;
-}

package/lib/runs.js

@@ -1,74 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TaskRunStore = exports.MAX_ATTEMPTS = exports.RENEW_MS = exports.LEASE_MS = void 0;
-const crypto_1 = require("crypto");
+exports.OBJECT_IDS = exports.RENEW_MS = exports.MAX_ATTEMPTS = exports.LEASE_MS = void 0;
 const mongodb_1 = require("mongodb");
-/** How long a replica holds a run before another may take it over, and how often it renews. */
-exports.LEASE_MS = 2 * 60 * 1000;
-exports.RENEW_MS = 30 * 1000;
-/** Attempts before a run that keeps losing its replica is given up. */
-exports.MAX_ATTEMPTS = 3;
-class TaskRunStore {
-    /**
-     * `project` limits the durable runs this replica takes to its project's:
-     * UAGs of different projects may share one database.
-     */
-    constructor(collection, project) {
-        this.collection = collection;
-        this.project = project;
-        /** This replica, as the owner of the runs it holds. */
-        this.owner = (0, crypto_1.randomUUID)();
-    }
-    get scope() {
-        return this.project === undefined ? {} : { project: this.project };
-    }
-    async add(run) {
-        const now = new Date();
-        const record = { ...run, _id: new mongodb_1.ObjectId(), status: run.status || 'pending', attempts: 0, created: now, modified: now };
-        await this.collection.insertOne(record);
-        return record._id;
-    }
-    /**
-     * Take the oldest durable run that is pending, or whose holder's lease ran
-     * out, for this replica. Only one replica can take a run.
-     */
-    async claim(now = new Date()) {
-        await this.giveUp(now);
-        return this.collection.findOneAndUpdate({
-            ...this.scope,
-            durable: true,
-            attempts: { $lt: exports.MAX_ATTEMPTS },
-            $or: [{ status: 'pending' }, { status: 'running', leaseUntil: { $lt: now } }]
-        }, { $set: { status: 'running', owner: this.owner, leaseUntil: new Date(now.getTime() + exports.LEASE_MS), started: now, modified: now }, $inc: { attempts: 1 } }, { sort: { created: 1 }, returnDocument: 'after' });
-    }
-    /** Fail the runs that lost their replica too many times. */
-    async giveUp(now) {
-        await this.collection.updateMany({ ...this.scope, durable: true, status: 'running', leaseUntil: { $lt: now }, attempts: { $gte: exports.MAX_ATTEMPTS } }, { $set: { status: 'failed', error: `The run was given up after ${exports.MAX_ATTEMPTS} attempts.`, finished: now, modified: now }, $unset: { leaseUntil: '', owner: '' } });
-    }
-    /** Keep holding a run. False when another replica took it over. */
-    async renew(id) {
-        const now = new Date();
-        const result = await this.collection.updateOne({ _id: id, owner: this.owner, status: 'running' }, { $set: { leaseUntil: new Date(now.getTime() + exports.LEASE_MS), modified: now } });
-        return result.matchedCount > 0;
-    }
-    /** Record how a run ended. Only the replica holding a durable run can. */
-    async finish(id, result) {
-        const now = new Date();
-        await this.collection.updateOne({ _id: id, $or: [{ durable: false }, { owner: this.owner }] }, { $set: { ...result, finished: now, modified: now }, $unset: { leaseUntil: '', owner: '' } });
-    }
-    async get(id) {
-        if (!mongodb_1.ObjectId.isValid(id))
-            return null;
-        return this.collection.findOne({ _id: new mongodb_1.ObjectId(id) });
-    }
-    /** The project's records matching a filter, newest change first. */
-    async list(filter, limit) {
-        const [items, total] = await Promise.all([
-            // A limit of 0 would be none at all to MongoDB.
-            limit > 0 ? this.collection.find(filter).sort({ modified: -1 }).limit(limit).toArray() : Promise.resolve([]),
-            this.collection.countDocuments(filter)
-        ]);
-        return { items, total };
-    }
-}
-exports.TaskRunStore = TaskRunStore;
+const formflow_1 = require("./formflow");
+Object.defineProperty(exports, "LEASE_MS", { enumerable: true, get: function () { return formflow_1.LEASE_MS; } });
+Object.defineProperty(exports, "MAX_ATTEMPTS", { enumerable: true, get: function () { return formflow_1.MAX_ATTEMPTS; } });
+Object.defineProperty(exports, "RENEW_MS", { enumerable: true, get: function () { return formflow_1.RENEW_MS; } });
+/** The ids of the UAG's database: MongoDB ObjectIds. */
+exports.OBJECT_IDS = {
+    create: () => new mongodb_1.ObjectId(),
+    parse: (id) => (mongodb_1.ObjectId.isValid(id) ? new mongodb_1.ObjectId(id) : null)
+};

package/lib/testing.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @formio/uag/testing: test a module without a Form.io project or a running UAG.
+ *
+ *   const { createTestModuleApi, testForm, testAuth, mountModuleRoutes } = require('@formio/uag/testing');
+ *
+ *   const api = await createTestModuleApi(MyModule, { config: { myModule: { max: 2 } } });
+ *   const app = await mountModuleRoutes(MyModule, { form: testForm(definition), auth: testAuth() });
+ *   await supertest(app).post('/notes/my-module/check').send({ ... });
+ *
+ * The API is the UAG's own (errors, stream, forms, converters, engine handles,
+ * Markdown, callerKey), with stand-ins only for what needs a project: the
+ * caller's access (from `testAuth`), the license (`licensed`), engines
+ * (`engines`) and stored files (`testForm` reads base64 values; `files` for
+ * others). Settings go through the module's own `settings`, with the server's rules.
+ */
+import express from 'express';
+import type { AuthRequest, ModuleForm, ServerModule } from '@formio/appserver';
+import type { UAGModuleApi } from './modules/types';
+/** An engine for tests: an agent engine that generates. */
+export type TestEngine = {
+    name: string;
+    model?: string;
+    accepts?: Array<'text' | 'pdf'>;
+    generate(request: any): any;
+    kind?: 'agent';
+};
+export type TestModuleOptions = {
+    /** The settings as given, instead of running the module's `settings`. */
+    settings?: Record<string, any>;
+    /** The configuration and environment the module's `settings` gets ({} by default). */
+    config?: Record<string, any>;
+    env?: Record<string, string | undefined>;
+    /** Plugins to register beside the module's own (document plugins, converters). */
+    plugins?: any[];
+    /** The engines `api.engines.select()` chooses from. */
+    engines?: TestEngine[];
+    /** Whether Agentic Formflow is licensed (true): false makes `requireLicense` and engine handles' `generate` refuse with 403. */
+    licensed?: boolean;
+    /** Reads a stored file value that is not base64 (the test form reads those). */
+    files?: (value: any, options: {
+        component?: any;
+        maxBytes?: number;
+    }) => Buffer | null | Promise<Buffer | null>;
+};
+/** A form for tests, as module routes get it: `definition` is the form's JSON. */
+export declare function testForm(definition: Record<string, any>, options?: {
+    id?: string;
+    files?: TestModuleOptions['files'];
+}): ModuleForm & {
+    readFile(value: any, auth: any, options?: any): Promise<Buffer | null>;
+};
+/**
+ * A caller for tests: a user with these permissions on every form (create and
+ * update by default), as a list (`['read']`) or as `formPermissions()` gives
+ * them (`{ read: true }`).
+ */
+export declare function testAuth(options?: {
+    user?: Record<string, any>;
+    permissions?: Array<'create' | 'read' | 'update' | 'delete'> | Partial<Record<'create' | 'read' | 'update' | 'delete', boolean>>;
+    admin?: boolean;
+}): AuthRequest;
+/** The UAG's module API for a module, in a test. */
+export declare function createTestModuleApi<Settings extends Record<string, any> = Record<string, any>>(module: ServerModule<any>, options?: TestModuleOptions): Promise<UAGModuleApi<Settings>>;
+/**
+ * The module's form routes on an Express app, as the UAG mounts them on a
+ * form (by its path, and by `form/<id>`), for supertest: with the form, the
+ * caller, a request id, the access check and the UAG's error shape. No rate
+ * limits. `api` is created with `options` unless given.
+ */
+export declare function mountModuleRoutes(module: ServerModule<any>, options: TestModuleOptions & {
+    form: ReturnType<typeof testForm>;
+    auth?: AuthRequest;
+    api?: UAGModuleApi;
+}): Promise<express.Express>;