callman-mcp 0.3.0 → 0.5.0

package/dist/tools/uiTests.js

@@ -0,0 +1,572 @@
+import { randomUUID } from "node:crypto";
+import { setPreconditions } from "callman-core";
+import { z } from "zod";
+import { CallmanApiError, ToolInputError } from "../client/errors.js";
+import { resolvedSummary } from "../domain/resolve.js";
+import { applyStepOps, composeFlow, ownSteps, splitFlow, joinFlow, setHeaderValue, stepsToYaml } from "../domain/uiTest/compose.js";
+import { flowSummaryView } from "../domain/uiTest/summarize.js";
+import { sliceWithCursor } from "../lib/pagination.js";
+import { strictObject } from "../lib/strict.js";
+import { LIMITS } from "../lib/truncate.js";
+import { isAllWorkspaces, loadUiTestFolders, loadUiTests, resolveUiTest, resolveUiTestFolder, uiTestFolderSubtree, workspaceTag } from "./lookups.js";
+import { confirmArg, cursorArgs, DESTRUCTIVE, dryRunArg, failureOf, guarded, IDEMPOTENT_WRITE, ok, READ, refArg, requireConfirm, workspaceArg, WRITE } from "./shared.js";
+import { conflictResult, datasetSourceSchema, flowArg, flowDetailView, groupArg, headerArg, lintContext, lintFlow, lintView, platformArg, refuseLintErrors, refuseMaskedDataset, resolveDatasetSources, resolveGroupId, runSettingsSchema, saveFlow, SEVERITIES, stepInputSchema, stepsArg, TEST_TYPES, upsertBodyOf, workspaceIdOf, } from "./uiTestShared.js";
+// UI tests (web / Android / iOS flows): the flow library and its folders.
+// A flow is YAML text — header (url / appId …), `---`, steps — stored whole;
+// every write sends the flow's full state (the backend upserts by clientId),
+// linted with callman-core's lintUiTestFlow against the library (runFlow
+// names) and the workspace's connections before it is saved.
+const REVIEW_STATUSES = ["draft", "pending_review", "approved", "changes_requested"];
+const flowFields = {
+    description: z.string().max(5000).nullable().optional(),
+    testType: z.enum(TEST_TYPES).nullable().optional(),
+    severity: z.enum(SEVERITIES).nullable().optional(),
+    tags: z.array(z.string().trim().min(1).max(50)).max(30).optional(),
+    dismissPopups: z.array(z.string().trim().min(1).max(200)).max(50).optional().describe("Mobile: popup texts dismissed automatically during runs"),
+    browserKind: z.enum(["chrome", "firefox", "webkit"]).nullable().optional().describe("Web: browser for desktop runs (the server runner is Chromium)"),
+    headless: z.boolean().nullable().optional().describe("Web: headless desktop runs"),
+    runSettings: runSettingsSchema.nullable().optional(),
+};
+const refuseCrossPlatformHeader = (platform, url, appId) => {
+    if (platform === "web" && appId)
+        throw new ToolInputError("ARG_PLATFORM_MISMATCH", "appId is for android/ios flows — a web flow starts at `url`.");
+    if (platform !== "web" && url)
+        throw new ToolInputError("ARG_PLATFORM_MISMATCH", "url is for web flows — a mobile flow names its app with `appId`.");
+};
+const nameTaken = (flows, workspaceId, name, except) => flows.find((flow) => flow.workspaceId === workspaceId && flow.clientId !== except && flow.name.trim().toLowerCase() === name.trim().toLowerCase());
+const callsFlow = (content, name) => new RegExp(`^[ \\t]*-[ \\t]+runFlow:[ \\t]+["']${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}["'][ \\t]*$`, "m").test(content);
+const datasetKeysOf = (flow) => [...Object.keys(flow.dataset ?? {}), ...Object.keys(flow.datasetSources ?? {})];
+const draftNote = (before, after) => {
+    if (!before && after.reviewStatus === "draft")
+        return "Saved as a draft. On-prem, schedules run the APPROVED version — submit_ui_test and have it approved; runs you start yourself (run_ui_test) use the current content.";
+    if (before?.reviewStatus === "approved" && after.reviewStatus && after.reviewStatus !== "approved")
+        return "The flow was approved and is now a draft again; schedules keep running the last approved version until it is re-approved (submit_ui_test).";
+    return undefined;
+};
+export const registerUiTestTools = (server, ctx) => {
+    server.registerTool("list_ui_tests", {
+        title: "List UI tests",
+        description: "List UI tests (web / Android / iOS flows) across your workspaces (on-prem: your groups): platform, folder path, tags, type, severity, version and review status. Filters: platform, folder (subfolders included; null = root only), tag, search (name/description), reviewStatus, awaitingMyReview (on-prem: flows waiting for YOUR approval). get_ui_test reads one with its steps.",
+        inputSchema: {
+            workspace: workspaceArg,
+            platform: platformArg.optional(),
+            folder: z.string().max(300).nullable().optional().describe("Folder id, name or path (A/B); null = only flows at the root"),
+            tag: z.string().max(50).optional(),
+            search: z.string().max(200).optional(),
+            reviewStatus: z.enum(REVIEW_STATUSES).optional(),
+            awaitingMyReview: z.boolean().optional(),
+            ...cursorArgs,
+        },
+        annotations: READ,
+    }, guarded(async ({ workspace, platform, folder, tag, search, reviewStatus, awaitingMyReview, cursor, limit }) => {
+        const ws = workspace && !isAllWorkspaces(workspace) ? await ctx.resolveWorkspace(workspace) : null;
+        let note;
+        let flows;
+        if (awaitingMyReview) {
+            try {
+                flows = await ctx.api.uiTestsAwaitingReview();
+            }
+            catch (error) {
+                if (!(error instanceof CallmanApiError && error.code === "REVIEW_DISABLED_CLOUD"))
+                    throw error;
+                flows = [];
+                note = "There is no review workflow on Callman cloud — nothing awaits approval.";
+            }
+        }
+        else {
+            flows = await loadUiTests(ctx);
+        }
+        const [folders, workspaces] = await Promise.all([loadUiTestFolders(ctx).catch(() => []), ctx.listWorkspaces()]);
+        const folderPath = new Map(folders.map((entry) => [entry.id, entry.path]));
+        const scope = folder ? uiTestFolderSubtree(folders, (await resolveUiTestFolder(ctx, workspace, folder)).item.id) : null;
+        const needle = search?.trim().toLowerCase();
+        const wantedTag = tag?.trim().toLowerCase();
+        const filtered = flows
+            .filter((flow) => !ws || flow.workspaceId === ws.id)
+            .filter((flow) => !platform || flow.platform === platform)
+            .filter((flow) => (folder === null ? !flow.folderId : !scope || (flow.folderId ? scope.has(flow.folderId) : false)))
+            .filter((flow) => !wantedTag || (flow.tags ?? []).some((entry) => entry.toLowerCase() === wantedTag))
+            .filter((flow) => !needle || flow.name.toLowerCase().includes(needle) || (flow.description ?? "").toLowerCase().includes(needle))
+            .filter((flow) => !reviewStatus || flow.reviewStatus === reviewStatus)
+            .sort((a, b) => a.name.localeCompare(b.name));
+        const page = sliceWithCursor(filtered, cursor, limit, JSON.stringify([ws?.id, platform, folder, wantedTag, needle, reviewStatus, awaitingMyReview]));
+        const workspaceName = new Map(workspaces.map((entry) => [entry.id, entry.name]));
+        return ok({
+            ...(ws ? { workspace: workspaceTag(ws) } : {}),
+            uiTests: page.items.map((flow) => ({
+                ...flowSummaryView(flow, flow.folderId ? (folderPath.get(flow.folderId) ?? null) : null),
+                ...(workspaces.length > 1 ? { workspace: { id: flow.workspaceId, name: workspaceName.get(flow.workspaceId) ?? null } } : {}),
+            })),
+            total: page.total,
+            nextCursor: page.nextCursor,
+            ...(note ? { note } : {}),
+        });
+    }));
+    server.registerTool("get_ui_test", {
+        title: "Get a UI test",
+        description: "Read one UI test: header (url / appId …), settings (browser, headless, popups, run settings), dataset (secret-looking values masked unless reveal: true with environments:reveal), dataset sources, precondition sub-flows, the numbered top-level steps (numbers patch_ui_test_steps uses), a lint result and the raw YAML `content`.",
+        inputSchema: {
+            workspace: workspaceArg,
+            flow: flowArg,
+            reveal: z.boolean().optional().describe("Return secret dataset values unmasked (needs environments:reveal)"),
+            includeContent: z.boolean().default(true).describe("false = leave the raw YAML out"),
+        },
+        annotations: READ,
+    }, guarded(async ({ workspace, flow, reveal, includeContent }) => {
+        const resolved = await resolveUiTest(ctx, workspace, flow);
+        const fresh = await ctx.api.getUiTest(resolved.item.clientId, reveal ?? false);
+        const context = await lintContext(ctx, workspaceIdOf(fresh));
+        const lint = lintFlow(fresh.content ?? "", fresh.platform, context, datasetKeysOf(fresh));
+        return ok({
+            uiTest: await flowDetailView(ctx, fresh, lint, context, { workspaces: await ctx.listWorkspaces(), reveal, includeContent }),
+            ...(resolved.annotation ? { resolved: [resolvedSummary(flow, resolved)] } : {}),
+        });
+    }));
+    server.registerTool("validate_ui_test", {
+        title: "Validate a UI test",
+        description: "Lint a flow without saving: YAML syntax, header (web needs url, mobile needs appId), unknown steps, missing arguments, steps the platform cannot run, runFlow names the library does not have, connection names the workspace does not have, {{placeholders}} nothing fills. Pass `content` (+ platform) to check a draft, or `flow` to check a saved one (with `content` it checks that text in the flow's context).",
+        inputSchema: {
+            workspace: workspaceArg,
+            flow: flowArg.optional(),
+            content: z.string().max(1_000_000).optional().describe("Full flow YAML (header, ---, steps)"),
+            platform: platformArg.optional(),
+            datasetKeys: z.array(z.string().max(200)).max(500).optional().describe("Dataset keys the flow will have (for the placeholder check)"),
+        },
+        annotations: READ,
+    }, guarded(async ({ workspace, flow, content, platform, datasetKeys }) => {
+        if (!flow && content === undefined)
+            throw new ToolInputError("VALIDATE_NOTHING", "Pass `content` (+ platform) or `flow`.");
+        let target = null;
+        if (flow)
+            target = await ctx.api.getUiTest((await resolveUiTest(ctx, workspace, flow)).item.clientId);
+        const effectivePlatform = platform ?? target?.platform;
+        if (!effectivePlatform)
+            throw new ToolInputError("PLATFORM_REQUIRED", "Pass `platform` (web, android or ios) with `content`.");
+        const ws = target ? target.workspaceId : (await ctx.resolveWorkspace(workspace)).id;
+        const context = await lintContext(ctx, ws);
+        const text = content ?? target?.content ?? "";
+        const lint = lintFlow(text, effectivePlatform, context, datasetKeys ?? (target ? datasetKeysOf(target) : []));
+        return ok({
+            ...(target ? { uiTest: { id: target.clientId, name: target.name } } : {}),
+            platform: effectivePlatform,
+            lint: lintView(lint, context),
+            header: lint.header,
+            preconditions: lint.preconditions,
+            steps: lint.steps,
+        });
+    }));
+    server.registerTool("create_ui_test", {
+        title: "Create a UI test",
+        description: "Create a UI test flow. READ callman://docs/ui-tests (concepts) and callman://docs/ui-test-steps (every step and its arguments) first. Give `platform`, `url` (web) or `appId` (android/ios), `steps` (YAML list or array of step objects) and optionally `preconditions` (names of existing flows that run first, e.g. Login — written as leading runFlow steps) — or the whole YAML as `content`. Data steps (dbQuery, apiCall, kafkaPublish/kafkaCheck, redisCheck) name workspace connections (list_connections). `{{key}}` placeholders come from `dataset` (or `datasetSources`: a DB query per key). The flow is linted against the library and connections: errors refuse the save unless force: true; dryRun: true returns the composed YAML and the lint result without saving. Names must be unique in the workspace (runFlow references flows by name).",
+        inputSchema: {
+            workspace: workspaceArg,
+            name: z.string().trim().min(1).max(200),
+            platform: platformArg,
+            folder: z.string().max(300).optional().describe("UI-test folder id, name or path"),
+            group: groupArg,
+            url: z.string().max(2000).optional().describe("Web: the entry URL ({{dataset}} placeholders allowed)"),
+            appId: z.string().max(300).optional().describe("Android package / iOS bundle id"),
+            header: headerArg,
+            preconditions: z.array(z.string().min(1).max(200)).max(20).optional().describe("Names of flows that run first (exact names)"),
+            steps: stepsArg.optional(),
+            content: z.string().max(1_000_000).optional().describe("The whole flow YAML instead of url/appId/header/preconditions/steps"),
+            ...flowFields,
+            dataset: z.record(z.string().max(10_000)).optional().describe("Test data: key → value, used as {{key}}"),
+            datasetSources: z.record(datasetSourceSchema).optional().describe("key → { connection, query, column? }: the value comes from a DB query at run time"),
+            force: z.boolean().optional().describe("Save even when the linter reports errors"),
+            dryRun: dryRunArg,
+        },
+        annotations: WRITE,
+    }, guarded(async ({ workspace, name, platform, folder, group, url, appId, header, preconditions, steps, content, dataset, datasetSources, force, dryRun, ...fields }) => {
+        if (content !== undefined && (steps !== undefined || url !== undefined || appId !== undefined || header !== undefined || preconditions !== undefined)) {
+            throw new ToolInputError("CONTENT_EXCLUSIVE", "Pass either `content` (the whole YAML) or url/appId/header/preconditions/steps — not both.");
+        }
+        refuseCrossPlatformHeader(platform, url, appId);
+        const targetFolder = folder ? await resolveUiTestFolder(ctx, workspace, folder) : null;
+        const ws = targetFolder ? { id: targetFolder.item.workspaceId } : await ctx.resolveWorkspace(workspace);
+        const existing = nameTaken(await loadUiTests(ctx), ws.id, name);
+        if (existing) {
+            throw new ToolInputError("UI_TEST_NAME_EXISTS", `A UI test named "${existing.name}" already exists in this workspace (id ${existing.clientId}) — runFlow finds flows by name, so names must be unique. Update it (update_ui_test) or pick another name.`, { existing: { id: existing.clientId, name: existing.name } });
+        }
+        const composed = content ??
+            composeFlow({
+                header: { ...(url ? { url } : {}), ...(appId ? { appId } : {}), ...(header ?? {}) },
+                preconditions,
+                steps: steps !== undefined ? stepsToYaml(steps) : "",
+            });
+        const sources = datasetSources ? await resolveDatasetSources(ctx, ws.id, datasetSources) : undefined;
+        const context = await lintContext(ctx, ws.id);
+        const lint = lintFlow(composed, platform, context, [...Object.keys(dataset ?? {}), ...Object.keys(sources ?? {})]);
+        if (dryRun)
+            return ok({ dryRun: true, uiTest: { name, platform, content: composed, steps: lint.steps, preconditions: lint.preconditions }, lint: lintView(lint, context) });
+        refuseLintErrors(lint, force, composed);
+        refuseMaskedDataset(dataset);
+        const targetGroup = await resolveGroupId(ctx, ws.id, group);
+        const body = {
+            clientId: randomUUID(),
+            name: name.trim(),
+            platform,
+            content: composed,
+            tags: fields.tags ?? [],
+            dataset: dataset ?? {},
+            folderId: targetFolder?.item.id ?? null,
+            ...(fields.description !== undefined ? { description: fields.description } : {}),
+            ...(fields.testType ? { testType: fields.testType } : {}),
+            ...(fields.severity ? { severity: fields.severity } : {}),
+            ...(sources ? { datasetSources: sources } : {}),
+            ...(fields.dismissPopups ? { dismissPopups: fields.dismissPopups } : {}),
+            ...(fields.browserKind !== undefined ? { browserKind: fields.browserKind } : {}),
+            ...(fields.headless !== undefined ? { headless: fields.headless } : {}),
+            ...(fields.runSettings !== undefined ? { runSettings: fields.runSettings } : {}),
+            ...(targetGroup.id ? { groupId: targetGroup.id } : {}),
+        };
+        const saved = await saveFlow(ctx, ws.id, body);
+        if ("conflict" in saved)
+            return conflictResult(saved.conflict);
+        const note = draftNote(null, saved.flow);
+        const warnings = [...lint.warnings.map((issue) => `${issue.step ? `step ${issue.step}: ` : ""}${issue.message}`), ...(targetGroup.note ? [targetGroup.note] : [])];
+        return ok({
+            uiTest: { ...flowSummaryView(saved.flow, targetFolder?.item.path ?? null), stepCount: lint.steps.length },
+            lint: lintView(lint, context),
+            ...(warnings.length > 0 ? { warnings } : {}),
+            note: note ?? "Created. Run it with run_ui_test (list_ui_test_devices shows where it can run).",
+            ...(targetFolder ? { resolved: [resolvedSummary(folder, targetFolder)] } : {}),
+        });
+    }));
+    server.registerTool("update_ui_test", {
+        title: "Update a UI test",
+        description: "Change any part of a UI test: rename, description, type/severity/tags, folder (null = root), platform, url / appId / header keys, preconditions (the leading runFlow steps), `steps` (replaces the flow's own steps, preconditions kept) or the whole `content`, dataset (merged: a key set to null is removed), datasetSources (merged the same way), popups, browser, headless, run settings. For step-level edits prefer patch_ui_test_steps. Linted like create_ui_test when the YAML or platform changes (errors refuse unless force: true). Version-checked: pass the `version` you read (expectedVersion) or it is read first; a conflict comes back structured. Secret dataset values: the flow is saved whole, so masked values must be revealed (environments:reveal) or re-supplied.",
+        inputSchema: {
+            workspace: workspaceArg,
+            flow: flowArg,
+            expectedVersion: z.number().int().min(1).optional(),
+            force: z.boolean().optional().describe("Save despite lint errors, and overwrite even if someone saved since expectedVersion"),
+            name: z.string().trim().min(1).max(200).optional(),
+            platform: platformArg.optional(),
+            folder: z.string().max(300).nullable().optional().describe("UI-test folder id, name or path; null = root"),
+            url: z.string().max(2000).nullable().optional(),
+            appId: z.string().max(300).nullable().optional(),
+            header: headerArg,
+            preconditions: z.array(z.string().min(1).max(200)).max(20).optional(),
+            steps: stepsArg.optional(),
+            content: z.string().max(1_000_000).optional(),
+            ...flowFields,
+            dataset: z.record(z.string().max(10_000).nullable()).optional().describe("Keys to set (null removes a key); other keys are kept"),
+            datasetSources: z.record(datasetSourceSchema.nullable()).optional().describe("Sources to set (null removes one); others are kept"),
+            dryRun: dryRunArg,
+        },
+        annotations: IDEMPOTENT_WRITE,
+    }, guarded(async ({ workspace, flow, expectedVersion, force, name, platform, folder, url, appId, header, preconditions, steps, content, dataset, datasetSources, dryRun, ...fields }) => {
+        if (content !== undefined && (steps !== undefined || url !== undefined || appId !== undefined || header !== undefined || preconditions !== undefined)) {
+            throw new ToolInputError("CONTENT_EXCLUSIVE", "Pass either `content` (the whole YAML) or url/appId/header/preconditions/steps — not both.");
+        }
+        const resolved = await resolveUiTest(ctx, workspace, flow);
+        const current = await ctx.api.getUiTest(resolved.item.clientId, true);
+        const ws = workspaceIdOf(current);
+        const nextPlatform = platform ?? current.platform;
+        refuseCrossPlatformHeader(nextPlatform, url, appId);
+        let nextContent = current.content ?? "";
+        if (content !== undefined)
+            nextContent = content;
+        if (url !== undefined || appId !== undefined || header !== undefined) {
+            const parts = splitFlow(nextContent);
+            let head = parts.head;
+            if (url !== undefined)
+                head = setHeaderValue(head, "url", url);
+            if (appId !== undefined)
+                head = setHeaderValue(head, "appId", appId);
+            for (const [key, value] of Object.entries(header ?? {}))
+                head = setHeaderValue(head, key, value);
+            nextContent = joinFlow(head, parts.body);
+        }
+        if (steps !== undefined) {
+            const own = ownSteps(nextContent);
+            nextContent = composeFlow({ head: splitFlow(nextContent).head, preconditions: preconditions ?? own.preconditions, steps: stepsToYaml(steps) });
+        }
+        else if (preconditions !== undefined) {
+            nextContent = setPreconditions(nextContent, preconditions);
+        }
+        const targetFolder = folder ? await resolveUiTestFolder(ctx, workspace ?? ws, folder) : null;
+        if (targetFolder && targetFolder.item.workspaceId !== ws) {
+            throw new ToolInputError("UI_TEST_FOLDER_OTHER_WORKSPACE", `Folder "${targetFolder.item.path}" is in another workspace than the flow.`);
+        }
+        const warnings = [];
+        if (name !== undefined && name.trim() !== current.name) {
+            const taken = nameTaken(await loadUiTests(ctx), ws, name, current.clientId);
+            if (taken)
+                throw new ToolInputError("UI_TEST_NAME_EXISTS", `A UI test named "${taken.name}" already exists in this workspace.`, { existing: { id: taken.clientId, name: taken.name } });
+            const callers = (await ctx.api.listUiTests(false).catch(() => [])).filter((entry) => entry.clientId !== current.clientId && callsFlow(entry.content ?? "", current.name));
+            if (callers.length > 0)
+                warnings.push(`These flows call "${current.name}" with runFlow and will not find it under the new name: ${callers.map((entry) => entry.name).join(", ")} — update them too.`);
+        }
+        const mergedDataset = { ...(current.dataset ?? {}) };
+        for (const [key, value] of Object.entries(dataset ?? {})) {
+            if (value === null)
+                delete mergedDataset[key];
+            else
+                mergedDataset[key] = value;
+        }
+        const sources = datasetSources ? await resolveDatasetSources(ctx, ws, datasetSources, current.datasetSources ?? {}) : current.datasetSources;
+        const next = {
+            ...current,
+            ...(name !== undefined ? { name: name.trim() } : {}),
+            platform: nextPlatform,
+            content: nextContent,
+            dataset: mergedDataset,
+            ...(sources !== undefined ? { datasetSources: sources } : {}),
+            ...(folder !== undefined ? { folderId: targetFolder?.item.id ?? null } : {}),
+            ...Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined)),
+        };
+        const body = upsertBodyOf(next);
+        const changed = Object.keys(body).filter((key) => JSON.stringify(body[key]) !== JSON.stringify(upsertBodyOf(current)[key]));
+        if (changed.length === 0)
+            throw new ToolInputError("NOTHING_TO_UPDATE", "Nothing would change — pass at least one field with a new value.");
+        const context = await lintContext(ctx, ws);
+        const lint = lintFlow(nextContent, nextPlatform, context, datasetKeysOf(next));
+        if (dryRun)
+            return ok({ dryRun: true, uiTest: { id: current.clientId, name: next.name, version: current.version ?? null }, changed, content: nextContent, lint: lintView(lint, context), ...(warnings.length > 0 ? { warnings } : {}) });
+        if (changed.includes("content") || changed.includes("platform"))
+            refuseLintErrors(lint, force, nextContent);
+        // Masks read from the flow go back as-is (the backend keeps the stored
+        // secret for an unchanged mask); only values the caller typed are checked.
+        refuseMaskedDataset(Object.fromEntries(Object.entries(dataset ?? {}).filter(([, value]) => value !== null)));
+        const saved = await saveFlow(ctx, ws, body, { expectedVersion: expectedVersion ?? current.version, force });
+        if ("conflict" in saved)
+            return conflictResult(saved.conflict);
+        const note = draftNote(current, saved.flow);
+        const folders = await loadUiTestFolders(ctx).catch(() => []);
+        return ok({
+            uiTest: { ...flowSummaryView(saved.flow, saved.flow.folderId ? (folders.find((entry) => entry.id === saved.flow.folderId)?.path ?? null) : null), stepCount: lint.steps.length },
+            previousVersion: current.version ?? null,
+            changed,
+            lint: lintView(lint, context),
+            ...(warnings.length > 0 ? { warnings } : {}),
+            ...(note ? { note } : {}),
+            ...(resolved.annotation ? { resolved: [resolvedSummary(flow, resolved)] } : {}),
+        });
+    }));
+    server.registerTool("patch_ui_test_steps", {
+        title: "Edit a UI test's steps",
+        description: "Edit steps in place without resending the flow. Step numbers are the 1-based top-level steps get_ui_test lists (precondition runFlow lines included), applied in order — each op sees the result of the previous one. Ops: insert { at, steps } (before step `at`; stepCount+1 appends), replace { at, step }, remove { at } or { from, to }, move { from, to }, setLabel { at, label }. Untouched steps keep their exact text. Linted after the edit (errors refuse unless force: true); dryRun: true returns the new YAML. Version-checked like update_ui_test.",
+        inputSchema: {
+            workspace: workspaceArg,
+            flow: flowArg,
+            expectedVersion: z.number().int().min(1).optional(),
+            force: z.boolean().optional().describe("Save despite lint errors, and overwrite even if someone saved since expectedVersion"),
+            ops: z
+                .array(z.discriminatedUnion("op", [
+                strictObject({ op: z.literal("insert"), at: z.number().int().min(1), steps: z.array(stepInputSchema).min(1).max(200) }, "field", "insert ops"),
+                strictObject({ op: z.literal("replace"), at: z.number().int().min(1), step: stepInputSchema }, "field", "replace ops"),
+                strictObject({ op: z.literal("remove"), at: z.number().int().min(1).optional(), from: z.number().int().min(1).optional(), to: z.number().int().min(1).optional() }, "field", "remove ops"),
+                strictObject({ op: z.literal("move"), from: z.number().int().min(1), to: z.number().int().min(1) }, "field", "move ops"),
+                strictObject({ op: z.literal("setLabel"), at: z.number().int().min(1), label: z.string().trim().min(1).max(200) }, "field", "setLabel ops"),
+            ]))
+                .min(1)
+                .max(200),
+            dryRun: dryRunArg,
+        },
+        annotations: IDEMPOTENT_WRITE,
+    }, guarded(async ({ workspace, flow, expectedVersion, force, ops, dryRun }) => {
+        for (const op of ops) {
+            if (op.op === "remove" && (op.at === undefined) === (op.from === undefined))
+                throw new ToolInputError("STEP_RANGE_INVALID", "remove takes `at`, or `from` (+ optional `to`).");
+        }
+        const resolved = await resolveUiTest(ctx, workspace, flow);
+        const current = await ctx.api.getUiTest(resolved.item.clientId, true);
+        const ws = workspaceIdOf(current);
+        const context = await lintContext(ctx, ws);
+        const before = lintFlow(current.content ?? "", current.platform, context, datasetKeysOf(current));
+        if (before.errors.some((issue) => issue.code === "YAML_SYNTAX")) {
+            throw new ToolInputError("UI_TEST_YAML_INVALID", "The stored flow is not valid YAML, so its steps cannot be addressed — replace it with update_ui_test content.", { errors: before.errors });
+        }
+        const patched = applyStepOps(current.content ?? "", ops, before.steps.length);
+        const lint = lintFlow(patched.content, current.platform, context, datasetKeysOf(current));
+        if (dryRun)
+            return ok({ dryRun: true, uiTest: { id: current.clientId, name: current.name, version: current.version ?? null }, content: patched.content, steps: lint.steps, lint: lintView(lint, context) });
+        refuseLintErrors(lint, force, patched.content);
+        const saved = await saveFlow(ctx, ws, upsertBodyOf({ ...current, content: patched.content }), { expectedVersion: expectedVersion ?? current.version, force });
+        if ("conflict" in saved)
+            return conflictResult(saved.conflict);
+        const note = draftNote(current, saved.flow);
+        return ok({
+            uiTest: { id: saved.flow.clientId, name: saved.flow.name, version: saved.flow.version ?? null, ...(saved.flow.reviewStatus ? { reviewStatus: saved.flow.reviewStatus } : {}) },
+            previousVersion: current.version ?? null,
+            steps: lint.steps,
+            lint: lintView(lint, context),
+            ...(note ? { note } : {}),
+            ...(resolved.annotation ? { resolved: [resolvedSummary(flow, resolved)] } : {}),
+        });
+    }));
+    server.registerTool("delete_ui_test", {
+        title: "Delete a UI test",
+        description: "Delete a UI test (exact name or id), its schedules and run history. Flows that call it with runFlow stop finding it. Permanent — confirm with the user first.",
+        inputSchema: { workspace: workspaceArg, flow: flowArg, confirm: confirmArg },
+        annotations: DESTRUCTIVE,
+    }, guarded(async ({ workspace, flow, confirm }) => {
+        requireConfirm(confirm, "a UI test");
+        const resolved = await resolveUiTest(ctx, workspace, flow, { exact: true });
+        await ctx.api.deleteUiTest(resolved.item.workspaceId ?? null, resolved.item.clientId);
+        ctx.invalidate("uitests:");
+        return ok({ deleted: { id: resolved.item.clientId, name: resolved.item.name }, resolved: [resolvedSummary(flow, resolved)] });
+    }));
+    // ── folders ──────────────────────────────────────────────────────────
+    server.registerTool("list_ui_test_folders", {
+        title: "List UI-test folders",
+        description: "The UI-test folder tree across your workspaces: id, name, path (A/B — usable as a reference), parent, and how many flows each holds directly and with its subfolders.",
+        inputSchema: { workspace: workspaceArg },
+        annotations: READ,
+    }, guarded(async ({ workspace }) => {
+        const ws = workspace && !isAllWorkspaces(workspace) ? await ctx.resolveWorkspace(workspace) : null;
+        const [folders, flows, workspaces] = await Promise.all([loadUiTestFolders(ctx), loadUiTests(ctx), ctx.listWorkspaces()]);
+        const scoped = folders.filter((folder) => !ws || folder.workspaceId === ws.id).sort((a, b) => a.path.localeCompare(b.path));
+        const direct = new Map();
+        for (const flow of flows)
+            if (flow.folderId)
+                direct.set(flow.folderId, (direct.get(flow.folderId) ?? 0) + 1);
+        const workspaceName = new Map(workspaces.map((entry) => [entry.id, entry.name]));
+        return ok({
+            ...(ws ? { workspace: workspaceTag(ws) } : {}),
+            folders: scoped.slice(0, LIMITS.TREE_ITEMS).map((folder) => ({
+                id: folder.id,
+                name: folder.name,
+                path: folder.path,
+                parentId: folder.parentId,
+                flowCount: direct.get(folder.id) ?? 0,
+                totalFlowCount: [...uiTestFolderSubtree(folders, folder.id)].reduce((sum, id) => sum + (direct.get(id) ?? 0), 0),
+                ...(workspaces.length > 1 ? { workspace: { id: folder.workspaceId, name: workspaceName.get(folder.workspaceId) ?? null } } : {}),
+            })),
+            rootFlowCount: flows.filter((flow) => (!ws || flow.workspaceId === ws.id) && !flow.folderId).length,
+        });
+    }));
+    server.registerTool("create_ui_test_folder", {
+        title: "Create a UI-test folder",
+        description: "Create a UI-test folder at the root or inside `parent` (id, name or path). An existing folder with the same name at that place is returned instead of a duplicate.",
+        inputSchema: {
+            workspace: workspaceArg,
+            name: z.string().trim().min(1).max(120),
+            parent: z.string().max(300).optional().describe("Parent folder id, name or path"),
+            group: groupArg,
+        },
+        annotations: WRITE,
+    }, guarded(async ({ workspace, name, parent, group }) => {
+        const parentFolder = parent ? await resolveUiTestFolder(ctx, workspace, parent) : null;
+        const ws = parentFolder ? { id: parentFolder.item.workspaceId } : await ctx.resolveWorkspace(workspace);
+        const folders = await loadUiTestFolders(ctx);
+        const sibling = folders.find((folder) => folder.workspaceId === ws.id && folder.parentId === (parentFolder?.item.id ?? null) && folder.name.trim().toLowerCase() === name.trim().toLowerCase());
+        if (sibling)
+            return ok({ folder: { id: sibling.id, name: sibling.name, path: sibling.path }, existed: true, note: "A folder with that name already exists there — returned instead of creating a duplicate." });
+        const targetGroup = await resolveGroupId(ctx, ws.id, group);
+        const siblings = folders.filter((folder) => folder.workspaceId === ws.id && folder.parentId === (parentFolder?.item.id ?? null));
+        const created = await ctx.api.upsertUiTestFolder(ws.id, {
+            clientId: randomUUID(),
+            name: name.trim(),
+            parentId: parentFolder?.item.id ?? null,
+            sortOrder: siblings.reduce((max, folder) => Math.max(max, folder.sortOrder + 1), 0),
+            ...(targetGroup.id ? { groupId: targetGroup.id } : parentFolder?.item.groupId ? { groupId: parentFolder.item.groupId } : {}),
+        });
+        ctx.invalidate("uitests:");
+        return ok({
+            folder: { id: created.clientId, name: created.name, parentId: created.parentId ?? null, path: parentFolder ? `${parentFolder.item.path}/${created.name}` : created.name },
+            ...(targetGroup.note ? { warnings: [targetGroup.note] } : {}),
+            ...(parentFolder ? { resolved: [resolvedSummary(parent, parentFolder)] } : {}),
+        });
+    }));
+    server.registerTool("update_ui_test_folder", {
+        title: "Rename / move a UI-test folder",
+        description: "Rename a UI-test folder and/or move it under another folder (`parent`: id, name or path; null = root). A folder cannot move into itself or its own subfolders.",
+        inputSchema: {
+            workspace: workspaceArg,
+            folder: refArg("UI-test folder", "(or its path A/B)"),
+            name: z.string().trim().min(1).max(120).optional(),
+            parent: z.string().max(300).nullable().optional(),
+        },
+        annotations: IDEMPOTENT_WRITE,
+    }, guarded(async ({ workspace, folder, name, parent }) => {
+        if (name === undefined && parent === undefined)
+            throw new ToolInputError("NOTHING_TO_UPDATE", "Pass name and/or parent.");
+        const target = await resolveUiTestFolder(ctx, workspace, folder);
+        const parentFolder = parent ? await resolveUiTestFolder(ctx, target.item.workspaceId, parent) : null;
+        if (parentFolder) {
+            if (parentFolder.item.workspaceId !== target.item.workspaceId)
+                throw new ToolInputError("UI_TEST_FOLDER_OTHER_WORKSPACE", "The new parent is in another workspace.");
+            if (uiTestFolderSubtree(await loadUiTestFolders(ctx), target.item.id).has(parentFolder.item.id)) {
+                throw new ToolInputError("FOLDER_CYCLE", `"${target.item.path}" cannot move into itself or one of its subfolders.`);
+            }
+        }
+        const updated = await ctx.api.upsertUiTestFolder(target.item.workspaceId, {
+            clientId: target.item.id,
+            name: name?.trim() ?? target.item.name,
+            parentId: parent === undefined ? target.item.parentId : (parentFolder?.item.id ?? null),
+            sortOrder: target.item.sortOrder,
+            ...(target.item.groupId ? { groupId: target.item.groupId } : {}),
+        });
+        ctx.invalidate("uitests:");
+        const refreshed = (await loadUiTestFolders(ctx)).find((entry) => entry.id === updated.clientId);
+        return ok({
+            folder: { id: updated.clientId, name: updated.name, parentId: updated.parentId ?? null, path: refreshed?.path ?? updated.name },
+            resolved: [resolvedSummary(folder, target), ...(parentFolder ? [resolvedSummary(parent, parentFolder)] : [])],
+        });
+    }));
+    server.registerTool("delete_ui_test_folder", {
+        title: "Delete a UI-test folder",
+        description: "Delete a UI-test folder (exact name, path or id) and its subfolders. The flows inside are NOT deleted — they move to the root. Confirm with the user first.",
+        inputSchema: { workspace: workspaceArg, folder: refArg("UI-test folder", "(or its path A/B)"), confirm: confirmArg },
+        annotations: DESTRUCTIVE,
+    }, guarded(async ({ workspace, folder, confirm }) => {
+        requireConfirm(confirm, "a UI-test folder");
+        const target = await resolveUiTestFolder(ctx, workspace, folder, { exact: true });
+        const [folders, flows] = await Promise.all([loadUiTestFolders(ctx), loadUiTests(ctx)]);
+        const subtree = uiTestFolderSubtree(folders, target.item.id);
+        const moved = flows.filter((flow) => flow.folderId && subtree.has(flow.folderId)).map((flow) => flow.name);
+        await ctx.api.deleteUiTestFolder(target.item.workspaceId, target.item.id);
+        ctx.invalidate("uitests:");
+        return ok({
+            deleted: { id: target.item.id, name: target.item.name, path: target.item.path, subfolders: subtree.size - 1 },
+            movedToRoot: moved,
+            resolved: [resolvedSummary(folder, target)],
+        });
+    }));
+    server.registerTool("move_ui_tests", {
+        title: "Move UI tests to a folder",
+        description: "Move UI tests (ids or names) into a folder (id, name or path) or to the root (folder: null). Each flow is saved with its new folder; failures are reported per flow.",
+        inputSchema: {
+            workspace: workspaceArg,
+            flows: z.array(flowArg).min(1).max(200),
+            folder: z.string().max(300).nullable().describe("Target folder id, name or path; null = root"),
+        },
+        annotations: IDEMPOTENT_WRITE,
+    }, guarded(async ({ workspace, flows, folder }) => {
+        const target = folder ? await resolveUiTestFolder(ctx, workspace, folder) : null;
+        const moved = [];
+        const unchanged = [];
+        const failed = [];
+        for (const ref of flows) {
+            try {
+                const resolved = await resolveUiTest(ctx, workspace, ref);
+                if (target && target.item.workspaceId !== resolved.item.workspaceId)
+                    throw new ToolInputError("UI_TEST_FOLDER_OTHER_WORKSPACE", `"${resolved.item.name}" is in another workspace than folder "${target.item.path}".`);
+                const nextFolder = target?.item.id ?? null;
+                if ((resolved.item.folderId ?? null) === nextFolder) {
+                    unchanged.push(resolved.item.name);
+                    continue;
+                }
+                const current = await ctx.api.getUiTest(resolved.item.clientId, true);
+                const saved = await saveFlow(ctx, workspaceIdOf(current), upsertBodyOf({ ...current, folderId: nextFolder }), { expectedVersion: current.version });
+                if ("conflict" in saved)
+                    throw new ToolInputError("UI_TEST_SCENARIO_VERSION_CONFLICT", String(saved.conflict.message));
+                moved.push({ id: saved.flow.clientId, name: saved.flow.name });
+            }
+            catch (error) {
+                failed.push({ flow: ref, error: failureOf(error) });
+            }
+        }
+        return ok({
+            folder: target ? { id: target.item.id, path: target.item.path } : null,
+            moved,
+            ...(unchanged.length > 0 ? { alreadyThere: unchanged } : {}),
+            failed,
+            ...(target ? { resolved: [resolvedSummary(folder, target)] } : {}),
+        });
+    }));
+};
+//# sourceMappingURL=uiTests.js.map