callman-mcp 0.3.0 → 0.5.0

package/dist-cjs/tools/uiTestRuns.js

@@ -0,0 +1,372 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerUiTestRunTools = exports.pollRun = exports.startRun = exports.DESKTOP_HINT = void 0;
+const zod_1 = require("zod");
+const errors_js_1 = require("../client/errors.js");
+const resolve_js_1 = require("../domain/resolve.js");
+const summarize_js_1 = require("../domain/uiTest/summarize.js");
+const lookups_js_1 = require("./lookups.js");
+const shared_js_1 = require("./shared.js");
+const uiTestShared_js_1 = require("./uiTestShared.js");
+// Running UI tests. Two executors:
+//   * server — the backend's ui-runner (Playwright, web flows only), when the
+//     installation has one (GET /ui-test-runner/status);
+//   * desktop — the user's own Callman desktop app, when "Let AI tools run UI
+//     tests on this computer" is on: it claims the queued job, runs it on a
+//     connected device / emulator / simulator (Android, iOS) or a local
+//     browser (web) and streams the steps back into the same report.
+// Either way the tool gets a reportId and polls GET /ui-test-runs/:id.
+const TERMINAL = new Set(["passed", "failed", "stopped"]);
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+exports.DESKTOP_HINT = "Open the Callman desktop app on your computer, sign in, and turn on Settings → AI tools → \"Let AI tools run UI tests on this computer\". For Android/iOS also connect a device or start an emulator/simulator. list_ui_test_devices shows what is available.";
+const targetArg = zod_1.z
+    .enum(["auto", "server", "desktop"])
+    .default("auto")
+    .describe("auto = the server runner for web flows when the installation has one, otherwise your desktop app; server = web only; desktop = your Callman desktop app");
+const desktopOptions = {
+    device: zod_1.z.string().max(200).optional().describe("Desktop runs: device id or name (list_ui_test_devices); default = the app's current / first online device"),
+    browserKind: zod_1.z.enum(["chrome", "firefox", "webkit"]).optional().describe("Desktop web runs: browser (default: the flow's setting)"),
+    headless: zod_1.z.boolean().optional().describe("Desktop web runs: headless browser"),
+    dataset: zod_1.z.record(zod_1.z.string().max(10_000)).optional().describe("Desktop runs: dataset values overriding the flow's for this run"),
+};
+const hasDesktopOptions = (options) => Object.values(options).some((value) => value !== undefined);
+const serverRunnerAvailable = async (ctx) => {
+    try {
+        return (await ctx.api.uiTestRunnerStatus()).serverRunner === true;
+    }
+    catch {
+        return false;
+    }
+};
+// Pick the executor and start the run. auto → server for a web flow when a
+// runner is up (and no desktop-only option was given), else desktop; a
+// server answer of "no runner" falls back to the desktop.
+const startRun = async (ctx, flow, target, options, serverRunner) => {
+    const ws = (0, uiTestShared_js_1.workspaceIdOf)(flow);
+    const notes = [];
+    if (target === "server") {
+        if (flow.platform !== "web")
+            throw new errors_js_1.ToolInputError("UI_TEST_PLATFORM_UNSUPPORTED", `The server runner runs web flows only — "${flow.name}" is ${flow.platform}. Use target: "desktop" (your Callman desktop app with a device/emulator).`);
+        if (hasDesktopOptions(options))
+            throw new errors_js_1.ToolInputError("ARG_TARGET_MISMATCH", "device / browserKind / headless / dataset apply to desktop runs only — drop them or use target: \"desktop\".");
+    }
+    const useServer = target === "server" || (target === "auto" && flow.platform === "web" && !hasDesktopOptions(options) && (serverRunner ?? (await serverRunnerAvailable(ctx))));
+    if (useServer) {
+        try {
+            return { flow, trigger: await ctx.api.runUiTestOnServer(ws, flow.clientId), executor: "server", notes };
+        }
+        catch (error) {
+            if (!(target === "auto" && error instanceof errors_js_1.CallmanApiError && error.code === "UI_RUNNER_UNAVAILABLE"))
+                throw error;
+            notes.push("The server runner is not available — the run went to your desktop app instead.");
+        }
+    }
+    (0, uiTestShared_js_1.refuseMaskedDataset)(options.dataset);
+    const body = {
+        ...(options.device ? { device: options.device } : {}),
+        ...(options.browserKind ? { browserKind: options.browserKind } : {}),
+        ...(options.headless !== undefined ? { headless: options.headless } : {}),
+        ...(options.dataset ? { dataset: options.dataset } : {}),
+    };
+    const trigger = await ctx.api.runUiTestOnDesktop(ws, flow.clientId, body);
+    // A desktop busy with a run the user started by hand still accepts the job
+    // (it waits in the queue) — say so, or a long "queued" looks like a hang.
+    const agents = await ctx.api.listUiTestDesktopAgents(ws).then((result) => result.agents ?? [], () => []);
+    const capable = agents.filter((agent) => agent.platforms.includes(flow.platform));
+    if (capable.length > 0 && capable.every((agent) => agent.busy)) {
+        notes.push(`Your desktop app${capable.length > 1 ? "s are" : " is"} busy with another UI-test run (e.g. one started by hand) — this run is queued behind it and starts when it finishes.`);
+    }
+    return { flow, trigger, executor: "desktop", notes };
+};
+exports.startRun = startRun;
+const fetchReport = async (ctx, ws, reportId) => {
+    try {
+        return await ctx.api.getUiTestRun(ws, reportId);
+    }
+    catch (error) {
+        if (error instanceof errors_js_1.CallmanApiError && error.status === 404)
+            return null; // not visible yet
+        throw error;
+    }
+};
+const pollRun = async (ctx, ws, reportId, timeoutSec) => {
+    const deadline = Date.now() + timeoutSec * 1000;
+    let polls = 0;
+    let last = null;
+    while (Date.now() < deadline) {
+        await sleep(polls < 5 ? ctx.pollDelaysMs.fast : ctx.pollDelaysMs.slow);
+        polls += 1;
+        last = (await fetchReport(ctx, ws, reportId)) ?? last;
+        if (last && TERMINAL.has(last.status))
+            return { report: last, timedOut: false };
+    }
+    return { report: last, timedOut: true };
+};
+exports.pollRun = pollRun;
+const screenshotImages = (report) => [
+    { caption: `Failure screenshot — ${report.flowName}`, image: (0, summarize_js_1.imageFromDataUrl)(report.failureScreenshot) },
+    { caption: `Final screenshot — ${report.flowName}`, image: (0, summarize_js_1.imageFromDataUrl)(report.finalScreenshot) },
+].flatMap((entry) => (entry.image ? [{ caption: entry.caption, ...entry.image }] : []));
+const timedOutNote = (status, executor, timeoutSec) => status === "queued" && executor === "desktop"
+    ? `No desktop app picked the run up within ${timeoutSec}s. ${exports.DESKTOP_HINT} The run stays queued for 10 minutes; check it later with get_ui_test_run, or cancel_ui_test_run.`
+    : `Still ${status ?? "running"} after ${timeoutSec}s — call get_ui_test_run with this reportId later.`;
+// The report's workspace is needed for the per-report routes: the flow's, or
+// found by trying each workspace.
+const findReport = async (ctx, workspace, reportId) => (0, lookups_js_1.findInWorkspaces)(ctx, workspace, "UI-test run", reportId, (ws) => ctx.api.getUiTestRun(ws.id, reportId), { matchOf: () => "id" });
+const registerUiTestRunTools = (server, ctx) => {
+    server.registerTool("list_ui_test_devices", {
+        title: "Where UI tests can run",
+        description: "Where UI tests can run right now: whether the server runner is up (web flows), and your desktop apps that let AI tools run UI tests — with their connected Android/iOS devices, emulators and simulators, the browsers they have, and whether they are busy. Call it before run_ui_test for mobile flows, or when a run says the desktop is offline.",
+        inputSchema: { workspace: shared_js_1.workspaceArg },
+        annotations: shared_js_1.READ,
+    }, (0, shared_js_1.guarded)(async ({ workspace }) => {
+        const ws = await ctx.resolveWorkspaceOrNull(workspace);
+        let agents = [];
+        let serverRunner;
+        let note;
+        try {
+            const result = await ctx.api.listUiTestDesktopAgents(ws?.id ?? null);
+            agents = result.agents ?? [];
+            serverRunner = result.serverRunner === true;
+        }
+        catch (error) {
+            if (!(error instanceof errors_js_1.CallmanApiError && (error.code === "ROUTE_NOT_FOUND" || error.status === 404)))
+                throw error;
+            serverRunner = await serverRunnerAvailable(ctx);
+            note = "This server does not support desktop runs yet (no desktop relay) — only the server runner is available.";
+        }
+        const online = (platform) => agents.flatMap((agent) => agent.devices.filter((device) => device.platform === platform && device.state === "online"));
+        const webDesktop = agents.some((agent) => agent.platforms.includes("web"));
+        return (0, shared_js_1.ok)({
+            serverRunner,
+            desktopAgents: agents.map((agent) => ({
+                agentId: agent.agentId,
+                hostName: agent.hostName,
+                appVersion: agent.appVersion,
+                lastSeenAt: agent.lastSeenAt,
+                busy: agent.busy,
+                platforms: agent.platforms,
+                browsers: agent.browsers,
+                devices: agent.devices,
+            })),
+            canRun: {
+                web: serverRunner ? (webDesktop ? "server or desktop" : "server") : webDesktop ? "desktop" : "nowhere",
+                android: online("android").length > 0 ? "desktop" : agents.some((agent) => agent.platforms.includes("android")) ? "desktop (no online device — connect one or start an emulator)" : "nowhere",
+                ios: online("ios").length > 0 ? "desktop" : agents.some((agent) => agent.platforms.includes("ios")) ? "desktop (no online simulator/device)" : "nowhere",
+            },
+            ...(agents.length === 0 ? { hint: exports.DESKTOP_HINT } : {}),
+            ...(note ? { note } : {}),
+        });
+    }));
+    server.registerTool("run_ui_test", {
+        title: "Run a UI test",
+        description: "Run one UI test and wait for the result (default up to 10 minutes). target auto (default): web flows on the server runner when the installation has one, everything else (Android, iOS, or no server runner) on your Callman desktop app — which must be open with \"Let AI tools run UI tests on this computer\" on (list_ui_test_devices). device / browserKind / headless / dataset apply to desktop runs. Returns per-step results, failing steps expanded with the data they saw, dataset issues and warnings; includeScreenshots: true adds the failure/final screenshots as images. wait: false returns the reportId at once.",
+        inputSchema: {
+            workspace: shared_js_1.workspaceArg,
+            flow: uiTestShared_js_1.flowArg,
+            target: targetArg,
+            ...desktopOptions,
+            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, flow, target, device, browserKind, headless, dataset, wait, timeoutSec, includeScreenshots }) => {
+        const resolved = await (0, lookups_js_1.resolveUiTest)(ctx, workspace, flow);
+        const started = await (0, exports.startRun)(ctx, resolved.item, target, { device, browserKind, headless, dataset });
+        const annotation = resolved.annotation ? { resolved: [(0, resolve_js_1.resolvedSummary)(flow, resolved)] } : {};
+        const header = { uiTest: { id: resolved.item.clientId, name: resolved.item.name, platform: resolved.item.platform }, reportId: started.trigger.reportId, executor: started.executor };
+        if (!wait) {
+            return (0, shared_js_1.ok)({ ...header, status: started.trigger.status, ...(started.notes.length ? { warnings: started.notes } : {}), note: "Check it with get_ui_test_run.", ...annotation });
+        }
+        const { report, timedOut } = await (0, exports.pollRun)(ctx, (0, uiTestShared_js_1.workspaceIdOf)(resolved.item), started.trigger.reportId, timeoutSec);
+        if (timedOut || !report) {
+            return (0, shared_js_1.ok)({ ...header, status: report?.status ?? started.trigger.status, timedOut: true, note: timedOutNote(report?.status ?? started.trigger.status, started.executor, timeoutSec), ...(started.notes.length ? { warnings: started.notes } : {}), ...annotation });
+        }
+        const structured = { run: (0, summarize_js_1.runReportView)({ ...report, executor: report.executor ?? started.executor }), ...(started.notes.length ? { warnings: started.notes } : {}), ...annotation };
+        return includeScreenshots ? (0, shared_js_1.okWithImages)(structured, screenshotImages(report)) : (0, shared_js_1.ok)(structured);
+    }));
+    server.registerTool("run_ui_tests", {
+        title: "Run several UI tests",
+        description: "Run a batch of UI tests — a list of flows, or every flow in a folder (subfolders included unless includeSubfolders: false) — and wait for all of them. Each flow goes to the same executor run_ui_test would pick (server runs may run in parallel; desktop runs queue one after another on your app). Returns totals and one row per flow (status, executor, duration, first failing step); read details with get_ui_test_run.",
+        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().describe("Run every flow in this folder (id, name or path)"),
+            includeSubfolders: zod_1.z.boolean().default(true),
+            target: targetArg,
+            wait: zod_1.z.boolean().default(true),
+            timeoutSec: zod_1.z.number().int().min(5).max(7200).default(1800).describe("For the whole batch"),
+        },
+        annotations: shared_js_1.RUN,
+    }, (0, shared_js_1.guarded)(async ({ workspace, flows, folder, includeSubfolders, target, wait, timeoutSec }) => {
+        if ((flows === undefined) === (folder === undefined))
+            throw new errors_js_1.ToolInputError("RUN_BATCH_SCOPE", "Pass `flows` or `folder` (one of them).");
+        let selected = [];
+        const notStarted = [];
+        let unresolved = 0;
+        if (folder) {
+            const target = await (0, lookups_js_1.resolveUiTestFolder)(ctx, workspace, folder);
+            const scope = includeSubfolders ? (0, lookups_js_1.uiTestFolderSubtree)(await (0, lookups_js_1.loadUiTestFolders)(ctx), target.item.id) : new Set([target.item.id]);
+            selected = (await (0, lookups_js_1.loadUiTests)(ctx)).filter((flow) => flow.folderId && scope.has(flow.folderId));
+            if (selected.length === 0)
+                throw new errors_js_1.ToolInputError("UI_TEST_FOLDER_EMPTY", `Folder "${target.item.path}" has no UI tests${includeSubfolders ? "" : " directly (try includeSubfolders: true)"}.`);
+            if (selected.length > 100)
+                throw new errors_js_1.ToolInputError("RUN_BATCH_TOO_LARGE", `Folder "${target.item.path}" has ${selected.length} UI tests (limit 100 per batch) — run a subfolder.`);
+        }
+        else {
+            for (const ref of flows ?? []) {
+                try {
+                    selected.push((await (0, lookups_js_1.resolveUiTest)(ctx, workspace, ref)).item);
+                }
+                catch (error) {
+                    notStarted.push({ flow: ref, error: (0, shared_js_1.failureOf)(error) });
+                    unresolved += 1;
+                }
+            }
+        }
+        const serverRunner = await serverRunnerAvailable(ctx);
+        const started = [];
+        for (const flow of selected) {
+            try {
+                started.push(await (0, exports.startRun)(ctx, flow, target, {}, serverRunner));
+            }
+            catch (error) {
+                notStarted.push({ flow: flow.name, error: (0, shared_js_1.failureOf)(error) });
+            }
+        }
+        const reports = new Map(started.map((run) => [run.trigger.reportId, null]));
+        let timedOut = false;
+        if (wait && started.length > 0) {
+            const deadline = Date.now() + timeoutSec * 1000;
+            let polls = 0;
+            for (;;) {
+                const pending = started.filter((run) => !TERMINAL.has(reports.get(run.trigger.reportId)?.status ?? ""));
+                if (pending.length === 0)
+                    break;
+                if (Date.now() >= deadline) {
+                    timedOut = true;
+                    break;
+                }
+                await sleep(polls < 5 ? ctx.pollDelaysMs.fast : ctx.pollDelaysMs.slow);
+                polls += 1;
+                for (const run of pending) {
+                    const report = await fetchReport(ctx, (0, uiTestShared_js_1.workspaceIdOf)(run.flow), run.trigger.reportId);
+                    if (report)
+                        reports.set(run.trigger.reportId, report);
+                }
+            }
+        }
+        const rows = started.map((run) => {
+            const report = reports.get(run.trigger.reportId);
+            return report
+                ? { ...(0, summarize_js_1.runListRow)(report), executor: report.executor ?? run.executor }
+                : { reportId: run.trigger.reportId, flow: { id: run.flow.clientId, name: run.flow.name }, status: run.trigger.status, executor: run.executor };
+        });
+        const count = (status) => rows.filter((row) => row.status === status).length;
+        const unfinished = rows.filter((row) => !TERMINAL.has(row.status));
+        const desktopQueued = unfinished.some((row) => row.status === "queued" && row.executor === "desktop");
+        return (0, shared_js_1.ok)({
+            total: selected.length + unresolved,
+            passed: count("passed"),
+            failed: count("failed"),
+            stopped: count("stopped"),
+            ...(unfinished.length > 0 ? { unfinished: unfinished.length } : {}),
+            runs: rows,
+            ...(notStarted.length > 0 ? { notStarted } : {}),
+            ...(timedOut ? { timedOut: true, note: `Some runs were still going after ${timeoutSec}s — check them with get_ui_test_run.${desktopQueued ? ` ${exports.DESKTOP_HINT}` : ""}` } : !wait ? { note: "Started — check each with get_ui_test_run." } : {}),
+            ...([...new Set(started.flatMap((run) => run.notes))].length > 0 ? { warnings: [...new Set(started.flatMap((run) => run.notes))] } : {}),
+        });
+    }));
+    server.registerTool("get_ui_test_run", {
+        title: "Get a UI-test run",
+        description: "One UI-test run report: status, executor and device, per-step results (command, status, duration, error, the sub-flow it came from), failing steps expanded with the data they returned (DB rows, API responses, extracted {{vars}}), dataset issues and warnings. By `reportId`, or `flow` for its latest run. includeScreenshots: true returns the failure/final screenshots as images; includeNetwork: true adds the captured API calls; stepData: true expands every data step, not only failing ones.",
+        inputSchema: {
+            workspace: shared_js_1.workspaceArg,
+            reportId: zod_1.z.string().max(64).optional(),
+            flow: uiTestShared_js_1.flowArg.optional(),
+            includeScreenshots: zod_1.z.boolean().default(false),
+            includeNetwork: zod_1.z.boolean().default(false),
+            stepData: zod_1.z.boolean().default(false),
+        },
+        annotations: shared_js_1.READ,
+    }, (0, shared_js_1.guarded)(async ({ workspace, reportId, flow, includeScreenshots, includeNetwork, stepData }) => {
+        if (!reportId && !flow)
+            throw new errors_js_1.ToolInputError("RUN_REF_REQUIRED", "Pass `reportId`, or `flow` for its latest run.");
+        let report;
+        if (reportId) {
+            report = (await findReport(ctx, workspace, reportId)).value;
+        }
+        else {
+            const resolved = await (0, lookups_js_1.resolveUiTest)(ctx, workspace, flow);
+            const [latest] = await ctx.api.listUiTestRuns({ flowClientId: resolved.item.clientId, limit: 1 });
+            if (!latest) {
+                const [history] = await ctx.api.listUiTestResults({ flowClientId: resolved.item.clientId, limit: 1 }).catch(() => []);
+                return (0, shared_js_1.ok)({
+                    uiTest: { id: resolved.item.clientId, name: resolved.item.name },
+                    run: null,
+                    ...(history ? { lastRecordedRun: (0, summarize_js_1.historyRow)(history), note: "The latest run was recorded by the desktop app without a full report (step list only)." } : { note: "This UI test has no runs yet. Use run_ui_test." }),
+                });
+            }
+            report = await ctx.api.getUiTestRun((0, uiTestShared_js_1.workspaceIdOf)(resolved.item), latest.id);
+        }
+        const structured = { run: (0, summarize_js_1.runReportView)(report, { includeNetwork, allStepData: stepData }) };
+        return includeScreenshots ? (0, shared_js_1.okWithImages)(structured, screenshotImages(report)) : (0, shared_js_1.ok)(structured);
+    }));
+    server.registerTool("list_ui_test_runs", {
+        title: "List UI-test runs",
+        description: "Recent UI-test runs, newest first — server, schedule and AI-started desktop runs (with reportIds), merged with the run history the desktop app recorded itself. Filter by flow and status.",
+        inputSchema: {
+            workspace: shared_js_1.workspaceArg,
+            flow: uiTestShared_js_1.flowArg.optional(),
+            status: zod_1.z.enum(["queued", "running", "passed", "failed", "stopped"]).optional(),
+            limit: zod_1.z.number().int().min(1).max(100).default(20),
+            includeHistory: zod_1.z.boolean().default(true).describe("Also list desktop-recorded runs that have no report"),
+        },
+        annotations: shared_js_1.READ,
+    }, (0, shared_js_1.guarded)(async ({ workspace, flow, status, limit, includeHistory }) => {
+        const resolved = flow ? await (0, lookups_js_1.resolveUiTest)(ctx, workspace, flow) : null;
+        const flowClientId = resolved?.item.clientId;
+        const [reports, history] = await Promise.all([
+            ctx.api.listUiTestRuns({ ...(flowClientId ? { flowClientId } : {}), ...(status ? { status } : {}), limit }),
+            includeHistory && (!status || ["passed", "failed", "stopped"].includes(status)) ? ctx.api.listUiTestResults({ ...(flowClientId ? { flowClientId } : {}), limit }).catch(() => []) : Promise.resolve([]),
+        ]);
+        const reportIds = new Set(reports.map((report) => report.id));
+        const extra = history.filter((row) => !row.reportId || !reportIds.has(row.reportId)).filter((row) => !status || row.status === status);
+        const rows = [
+            ...reports.map((report) => ({ at: Number(new Date(report.startedAt ?? 0)) || 0, row: (0, summarize_js_1.runListRow)(report) })),
+            ...extra.map((row) => ({ at: Number(row.startedAt) || 0, row: (0, summarize_js_1.historyRow)(row) })),
+        ]
+            .sort((a, b) => b.at - a.at)
+            .slice(0, limit)
+            .map((entry) => entry.row);
+        return (0, shared_js_1.ok)({ ...(resolved ? { uiTest: { id: resolved.item.clientId, name: resolved.item.name } } : {}), runs: rows, total: rows.length });
+    }));
+    server.registerTool("cancel_ui_test_run", {
+        title: "Cancel a UI-test run",
+        description: "Stop a queued or running UI-test run (server or desktop). A queued desktop run is dropped at once; a running one stops at the next step.",
+        inputSchema: { workspace: shared_js_1.workspaceArg, reportId: zod_1.z.string().min(1).max(64) },
+        annotations: shared_js_1.RUN,
+    }, (0, shared_js_1.guarded)(async ({ workspace, reportId }) => {
+        const found = await findReport(ctx, workspace, reportId);
+        if (TERMINAL.has(found.value.status)) {
+            return (0, shared_js_1.ok)({ reportId, status: found.value.status, note: "The run had already finished — nothing to cancel." });
+        }
+        const result = (await ctx.api.cancelUiTestRun(found.ws.id, reportId));
+        // Dropped from the queue = already stopped; a running one stops at its
+        // next step — re-read once so the answer is the report's real status.
+        let status = result?.status ?? (result?.cancelledFromQueue ? "stopped" : "stopping");
+        if (!TERMINAL.has(status)) {
+            const after = await ctx.api.getUiTestRun(found.ws.id, reportId).catch(() => null);
+            if (after && TERMINAL.has(after.status))
+                status = after.status;
+        }
+        return (0, shared_js_1.ok)({
+            reportId,
+            flow: { id: found.value.flowClientId, name: found.value.flowName },
+            status,
+            note: status === "stopped" ? "The run was still queued — it will not run." : "Cancel requested — get_ui_test_run shows the final status.",
+        });
+    }));
+};
+exports.registerUiTestRunTools = registerUiTestRunTools;

