@ishlabs/cli 0.8.1

package/dist/lib/alias-store.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Short alias system for entity IDs.
+ *
+ * Generates deterministic aliases from UUID prefixes (e.g. w-6ec, s-b2c, tp-d4e).
+ * Same UUID always produces the same alias — stable across commands and terminals.
+ * Aliases are persisted to ~/.ish/aliases.json for resolution.
+ */
+/** Entity type → alias prefix */
+export declare const ALIAS_PREFIX: {
+    readonly workspace: "w";
+    readonly study: "s";
+    readonly iteration: "i";
+    readonly testerProfile: "tp";
+    readonly tester: "t";
+    readonly config: "c";
+    readonly job: "j";
+};
+/**
+ * Save aliases for a list of IDs under the given prefix.
+ * Clears all existing aliases for that prefix before saving.
+ * Numbers start at `startIndex` (default 1) to support pagination.
+ */
+export declare function saveAliases(prefix: string, ids: string[], startIndex?: number): void;
+/**
+ * Build a uuid→alias map for a given prefix (used by formatters to display aliases).
+ */
+export declare function getAliasMap(prefix: string): Map<string, string>;
+/**
+ * Register a single entity ID under the given prefix.
+ * If the ID already has an alias, returns the existing one.
+ * Otherwise assigns the next available number.
+ */
+export declare function tagAlias(prefix: string, id: string): string;
+/**
+ * Generate a deterministic alias from a UUID prefix (like git short hashes).
+ * Format: {prefix}-{first 3 hex chars}, extended on collision.
+ * Same UUID always produces the same alias — stable across commands and terminals.
+ */
+export declare function deterministicAlias(prefix: string, uuid: string): string;
+/**
+ * Resolve a short alias to a full UUID, or validate and pass through a full UUID.
+ *
+ * Accepted formats:
+ *   - Short alias: w-6ec, s-b2c, tp-d4e (resolved from ~/.ish/aliases.json)
+ *   - Full UUID:   6ecf2857-1d7a-4f9c-85da-c2ac6c5c5346
+ *
+ * Everything else throws with guidance toward the correct usage.
+ */
+export declare function resolveId(input: string): string;

package/dist/lib/alias-store.js

