callman-mcp 0.3.0 → 0.5.0

package/dist-cjs/tools/uiTests.js

@@ -0,0 +1,575 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerUiTestTools = void 0;
+const node_crypto_1 = require("node:crypto");
+const callman_core_1 = require("callman-core");
+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 pagination_js_1 = require("../lib/pagination.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");
+// 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: zod_1.z.string().max(5000).nullable().optional(),
+    testType: zod_1.z.enum(uiTestShared_js_1.TEST_TYPES).nullable().optional(),
+    severity: zod_1.z.enum(uiTestShared_js_1.SEVERITIES).nullable().optional(),
+    tags: zod_1.z.array(zod_1.z.string().trim().min(1).max(50)).max(30).optional(),
+    dismissPopups: zod_1.z.array(zod_1.z.string().trim().min(1).max(200)).max(50).optional().describe("Mobile: popup texts dismissed automatically during runs"),
+    browserKind: zod_1.z.enum(["chrome", "firefox", "webkit"]).nullable().optional().describe("Web: browser for desktop runs (the server runner is Chromium)"),
+    headless: zod_1.z.boolean().nullable().optional().describe("Web: headless desktop runs"),
+    runSettings: uiTestShared_js_1.runSettingsSchema.nullable().optional(),
+};
+const refuseCrossPlatformHeader = (platform, url, appId) => {
+    if (platform === "web" && appId)
+        throw new errors_js_1.ToolInputError("ARG_PLATFORM_MISMATCH", "appId is for android/ios flows — a web flow starts at `url`.");
+    if (platform !== "web" && url)
+        throw new errors_js_1.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;
+};
+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: shared_js_1.workspaceArg,
+            platform: uiTestShared_js_1.platformArg.optional(),
+            folder: zod_1.z.string().max(300).nullable().optional().describe("Folder id, name or path (A/B); null = only flows at the root"),
+            tag: zod_1.z.string().max(50).optional(),
+            search: zod_1.z.string().max(200).optional(),
+            reviewStatus: zod_1.z.enum(REVIEW_STATUSES).optional(),
+            awaitingMyReview: zod_1.z.boolean().optional(),
+            ...shared_js_1.cursorArgs,
+        },
+        annotations: shared_js_1.READ,
+    }, (0, shared_js_1.guarded)(async ({ workspace, platform, folder, tag, search, reviewStatus, awaitingMyReview, cursor, limit }) => {
+        const ws = workspace && !(0, lookups_js_1.isAllWorkspaces)(workspace) ? await ctx.resolveWorkspace(workspace) : null;
+        let note;
+        let flows;
+        if (awaitingMyReview) {
+            try {
+                flows = await ctx.api.uiTestsAwaitingReview();
+            }
+            catch (error) {
+                if (!(error instanceof errors_js_1.CallmanApiError && error.code === "REVIEW_DISABLED_CLOUD"))
+                    throw error;
+                flows = [];
+                note = "There is no review workflow on Callman cloud — nothing awaits approval.";
+            }
+        }
+        else {
+            flows = await (0, lookups_js_1.loadUiTests)(ctx);
+        }
+        const [folders, workspaces] = await Promise.all([(0, lookups_js_1.loadUiTestFolders)(ctx).catch(() => []), ctx.listWorkspaces()]);
+        const folderPath = new Map(folders.map((entry) => [entry.id, entry.path]));
+        const scope = folder ? (0, lookups_js_1.uiTestFolderSubtree)(folders, (await (0, lookups_js_1.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 = (0, pagination_js_1.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 (0, shared_js_1.ok)({
+            ...(ws ? { workspace: (0, lookups_js_1.workspaceTag)(ws) } : {}),
+            uiTests: page.items.map((flow) => ({
+                ...(0, summarize_js_1.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: shared_js_1.workspaceArg,
+            flow: uiTestShared_js_1.flowArg,
+            reveal: zod_1.z.boolean().optional().describe("Return secret dataset values unmasked (needs environments:reveal)"),
+            includeContent: zod_1.z.boolean().default(true).describe("false = leave the raw YAML out"),
+        },
+        annotations: shared_js_1.READ,
+    }, (0, shared_js_1.guarded)(async ({ workspace, flow, reveal, includeContent }) => {
+        const resolved = await (0, lookups_js_1.resolveUiTest)(ctx, workspace, flow);
+        const fresh = await ctx.api.getUiTest(resolved.item.clientId, reveal ?? false);
+        const context = await (0, uiTestShared_js_1.lintContext)(ctx, (0, uiTestShared_js_1.workspaceIdOf)(fresh));
+        const lint = (0, uiTestShared_js_1.lintFlow)(fresh.content ?? "", fresh.platform, context, datasetKeysOf(fresh));
+        return (0, shared_js_1.ok)({
+            uiTest: await (0, uiTestShared_js_1.flowDetailView)(ctx, fresh, lint, context, { workspaces: await ctx.listWorkspaces(), reveal, includeContent }),
+            ...(resolved.annotation ? { resolved: [(0, resolve_js_1.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: shared_js_1.workspaceArg,
+            flow: uiTestShared_js_1.flowArg.optional(),
+            content: zod_1.z.string().max(1_000_000).optional().describe("Full flow YAML (header, ---, steps)"),
+            platform: uiTestShared_js_1.platformArg.optional(),
+            datasetKeys: zod_1.z.array(zod_1.z.string().max(200)).max(500).optional().describe("Dataset keys the flow will have (for the placeholder check)"),
+        },
+        annotations: shared_js_1.READ,
+    }, (0, shared_js_1.guarded)(async ({ workspace, flow, content, platform, datasetKeys }) => {
+        if (!flow && content === undefined)
+            throw new errors_js_1.ToolInputError("VALIDATE_NOTHING", "Pass `content` (+ platform) or `flow`.");
+        let target = null;
+        if (flow)
+            target = await ctx.api.getUiTest((await (0, lookups_js_1.resolveUiTest)(ctx, workspace, flow)).item.clientId);
+        const effectivePlatform = platform ?? target?.platform;
+        if (!effectivePlatform)
+            throw new errors_js_1.ToolInputError("PLATFORM_REQUIRED", "Pass `platform` (web, android or ios) with `content`.");
+        const ws = target ? target.workspaceId : (await ctx.resolveWorkspace(workspace)).id;
+        const context = await (0, uiTestShared_js_1.lintContext)(ctx, ws);
+        const text = content ?? target?.content ?? "";
+        const lint = (0, uiTestShared_js_1.lintFlow)(text, effectivePlatform, context, datasetKeys ?? (target ? datasetKeysOf(target) : []));
+        return (0, shared_js_1.ok)({
+            ...(target ? { uiTest: { id: target.clientId, name: target.name } } : {}),
+            platform: effectivePlatform,
+            lint: (0, uiTestShared_js_1.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: shared_js_1.workspaceArg,
+            name: zod_1.z.string().trim().min(1).max(200),
+            platform: uiTestShared_js_1.platformArg,
+            folder: zod_1.z.string().max(300).optional().describe("UI-test folder id, name or path"),
+            group: uiTestShared_js_1.groupArg,
+            url: zod_1.z.string().max(2000).optional().describe("Web: the entry URL ({{dataset}} placeholders allowed)"),
+            appId: zod_1.z.string().max(300).optional().describe("Android package / iOS bundle id"),
+            header: uiTestShared_js_1.headerArg,
+            preconditions: zod_1.z.array(zod_1.z.string().min(1).max(200)).max(20).optional().describe("Names of flows that run first (exact names)"),
+            steps: uiTestShared_js_1.stepsArg.optional(),
+            content: zod_1.z.string().max(1_000_000).optional().describe("The whole flow YAML instead of url/appId/header/preconditions/steps"),
+            ...flowFields,
+            dataset: zod_1.z.record(zod_1.z.string().max(10_000)).optional().describe("Test data: key → value, used as {{key}}"),
+            datasetSources: zod_1.z.record(uiTestShared_js_1.datasetSourceSchema).optional().describe("key → { connection, query, column? }: the value comes from a DB query at run time"),
+            force: zod_1.z.boolean().optional().describe("Save even when the linter reports errors"),
+            dryRun: shared_js_1.dryRunArg,
+        },
+        annotations: shared_js_1.WRITE,
+    }, (0, shared_js_1.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 errors_js_1.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 (0, lookups_js_1.resolveUiTestFolder)(ctx, workspace, folder) : null;
+        const ws = targetFolder ? { id: targetFolder.item.workspaceId } : await ctx.resolveWorkspace(workspace);
+        const existing = nameTaken(await (0, lookups_js_1.loadUiTests)(ctx), ws.id, name);
+        if (existing) {
+            throw new errors_js_1.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 ??
+            (0, compose_js_1.composeFlow)({
+                header: { ...(url ? { url } : {}), ...(appId ? { appId } : {}), ...(header ?? {}) },
+                preconditions,
+                steps: steps !== undefined ? (0, compose_js_1.stepsToYaml)(steps) : "",
+            });
+        const sources = datasetSources ? await (0, uiTestShared_js_1.resolveDatasetSources)(ctx, ws.id, datasetSources) : undefined;
+        const context = await (0, uiTestShared_js_1.lintContext)(ctx, ws.id);
+        const lint = (0, uiTestShared_js_1.lintFlow)(composed, platform, context, [...Object.keys(dataset ?? {}), ...Object.keys(sources ?? {})]);
+        if (dryRun)
+            return (0, shared_js_1.ok)({ dryRun: true, uiTest: { name, platform, content: composed, steps: lint.steps, preconditions: lint.preconditions }, lint: (0, uiTestShared_js_1.lintView)(lint, context) });
+        (0, uiTestShared_js_1.refuseLintErrors)(lint, force, composed);
+        (0, uiTestShared_js_1.refuseMaskedDataset)(dataset);
+        const targetGroup = await (0, uiTestShared_js_1.resolveGroupId)(ctx, ws.id, group);
+        const body = {
+            clientId: (0, node_crypto_1.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 (0, uiTestShared_js_1.saveFlow)(ctx, ws.id, body);
+        if ("conflict" in saved)
+            return (0, uiTestShared_js_1.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 (0, shared_js_1.ok)({
+            uiTest: { ...(0, summarize_js_1.flowSummaryView)(saved.flow, targetFolder?.item.path ?? null), stepCount: lint.steps.length },
+            lint: (0, uiTestShared_js_1.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: [(0, resolve_js_1.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: shared_js_1.workspaceArg,
+            flow: uiTestShared_js_1.flowArg,
+            expectedVersion: zod_1.z.number().int().min(1).optional(),
+            force: zod_1.z.boolean().optional().describe("Save despite lint errors, and overwrite even if someone saved since expectedVersion"),
+            name: zod_1.z.string().trim().min(1).max(200).optional(),
+            platform: uiTestShared_js_1.platformArg.optional(),
+            folder: zod_1.z.string().max(300).nullable().optional().describe("UI-test folder id, name or path; null = root"),
+            url: zod_1.z.string().max(2000).nullable().optional(),
+            appId: zod_1.z.string().max(300).nullable().optional(),
+            header: uiTestShared_js_1.headerArg,
+            preconditions: zod_1.z.array(zod_1.z.string().min(1).max(200)).max(20).optional(),
+            steps: uiTestShared_js_1.stepsArg.optional(),
+            content: zod_1.z.string().max(1_000_000).optional(),
+            ...flowFields,
+            dataset: zod_1.z.record(zod_1.z.string().max(10_000).nullable()).optional().describe("Keys to set (null removes a key); other keys are kept"),
+            datasetSources: zod_1.z.record(uiTestShared_js_1.datasetSourceSchema.nullable()).optional().describe("Sources to set (null removes one); others are kept"),
+            dryRun: shared_js_1.dryRunArg,
+        },
+        annotations: shared_js_1.IDEMPOTENT_WRITE,
+    }, (0, shared_js_1.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 errors_js_1.ToolInputError("CONTENT_EXCLUSIVE", "Pass either `content` (the whole YAML) or url/appId/header/preconditions/steps — not both.");
+        }
+        const resolved = await (0, lookups_js_1.resolveUiTest)(ctx, workspace, flow);
+        const current = await ctx.api.getUiTest(resolved.item.clientId, true);
+        const ws = (0, uiTestShared_js_1.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 = (0, compose_js_1.splitFlow)(nextContent);
+            let head = parts.head;
+            if (url !== undefined)
+                head = (0, compose_js_1.setHeaderValue)(head, "url", url);
+            if (appId !== undefined)
+                head = (0, compose_js_1.setHeaderValue)(head, "appId", appId);
+            for (const [key, value] of Object.entries(header ?? {}))
+                head = (0, compose_js_1.setHeaderValue)(head, key, value);
+            nextContent = (0, compose_js_1.joinFlow)(head, parts.body);
+        }
+        if (steps !== undefined) {
+            const own = (0, compose_js_1.ownSteps)(nextContent);
+            nextContent = (0, compose_js_1.composeFlow)({ head: (0, compose_js_1.splitFlow)(nextContent).head, preconditions: preconditions ?? own.preconditions, steps: (0, compose_js_1.stepsToYaml)(steps) });
+        }
+        else if (preconditions !== undefined) {
+            nextContent = (0, callman_core_1.setPreconditions)(nextContent, preconditions);
+        }
+        const targetFolder = folder ? await (0, lookups_js_1.resolveUiTestFolder)(ctx, workspace ?? ws, folder) : null;
+        if (targetFolder && targetFolder.item.workspaceId !== ws) {
+            throw new errors_js_1.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 (0, lookups_js_1.loadUiTests)(ctx), ws, name, current.clientId);
+            if (taken)
+                throw new errors_js_1.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 (0, uiTestShared_js_1.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 = (0, uiTestShared_js_1.upsertBodyOf)(next);
+        const changed = Object.keys(body).filter((key) => JSON.stringify(body[key]) !== JSON.stringify((0, uiTestShared_js_1.upsertBodyOf)(current)[key]));
+        if (changed.length === 0)
+            throw new errors_js_1.ToolInputError("NOTHING_TO_UPDATE", "Nothing would change — pass at least one field with a new value.");
+        const context = await (0, uiTestShared_js_1.lintContext)(ctx, ws);
+        const lint = (0, uiTestShared_js_1.lintFlow)(nextContent, nextPlatform, context, datasetKeysOf(next));
+        if (dryRun)
+            return (0, shared_js_1.ok)({ dryRun: true, uiTest: { id: current.clientId, name: next.name, version: current.version ?? null }, changed, content: nextContent, lint: (0, uiTestShared_js_1.lintView)(lint, context), ...(warnings.length > 0 ? { warnings } : {}) });
+        if (changed.includes("content") || changed.includes("platform"))
+            (0, uiTestShared_js_1.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.
+        (0, uiTestShared_js_1.refuseMaskedDataset)(Object.fromEntries(Object.entries(dataset ?? {}).filter(([, value]) => value !== null)));
+        const saved = await (0, uiTestShared_js_1.saveFlow)(ctx, ws, body, { expectedVersion: expectedVersion ?? current.version, force });
+        if ("conflict" in saved)
+            return (0, uiTestShared_js_1.conflictResult)(saved.conflict);
+        const note = draftNote(current, saved.flow);
+        const folders = await (0, lookups_js_1.loadUiTestFolders)(ctx).catch(() => []);
+        return (0, shared_js_1.ok)({
+            uiTest: { ...(0, summarize_js_1.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: (0, uiTestShared_js_1.lintView)(lint, context),
+            ...(warnings.length > 0 ? { warnings } : {}),
+            ...(note ? { note } : {}),
+            ...(resolved.annotation ? { resolved: [(0, resolve_js_1.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: shared_js_1.workspaceArg,
+            flow: uiTestShared_js_1.flowArg,
+            expectedVersion: zod_1.z.number().int().min(1).optional(),
+            force: zod_1.z.boolean().optional().describe("Save despite lint errors, and overwrite even if someone saved since expectedVersion"),
+            ops: zod_1.z
+                .array(zod_1.z.discriminatedUnion("op", [
+                (0, strict_js_1.strictObject)({ op: zod_1.z.literal("insert"), at: zod_1.z.number().int().min(1), steps: zod_1.z.array(uiTestShared_js_1.stepInputSchema).min(1).max(200) }, "field", "insert ops"),
+                (0, strict_js_1.strictObject)({ op: zod_1.z.literal("replace"), at: zod_1.z.number().int().min(1), step: uiTestShared_js_1.stepInputSchema }, "field", "replace ops"),
+                (0, strict_js_1.strictObject)({ op: zod_1.z.literal("remove"), at: zod_1.z.number().int().min(1).optional(), from: zod_1.z.number().int().min(1).optional(), to: zod_1.z.number().int().min(1).optional() }, "field", "remove ops"),
+                (0, strict_js_1.strictObject)({ op: zod_1.z.literal("move"), from: zod_1.z.number().int().min(1), to: zod_1.z.number().int().min(1) }, "field", "move ops"),
+                (0, strict_js_1.strictObject)({ op: zod_1.z.literal("setLabel"), at: zod_1.z.number().int().min(1), label: zod_1.z.string().trim().min(1).max(200) }, "field", "setLabel ops"),
+            ]))
+                .min(1)
+                .max(200),
+            dryRun: shared_js_1.dryRunArg,
+        },
+        annotations: shared_js_1.IDEMPOTENT_WRITE,
+    }, (0, shared_js_1.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 errors_js_1.ToolInputError("STEP_RANGE_INVALID", "remove takes `at`, or `from` (+ optional `to`).");
+        }
+        const resolved = await (0, lookups_js_1.resolveUiTest)(ctx, workspace, flow);
+        const current = await ctx.api.getUiTest(resolved.item.clientId, true);
+        const ws = (0, uiTestShared_js_1.workspaceIdOf)(current);
+        const context = await (0, uiTestShared_js_1.lintContext)(ctx, ws);
+        const before = (0, uiTestShared_js_1.lintFlow)(current.content ?? "", current.platform, context, datasetKeysOf(current));
+        if (before.errors.some((issue) => issue.code === "YAML_SYNTAX")) {
+            throw new errors_js_1.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 = (0, compose_js_1.applyStepOps)(current.content ?? "", ops, before.steps.length);
+        const lint = (0, uiTestShared_js_1.lintFlow)(patched.content, current.platform, context, datasetKeysOf(current));
+        if (dryRun)
+            return (0, shared_js_1.ok)({ dryRun: true, uiTest: { id: current.clientId, name: current.name, version: current.version ?? null }, content: patched.content, steps: lint.steps, lint: (0, uiTestShared_js_1.lintView)(lint, context) });
+        (0, uiTestShared_js_1.refuseLintErrors)(lint, force, patched.content);
+        const saved = await (0, uiTestShared_js_1.saveFlow)(ctx, ws, (0, uiTestShared_js_1.upsertBodyOf)({ ...current, content: patched.content }), { expectedVersion: expectedVersion ?? current.version, force });
+        if ("conflict" in saved)
+            return (0, uiTestShared_js_1.conflictResult)(saved.conflict);
+        const note = draftNote(current, saved.flow);
+        return (0, shared_js_1.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: (0, uiTestShared_js_1.lintView)(lint, context),
+            ...(note ? { note } : {}),
+            ...(resolved.annotation ? { resolved: [(0, resolve_js_1.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: shared_js_1.workspaceArg, flow: uiTestShared_js_1.flowArg, confirm: shared_js_1.confirmArg },
+        annotations: shared_js_1.DESTRUCTIVE,
+    }, (0, shared_js_1.guarded)(async ({ workspace, flow, confirm }) => {
+        (0, shared_js_1.requireConfirm)(confirm, "a UI test");
+        const resolved = await (0, lookups_js_1.resolveUiTest)(ctx, workspace, flow, { exact: true });
+        await ctx.api.deleteUiTest(resolved.item.workspaceId ?? null, resolved.item.clientId);
+        ctx.invalidate("uitests:");
+        return (0, shared_js_1.ok)({ deleted: { id: resolved.item.clientId, name: resolved.item.name }, resolved: [(0, resolve_js_1.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: shared_js_1.workspaceArg },
+        annotations: shared_js_1.READ,
+    }, (0, shared_js_1.guarded)(async ({ workspace }) => {
+        const ws = workspace && !(0, lookups_js_1.isAllWorkspaces)(workspace) ? await ctx.resolveWorkspace(workspace) : null;
+        const [folders, flows, workspaces] = await Promise.all([(0, lookups_js_1.loadUiTestFolders)(ctx), (0, lookups_js_1.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 (0, shared_js_1.ok)({
+            ...(ws ? { workspace: (0, lookups_js_1.workspaceTag)(ws) } : {}),
+            folders: scoped.slice(0, truncate_js_1.LIMITS.TREE_ITEMS).map((folder) => ({
+                id: folder.id,
+                name: folder.name,
+                path: folder.path,
+                parentId: folder.parentId,
+                flowCount: direct.get(folder.id) ?? 0,
+                totalFlowCount: [...(0, lookups_js_1.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: shared_js_1.workspaceArg,
+            name: zod_1.z.string().trim().min(1).max(120),
+            parent: zod_1.z.string().max(300).optional().describe("Parent folder id, name or path"),
+            group: uiTestShared_js_1.groupArg,
+        },
+        annotations: shared_js_1.WRITE,
+    }, (0, shared_js_1.guarded)(async ({ workspace, name, parent, group }) => {
+        const parentFolder = parent ? await (0, lookups_js_1.resolveUiTestFolder)(ctx, workspace, parent) : null;
+        const ws = parentFolder ? { id: parentFolder.item.workspaceId } : await ctx.resolveWorkspace(workspace);
+        const folders = await (0, lookups_js_1.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 (0, shared_js_1.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 (0, uiTestShared_js_1.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: (0, node_crypto_1.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 (0, shared_js_1.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: [(0, resolve_js_1.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: shared_js_1.workspaceArg,
+            folder: (0, shared_js_1.refArg)("UI-test folder", "(or its path A/B)"),
+            name: zod_1.z.string().trim().min(1).max(120).optional(),
+            parent: zod_1.z.string().max(300).nullable().optional(),
+        },
+        annotations: shared_js_1.IDEMPOTENT_WRITE,
+    }, (0, shared_js_1.guarded)(async ({ workspace, folder, name, parent }) => {
+        if (name === undefined && parent === undefined)
+            throw new errors_js_1.ToolInputError("NOTHING_TO_UPDATE", "Pass name and/or parent.");
+        const target = await (0, lookups_js_1.resolveUiTestFolder)(ctx, workspace, folder);
+        const parentFolder = parent ? await (0, lookups_js_1.resolveUiTestFolder)(ctx, target.item.workspaceId, parent) : null;
+        if (parentFolder) {
+            if (parentFolder.item.workspaceId !== target.item.workspaceId)
+                throw new errors_js_1.ToolInputError("UI_TEST_FOLDER_OTHER_WORKSPACE", "The new parent is in another workspace.");
+            if ((0, lookups_js_1.uiTestFolderSubtree)(await (0, lookups_js_1.loadUiTestFolders)(ctx), target.item.id).has(parentFolder.item.id)) {
+                throw new errors_js_1.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 (0, lookups_js_1.loadUiTestFolders)(ctx)).find((entry) => entry.id === updated.clientId);
+        return (0, shared_js_1.ok)({
+            folder: { id: updated.clientId, name: updated.name, parentId: updated.parentId ?? null, path: refreshed?.path ?? updated.name },
+            resolved: [(0, resolve_js_1.resolvedSummary)(folder, target), ...(parentFolder ? [(0, resolve_js_1.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: shared_js_1.workspaceArg, folder: (0, shared_js_1.refArg)("UI-test folder", "(or its path A/B)"), confirm: shared_js_1.confirmArg },
+        annotations: shared_js_1.DESTRUCTIVE,
+    }, (0, shared_js_1.guarded)(async ({ workspace, folder, confirm }) => {
+        (0, shared_js_1.requireConfirm)(confirm, "a UI-test folder");
+        const target = await (0, lookups_js_1.resolveUiTestFolder)(ctx, workspace, folder, { exact: true });
+        const [folders, flows] = await Promise.all([(0, lookups_js_1.loadUiTestFolders)(ctx), (0, lookups_js_1.loadUiTests)(ctx)]);
+        const subtree = (0, lookups_js_1.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 (0, shared_js_1.ok)({
+            deleted: { id: target.item.id, name: target.item.name, path: target.item.path, subfolders: subtree.size - 1 },
+            movedToRoot: moved,
+            resolved: [(0, resolve_js_1.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: shared_js_1.workspaceArg,
+            flows: zod_1.z.array(uiTestShared_js_1.flowArg).min(1).max(200),
+            folder: zod_1.z.string().max(300).nullable().describe("Target folder id, name or path; null = root"),
+        },
+        annotations: shared_js_1.IDEMPOTENT_WRITE,
+    }, (0, shared_js_1.guarded)(async ({ workspace, flows, folder }) => {
+        const target = folder ? await (0, lookups_js_1.resolveUiTestFolder)(ctx, workspace, folder) : null;
+        const moved = [];
+        const unchanged = [];
+        const failed = [];
+        for (const ref of flows) {
+            try {
+                const resolved = await (0, lookups_js_1.resolveUiTest)(ctx, workspace, ref);
+                if (target && target.item.workspaceId !== resolved.item.workspaceId)
+                    throw new errors_js_1.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 (0, uiTestShared_js_1.saveFlow)(ctx, (0, uiTestShared_js_1.workspaceIdOf)(current), (0, uiTestShared_js_1.upsertBodyOf)({ ...current, folderId: nextFolder }), { expectedVersion: current.version });
+                if ("conflict" in saved)
+                    throw new errors_js_1.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: (0, shared_js_1.failureOf)(error) });
+            }
+        }
+        return (0, shared_js_1.ok)({
+            folder: target ? { id: target.item.id, path: target.item.path } : null,
+            moved,
+            ...(unchanged.length > 0 ? { alreadyThere: unchanged } : {}),
+            failed,
+            ...(target ? { resolved: [(0, resolve_js_1.resolvedSummary)(folder, target)] } : {}),
+        });
+    }));
+};
+exports.registerUiTestTools = registerUiTestTools;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "callman-mcp",
-  "version": "0.3.0",
-  "description": "MCP server for Callman: lets Claude Code, Claude Desktop, Cursor, Codex and Gemini CLI manage collections, requests, environments, test scenarios and system-design diagrams in your Callman workspace — cloud or on-prem.",
+  "version": "0.5.0",
+  "description": "MCP server for Callman: lets Claude Code, Claude Desktop, Cursor, Codex and Gemini CLI manage collections, requests, environments, test scenarios, UI tests (web, Android, iOS) and system-design diagrams in your Callman workspace — cloud or on-prem.",
   "keywords": [
     "callman",
     "mcp",
@@ -62,7 +62,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "callman-core": "^1.29.0",
+    "callman-core": "^1.31.0",
     "elkjs": "^0.12.0",
     "js-yaml": "^4.1.0",
     "zod": "^3.25.0"