agent-scenario-loop 0.1.0

package/dist/runner/argent-driver.d.ts

@@ -0,0 +1,183 @@
+type ArgentCommandResult = {
+    action: string;
+    args: string[];
+    capturePath?: string;
+    command: string;
+    exitCode: number;
+    rawFileName: string;
+    stderr: string;
+    stdout: string;
+};
+type ArgentCommandExecutor = (command: string, args: string[]) => Promise<{
+    args: string[];
+    command: string;
+    exitCode: number;
+    stderr: string;
+    stdout: string;
+}>;
+type ArgentDriverOptions = {
+    appFlag?: string;
+    appId?: string;
+    argentCommand: string;
+    baseArgs?: string[];
+    deviceFlag?: string;
+    deviceId: string;
+    executor: ArgentCommandExecutor;
+    extraArgs?: string[];
+    screenSize?: ArgentScreenSize;
+};
+type ArgentDriver = {
+    assertVisible: (options: ArgentAssertVisibleOptions) => Promise<ArgentCommandResult>;
+    inspectTree: (options?: ArgentInspectTreeOptions) => Promise<ArgentCommandResult>;
+    launchApp: (options?: ArgentLaunchAppOptions) => Promise<ArgentCommandResult>;
+    openUrl: (options: ArgentOpenUrlOptions) => Promise<ArgentCommandResult>;
+    screenshot: (options?: ArgentScreenshotOptions) => Promise<ArgentCommandResult>;
+    scroll: (options: ArgentScrollOptions) => Promise<ArgentCommandResult>;
+    tap: (options: ArgentTapOptions) => Promise<ArgentCommandResult>;
+};
+type ArgentScreenSize = {
+    height: number;
+    width: number;
+};
+type ArgentPointInput = {
+    screenSize?: ArgentScreenSize;
+    x: number;
+    y: number;
+};
+type ArgentNormalizedPoint = {
+    x: number;
+    y: number;
+};
+type ArgentSelector = {
+    kind: string;
+    match?: string;
+    value: string;
+};
+type ArgentAssertVisibleOptions = {
+    appId?: string;
+    rawFileName?: string;
+    selector: ArgentSelector;
+};
+type ArgentInspectTreeOptions = {
+    appId?: string;
+    rawFileName?: string;
+};
+type ArgentLaunchAppOptions = {
+    appId?: string;
+    rawFileName?: string;
+};
+type ArgentOpenUrlOptions = {
+    rawFileName?: string;
+    url: string;
+};
+type ArgentScreenshotOptions = {
+    rawFileName?: string;
+};
+type ArgentScrollOptions = {
+    durationMs?: number;
+    endX: number;
+    endY: number;
+    rawFileName?: string;
+    screenSize?: ArgentScreenSize;
+    startX: number;
+    startY: number;
+};
+type ArgentTapOptions = {
+    rawFileName?: string;
+    screenSize?: ArgentScreenSize;
+    x: number;
+    y: number;
+};
+/**
+ * Returns true when Argent emitted a complete action result before a wrapper timeout.
+ *
+ * @param {string} action
+ * @param {string} stdout
+ * @param {string | undefined} capturePath
+ * @returns {boolean}
+ */
+declare function hasCompletedArgentOutput(action: string, stdout: string, capturePath?: string): boolean;
+/**
+ * Keeps successful Argent output from being failed only because a wrapper helper lingered.
+ *
+ * @param {ArgentCommandResult} result
+ * @returns {ArgentCommandResult}
+ */
+declare function normalizeArgentResultExitCode(result: ArgentCommandResult): ArgentCommandResult;
+/**
+ * Combines stdout and stderr into raw evidence text.
+ *
+ * @param {{stdout: string, stderr: string}} result
+ * @returns {string}
+ */
+declare function formatArgentRawOutput(result: {
+    stdout: string;
+    stderr: string;
+}): string;
+/**
+ * Builds the command argv for one `argent run <tool>` style invocation.
+ *
+ * @param {ArgentDriverOptions} options
+ * @param {string} tool
+ * @param {string[]} [args]
+ * @returns {string[]}
+ */
+declare function buildArgentRunArgs(options: ArgentDriverOptions, tool: string, args?: string[]): string[];
+/**
+ * Extracts a local screenshot path from common Argent CLI output.
+ *
+ * @param {string} text
+ * @returns {string | null}
+ */
+declare function extractArgentScreenshotPath(text: string): string | null;
+/**
+ * Parses a JSON object from Argent output when the tool returns structured data.
+ *
+ * @param {string} text
+ * @returns {Record<string, unknown> | null}
+ */
+declare function parseArgentRunJson(text: string): Record<string, unknown> | null;
+/**
+ * Returns the Argent description text from either plain or JSON command output.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+declare function readArgentDescription(text: string): string;
+/**
+ * Detects collapsed UI descriptions that should fail scenario health upstream.
+ *
+ * @param {string} text
+ * @returns {boolean}
+ */
+declare function isArgentRootOnlyDescription(text: string): boolean;
+/**
+ * Converts pixel coordinates into Argent's normalized 0-1 coordinate space.
+ *
+ * @param {ArgentPointInput} point
+ * @returns {ArgentNormalizedPoint}
+ */
+declare function normalizeArgentPoint({ screenSize, x, y }: ArgentPointInput): ArgentNormalizedPoint;
+/**
+ * Checks whether an Argent UI description contains a portable selector target.
+ *
+ * @param {{description: string, selector: ArgentSelector}} options
+ * @returns {boolean}
+ */
+declare function matchesArgentSelector({ description, selector, }: {
+    description: string;
+    selector: ArgentSelector;
+}): boolean;
+/**
+ * Creates an Argent-backed driver for portable interaction actions.
+ *
+ * The adapter shells out through an injected executor so consumers can use a
+ * global `argent` binary, `npx --yes @swmansion/argent run`, or a test double
+ * without making Argent a package dependency.
+ *
+ * @param {ArgentDriverOptions} options
+ * @returns {ArgentDriver}
+ */
+declare function createArgentDriver(options: ArgentDriverOptions): ArgentDriver;
+export { buildArgentRunArgs, createArgentDriver, extractArgentScreenshotPath, formatArgentRawOutput, hasCompletedArgentOutput, isArgentRootOnlyDescription, matchesArgentSelector, normalizeArgentPoint, normalizeArgentResultExitCode, parseArgentRunJson, readArgentDescription, };
+export type { ArgentAssertVisibleOptions, ArgentCommandExecutor, ArgentCommandResult, ArgentDriver, ArgentDriverOptions, ArgentInspectTreeOptions, ArgentLaunchAppOptions, ArgentNormalizedPoint, ArgentOpenUrlOptions, ArgentPointInput, ArgentScreenshotOptions, ArgentScreenSize, ArgentScrollOptions, ArgentSelector, ArgentTapOptions, };