@@ -0,0 +1,138 @@
+/**
+ * Short alias system for entity IDs.
+ *
+ * Generates deterministic aliases from UUID prefixes (e.g. w-6ec, s-b2c, tp-d4e).
+ * Same UUID always produces the same alias — stable across commands and terminals.
+ * Aliases are persisted to ~/.ish/aliases.json for resolution.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+const ALIASES_FILE = path.join(os.homedir(), ".ish", "aliases.json");
+/** Entity type → alias prefix */
+export const ALIAS_PREFIX = {
+    workspace: "w",
+    study: "s",
+    iteration: "i",
+    testerProfile: "tp",
+    tester: "t",
+    config: "c",
+    job: "j",
+};
+/** Format a number with zero-padding (minimum 2 digits). */
+function padNum(n) {
+    return String(n).padStart(2, "0");
+}
+function loadAliases() {
+    try {
+        if (fs.existsSync(ALIASES_FILE)) {
+            return JSON.parse(fs.readFileSync(ALIASES_FILE, "utf-8"));
+        }
+    }
+    catch {
+        // Corrupted — start fresh
+    }
+    return {};
+}
+function persistAliases(aliases) {
+    const dir = path.dirname(ALIASES_FILE);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const tmp = ALIASES_FILE + ".tmp";
+    fs.writeFileSync(tmp, JSON.stringify(aliases, null, 2) + "\n", { mode: 0o600 });
+    fs.renameSync(tmp, ALIASES_FILE);
+}
+/**
+ * Save aliases for a list of IDs under the given prefix.
+ * Clears all existing aliases for that prefix before saving.
+ * Numbers start at `startIndex` (default 1) to support pagination.
+ */
+export function saveAliases(prefix, ids, startIndex = 1) {
+    const aliases = loadAliases();
+    // Remove existing entries for this prefix (both old and new format)
+    const prefixPattern = new RegExp(`^${prefix}\\d+$`);
+    for (const key of Object.keys(aliases)) {
+        if (prefixPattern.test(key)) {
+            delete aliases[key];
+        }
+    }
+    // Save new mappings with zero-padded numbers
+    for (let i = 0; i < ids.length; i++) {
+        aliases[`${prefix}${padNum(startIndex + i)}`] = ids[i];
+    }
+    persistAliases(aliases);
+}
+/**
+ * Build a uuid→alias map for a given prefix (used by formatters to display aliases).
+ */
+export function getAliasMap(prefix) {
+    const aliases = loadAliases();
+    const map = new Map();
+    const prefixPattern = new RegExp(`^${prefix}(\\d{2,}|-[0-9a-f]{3,})$`);
+    for (const [alias, uuid] of Object.entries(aliases)) {
+        if (prefixPattern.test(alias)) {
+            map.set(uuid, alias);
+        }
+    }
+    return map;
+}
+/**
+ * Register a single entity ID under the given prefix.
+ * If the ID already has an alias, returns the existing one.
+ * Otherwise assigns the next available number.
+ */
+export function tagAlias(prefix, id) {
+    // Delegate to deterministic alias for consistency
+    return deterministicAlias(prefix, id);
+}
+/**
+ * Generate a deterministic alias from a UUID prefix (like git short hashes).
+ * Format: {prefix}-{first 3 hex chars}, extended on collision.
+ * Same UUID always produces the same alias — stable across commands and terminals.
+ */
+export function deterministicAlias(prefix, uuid) {
+    const clean = uuid.replace(/-/g, "");
+    let len = 3;
+    let alias = `${prefix}-${clean.slice(0, len)}`;
+    const aliases = loadAliases();
+    // Adaptive extension: if this alias maps to a DIFFERENT UUID, extend
+    while (aliases[alias] && aliases[alias] !== uuid) {
+        len++;
+        alias = `${prefix}-${clean.slice(0, len)}`;
+    }
+    // Persist if new
+    if (!aliases[alias]) {
+        aliases[alias] = uuid;
+        persistAliases(aliases);
+    }
+    return alias;
+}
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const ALIAS_RE = /^[a-z]+-[0-9a-f]{3,}$|^[a-z]+\d{2,}$/;
+/**
+ * Resolve a short alias to a full UUID, or validate and pass through a full UUID.
+ *
+ * Accepted formats:
+ *   - Short alias: w-6ec, s-b2c, tp-d4e (resolved from ~/.ish/aliases.json)
+ *   - Full UUID:   6ecf2857-1d7a-4f9c-85da-c2ac6c5c5346
+ *
+ * Everything else throws with guidance toward the correct usage.
+ */
+export function resolveId(input) {
+    // 1. Full UUID — validate format and pass through
+    if (UUID_RE.test(input)) {
+        return input;
+    }
+    // 2. Known alias pattern — resolve from store
+    if (ALIAS_RE.test(input)) {
+        const aliases = loadAliases();
+        const uuid = aliases[input];
+        if (uuid)
+            return uuid;
+        throw new Error(`Unknown alias "${input}". Run a list command first to generate aliases.`);
+    }
+    // 3. Anything else — fail with helpful guidance
+    throw new Error(`Invalid ID "${input}". Use a short alias (e.g. w-a3f, s-b2c) or a full UUID.\n` +
+        "Run a list command first to see available aliases:\n" +
+        "  ish workspace list\n" +
+        "  ish study list --workspace <id>");
+}

