callman-mcp 0.3.0 → 0.5.0

package/dist-cjs/tools/uiTestAdmin.js

@@ -0,0 +1,512 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerUiTestAdminTools = void 0;
+const zod_1 = require("zod");
+const errors_js_1 = require("../client/errors.js");
+const resolve_js_1 = require("../domain/resolve.js");
+const compose_js_1 = require("../domain/uiTest/compose.js");
+const summarize_js_1 = require("../domain/uiTest/summarize.js");
+const strict_js_1 = require("../lib/strict.js");
+const truncate_js_1 = require("../lib/truncate.js");
+const lookups_js_1 = require("./lookups.js");
+const shared_js_1 = require("./shared.js");
+const uiTestShared_js_1 = require("./uiTestShared.js");
+const uiTestRuns_js_1 = require("./uiTestRuns.js");
+// UI-test schedules (web flows on the server runner), the on-prem review
+// workflow (submit / approve / reject, approved versions) and export/import
+// of `callman.uitest` envelopes.
+const EXPORT_MAX_BYTES = 2 * 1024 * 1024;
+const ENVELOPE_MAX = 8 * 1024 * 1024;
+const CLOUD_REVIEW_NOTE = "Callman cloud has no review workflow for UI tests — flows run and schedule as saved. Approval and versions exist on on-prem installations.";
+const isReviewDisabled = (error) => error instanceof errors_js_1.CallmanApiError && error.code === "REVIEW_DISABLED_CLOUD";
+// ── schedules ──────────────────────────────────────────────────────────
+const timesArg = zod_1.z.array(zod_1.z.string().regex(/^([01]\d|2[0-3]):([0-5]\d)$/, "HH:mm")).min(1).max(24);
+const scheduleFields = {
+    description: zod_1.z.string().max(1000).nullable().optional(),
+    enabled: zod_1.z.boolean().optional(),
+    triggerType: zod_1.z.enum(["daily", "weekly", "monthly", "custom_cron"]).optional(),
+    times: timesArg.optional().describe('Times of day (HH:mm, 24h) for daily / weekly / monthly, e.g. ["09:00", "18:30"]'),
+    daysOfWeek: zod_1.z.array(zod_1.z.number().int().min(0).max(6)).min(1).max(7).optional().describe("weekly: 0 = Sunday … 6 = Saturday"),
+    daysOfMonth: zod_1.z.array(zod_1.z.number().int().min(1).max(31)).min(1).max(31).optional().describe("monthly: 1–31"),
+    cronExpression: zod_1.z.string().max(120).optional().describe("custom_cron: a 5-field cron expression"),
+    timezone: zod_1.z.string().max(100).optional().describe("IANA time zone, e.g. Asia/Baku (default: the server's)"),
+    executionPolicy: (0, strict_js_1.strictObject)({
+        allowParallelRuns: zod_1.z.boolean().optional(),
+        skipIfAlreadyRunning: zod_1.z.boolean().optional(),
+        maxRuntimeMinutes: zod_1.z.number().int().min(1).max(1440).nullable().optional(),
+    }, "execution policy field").optional(),
+    failurePolicy: (0, strict_js_1.strictObject)({
+        retryCount: zod_1.z.number().int().min(0).max(10).optional(),
+        retryIntervalMinutes: zod_1.z.number().int().min(1).max(1440).optional(),
+    }, "failure policy field").optional(),
+    notification: (0, strict_js_1.strictObject)({
+        notifyOnSuccess: zod_1.z.boolean().optional(),
+        notifyOnFailure: zod_1.z.boolean().optional(),
+        connection: zod_1.z.string().max(200).nullable().optional().describe("Notification connection (Slack / Teams / email …) id or name"),
+        channelOverride: zod_1.z.string().max(500).nullable().optional(),
+    }, "notification field")
+        .nullable()
+        .optional(),
+};
+// Flat tool arguments → the backend's trigger configs.
+const scheduleBody = async (ctx, ws, input, current) => {
+    const body = {};
+    if (input.description !== undefined)
+        body.description = input.description;
+    if (input.enabled !== undefined)
+        body.enabled = input.enabled;
+    if (input.timezone !== undefined)
+        body.timezone = input.timezone;
+    if (input.executionPolicy)
+        body.executionPolicy = input.executionPolicy;
+    if (input.failurePolicy)
+        body.failurePolicy = input.failurePolicy;
+    const triggerTouched = input.triggerType !== undefined || input.times !== undefined || input.daysOfWeek !== undefined || input.daysOfMonth !== undefined || input.cronExpression !== undefined;
+    if (triggerTouched) {
+        const type = input.triggerType ?? current?.triggerType;
+        if (!type)
+            throw new errors_js_1.ToolInputError("SCHEDULE_TRIGGER_REQUIRED", "Pass triggerType (daily, weekly, monthly or custom_cron).");
+        const times = input.times ?? current?.dailyConfig?.times ?? current?.weeklyConfig?.times ?? current?.monthlyConfig?.times;
+        body.triggerType = type;
+        if (type === "custom_cron") {
+            const cron = input.cronExpression ?? current?.customCronExpression;
+            if (!cron)
+                throw new errors_js_1.ToolInputError("SCHEDULE_CRON_REQUIRED", "custom_cron needs cronExpression.");
+            body.customCronExpression = cron;
+        }
+        else {
+            if (!times)
+                throw new errors_js_1.ToolInputError("SCHEDULE_TIMES_REQUIRED", `A ${type} schedule needs times (HH:mm).`);
+            if (type === "daily")
+                body.dailyConfig = { times };
+            if (type === "weekly") {
+                const days = input.daysOfWeek ?? current?.weeklyConfig?.daysOfWeek;
+                if (!days)
+                    throw new errors_js_1.ToolInputError("SCHEDULE_DAYS_REQUIRED", "A weekly schedule needs daysOfWeek (0 = Sunday … 6 = Saturday).");
+                body.weeklyConfig = { daysOfWeek: days, times };
+            }
+            if (type === "monthly") {
+                const days = input.daysOfMonth ?? current?.monthlyConfig?.daysOfMonth;
+                if (!days)
+                    throw new errors_js_1.ToolInputError("SCHEDULE_DAYS_REQUIRED", "A monthly schedule needs daysOfMonth (1–31).");
+                body.monthlyConfig = { daysOfMonth: days, times };
+            }
+        }
+    }
+    if (input.notification !== undefined) {
+        if (input.notification === null)
+            body.notificationConfig = null;
+        else {
+            const { connection, ...rest } = input.notification;
+            let connectionId = connection === null ? null : undefined;
+            if (connection)
+                connectionId = (0, resolve_js_1.resolveRef)("connection", connection, await (0, lookups_js_1.loadConnections)(ctx, ws), { describe: (entry) => ({ type: entry.type }) }).item.id;
+            body.notificationConfig = { ...rest, ...(connectionId !== undefined ? { connectionId } : {}) };
+        }
+    }
+    return body;
+};
+const listSchedulesAcross = async (ctx, workspace, flowClientId) => {
+    const out = [];
+    for (const ws of await (0, lookups_js_1.workspacesForListing)(ctx, workspace)) {
+        try {
+            for (const schedule of await ctx.api.listUiTestSchedules(ws.id, flowClientId)) {
+                if (!out.some((entry) => entry.schedule.id === schedule.id))
+                    out.push({ ws, schedule });
+            }
+        }
+        catch (error) {
+            if (error instanceof errors_js_1.CallmanApiError && (error.status === 403 || error.status === 404))
+                continue;
+            throw error;
+        }
+    }
+    return out;
+};
+const resolveSchedule = async (ctx, workspace, ref, exact = false) => {
+    const all = await listSchedulesAcross(ctx, workspace);
+    const resolved = (0, resolve_js_1.resolveRef)("UI-test schedule", ref, all.map((entry) => ({ id: entry.schedule.id, name: entry.schedule.name, entry })), { describe: (item) => ({ flow: item.entry.schedule.flowName, triggerType: item.entry.schedule.triggerType }), aliases: (item) => [`${item.entry.schedule.flowName}/${item.entry.schedule.name}`], exact });
+    return { schedule: resolved.item.entry.schedule, ws: resolved.item.entry.ws, annotation: resolved.annotation };
+};
+const refuseMobile = (flows) => {
+    const mobile = flows.filter((flow) => flow.platform !== "web");
+    if (mobile.length > 0) {
+        throw new errors_js_1.ToolInputError("UI_TEST_PLATFORM_UNSUPPORTED", `Schedules run on the server runner, which runs web flows only — not ${mobile.map((flow) => `"${flow.name}" (${flow.platform})`).join(", ")}. Run mobile flows with run_ui_test on your desktop app.`);
+    }
+};
+// ── review helpers ─────────────────────────────────────────────────────
+const flowStatus = (flow) => ({ id: flow.clientId, name: flow.name, reviewStatus: flow.reviewStatus ?? null, version: flow.version ?? null, activeVersionNumber: flow.activeVersionNumber ?? null, ...(flow.reviewNote ? { reviewNote: flow.reviewNote } : {}) });
+const registerUiTestAdminTools = (server, ctx) => {
+    // ── schedules ────────────────────────────────────────────────────────
+    server.registerTool("list_ui_test_schedules", {
+        title: "List UI-test schedules",
+        description: "Schedules that run UI tests on the server runner (web flows), across your workspaces or for one flow: trigger (daily / weekly / monthly / cron), times, enabled, last and next run.",
+        inputSchema: { workspace: shared_js_1.workspaceArg, flow: uiTestShared_js_1.flowArg.optional() },
+        annotations: shared_js_1.READ,
+    }, (0, shared_js_1.guarded)(async ({ workspace, flow }) => {
+        const resolved = flow ? await (0, lookups_js_1.resolveUiTest)(ctx, workspace, flow) : null;
+        const rows = await listSchedulesAcross(ctx, resolved ? resolved.item.workspaceId : workspace, resolved?.item.clientId);
+        const workspaces = await ctx.listWorkspaces();
+        return (0, shared_js_1.ok)({
+            ...(resolved ? { uiTest: { id: resolved.item.clientId, name: resolved.item.name } } : {}),
+            schedules: rows.map((entry) => ({ ...(0, summarize_js_1.scheduleView)(entry.schedule), ...(workspaces.length > 1 ? { workspace: (0, lookups_js_1.workspaceTag)(entry.ws) } : {}) })),
+            total: rows.length,
+        });
+    }));
+    server.registerTool("create_ui_test_schedule", {
+        title: "Schedule UI tests",
+        description: "Schedule one or many web UI tests to run on the server runner: triggerType daily / weekly / monthly (with times HH:mm, daysOfWeek 0–6 or daysOfMonth 1–31) or custom_cron (cronExpression), timezone, execution / failure (retries) policies and notifications. Many flows = one schedule each; conflictMode says what to do with flows that already have schedules (add — default, replace, skip). dryRun: true shows what would be created. Mobile flows cannot be scheduled. On-prem, schedules run the flow's APPROVED version.",
+        inputSchema: {
+            workspace: shared_js_1.workspaceArg,
+            flows: zod_1.z.array(uiTestShared_js_1.flowArg).min(1).max(200),
+            name: zod_1.z.string().trim().min(1).max(120),
+            ...scheduleFields,
+            triggerType: zod_1.z.enum(["daily", "weekly", "monthly", "custom_cron"]),
+            conflictMode: zod_1.z.enum(["add", "replace", "skip"]).optional(),
+            dryRun: shared_js_1.dryRunArg,
+        },
+        annotations: shared_js_1.WRITE,
+    }, (0, shared_js_1.guarded)(async ({ workspace, flows, name, conflictMode, dryRun, ...fields }) => {
+        const resolved = [];
+        for (const ref of flows)
+            resolved.push(await (0, lookups_js_1.resolveUiTest)(ctx, workspace, ref));
+        const targets = resolved.map((entry) => entry.item);
+        refuseMobile(targets);
+        const workspaceIds = [...new Set(targets.map((flow) => flow.workspaceId))];
+        if (workspaceIds.length > 1)
+            throw new errors_js_1.ToolInputError("UI_TEST_SCHEDULE_WORKSPACES", "The flows are in different workspaces — create one schedule call per workspace.");
+        const ws = (0, uiTestShared_js_1.workspaceIdOf)(targets[0]);
+        const base = { name, ...(await scheduleBody(ctx, ws, fields)) };
+        if (targets.length === 1 && !dryRun && !conflictMode) {
+            const created = await ctx.api.createUiTestSchedule(ws, { ...base, flowClientId: targets[0].clientId });
+            return (0, shared_js_1.ok)({ schedule: (0, summarize_js_1.scheduleView)(created), ...(resolved[0].annotation ? { resolved: [(0, resolve_js_1.resolvedSummary)(flows[0], resolved[0])] } : {}) });
+        }
+        const result = await ctx.api.bulkCreateUiTestSchedules(ws, { ...base, flowClientIds: targets.map((flow) => flow.clientId), conflictMode: conflictMode ?? "add", dryRun: dryRun ?? false });
+        const nameOf = new Map(targets.map((flow) => [flow.clientId, flow.name]));
+        const names = (ids) => ids.map((id) => nameOf.get(id) ?? id);
+        return (0, shared_js_1.ok)({
+            ...(dryRun ? { dryRun: true } : {}),
+            created: result.created,
+            schedules: result.createdSchedules.map(summarize_js_1.scheduleView),
+            ...(result.conflictIds.length ? { alreadyScheduled: names(result.conflictIds) } : {}),
+            ...(result.skippedIds.length ? { skipped: names(result.skippedIds) } : {}),
+            ...(result.replacedCount ? { replaced: result.replacedCount } : {}),
+            ...(result.blockedIds.length ? { blocked: names(result.blockedIds), blockedReason: result.blockedReason } : {}),
+            ...(result.failures.length ? { failed: result.failures.map((failure) => ({ ...failure, flow: nameOf.get(failure.flowClientId) ?? failure.flowClientId })) } : {}),
+            conflictMode: result.conflictMode,
+        });
+    }));
+    server.registerTool("update_ui_test_schedule", {
+        title: "Update a UI-test schedule",
+        description: "Change a UI-test schedule (id or name): name, enabled (enable / disable), trigger and times, timezone, policies, notifications. Only the fields you pass change.",
+        inputSchema: {
+            workspace: shared_js_1.workspaceArg,
+            schedule: (0, shared_js_1.refArg)("UI-test schedule"),
+            name: zod_1.z.string().trim().min(1).max(120).optional(),
+            ...scheduleFields,
+        },
+        annotations: shared_js_1.IDEMPOTENT_WRITE,
+    }, (0, shared_js_1.guarded)(async ({ workspace, schedule, name, ...fields }) => {
+        const found = await resolveSchedule(ctx, workspace, schedule);
+        const body = { ...(name !== undefined ? { name } : {}), ...(await scheduleBody(ctx, found.ws.id, fields, found.schedule)) };
+        if (Object.keys(body).length === 0)
+            throw new errors_js_1.ToolInputError("NOTHING_TO_UPDATE", "Pass at least one field to change.");
+        const updated = Object.keys(body).length === 1 && body.enabled !== undefined
+            ? await ctx.api.toggleUiTestSchedule(found.ws.id, found.schedule.id, body.enabled)
+            : await ctx.api.updateUiTestSchedule(found.ws.id, found.schedule.id, body);
+        return (0, shared_js_1.ok)({ schedule: (0, summarize_js_1.scheduleView)(updated), ...(found.annotation ? { resolved: [{ input: schedule, matched: found.schedule.name, id: found.schedule.id, note: found.annotation }] } : {}) });
+    }));
+    server.registerTool("delete_ui_test_schedule", {
+        title: "Delete a UI-test schedule",
+        description: "Delete a UI-test schedule (exact name or id). The flow itself is kept. Confirm with the user first.",
+        inputSchema: { workspace: shared_js_1.workspaceArg, schedule: (0, shared_js_1.refArg)("UI-test schedule"), confirm: shared_js_1.confirmArg },
+        annotations: shared_js_1.DESTRUCTIVE,
+    }, (0, shared_js_1.guarded)(async ({ workspace, schedule, confirm }) => {
+        (0, shared_js_1.requireConfirm)(confirm, "a UI-test schedule");
+        const found = await resolveSchedule(ctx, workspace, schedule, true);
+        await ctx.api.deleteUiTestSchedule(found.ws.id, found.schedule.id);
+        return (0, shared_js_1.ok)({ deleted: { id: found.schedule.id, name: found.schedule.name, flow: found.schedule.flowName } });
+    }));
+    server.registerTool("run_ui_test_schedule_now", {
+        title: "Run a UI-test schedule now",
+        description: "Trigger a UI-test schedule immediately (server runner, the flow's approved version on-prem) and wait for the result like run_ui_test. Refused while the schedule is already running.",
+        inputSchema: {
+            workspace: shared_js_1.workspaceArg,
+            schedule: (0, shared_js_1.refArg)("UI-test schedule"),
+            wait: zod_1.z.boolean().default(true),
+            timeoutSec: zod_1.z.number().int().min(5).max(1800).default(600),
+            includeScreenshots: zod_1.z.boolean().default(false),
+        },
+        annotations: shared_js_1.RUN,
+    }, (0, shared_js_1.guarded)(async ({ workspace, schedule, wait, timeoutSec, includeScreenshots }) => {
+        const found = await resolveSchedule(ctx, workspace, schedule);
+        const trigger = await ctx.api.runUiTestScheduleNow(found.ws.id, found.schedule.id);
+        const header = { schedule: { id: found.schedule.id, name: found.schedule.name }, flow: { id: found.schedule.flowClientId, name: found.schedule.flowName }, reportId: trigger.reportId };
+        if (!wait)
+            return (0, shared_js_1.ok)({ ...header, status: trigger.status, note: "Check it with get_ui_test_run." });
+        const { report, timedOut } = await (0, uiTestRuns_js_1.pollRun)(ctx, found.ws.id, trigger.reportId, timeoutSec);
+        if (timedOut || !report)
+            return (0, shared_js_1.ok)({ ...header, status: report?.status ?? trigger.status, timedOut: true, note: `Still running after ${timeoutSec}s — call get_ui_test_run with this reportId later.` });
+        const structured = { ...header, run: (0, summarize_js_1.runReportView)(report) };
+        if (!includeScreenshots)
+            return (0, shared_js_1.ok)(structured);
+        const images = [
+            { caption: "Failure screenshot", image: (0, summarize_js_1.imageFromDataUrl)(report.failureScreenshot) },
+            { caption: "Final screenshot", image: (0, summarize_js_1.imageFromDataUrl)(report.finalScreenshot) },
+        ].flatMap((entry) => (entry.image ? [{ caption: entry.caption, ...entry.image }] : []));
+        return (0, shared_js_1.okWithImages)(structured, images);
+    }));
+    // ── review (on-prem) ─────────────────────────────────────────────────
+    server.registerTool("submit_ui_test", {
+        title: "Submit a UI test for approval",
+        description: "Send a draft UI test for review (on-prem approval workflow — schedules run the APPROVED version). Optionally name approvers (email, name or user id; default: every eligible approver is notified). On cloud there is no review workflow and this says so.",
+        inputSchema: {
+            workspace: shared_js_1.workspaceArg,
+            flow: uiTestShared_js_1.flowArg,
+            approvers: zod_1.z.array(zod_1.z.string().max(255)).max(100).optional(),
+        },
+        annotations: shared_js_1.WRITE,
+    }, (0, shared_js_1.guarded)(async ({ workspace, flow, approvers }) => {
+        const resolved = await (0, lookups_js_1.resolveUiTest)(ctx, workspace, flow);
+        const ws = (0, uiTestShared_js_1.workspaceIdOf)(resolved.item);
+        try {
+            let approverIds;
+            if (approvers && approvers.length > 0) {
+                const { items } = await ctx.api.uiTestApproverCandidates(ws, resolved.item.clientId);
+                approverIds = approvers.map((ref) => {
+                    const needle = ref.trim().toLowerCase();
+                    const match = items.find((candidate) => candidate.userId === ref.trim() || candidate.email.toLowerCase() === needle || (candidate.displayName ?? "").toLowerCase() === needle);
+                    if (!match)
+                        throw new errors_js_1.ToolInputError("APPROVER_NOT_ELIGIBLE", `"${ref}" cannot approve this UI test.`, { candidates: items.map((candidate) => ({ email: candidate.email, name: candidate.displayName })) });
+                    return match.userId;
+                });
+            }
+            const submitted = await ctx.api.submitUiTest(ws, resolved.item.clientId, approverIds ? { approverIds } : {});
+            ctx.invalidate("uitests:");
+            return (0, shared_js_1.ok)({ uiTest: flowStatus(submitted), note: "Submitted — an approver approves it with review_ui_test or in the desktop app." });
+        }
+        catch (error) {
+            if (!isReviewDisabled(error))
+                throw error;
+            return (0, shared_js_1.ok)({ uiTest: { id: resolved.item.clientId, name: resolved.item.name }, reviewWorkflow: false, note: CLOUD_REVIEW_NOTE });
+        }
+    }));
+    server.registerTool("review_ui_test", {
+        title: "Approve or reject a UI test",
+        description: "As an approver (on-prem), approve a UI test waiting for review — its current content becomes the new approved version that schedules run — or reject it with a note explaining the changes needed. list_ui_tests awaitingMyReview: true lists what waits for you; list_ui_test_versions shows what changed.",
+        inputSchema: {
+            workspace: shared_js_1.workspaceArg,
+            flow: uiTestShared_js_1.flowArg,
+            decision: zod_1.z.enum(["approve", "reject"]),
+            note: zod_1.z.string().trim().max(2000).optional().describe("Required when rejecting"),
+        },
+        annotations: shared_js_1.WRITE,
+    }, (0, shared_js_1.guarded)(async ({ workspace, flow, decision, note }) => {
+        if (decision === "reject" && !note)
+            throw new errors_js_1.ToolInputError("REVIEW_NOTE_REQUIRED", "Rejecting needs a `note` telling the author what to change.");
+        const resolved = await (0, lookups_js_1.resolveUiTest)(ctx, workspace, flow);
+        const ws = (0, uiTestShared_js_1.workspaceIdOf)(resolved.item);
+        try {
+            const result = decision === "approve" ? await ctx.api.approveUiTest(ws, resolved.item.clientId) : await ctx.api.rejectUiTest(ws, resolved.item.clientId, note);
+            ctx.invalidate("uitests:");
+            return (0, shared_js_1.ok)({ uiTest: flowStatus(result), decision, note: decision === "approve" ? `Approved — version ${result.activeVersionNumber ?? "?"} is what schedules run now.` : "Rejected — the author sees your note (changes requested)." });
+        }
+        catch (error) {
+            if (!isReviewDisabled(error))
+                throw error;
+            return (0, shared_js_1.ok)({ uiTest: { id: resolved.item.clientId, name: resolved.item.name }, reviewWorkflow: false, note: CLOUD_REVIEW_NOTE });
+        }
+    }));
+    server.registerTool("list_ui_test_versions", {
+        title: "UI-test approved versions",
+        description: "The approved versions of a UI test (on-prem): number, who submitted and approved it, when, and which one is active (what schedules run). With `version`: that version's snapshot (content, settings) and a line diff of its YAML against the current flow.",
+        inputSchema: {
+            workspace: shared_js_1.workspaceArg,
+            flow: uiTestShared_js_1.flowArg,
+            version: zod_1.z.number().int().min(1).optional(),
+        },
+        annotations: shared_js_1.READ,
+    }, (0, shared_js_1.guarded)(async ({ workspace, flow, version }) => {
+        const resolved = await (0, lookups_js_1.resolveUiTest)(ctx, workspace, flow);
+        const ws = (0, uiTestShared_js_1.workspaceIdOf)(resolved.item);
+        const head = { uiTest: { id: resolved.item.clientId, name: resolved.item.name, version: resolved.item.version ?? null, reviewStatus: resolved.item.reviewStatus ?? null } };
+        try {
+            if (version === undefined) {
+                const list = await ctx.api.listUiTestVersions(ws, resolved.item.clientId);
+                return (0, shared_js_1.ok)({
+                    ...head,
+                    activeVersionNumber: list.activeVersionNumber,
+                    versions: list.items.map(({ snapshot: _snapshot, ...item }) => item),
+                    ...(list.items.length === 0 ? { note: "Never approved yet — submit_ui_test sends it for review." } : {}),
+                });
+            }
+            const [detail, current] = await Promise.all([ctx.api.getUiTestVersion(ws, resolved.item.clientId, version), ctx.api.getUiTest(resolved.item.clientId)]);
+            const snapshotContent = detail.snapshot?.content ?? "";
+            const { snapshot, ...meta } = detail;
+            return (0, shared_js_1.ok)({
+                ...head,
+                version: meta,
+                snapshot: snapshot ? { ...snapshot, content: (0, truncate_js_1.clipBytes)(snapshotContent, truncate_js_1.LIMITS.SCENARIO_FULL).text } : null,
+                diffAgainstCurrent: (0, compose_js_1.diffLines)(snapshotContent, current.content ?? ""),
+            });
+        }
+        catch (error) {
+            if (!isReviewDisabled(error))
+                throw error;
+            return (0, shared_js_1.ok)({ ...head, reviewWorkflow: false, versions: [], note: CLOUD_REVIEW_NOTE });
+        }
+    }));
+    server.registerTool("restore_ui_test_version", {
+        title: "Restore an approved UI-test version",
+        description: "Make an earlier approved version the ACTIVE one again (on-prem; approvers): schedules run it from now on. The flow's current content, version and review status are not changed.",
+        inputSchema: { workspace: shared_js_1.workspaceArg, flow: uiTestShared_js_1.flowArg, version: zod_1.z.number().int().min(1) },
+        annotations: shared_js_1.IDEMPOTENT_WRITE,
+    }, (0, shared_js_1.guarded)(async ({ workspace, flow, version }) => {
+        const resolved = await (0, lookups_js_1.resolveUiTest)(ctx, workspace, flow);
+        try {
+            const restored = await ctx.api.restoreUiTestVersion((0, uiTestShared_js_1.workspaceIdOf)(resolved.item), resolved.item.clientId, version);
+            ctx.invalidate("uitests:");
+            return (0, shared_js_1.ok)({ uiTest: flowStatus(restored), note: `Version ${version} is active — schedules run it from now on.` });
+        }
+        catch (error) {
+            if (!isReviewDisabled(error))
+                throw error;
+            return (0, shared_js_1.ok)({ uiTest: { id: resolved.item.clientId, name: resolved.item.name }, reviewWorkflow: false, note: CLOUD_REVIEW_NOTE });
+        }
+    }));
+    // ── export / import ──────────────────────────────────────────────────
+    server.registerTool("export_ui_tests", {
+        title: "Export UI tests",
+        description: "Export UI tests (a list of flows, or a folder with its subfolders) as a `callman.uitest` envelope — the .callman.uitest file format the desktop app imports. Sub-flows they call with runFlow are bundled; connections they use are included as safe descriptions (never credentials). includeDataset: false leaves test data out; secret-looking dataset values are masked unless reveal: true (needs environments:reveal) — a masked envelope cannot be imported until those values are filled in. The envelope comes back in the result: save it yourself if a file is wanted.",
+        inputSchema: {
+            workspace: shared_js_1.workspaceArg,
+            flows: zod_1.z.array(uiTestShared_js_1.flowArg).min(1).max(100).optional(),
+            folder: zod_1.z.string().max(300).optional(),
+            includeDataset: zod_1.z.boolean().default(true),
+            reveal: zod_1.z.boolean().optional().describe("Export secret dataset values unmasked (needs environments:reveal)"),
+        },
+        annotations: shared_js_1.READ,
+    }, (0, shared_js_1.guarded)(async ({ workspace, flows, folder, includeDataset, reveal }) => {
+        if ((flows === undefined) === (folder === undefined))
+            throw new errors_js_1.ToolInputError("EXPORT_SCOPE", "Pass `flows` or `folder` (one of them).");
+        let targets;
+        if (folder) {
+            const found = await (0, lookups_js_1.resolveUiTestFolder)(ctx, workspace, folder);
+            const scope = (0, lookups_js_1.uiTestFolderSubtree)(await (0, lookups_js_1.loadUiTestFolders)(ctx), found.item.id);
+            targets = (await (0, lookups_js_1.loadUiTests)(ctx)).filter((flow) => flow.folderId && scope.has(flow.folderId));
+            if (targets.length === 0)
+                throw new errors_js_1.ToolInputError("UI_TEST_FOLDER_EMPTY", `Folder "${found.item.path}" has no UI tests.`);
+        }
+        else {
+            targets = [];
+            for (const ref of flows ?? [])
+                targets.push((await (0, lookups_js_1.resolveUiTest)(ctx, workspace, ref)).item);
+        }
+        if (targets.length > 100)
+            throw new errors_js_1.ToolInputError("EXPORT_TOO_MANY", `${targets.length} flows (limit 100 per export).`);
+        const envelope = await ctx.api.exportUiTests((0, uiTestShared_js_1.workspaceIdOf)(targets[0]), { clientIds: targets.map((flow) => flow.clientId), includeDataset }, reveal ?? false);
+        const masked = envelope.flows.flatMap((entry) => (0, summarize_js_1.maskedDatasetKeys)(entry.dataset).map((key) => `${entry.name}: ${key}`));
+        const bytes = (0, truncate_js_1.byteLength)(envelope);
+        if (bytes > EXPORT_MAX_BYTES)
+            throw new errors_js_1.ToolInputError("EXPORT_TOO_LARGE", `The export is ${bytes} bytes (limit ${EXPORT_MAX_BYTES}). Export fewer flows, or from the desktop app.`, { bytes });
+        return (0, shared_js_1.ok)({
+            flows: envelope.flows.map((entry) => ({ name: entry.name, platform: entry.platform, ...(entry.isSubFlow ? { bundledSubFlow: true } : {}) })),
+            connections: (envelope.connections ?? []).map((connection) => ({ refId: connection.refId, name: connection.name, type: connection.type })),
+            bytes,
+            ...(masked.length > 0
+                ? { maskedDatasetValues: masked, note: "Secret dataset values are masked in this envelope — importing it is refused until they are replaced with real values (or export with reveal: true, which needs environments:reveal)." }
+                : includeDataset
+                    ? { note: "Dataset values are included as stored — treat the envelope as sensitive." }
+                    : {}),
+            envelope: envelope,
+        });
+    }));
+    server.registerTool("import_ui_tests", {
+        title: "Import UI tests",
+        description: "Import a `callman.uitest` envelope (the JSON of a .callman.uitest file, as text or object) into a workspace. Connections it references are matched to the workspace's connections of the same type and name automatically; `connections` overrides per export connection (workspace connection id or name, or \"skip\"). dryRun: true shows the flows, name clashes and the connection plan without importing. On-prem, `group` picks the owning group.",
+        inputSchema: {
+            workspace: shared_js_1.workspaceArg,
+            envelope: zod_1.z.union([zod_1.z.string().max(ENVELOPE_MAX), zod_1.z.record(zod_1.z.unknown())]).describe("The envelope (JSON text or object)"),
+            group: zod_1.z.string().max(200).optional().describe('On-prem group (name or id, or "personal")'),
+            connections: zod_1.z
+                .array((0, strict_js_1.strictObject)({
+                from: zod_1.z.string().min(1).max(300).describe("The envelope's connection (refId or name)"),
+                to: zod_1.z.string().min(1).max(200).describe('Workspace connection id or name, or "skip"'),
+            }, "connection mapping field"))
+                .max(200)
+                .optional(),
+            dryRun: shared_js_1.dryRunArg,
+        },
+        annotations: shared_js_1.WRITE,
+    }, (0, shared_js_1.guarded)(async ({ workspace, envelope, group, connections: mapping, dryRun }) => {
+        const ws = await ctx.resolveWorkspace(workspace);
+        let parsed = envelope;
+        if (typeof envelope === "string") {
+            try {
+                parsed = JSON.parse(envelope);
+            }
+            catch {
+                throw new errors_js_1.ToolInputError("IMPORT_INVALID_JSON", "The envelope is not valid JSON.");
+            }
+        }
+        const record = parsed;
+        if (record?.kind !== "callman.uitest") {
+            throw new errors_js_1.ToolInputError("IMPORT_NOT_UI_TESTS", `This is not a UI-test export (expected kind: "callman.uitest"${record?.kind ? `, got "${String(record.kind)}"` : ""}).${record?.kind === "callman.scenario" ? " Use import_scenario." : ""}`);
+        }
+        if (!Array.isArray(record.flows) || record.flows.length === 0)
+            throw new errors_js_1.ToolInputError("IMPORT_EMPTY", "The envelope has no flows.");
+        const masked = record.flows.flatMap((entry) => (0, summarize_js_1.maskedDatasetKeys)(entry.dataset).map((key) => `${entry.name}: ${key}`));
+        if (masked.length > 0) {
+            throw new errors_js_1.ToolInputError("MASKED_VALUE", `The envelope carries masked dataset values (${masked.join(", ")}) — replace them with the real values, or export again with reveal: true (needs environments:reveal).`, { keys: masked });
+        }
+        const exported = (record.connections ?? []).filter((connection) => connection.refId);
+        for (const entry of mapping ?? []) {
+            if (!exported.some((connection) => connection.refId === entry.from || connection.name === entry.from)) {
+                throw new errors_js_1.ToolInputError("IMPORT_CONNECTION_UNKNOWN", `The envelope has no connection "${entry.from}".`, { exportConnections: exported.map((connection) => ({ refId: connection.refId, name: connection.name, type: connection.type })) });
+            }
+        }
+        const available = exported.length > 0 ? await (0, lookups_js_1.loadConnections)(ctx, ws.id) : [];
+        const decisions = [];
+        const connectionMap = {};
+        for (const connection of exported) {
+            const override = (mapping ?? []).find((entry) => entry.from === connection.refId || entry.from === connection.name);
+            let target;
+            if (override && override.to.trim().toLowerCase() !== "skip") {
+                target = available.find((candidate) => candidate.id === override.to) ?? available.find((candidate) => candidate.name.toLowerCase() === override.to.toLowerCase());
+                if (!target)
+                    throw new errors_js_1.ToolInputError("CONNECTION_NOT_FOUND", `No workspace connection "${override.to}" (list_connections shows them).`);
+                if (connection.type && target.type !== connection.type)
+                    throw new errors_js_1.ToolInputError("CONNECTION_WRONG_TYPE", `"${target.name}" is a ${target.type} connection; the envelope's "${connection.name}" is ${connection.type}.`);
+            }
+            else if (!override) {
+                const sameName = available.filter((candidate) => candidate.type === connection.type && candidate.name.toLowerCase() === (connection.name ?? "").toLowerCase());
+                target = sameName.length === 1 ? sameName[0] : undefined;
+            }
+            connectionMap[connection.refId] = target ? { action: "map", connectionId: target.id } : { action: "skip" };
+            decisions.push({ export: connection.name ?? connection.refId, type: connection.type ?? null, mappedTo: target ? target.name : null });
+        }
+        const existingNames = new Set((await (0, lookups_js_1.loadUiTests)(ctx)).filter((flow) => flow.workspaceId === ws.id).map((flow) => flow.name.toLowerCase()));
+        const clashes = record.flows.filter((flow) => existingNames.has(String(flow.name).toLowerCase())).map((flow) => flow.name);
+        const targetGroup = await (0, uiTestShared_js_1.resolveGroupId)(ctx, ws.id, group);
+        if (dryRun) {
+            return (0, shared_js_1.ok)({
+                dryRun: true,
+                workspace: (0, lookups_js_1.workspaceTag)(ws),
+                flows: record.flows.map((flow) => ({ name: flow.name, platform: flow.platform, ...(flow.isSubFlow ? { bundledSubFlow: true } : {}) })),
+                connections: decisions,
+                ...(clashes.length > 0 ? { nameClashes: clashes, note: "Flows with these names already exist in the workspace — the server resolves clashes (see its warnings after the import)." } : {}),
+            });
+        }
+        const result = await ctx.api.importUiTests(ws.id, { envelope: parsed, connectionMap, ...(targetGroup.id ? { groupId: targetGroup.id } : {}) });
+        ctx.invalidate("uitests:");
+        const skipped = decisions.filter((decision) => !decision.mappedTo);
+        return (0, shared_js_1.ok)({
+            workspace: (0, lookups_js_1.workspaceTag)(ws),
+            imported: result.flows.map((flow) => ({ id: flow.clientId, name: flow.name, platform: flow.platform })),
+            connections: decisions,
+            warnings: [...(result.warnings ?? []), ...(targetGroup.note ? [targetGroup.note] : [])],
+            ...(skipped.length > 0 ? { note: `Not connected: ${skipped.map((decision) => decision.export).join(", ")} — data steps using them need a workspace connection (validate_ui_test shows which; fix with patch_ui_test_steps).` } : {}),
+        });
+    }));
+};
+exports.registerUiTestAdminTools = registerUiTestAdminTools;