package/dist/runner/argent-driver.js

@@ -0,0 +1,297 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildArgentRunArgs = buildArgentRunArgs;
+exports.createArgentDriver = createArgentDriver;
+exports.extractArgentScreenshotPath = extractArgentScreenshotPath;
+exports.formatArgentRawOutput = formatArgentRawOutput;
+exports.hasCompletedArgentOutput = hasCompletedArgentOutput;
+exports.isArgentRootOnlyDescription = isArgentRootOnlyDescription;
+exports.matchesArgentSelector = matchesArgentSelector;
+exports.normalizeArgentPoint = normalizeArgentPoint;
+exports.normalizeArgentResultExitCode = normalizeArgentResultExitCode;
+exports.parseArgentRunJson = parseArgentRunJson;
+exports.readArgentDescription = readArgentDescription;
+/**
+ * Adds stable driver metadata to one Argent command result.
+ *
+ * @param {{action: string, capturePath?: string, rawFileName: string, result: Awaited<ReturnType<ArgentCommandExecutor>>}} options
+ * @returns {ArgentCommandResult}
+ */
+function buildArgentResult({ action, capturePath, rawFileName, result, }) {
+    return {
+        action,
+        args: result.args,
+        command: result.command,
+        exitCode: result.exitCode,
+        rawFileName,
+        stderr: result.stderr,
+        stdout: result.stdout,
+        ...(capturePath ? { capturePath } : {}),
+    };
+}
+/**
+ * Returns true when Argent emitted a complete action result before a wrapper timeout.
+ *
+ * @param {string} action
+ * @param {string} stdout
+ * @param {string | undefined} capturePath
+ * @returns {boolean}
+ */
+function hasCompletedArgentOutput(action, stdout, capturePath) {
+    const parsed = parseArgentRunJson(stdout);
+    if (action === 'screenshot') {
+        return typeof capturePath === 'string' && capturePath.length > 0;
+    }
+    if (['assertVisible', 'inspectTree'].includes(action)) {
+        return readArgentDescription(stdout).trim().length > 0;
+    }
+    if (parsed?.success === true || parsed?.launched === true) {
+        return true;
+    }
+    if (action === 'launch' && typeof parsed?.bundleId === 'string') {
+        return true;
+    }
+    return false;
+}
+/**
+ * Keeps successful Argent output from being failed only because a wrapper helper lingered.
+ *
+ * @param {ArgentCommandResult} result
+ * @returns {ArgentCommandResult}
+ */
+function normalizeArgentResultExitCode(result) {
+    if (result.exitCode !== 0 &&
+        /timed out after \d+ms/iu.test(result.stderr) &&
+        hasCompletedArgentOutput(result.action, result.stdout, result.capturePath)) {
+        return {
+            ...result,
+            exitCode: 0,
+        };
+    }
+    return result;
+}
+/**
+ * Combines stdout and stderr into raw evidence text.
+ *
+ * @param {{stdout: string, stderr: string}} result
+ * @returns {string}
+ */
+function formatArgentRawOutput(result) {
+    return [result.stdout, result.stderr].filter(Boolean).join('\n');
+}
+/**
+ * Builds the command argv for one `argent run <tool>` style invocation.
+ *
+ * @param {ArgentDriverOptions} options
+ * @param {string} tool
+ * @param {string[]} [args]
+ * @returns {string[]}
+ */
+function buildArgentRunArgs(options, tool, args = []) {
+    return [
+        ...(options.baseArgs ?? ['run']),
+        tool,
+        options.deviceFlag ?? '--udid',
+        options.deviceId,
+        ...args,
+        ...(options.extraArgs ?? []),
+    ];
+}
+/**
+ * Extracts a local screenshot path from common Argent CLI output.
+ *
+ * @param {string} text
+ * @returns {string | null}
+ */
+function extractArgentScreenshotPath(text) {
+    const parsed = parseArgentRunJson(text);
+    for (const key of ['path', 'image']) {
+        const jsonPath = parsed?.[key];
+        if (typeof jsonPath === 'string' && jsonPath.length > 0) {
+            return jsonPath;
+        }
+    }
+    const savedMatch = /(?:Saved screenshot|Screenshot saved(?: to)?):\s*(?<path>\S.+)$/imu.exec(text);
+    return savedMatch?.groups?.path?.trim() ?? null;
+}
+/**
+ * Parses a JSON object from Argent output when the tool returns structured data.
+ *
+ * @param {string} text
+ * @returns {Record<string, unknown> | null}
+ */
+function parseArgentRunJson(text) {
+    const trimmed = text.trim();
+    if (!trimmed) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(trimmed);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Returns the Argent description text from either plain or JSON command output.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+function readArgentDescription(text) {
+    const parsed = parseArgentRunJson(text);
+    return typeof parsed?.description === 'string' ? parsed.description : text;
+}
+/**
+ * Detects collapsed UI descriptions that should fail scenario health upstream.
+ *
+ * @param {string} text
+ * @returns {boolean}
+ */
+function isArgentRootOnlyDescription(text) {
+    const description = readArgentDescription(text).trim();
+    return /^root$/iu.test(description) || /^<root\s*\/?>$/iu.test(description);
+}
+/**
+ * Converts pixel coordinates into Argent's normalized 0-1 coordinate space.
+ *
+ * @param {ArgentPointInput} point
+ * @returns {ArgentNormalizedPoint}
+ */
+function normalizeArgentPoint({ screenSize, x, y }) {
+    if (!screenSize) {
+        return { x, y };
+    }
+    if (!Number.isFinite(screenSize.width) ||
+        !Number.isFinite(screenSize.height) ||
+        screenSize.width <= 0 ||
+        screenSize.height <= 0) {
+        throw new Error('Argent screen size must have positive width and height.');
+    }
+    return {
+        x: Math.min(Math.max(x / screenSize.width, 0), 1),
+        y: Math.min(Math.max(y / screenSize.height, 0), 1),
+    };
+}
+/**
+ * Normalizes a point while preserving exact optional property semantics.
+ *
+ * @param {{screenSize?: ArgentScreenSize, x: number, y: number}} point
+ * @returns {ArgentNormalizedPoint}
+ */
+function normalizeArgentPointWithOptionalScreenSize({ screenSize, x, y, }) {
+    return screenSize
+        ? normalizeArgentPoint({ screenSize, x, y })
+        : normalizeArgentPoint({ x, y });
+}
+/**
+ * Checks whether an Argent UI description contains a portable selector target.
+ *
+ * @param {{description: string, selector: ArgentSelector}} options
+ * @returns {boolean}
+ */
+function matchesArgentSelector({ description, selector, }) {
+    const descriptionText = readArgentDescription(description);
+    const matchMode = selector.match ?? (selector.kind === 'regex' ? 'regex' : undefined);
+    if (matchMode === 'regex') {
+        try {
+            return new RegExp(selector.value, 'u').test(descriptionText);
+        }
+        catch {
+            return false;
+        }
+    }
+    return descriptionText.includes(selector.value);
+}
+/**
+ * Creates an Argent-backed driver for portable interaction actions.
+ *
+ * The adapter shells out through an injected executor so consumers can use a
+ * global `argent` binary, `npx --yes @swmansion/argent run`, or a test double
+ * without making Argent a package dependency.
+ *
+ * @param {ArgentDriverOptions} options
+ * @returns {ArgentDriver}
+ */
+function createArgentDriver(options) {
+    const run = async (action, tool, rawFileName, args = [], capturePath) => {
+        const result = await options.executor(options.argentCommand, buildArgentRunArgs(options, tool, args));
+        return normalizeArgentResultExitCode(buildArgentResult({
+            action,
+            rawFileName,
+            result,
+            ...(capturePath ? { capturePath } : {}),
+        }));
+    };
+    const appArgs = (appId) => {
+        const resolvedAppId = appId ?? options.appId;
+        return resolvedAppId ? [options.appFlag ?? '--bundleId', resolvedAppId] : [];
+    };
+    return {
+        async assertVisible({ appId, rawFileName = 'argent-assert-visible.txt', selector, }) {
+            const result = await run('assertVisible', 'describe', rawFileName, appArgs(appId));
+            if (!matchesArgentSelector({ description: formatArgentRawOutput(result), selector })) {
+                return {
+                    ...result,
+                    exitCode: result.exitCode === 0 ? 1 : result.exitCode,
+                    stderr: [result.stderr, `Argent description did not include ${selector.kind} \`${selector.value}\`.`]
+                        .filter(Boolean)
+                        .join('\n'),
+                };
+            }
+            return {
+                ...result,
+                exitCode: 0,
+            };
+        },
+        async inspectTree({ appId, rawFileName = 'argent-describe.txt', } = {}) {
+            return run('inspectTree', 'describe', rawFileName, appArgs(appId));
+        },
+        async launchApp({ appId, rawFileName = 'argent-launch-app.txt', } = {}) {
+            return run('launch', 'launch-app', rawFileName, appArgs(appId));
+        },
+        async openUrl({ rawFileName = 'argent-open-url.txt', url, }) {
+            return run('openUrl', 'open-url', rawFileName, ['--url', url]);
+        },
+        async screenshot({ rawFileName = 'argent-screenshot.txt', } = {}) {
+            const result = await run('screenshot', 'screenshot', rawFileName, ['--includeImageInContext', 'false']);
+            const capturePath = extractArgentScreenshotPath(result.stdout);
+            return normalizeArgentResultExitCode(capturePath ? { ...result, capturePath } : result);
+        },
+        async scroll({ durationMs = 300, endX, endY, rawFileName = 'argent-swipe.txt', screenSize, startX, startY, }) {
+            const from = normalizeArgentPointWithOptionalScreenSize({
+                ...(screenSize ?? options.screenSize ? { screenSize: screenSize ?? options.screenSize } : {}),
+                x: startX,
+                y: startY,
+            });
+            const to = normalizeArgentPointWithOptionalScreenSize({
+                ...(screenSize ?? options.screenSize ? { screenSize: screenSize ?? options.screenSize } : {}),
+                x: endX,
+                y: endY,
+            });
+            return run('scroll', 'gesture-swipe', rawFileName, [
+                '--fromX',
+                String(from.x),
+                '--fromY',
+                String(from.y),
+                '--toX',
+                String(to.x),
+                '--toY',
+                String(to.y),
+                '--durationMs',
+                String(durationMs),
+            ]);
+        },
+        async tap({ rawFileName = 'argent-tap.txt', screenSize, x, y, }) {
+            const point = normalizeArgentPointWithOptionalScreenSize({
+                ...(screenSize ?? options.screenSize ? { screenSize: screenSize ?? options.screenSize } : {}),
+                x,
+                y,
+            });
+            return run('tap', 'gesture-tap', rawFileName, ['--x', String(point.x), '--y', String(point.y)]);
+        },
+    };
+}