package/dist/lib/api-client.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Shared HTTP API client for the Ish backend.
+ */
+export declare class ApiError extends Error {
+    status: number;
+    statusText: string;
+    body: unknown;
+    error_code: string;
+    retryable: boolean;
+    constructor(status: number, statusText: string, body: unknown);
+}
+export declare class ApiClient {
+    private baseUrl;
+    private token;
+    constructor(opts: {
+        apiUrl: string;
+        token: string;
+    });
+    get accessToken(): string;
+    private headers;
+    get<T = unknown>(path: string, params?: Record<string, string>): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown, opts?: {
+        timeout?: number;
+    }): Promise<T>;
+    put<T = unknown>(path: string, body?: unknown): Promise<T>;
+    del(path: string): Promise<void>;
+    localSimInit(body: {
+        tester_id: string;
+        study_id: string;
+        product_id: string;
+        iteration_id: string;
+    }): Promise<import("./local-sim/types.js").LocalSimInitResponse>;
+    localSimStep(body: import("./local-sim/types.js").LocalSimStepRequest): Promise<import("./local-sim/types.js").LocalSimStepResponseRaw>;
+    localSimRecord(body: import("./local-sim/types.js").LocalSimRecordRequest): Promise<import("./local-sim/types.js").LocalSimRecordResponse>;
+    localSimMatchFrame(body: {
+        product_id: string;
+        study_id: string;
+        screenshot_base64: string;
+        screenshot_url?: string;
+        location_name: string;
+        screen_format?: string;
+    }): Promise<{
+        frame_version_id: string;
+    }>;
+    localSimScreenshotUpload(body: {
+        product_id: string;
+        screenshot_id: string;
+        content_type: string;
+    }): Promise<{
+        upload_info: {
+            signed_upload_url: string;
+            file_path: string;
+            expires_in_seconds: number;
+        };
+        screenshot_url: string;
+    }>;
+    private handleResponse;
+}

package/dist/lib/api-client.js

@@ -0,0 +1,177 @@
+/**
+ * Shared HTTP API client for the Ish backend.
+ */
+import { API_BASE } from "./auth.js";
+function mapErrorCode(status) {
+    if (status === 401)
+        return "auth_failed";
+    if (status === 403)
+        return "forbidden";
+    if (status === 404)
+        return "not_found";
+    if (status === 402)
+        return "insufficient_credits";
+    if (status === 422)
+        return "validation_error";
+    if (status === 429)
+        return "rate_limited";
+    if (status >= 500)
+        return "server_error";
+    return "request_failed";
+}
+function isRetryable(status) {
+    return status === 429 || status >= 500;
+}
+export class ApiError extends Error {
+    status;
+    statusText;
+    body;
+    error_code;
+    retryable;
+    constructor(status, statusText, body) {
+        const msg = typeof body === "object" && body !== null && "detail" in body
+            ? String(body.detail)
+            : `HTTP ${status} ${statusText}`;
+        super(msg);
+        this.status = status;
+        this.statusText = statusText;
+        this.body = body;
+        this.name = "ApiError";
+        this.error_code = mapErrorCode(status);
+        this.retryable = isRetryable(status);
+    }
+}
+export class ApiClient {
+    baseUrl;
+    token;
+    constructor(opts) {
+        this.baseUrl = `${opts.apiUrl}${API_BASE}`;
+        this.token = opts.token;
+    }
+    get accessToken() {
+        return this.token;
+    }
+    headers() {
+        return {
+            Authorization: `Bearer ${this.token}`,
+            "Content-Type": "application/json",
+        };
+    }
+    async get(path, params) {
+        let url = `${this.baseUrl}${path}`;
+        if (params) {
+            const filtered = Object.entries(params).filter(([, v]) => v !== undefined && v !== "");
+            if (filtered.length > 0) {
+                url += "?" + new URLSearchParams(filtered).toString();
+            }
+        }
+        let res;
+        try {
+            res = await fetch(url, {
+                headers: this.headers(),
+                signal: AbortSignal.timeout(15_000),
+            });
+        }
+        catch (err) {
+            if (err instanceof DOMException && (err.name === 'TimeoutError' || err.name === 'AbortError')) {
+                throw new Error('Request timed out after 15s. The server may be slow — try again.');
+            }
+            throw err;
+        }
+        return this.handleResponse(res);
+    }
+    async post(path, body, opts) {
+        const timeout = opts?.timeout ?? 15_000;
+        let res;
+        try {
+            res = await fetch(`${this.baseUrl}${path}`, {
+                method: "POST",
+                headers: this.headers(),
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+                signal: AbortSignal.timeout(timeout),
+            });
+        }
+        catch (err) {
+            if (err instanceof DOMException && (err.name === 'TimeoutError' || err.name === 'AbortError')) {
+                throw new Error(`Request timed out after ${timeout / 1000}s. The server may be slow — try again.`);
+            }
+            throw err;
+        }
+        return this.handleResponse(res);
+    }
+    async put(path, body) {
+        let res;
+        try {
+            res = await fetch(`${this.baseUrl}${path}`, {
+                method: "PUT",
+                headers: this.headers(),
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+                signal: AbortSignal.timeout(15_000),
+            });
+        }
+        catch (err) {
+            if (err instanceof DOMException && (err.name === 'TimeoutError' || err.name === 'AbortError')) {
+                throw new Error('Request timed out after 15s. The server may be slow — try again.');
+            }
+            throw err;
+        }
+        return this.handleResponse(res);
+    }
+    async del(path) {
+        let res;
+        try {
+            res = await fetch(`${this.baseUrl}${path}`, {
+                method: "DELETE",
+                headers: this.headers(),
+                signal: AbortSignal.timeout(15_000),
+            });
+        }
+        catch (err) {
+            if (err instanceof DOMException && (err.name === 'TimeoutError' || err.name === 'AbortError')) {
+                throw new Error('Request timed out after 15s. The server may be slow — try again.');
+            }
+            throw err;
+        }
+        if (!res.ok) {
+            let body;
+            try {
+                body = await res.json();
+            }
+            catch {
+                body = null;
+            }
+            throw new ApiError(res.status, res.statusText, body);
+        }
+    }
+    // --- Local simulation endpoints ---
+    async localSimInit(body) {
+        return this.post("/simulation/local/init", body, { timeout: 30_000 });
+    }
+    async localSimStep(body) {
+        return this.post("/simulation/local/step", body, { timeout: 60_000 });
+    }
+    async localSimRecord(body) {
+        return this.post("/simulation/local/record", body, { timeout: 60_000 });
+    }
+    async localSimMatchFrame(body) {
+        return this.post("/simulation/local/match-frame", body, { timeout: 30_000 });
+    }
+    async localSimScreenshotUpload(body) {
+        return this.post("/simulation/local/screenshot/upload", body);
+    }
+    async handleResponse(resp) {
+        if (!resp.ok) {
+            let body;
+            try {
+                body = await resp.json();
+            }
+            catch {
+                body = null;
+            }
+            throw new ApiError(resp.status, resp.statusText, body);
+        }
+        if (resp.status === 204)
+            return undefined;
+        return await resp.json();
+    }
+}