package/dist-cjs/tools/uiTestShared.js

@@ -0,0 +1,202 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.workspaceIdOf = exports.flowDetailView = exports.connectionNames = exports.conflictResult = exports.saveFlow = exports.refuseMaskedDataset = exports.upsertBodyOf = exports.resolveDatasetSources = exports.refuseLintErrors = exports.lintView = exports.lintFlow = exports.lintContext = exports.resolveGroupId = exports.groupArg = exports.headerArg = exports.runSettingsSchema = exports.datasetSourceSchema = exports.stepsArg = exports.stepInputSchema = exports.flowArg = exports.platformArg = exports.SEVERITIES = exports.TEST_TYPES = exports.PLATFORMS = void 0;
+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 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");
+// Shared by the UI-test tool modules: argument schemas, the lint context
+// (library names + workspace connections), the full-state upsert with its
+// masked-value guard and version conflict, and the flow detail view.
+exports.PLATFORMS = ["web", "android", "ios"];
+exports.TEST_TYPES = ["regression", "smoke", "sanity", "integration", "e2e", "functional", "acceptance"];
+exports.SEVERITIES = ["critical", "high-risk", "major", "minor"];
+exports.platformArg = zod_1.z.enum(exports.PLATFORMS);
+exports.flowArg = zod_1.z.string().min(1).max(500).describe("UI test (flow) id or name");
+exports.stepInputSchema = zod_1.z.union([zod_1.z.string().min(1).max(20_000), zod_1.z.record(zod_1.z.unknown())]);
+exports.stepsArg = zod_1.z
+    .union([zod_1.z.string().max(1_000_000), zod_1.z.array(exports.stepInputSchema).max(1000)])
+    .describe('The flow\'s own steps: a YAML list (`- tapOn: "Login"` lines) or an array of steps — objects ({ tapOn: "Login" }, { assertVisible: { text: "Welcome", label: "Welcome shown" } }), bare command names ("launchApp") or YAML snippets. Step reference: callman://docs/ui-test-steps');
+exports.datasetSourceSchema = (0, strict_js_1.strictObject)({
+    kind: zod_1.z.literal("db").optional(),
+    connection: zod_1.z.string().min(1).max(200).describe("Workspace connection id or name (list_connections)"),
+    query: zod_1.z.string().min(1).max(10_000),
+    column: zod_1.z.string().max(200).optional().describe("Column to read (default: the first)"),
+}, "dataset source field");
+exports.runSettingsSchema = (0, strict_js_1.strictObject)({
+    screenshotOnSuccess: zod_1.z.boolean().nullable().optional(),
+    screenshotOnFailure: zod_1.z.boolean().nullable().optional(),
+    autoRetryTransient: zod_1.z.boolean().nullable().optional(),
+    captureNetwork: zod_1.z.boolean().nullable().optional(),
+}, "run setting").describe("Per-flow run toggles; null = the shared default");
+exports.headerArg = zod_1.z
+    .record(zod_1.z.unknown())
+    .optional()
+    .describe("Extra header keys (appActivity, deviceName, env, tags, onFlowStart …; null removes one). url/appId have their own arguments");
+exports.groupArg = zod_1.z
+    .string()
+    .max(200)
+    .optional()
+    .describe('On-prem: the group that owns it (name or id, or "personal"). Needed when you belong to several groups; ignored on cloud');
+const resolveGroupId = async (ctx, ws, ref) => {
+    if (!ref)
+        return {};
+    if (ref.trim().toLowerCase() === "personal")
+        return { id: "personal" };
+    const { items } = await ctx.api.listMyScenarioGroups(ws);
+    if (items.length === 0)
+        return { note: "Groups exist only on-prem — `group` was ignored." };
+    return { id: (0, resolve_js_1.resolveRef)("group", ref, items).item.id };
+};
+exports.resolveGroupId = resolveGroupId;
+const lintContext = async (ctx, workspaceId) => {
+    const [flows, connections] = await Promise.all([
+        (0, lookups_js_1.loadUiTests)(ctx),
+        // A token without requests:read / scenarios:read cannot list connections —
+        // then the connection check is skipped, not failed.
+        (0, lookups_js_1.loadConnections)(ctx, workspaceId).catch(() => null),
+    ]);
+    return { flowNames: [...new Set(flows.map((flow) => flow.name))], connections };
+};
+exports.lintContext = lintContext;
+const lintFlow = (content, platform, context, datasetKeys) => (0, callman_core_1.lintUiTestFlow)(content, {
+    platform,
+    knownFlowNames: context.flowNames,
+    ...(context.connections ? { knownConnections: context.connections.flatMap((connection) => [connection.name, connection.id]) } : {}),
+    datasetKeys,
+});
+exports.lintFlow = lintFlow;
+const lintView = (lint, context) => ({
+    ok: lint.ok,
+    errors: lint.errors,
+    warnings: lint.warnings,
+    ...(context && !context.connections ? { note: "Connection names were not checked (the token cannot list connections)." } : {}),
+});
+exports.lintView = lintView;
+const refuseLintErrors = (lint, force, content) => {
+    if (lint.ok || force)
+        return;
+    throw new errors_js_1.ToolInputError("UI_TEST_LINT_FAILED", `The flow has ${lint.errors.length} error${lint.errors.length === 1 ? "" : "s"} the engine would trip on — fix them (callman://docs/ui-test-steps), or pass force: true to save anyway.`, {
+        errors: lint.errors,
+        warnings: lint.warnings,
+        content: (0, truncate_js_1.clipBytes)(content, 8_000).text,
+    });
+};
+exports.refuseLintErrors = refuseLintErrors;
+const resolveDatasetSources = async (ctx, ws, sources, current = {}) => {
+    const out = { ...current };
+    const entries = Object.entries(sources);
+    const connections = entries.some(([, source]) => source) ? await (0, lookups_js_1.loadConnections)(ctx, ws) : [];
+    for (const [key, source] of entries) {
+        if (!source) {
+            delete out[key];
+            continue;
+        }
+        const connection = (0, resolve_js_1.resolveRef)("connection", source.connection, connections, { describe: (entry) => ({ type: entry.type }) }).item;
+        if (connection.type !== "database") {
+            throw new errors_js_1.ToolInputError("CONNECTION_WRONG_TYPE", `Dataset source "${key}": "${connection.name}" is a ${connection.type} connection — a dataset source needs a database connection.`);
+        }
+        out[key] = { kind: "db", connection: connection.id, query: source.query, ...(source.column ? { column: source.column } : {}) };
+    }
+    return out;
+};
+exports.resolveDatasetSources = resolveDatasetSources;
+// ── the full-state upsert ──────────────────────────────────────────────
+const UPSERT_FIELDS = ["name", "description", "platform", "content", "testType", "severity", "tags", "folderId", "dataset", "datasetSources", "dismissPopups", "browserKind", "headless", "runSettings"];
+// The backend accepts null for "clear" on description / folderId / browserKind /
+// headless / runSettings, but testType and severity are optional, not nullable.
+const NOT_NULLABLE = new Set(["testType", "severity"]);
+const upsertBodyOf = (flow) => {
+    const body = { clientId: flow.clientId };
+    for (const field of UPSERT_FIELDS) {
+        const value = flow[field];
+        if (value === undefined || (value === null && NOT_NULLABLE.has(field)))
+            continue;
+        body[field] = value;
+    }
+    return body;
+};
+exports.upsertBodyOf = upsertBodyOf;
+/** Refuses masked values the CALLER supplied. Masks read back from the flow
+ *  itself may be sent unchanged: the backend keeps the stored secret when a
+ *  value equals the mask of what is stored under that key. */
+const refuseMaskedDataset = (dataset) => {
+    const keys = (0, summarize_js_1.maskedDatasetKeys)(dataset);
+    if (keys.length === 0)
+        return;
+    throw new errors_js_1.ToolInputError("MASKED_VALUE", `Masked values cannot be saved (dataset keys: ${keys.join(", ")}). Supply the real values, or leave those keys out to keep what is stored.`, { keys });
+};
+exports.refuseMaskedDataset = refuseMaskedDataset;
+const saveFlow = async (ctx, ws, body, options = {}) => {
+    try {
+        const flow = await ctx.api.upsertUiTest(ws, { ...body, ...(options.expectedVersion !== undefined ? { expectedVersion: options.expectedVersion } : {}), ...(options.force ? { force: true } : {}) });
+        ctx.invalidate("uitests:");
+        return { flow };
+    }
+    catch (error) {
+        if (error instanceof errors_js_1.CallmanApiError && error.code === "UI_TEST_SCENARIO_VERSION_CONFLICT") {
+            const details = (error.details ?? {});
+            return {
+                conflict: {
+                    conflict: true,
+                    code: error.code,
+                    message: error.message,
+                    currentVersion: details.currentVersion ?? details.currentScenario?.version ?? null,
+                    hint: "Someone saved the flow since you read it. Re-read it (get_ui_test), reapply your change and retry with expectedVersion = currentVersion — or force: true to overwrite.",
+                },
+            };
+        }
+        throw error;
+    }
+};
+exports.saveFlow = saveFlow;
+const conflictResult = (conflict) => (0, shared_js_1.ok)(conflict);
+exports.conflictResult = conflictResult;
+// ── views ──────────────────────────────────────────────────────────────
+const connectionNames = (connections) => new Map((connections ?? []).map((connection) => [connection.id, connection.name]));
+exports.connectionNames = connectionNames;
+const flowDetailView = async (ctx, flow, lint, context, options) => {
+    const folders = await (0, lookups_js_1.loadUiTestFolders)(ctx).catch(() => []);
+    const folder = flow.folderId ? folders.find((entry) => entry.id === flow.folderId) : undefined;
+    const names = (0, exports.connectionNames)(context.connections);
+    const workspace = options.workspaces.find((entry) => entry.id === flow.workspaceId);
+    const content = flow.content ?? "";
+    const clipped = (0, truncate_js_1.clipBytes)(content, truncate_js_1.LIMITS.SCENARIO_FULL);
+    const masked = (0, summarize_js_1.maskedDatasetKeys)(flow.dataset);
+    return {
+        id: flow.clientId,
+        name: flow.name,
+        platform: flow.platform,
+        workspace: { id: flow.workspaceId, name: workspace?.name ?? null },
+        folder: folder ? { id: folder.id, path: folder.path } : null,
+        ...(flow.groupName ? { group: flow.groupName } : {}),
+        description: flow.description ?? null,
+        testType: flow.testType ?? null,
+        severity: flow.severity ?? null,
+        tags: flow.tags ?? [],
+        version: flow.version ?? null,
+        ...(flow.reviewStatus ? { reviewStatus: flow.reviewStatus, approvedVersion: flow.approvedVersion ?? null, activeVersionNumber: flow.activeVersionNumber ?? null, ...(flow.reviewNote ? { reviewNote: flow.reviewNote } : {}) } : {}),
+        header: lint.header,
+        settings: (0, summarize_js_1.settingsView)(flow),
+        dataset: flow.dataset ?? {},
+        ...(masked.length > 0 ? { datasetMasked: masked } : {}),
+        datasetSources: Object.fromEntries(Object.entries(flow.datasetSources ?? {}).map(([key, source]) => [key, { ...source, ...(names.get(source.connection) ? { connectionName: names.get(source.connection) } : {}) }])),
+        preconditions: lint.preconditions,
+        steps: lint.steps,
+        lint: (0, exports.lintView)(lint, context),
+        ...(options.includeContent === false ? {} : { content: clipped.text, ...(clipped.truncated ? { contentTruncated: true, contentBytes: clipped.totalBytes } : {}) }),
+        ...(masked.length > 0 && options.reveal ? { note: "Secret dataset values stayed masked: the token lacks environments:reveal." } : {}),
+    };
+};
+exports.flowDetailView = flowDetailView;
+const workspaceIdOf = (flow) => {
+    if (!flow.workspaceId)
+        throw new errors_js_1.ToolInputError("UI_TEST_WORKSPACE_UNKNOWN", `The server did not say which workspace "${flow.name}" is in.`);
+    return flow.workspaceId;
+};
+exports.workspaceIdOf = workspaceIdOf;