package/dist/lib/auth.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Shared authentication and configuration utilities for CLI commands.
+ * Uses the canonical config from src/config.ts and OAuth refresh from src/auth.ts.
+ */
+export declare const DEFAULT_API_URL = "https://api.ishlabs.io";
+export declare const API_BASE = "/api/v1";
+export declare function resolveApiUrl(apiUrlArg?: string, dev?: boolean): string;
+export declare function resolveToken(tokenArg: string | undefined, apiUrl: string): Promise<string>;

package/dist/lib/auth.js

@@ -0,0 +1,73 @@
+/**
+ * Shared authentication and configuration utilities for CLI commands.
+ * Uses the canonical config from src/config.ts and OAuth refresh from src/auth.ts.
+ */
+import { loadConfig, saveConfig } from "../config.js";
+import { refreshTokens, isTokenExpired } from "../auth.js";
+export const DEFAULT_API_URL = "https://api.ishlabs.io";
+export const API_BASE = "/api/v1";
+export function resolveApiUrl(apiUrlArg, dev) {
+    if (dev)
+        return "http://localhost:8000";
+    if (apiUrlArg)
+        return apiUrlArg;
+    return process.env.ISH_API_URL ?? DEFAULT_API_URL;
+}
+async function verifyToken(token, apiUrl) {
+    try {
+        const resp = await fetch(`${apiUrl}${API_BASE}/connect/active`, {
+            headers: { Authorization: `Bearer ${token}` },
+            signal: AbortSignal.timeout(10_000),
+        });
+        // 404 = valid token, no connection (expected). 401/403 = bad token.
+        return resp.status !== 401 && resp.status !== 403;
+    }
+    catch {
+        // Network error — can't verify, assume ok
+        console.error("Warning: Could not verify token (network error). Proceeding anyway.");
+        return true;
+    }
+}
+export async function resolveToken(tokenArg, apiUrl) {
+    // 1. Explicit token argument
+    if (tokenArg)
+        return tokenArg;
+    // 2. Environment variable
+    const envToken = process.env.ISH_TOKEN;
+    if (envToken)
+        return envToken;
+    // 3. Saved config with OAuth tokens (access_token + refresh_token)
+    const config = loadConfig();
+    if (config.access_token && config.refresh_token) {
+        let accessToken = config.access_token;
+        // Refresh if expired or close to expiry
+        if (isTokenExpired(accessToken)) {
+            try {
+                const tokens = await refreshTokens(config.refresh_token);
+                accessToken = tokens.accessToken;
+                config.access_token = tokens.accessToken;
+                config.refresh_token = tokens.refreshToken;
+                saveConfig(config);
+            }
+            catch (err) {
+                if (err instanceof TypeError || (err instanceof Error && err.message.includes('fetch'))) {
+                    throw new Error('Could not refresh session (network error). Check your connection or run "ish login".');
+                }
+                throw new Error('Session expired. Run "ish login" to re-authenticate.');
+            }
+        }
+        if (await verifyToken(accessToken, apiUrl)) {
+            return accessToken;
+        }
+        throw new Error('Saved token is invalid. Run "ish login" to re-authenticate.');
+    }
+    // 4. Legacy saved token (no refresh token)
+    if (config.token) {
+        if (await verifyToken(config.token, apiUrl)) {
+            return config.token;
+        }
+        throw new Error('Saved token is invalid. Run "ish login" to re-authenticate.');
+    }
+    // 5. No token found
+    throw new Error('No auth token found. Run "ish login" or set ISH_TOKEN environment variable or pass --token <token>.');
+}

package/dist/lib/command-helpers.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared helpers for command actions.
+ * Resolves global options, creates API client, handles errors.
+ */
+import type { Command } from "commander";
+import { ApiClient } from "./api-client.js";
+export interface GlobalOpts {
+    token?: string;
+    apiUrl?: string;
+    dev?: boolean;
+    json: boolean;
+    verbose: boolean;
+    quiet: boolean;
+    fields?: string[];
+}
+export declare function getGlobals(cmd: Command): GlobalOpts;
+/**
+ * Map errors to semantic exit codes.
+ * 0=success, 1=general, 2=usage/validation, 3=auth, 4=not found, 5=transient
+ */
+export declare function exitCodeFromError(err: unknown): number;
+export declare function createClient(globals: GlobalOpts): Promise<ApiClient>;
+export declare function withClient(cmd: Command, fn: (client: ApiClient, globals: GlobalOpts) => Promise<void>): Promise<void>;
+export declare function getWebUrl(globals: GlobalOpts, path: string): string;
+export declare function terminalLink(url: string, text: string): string;
+export declare function readJsonFileOrStdin(filePath?: string): Promise<unknown>;
+export declare function resolveWorkspace(explicit?: string): string;
+export declare function resolveStudy(explicit?: string): string;

package/dist/lib/command-helpers.js

@@ -0,0 +1,131 @@
+/**
+ * Shared helpers for command actions.
+ * Resolves global options, creates API client, handles errors.
+ */
+import * as fs from "node:fs";
+import { resolveApiUrl, resolveToken } from "./auth.js";
+import { getAppUrl } from "../auth.js";
+import { ApiClient, ApiError } from "./api-client.js";
+import { outputError, setVerbose, setFields } from "./output.js";
+import { loadConfig } from "../config.js";
+import { resolveId } from "./alias-store.js";
+export function getGlobals(cmd) {
+    const opts = cmd.optsWithGlobals();
+    // Auto-switch to JSON when stdout is piped (non-TTY)
+    const json = opts.json ?? !process.stdout.isTTY;
+    // Parse --fields into an array
+    const fields = opts.fields
+        ? String(opts.fields).split(",").map((f) => f.trim()).filter(Boolean)
+        : undefined;
+    return {
+        token: opts.token,
+        apiUrl: opts.apiUrl,
+        dev: opts.dev,
+        json,
+        verbose: opts.verbose ?? false,
+        quiet: opts.quiet ?? (json && !opts.json), // auto-quiet when auto-json via pipe
+        fields,
+    };
+}
+/**
+ * Map errors to semantic exit codes.
+ * 0=success, 1=general, 2=usage/validation, 3=auth, 4=not found, 5=transient
+ */
+export function exitCodeFromError(err) {
+    if (err instanceof ApiError) {
+        if (err.status === 401 || err.status === 403)
+            return 3;
+        if (err.status === 404)
+            return 4;
+        if (err.status === 400 || err.status === 422)
+            return 2;
+        if (err.retryable)
+            return 5;
+    }
+    // Auth-related client errors (e.g. missing token)
+    if (err instanceof Error && /no auth token found|run "ish login"|saved token is invalid|session expired/i.test(err.message))
+        return 3;
+    return 1;
+}
+export async function createClient(globals) {
+    const apiUrl = resolveApiUrl(globals.apiUrl, globals.dev);
+    const token = await resolveToken(globals.token, apiUrl);
+    return new ApiClient({ apiUrl, token });
+}
+export async function withClient(cmd, fn) {
+    const globals = getGlobals(cmd);
+    setVerbose(globals.verbose);
+    setFields(globals.fields);
+    try {
+        const client = await createClient(globals);
+        await fn(client, globals);
+    }
+    catch (err) {
+        outputError(err, globals.json);
+        process.exit(exitCodeFromError(err));
+    }
+}
+export function getWebUrl(globals, path) {
+    const base = globals.dev ? "http://localhost:3000" : getAppUrl();
+    return `${base}${path}`;
+}
+export function terminalLink(url, text) {
+    return `\x1b]8;;${url}\x07${text}\x1b]8;;\x07`;
+}
+export function readJsonFileOrStdin(filePath) {
+    if (filePath) {
+        let content;
+        try {
+            content = fs.readFileSync(filePath, "utf-8");
+        }
+        catch (e) {
+            return Promise.reject(new Error(`Cannot read file: ${filePath}`));
+        }
+        try {
+            return Promise.resolve(JSON.parse(content));
+        }
+        catch {
+            return Promise.reject(new Error(`Invalid JSON in file: ${filePath}`));
+        }
+    }
+    // Read from stdin
+    if (process.stdin.isTTY) {
+        return Promise.reject(new Error("No input provided. Pipe JSON to stdin or use --file <path>."));
+    }
+    return new Promise((resolve, reject) => {
+        let data = "";
+        process.stdin.setEncoding("utf-8");
+        process.stdin.on("data", (chunk) => { data += chunk; });
+        process.stdin.on("end", () => {
+            try {
+                resolve(JSON.parse(data));
+            }
+            catch (e) {
+                reject(new Error("Invalid JSON from stdin"));
+            }
+        });
+        process.stdin.on("error", reject);
+    });
+}
+export function resolveWorkspace(explicit) {
+    if (explicit)
+        return resolveId(explicit);
+    const env = process.env.ISH_WORKSPACE;
+    if (env)
+        return resolveId(env);
+    const config = loadConfig();
+    if (config.workspace)
+        return config.workspace;
+    throw new Error('No workspace set. Use `ish workspace use <alias>` or pass --workspace.');
+}
+export function resolveStudy(explicit) {
+    if (explicit)
+        return resolveId(explicit);
+    const env = process.env.ISH_STUDY;
+    if (env)
+        return resolveId(env);
+    const config = loadConfig();
+    if (config.study)
+        return config.study;
+    throw new Error('No study set. Use `ish study use <alias>` or pass --study.');
+}

package/dist/lib/local-sim/actions.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Action executor — resolves elements and executes Playwright actions.
+ *
+ * Resolution strategy:
+ * 1. CDP node resolution (using node_id from tree data)
+ * 2. Playwright locator fallback (using element_name + element_type)
+ * 3. Coordinate fallback (if returned by backend)
+ */
+import type { Page } from "playwright-core";
+import type { LocalStepAction, ActionResult, ContextValue, TreeData } from "./types.js";
+/**
+ * Execute a single action on the page.
+ */
+export declare function executeAction(page: Page, action: LocalStepAction, treeData: TreeData, contextValues: ContextValue[]): Promise<ActionResult>;
+/**
+ * Compare two base64 screenshots to detect visible change.
+ */
+export declare function detectNoVisibleChange(before: string, after: string): boolean;
+/**
+ * Build a human-readable action description matching backend's format_action_detail().
+ */
+export declare function describeAction(action: LocalStepAction): string;