flowstride 1.0.19 → 1.0.20-rc.6

package/dist/runner/flow_worker.js

@@ -37,6 +37,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FlowWorker = void 0;
+const projectPaths_1 = require("../utils/projectPaths");
+const redaction_1 = require("../security/redaction");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const chalk_1 = __importDefault(require("chalk"));
@@ -55,6 +57,7 @@ class FlowWorker extends events_1.EventEmitter {
     pluginManager;
     isSilent = process.env.FLOWSTRIDE_PARALLEL === "true";
     isAborted = false;
+    bailTriggered = false;
     isDebugHalted = false;
     currentStepContext = "Initializing...";
     currentFileName = "System";
@@ -76,7 +79,8 @@ class FlowWorker extends events_1.EventEmitter {
         this.pluginManager = pluginManager;
     }
     broadcast(type, payload) {
-        this.emit("worker_event", { type, payload });
+        const secrets = [this.config.machineToken || '', ...(this.dataGen?.sensitiveValues?.() || []), ...Object.entries(process.env).filter(([key]) => /password|token|secret|api.?key/i.test(key)).map(([, value]) => String(value)), ...Object.entries(this.localVariables).filter(([key]) => /password|passcode|token|secret|otp|api.?key/i.test(key)).map(([, value]) => String(value))];
+        this.emit('worker_event', { type, payload: (0, redaction_1.redactWorkerPayload)(type, payload, secrets, this.config.ci === false) });
     }
     emitLog(type, status, summary, details, customId, overrideFileName) {
         const id = customId || Math.random().toString(36).substr(2, 9);
@@ -362,8 +366,13 @@ class FlowWorker extends events_1.EventEmitter {
         }
         this.activeAudioPath = undefined;
         this.isAborted = false;
+        this.bailTriggered = false;
         this.isDebugHalted = false;
         const sigintHandler = async () => {
+            if (this.config.ci) {
+                this.abort();
+                return;
+            }
             if (!this.isSilent) {
                 console.log(chalk_1.default.yellow("\n[Flowstride]: Process interrupted. Gracefully shutting down..."));
             }
@@ -373,7 +382,8 @@ class FlowWorker extends events_1.EventEmitter {
                 await this.web.shutdown();
             }
             catch (e) { }
-            process.exit(0);
+            if (!this.config.ci)
+                process.exit(0);
         };
         process.once("SIGINT", sigintHandler);
         try {
@@ -382,7 +392,7 @@ class FlowWorker extends events_1.EventEmitter {
                 const audioMatch = content.match(/(?:flow\.)?injectAudio\s+["']([^"']+)["']/i);
                 if (audioMatch && audioMatch[1]) {
                     const rawPath = audioMatch[1];
-                    const absolutePath = path.resolve(process.cwd(), rawPath);
+                    const absolutePath = (0, projectPaths_1.projectPath)(process.cwd(), rawPath);
                     if (!fs.existsSync(absolutePath)) {
                         throw new Error(`Pre-launch initialization failed: Audio file not found at ${absolutePath}`);
                     }
@@ -391,12 +401,13 @@ class FlowWorker extends events_1.EventEmitter {
                 }
             }
             for (const filePath of filesToProcess) {
-                if (this.isAborted || this.isDebugHalted)
+                if (this.isAborted || this.isDebugHalted || this.bailTriggered)
                     break;
                 const fileStartTime = Date.now();
                 try {
-                    const fileName = path.basename(filePath);
+                    const fileName = (0, projectPaths_1.flowIdentity)(filePath, this.config.flowRoot);
                     this.currentFileName = fileName;
+                    this.config.testFile = fileName;
                     this.localVariables = {};
                     this.localBrowserSessions = {};
                     this.api.resetState();
@@ -445,14 +456,14 @@ class FlowWorker extends events_1.EventEmitter {
                         });
                     }
                     for (const f of features) {
-                        if (this.isAborted || this.isDebugHalted)
+                        if (this.isAborted || this.isDebugHalted || this.bailTriggered)
                             break;
                         if (f.scenarios.length === 0)
                             continue;
                         if (!this.isSilent)
                             console.log(chalk_1.default.magenta.bold(`  Feature: ${f.name}`));
                         for (const s of f.scenarios) {
-                            if (this.isAborted || this.isDebugHalted)
+                            if (this.isAborted || this.isDebugHalted || this.bailTriggered)
                                 break;
                             if (!this.isSilent)
                                 console.log(chalk_1.default.cyan(`    Scenario: ${s.name}`));
@@ -461,7 +472,7 @@ class FlowWorker extends events_1.EventEmitter {
                                 fileName: this.currentFileName,
                             });
                             await this.runScenario(s, f.declarations);
-                            if (this.isDebugHalted)
+                            if (this.isDebugHalted || this.bailTriggered)
                                 break;
                             await this.web
                                 .getPage()
@@ -471,20 +482,24 @@ class FlowWorker extends events_1.EventEmitter {
                                 .getPage()
                                 .waitForLoadState("networkidle", { timeout: 4000 })
                                 .catch(() => { });
-                            await new Promise((resolve) => setTimeout(resolve, 2000));
+                            if (!this.config.ci)
+                                await new Promise((resolve) => setTimeout(resolve, 2000));
                         }
                     }
                     if (this.isAborted)
                         break;
                     if (!this.isSilent)
                         console.log(chalk_1.default.gray("\n[Execution]: Finalizing browser actions..."));
-                    await new Promise((resolve) => setTimeout(resolve, 2000));
+                    if (!this.config.ci)
+                        await new Promise((resolve) => setTimeout(resolve, 2000));
                     try {
-                        const baseName = this.currentFileName.replace(".flow", "");
+                        const baseName = (0, projectPaths_1.videoFileName)(this.currentFileName).replace(/\.webm$/, '');
                         const mockCloudDir = path.join(process.cwd(), ".flowstride", "mock-cloud");
                         if (!fs.existsSync(mockCloudDir))
                             fs.mkdirSync(mockCloudDir, { recursive: true });
                         const targetVideoPath = path.join(mockCloudDir, `${baseName}.webm`);
+                        for (const message of this.web.pageErrors || [])
+                            this.broadcast('BROWSER_ERROR', { message, fileName: this.currentFileName });
                         await this.web.shutdown(targetVideoPath);
                         if (!this.isSilent)
                             console.log(chalk_1.default.gray(`      [Cloud Sync]: Video safely encoded and preserved for ${this.currentFileName}`));
@@ -501,11 +516,13 @@ class FlowWorker extends events_1.EventEmitter {
                     if (!this.isSilent)
                         console.error(chalk_1.default.red(`\n[Execution]: Failed processing ${this.currentFileName}: ${e.message}`));
                     try {
-                        const baseName = this.currentFileName.replace(".flow", "");
+                        const baseName = (0, projectPaths_1.videoFileName)(this.currentFileName).replace(/\.webm$/, '');
                         const mockCloudDir = path.join(process.cwd(), ".flowstride", "mock-cloud");
                         if (!fs.existsSync(mockCloudDir))
                             fs.mkdirSync(mockCloudDir, { recursive: true });
                         const targetVideoPath = path.join(mockCloudDir, `${baseName}.webm`);
+                        for (const message of this.web.pageErrors || [])
+                            this.broadcast('BROWSER_ERROR', { message, fileName: this.currentFileName });
                         await this.web.shutdown(targetVideoPath);
                         if (!this.isSilent)
                             console.log(chalk_1.default.gray(`      [Cloud Sync]: Video safely encoded and preserved for ${this.currentFileName}`));
@@ -518,7 +535,7 @@ class FlowWorker extends events_1.EventEmitter {
                     });
                 }
             }
-            if (!this.isSilent && !this.isAborted) {
+            if (!this.config.ci && !this.isSilent && !this.isAborted) {
                 if (this.isDebugHalted) {
                     console.log(chalk_1.default.cyan("\n[Execution]: Test suite halted by debug flag."));
                 }
@@ -528,10 +545,21 @@ class FlowWorker extends events_1.EventEmitter {
             }
         }
         finally {
+            if (this.config.ci && this.isAborted) {
+                try {
+                    const directory = path.join(process.cwd(), '.flowstride', 'artifacts');
+                    fs.mkdirSync(directory, { recursive: true });
+                    await this.web.shutdown(path.join(directory, (0, projectPaths_1.videoFileName)(this.currentFileName)));
+                }
+                catch (error) {
+                    this.broadcast('WORKER_ERROR', { message: error.message });
+                }
+            }
             process.removeListener("SIGINT", sigintHandler);
         }
     }
     async runScenario(scenario, globalDeclarations = []) {
+        let hasScenarioFailed = false;
         for (const step of scenario.steps) {
             if (this.isAborted)
                 break;
@@ -543,6 +571,11 @@ class FlowWorker extends events_1.EventEmitter {
             step.payload = this.resolveTemplateData(step.payload);
             this.currentStepContext = `${blockName} ${blockDesc}`;
             const isOpt = step.payload?.optional;
+            if (hasScenarioFailed) {
+                this.broadcast('STEP_ADD', { id: step.id, type: blockName, description: blockDesc, command: step.action, status: 'not_tested', fileName: this.currentFileName });
+                this.broadcast('STEP_UPDATE', { id: step.id, status: 'not_tested', fileName: this.currentFileName });
+                continue;
+            }
             const mockSpinner = {
                 text: "",
                 start() {
@@ -671,7 +704,11 @@ class FlowWorker extends events_1.EventEmitter {
                     screenshot: stepContext.screenshot,
                     fileName: this.currentFileName,
                 });
-                throw e;
+                hasScenarioFailed = true;
+                if (this.config.bail && !this.bailTriggered) {
+                    this.bailTriggered = true;
+                    this.broadcast('BAIL', { fileName: this.currentFileName, id: step.id });
+                }
             }
         }
     }
@@ -1167,11 +1204,12 @@ class FlowWorker extends events_1.EventEmitter {
             const sharedId = Math.random().toString(36).substr(2, 9);
             const urlObj = new URL(request.url());
             const endpointName = urlObj.pathname.split("/").pop() || urlObj.pathname;
-            const curlString = this.web.synthesizeCurl(request.method(), request.url(), request.headers(), rawPostData);
+            const requestHeaders = await request.allHeaders().catch(() => request.headers());
+            const curlString = this.web.synthesizeCurl(request.method(), request.url(), requestHeaders, rawPostData);
             this.emitLog("REST", response.status() < 400 ? "success" : "error", `${request.method()} ${endpointName}`, {
                 method: request.method(),
                 url: request.url(),
-                requestHeaders: request.headers(),
+                requestHeaders: requestHeaders,
                 requestBody: requestBody,
                 responseStatus: response.status(),
                 responseHeaders: response.headers(),
@@ -1196,6 +1234,8 @@ class FlowWorker extends events_1.EventEmitter {
         });
     }
     async startStreaming() {
+        if (this.config.ci)
+            return;
         const page = this.web.getPage();
         if (this.currentCdpSession) {
             await this.currentCdpSession.detach().catch(() => { });

package/dist/runner/persistent_vault.js

@@ -34,13 +34,14 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PersistentVault = void 0;
+const projectPaths_1 = require("../utils/projectPaths");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 class PersistentVault {
     vaultPath;
     data = {};
     constructor(projectRoot = process.cwd()) {
-        this.vaultPath = path.join(projectRoot, ".flowstride", "vault.json");
+        this.vaultPath = (0, projectPaths_1.projectPath)(projectRoot, path.join(projectRoot, ".flowstride", "vault.json"));
         this.initialiseVault();
     }
     initialiseVault() {

package/dist/runner/plugin_manager.d.ts

@@ -8,6 +8,7 @@ export declare class PluginManager {
     private store;
     private apiProxy;
     private dbProxy;
+    private game;
     constructor(config: FlowstrideConfig, web: WebAdapter, store: TemporaryStore, apiProxy: ApiProxy);
     execute(actionName: string, args: any, saveAs?: string): Promise<any>;
 }

package/dist/runner/plugin_manager.js

@@ -32,8 +32,15 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PluginManager = void 0;
+const projectPaths_1 = require("../utils/projectPaths");
+const deadline_1 = require("../ci/deadline");
+const node_fs_1 = __importDefault(require("node:fs"));
+const sdk_1 = require("../game/sdk");
 const path = __importStar(require("path"));
 const db_proxy_1 = require("../sdk/db_proxy");
 class PluginManager {
@@ -42,12 +49,14 @@ class PluginManager {
     store;
     apiProxy;
     dbProxy;
+    game;
     constructor(config, web, store, apiProxy) {
         this.config = config;
         this.web = web;
         this.store = store;
         this.apiProxy = apiProxy;
         this.dbProxy = new db_proxy_1.DbProxy();
+        this.game = new sdk_1.GameSDK(() => this.web.getPage(), this.config);
     }
     async execute(actionName, args, saveAs) {
         const lastDotIndex = actionName.lastIndexOf(".");
@@ -56,6 +65,16 @@ class PluginManager {
         }
         const pluginFile = actionName.substring(0, lastDotIndex);
         const functionName = actionName.substring(lastDotIndex + 1);
+        if (pluginFile === 'flowstride:game') {
+            const actions = ['tap', 'drag', 'swipe', 'key', 'checkpoint', 'snapshot', 'expectVisual', 'state', 'expectState', 'snapshotState', 'expectPreserved', 'fixture', 'select'];
+            if (!actions.includes(functionName))
+                throw new Error(`Unknown native game action: ${functionName}`);
+            const operation = this.game[functionName](args);
+            const result = this.config.ci ? await (0, deadline_1.withDeadline)(operation, this.config.timeout) : await operation;
+            if (saveAs)
+                this.store.set(saveAs, result);
+            return result;
+        }
         let fullPath;
         if (pluginFile.includes("/") || pluginFile.includes("\\")) {
             fullPath = path.resolve(process.cwd(), `${pluginFile}.ts`);
@@ -64,6 +83,7 @@ class PluginManager {
             const pluginsPath = this.config.pluginsDir || path.join(process.cwd(), "plugins");
             fullPath = path.resolve(pluginsPath, `${pluginFile}.ts`);
         }
+        fullPath = (0, projectPaths_1.projectPath)(process.cwd(), fullPath);
         try {
             let module;
             if (fullPath.endsWith(".ts")) {
@@ -84,6 +104,19 @@ class PluginManager {
                 throw new Error(`Plugin function "${functionName}" not found in ${fullPath}`);
             }
             const sdk = {
+                game: this.game,
+                browser: { page: () => this.web.getPage() },
+                run: { device: this.config.device || 'desktop', artifactsDir: this.config.artifactsDir || path.resolve('flowstride-artifacts'),
+                    attach: (name, data) => {
+                        if (!/^[a-zA-Z0-9_.-]+$/.test(name) || name === '.' || name === '..')
+                            throw new Error('Attachment name must be a simple filename.');
+                        const directory = this.config.artifactsDir || path.resolve('flowstride-artifacts');
+                        node_fs_1.default.mkdirSync(directory, { recursive: true });
+                        const prefix = (0, projectPaths_1.artifactPrefix)(this.config.testFile);
+                        const file = path.join(directory, prefix + name);
+                        node_fs_1.default.writeFileSync(file, data);
+                        return file;
+                    } },
                 api: {
                     get: (url, headers) => this.apiProxy.get(url, headers),
                     post: (url, body, headers) => this.apiProxy.post(url, body, headers),
@@ -150,7 +183,8 @@ class PluginManager {
                         .substring(2, 2 + length),
                 },
             };
-            const result = await action(sdk, args);
+            const operation = action(sdk, args);
+            const result = this.config.ci ? await (0, deadline_1.withDeadline)(operation, this.config.timeout) : await operation;
             if (saveAs) {
                 this.store.set(saveAs, result);
             }

package/dist/security/localDashboard.d.ts

@@ -0,0 +1,2 @@
+/** Reject remote hosts and browser origins before exposing local debugger data. */
+export declare function isLocalDashboardRequest(host?: string, origin?: string): boolean;

package/dist/security/localDashboard.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isLocalDashboardRequest = isLocalDashboardRequest;
+/** Reject remote hosts and browser origins before exposing local debugger data. */
+function isLocalDashboardRequest(host, origin) {
+    if (!host)
+        return false;
+    try {
+        const target = new URL(`http://${host}`);
+        if (!['localhost', '127.0.0.1', '[::1]'].includes(target.hostname) || !target.port || target.username || target.password || target.pathname !== '/' || target.search || target.hash)
+            return false;
+        if (origin !== undefined) {
+            const source = new URL(origin);
+            if (source.origin !== target.origin || source.pathname !== '/' || source.search || source.hash || source.username || source.password)
+                return false;
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/security/redaction.d.ts

@@ -0,0 +1,4 @@
+export declare function redactText(input: string, secrets?: string[]): string;
+export declare function redactPayload(value: any, secrets?: string[], depth?: number): any;
+/** Raw network commands belong only to the local interactive debugger. */
+export declare function redactWorkerPayload(type: string, payload: any, secrets: string[], localDebug?: boolean): any;

package/dist/security/redaction.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.redactText = redactText;
+exports.redactPayload = redactPayload;
+exports.redactWorkerPayload = redactWorkerPayload;
+const sensitive = /password|passcode|secret|token|authorization|cookie|api.?key|master.?key|otp|email|curlString|strippedDom/i;
+function redactText(input, secrets = []) {
+    let value = String(input);
+    for (const secret of secrets.filter(s => typeof s === 'string' && s.length >= 4).sort((a, b) => b.length - a.length))
+        value = value.split(secret).join('[REDACTED]');
+    value = value.replace(/\bBearer\s+[^\s"'<>]+/gi, 'Bearer [REDACTED]')
+        .replace(/\beyJ[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+\b/g, '[REDACTED]')
+        .replace(/(["']?(?:password|passcode|secret|token|otp|authorization|cookie|api[_-]?key|master[_-]?key)["']?\s*[:=]\s*)(["']?)[^\s,;"'<>}]+\2/gi, '$1[REDACTED]')
+        .replace(/([?&](?:ticket|token|signature|x-amz-[^=&#]+)=)[^&#\s]+/gi, '$1[REDACTED]');
+    return value;
+}
+function redactPayload(value, secrets = [], depth = 0) {
+    if (depth > 12)
+        return '[omitted]';
+    if (typeof value === 'string') {
+        if (/^data:image\//.test(value))
+            return value;
+        const trimmed = value.trim();
+        if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+            try {
+                return JSON.stringify(redactPayload(JSON.parse(value), secrets, depth + 1));
+            }
+            catch { }
+        }
+        return redactText(value, secrets);
+    }
+    if (Array.isArray(value))
+        return value.map(item => redactPayload(item, secrets, depth + 1));
+    if (!value || typeof value !== 'object')
+        return value;
+    if (Buffer.isBuffer(value))
+        return '[binary]';
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, sensitive.test(key) ? '[REDACTED]' : redactPayload(item, secrets, depth + 1)]));
+}
+/** Raw network commands belong only to the local interactive debugger. */
+function redactWorkerPayload(type, payload, secrets, localDebug = false) {
+    const result = redactPayload(payload, secrets);
+    if (!localDebug || !payload || !result)
+        return result;
+    if (type === 'LOG_EVENT' && ['REST', 'GRAPHQL'].includes(payload.type) && typeof payload.details?.curlString === 'string') {
+        result.details.rawCurlString = payload.details.curlString;
+    }
+    return result;
+}

package/dist/types/index.d.ts

@@ -1,4 +1,38 @@
 export interface FlowstrideConfig {
+    ci?: boolean;
+    flowRoot?: string;
+    projectRoot?: string;
+    cloudSyncResult?: {
+        reporting: string;
+        video: string;
+        error?: unknown;
+    };
+    device?: 'desktop' | 'phone' | 'landscape';
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    testDir?: string;
+    artifactsDir?: string;
+    recordVideo?: boolean;
+    browserErrors?: 'fail' | 'record';
+    webServer?: {
+        command: string;
+        url: string;
+        cwd?: string;
+        timeout?: number;
+    };
+    testFile?: string;
+    onRunEvent?: (event: any) => void;
+    bail?: boolean;
+    isCloudSyncActive?: boolean;
+    machineToken?: string | null;
+    workspaceId?: string | null;
+    manifest?: {
+        plan?: string;
+        maxWorkers?: number | 'unlimited';
+        [key: string]: any;
+    } | null;
     baseUrl?: string;
     timeout: number;
     headless: boolean;
@@ -46,6 +80,15 @@ export interface SessionDefinition {
     };
 }
 export interface FlowstrideSDK {
+    game: import('../game/sdk').GameSDK;
+    browser: {
+        page: () => import('playwright').Page;
+    };
+    run: {
+        device: string;
+        artifactsDir: string;
+        attach: (name: string, data: string | Buffer) => string;
+    };
     api: {
         get: (url: string, headers?: Record<string, string>) => Promise<any>;
         post: (url: string, body: any, headers?: Record<string, string>) => Promise<any>;

package/dist/utils/cloud.d.ts

@@ -0,0 +1,6 @@
+export declare function cloudApiBase(env?: Record<string, string | undefined>): string;
+export declare function cloudFailure(error: any, secrets?: string[]): {
+    status: number | undefined;
+    code: string | undefined;
+    message: string;
+};

package/dist/utils/cloud.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cloudApiBase = cloudApiBase;
+exports.cloudFailure = cloudFailure;
+const redaction_1 = require("../security/redaction");
+function cloudApiBase(env = process.env) {
+    const value = env.FLOWSTRIDE_API_URL || env.NEXTJS_WEBHOOK_URL || 'https://cloud.flowstride.io';
+    const url = new URL(value);
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash)
+        throw new Error('Cloud URL must be an HTTP(S) URL without credentials or query parameters.');
+    const pathname = url.pathname.replace(/\/api\/cloud\/execution-complete\/?$/, '').replace(/\/+$/, '');
+    return url.origin + pathname;
+}
+function cloudFailure(error, secrets = []) {
+    const status = Number(error?.response?.status) || undefined;
+    const code = typeof error?.response?.data?.code === 'string' ? error.response.data.code.slice(0, 80) : typeof error?.code === 'string' ? error.code.slice(0, 80) : undefined;
+    const authenticationMessages = {
+        TOKEN_EXPIRED: 'This developer token has expired. Generate a replacement; logging in with the same key does not renew it.',
+        TOKEN_REVOKED: 'This developer token has been revoked. Use a replacement token.',
+        TOKEN_INVALID: 'Cloud did not recognize a valid developer token. Check the credential source and Cloud URL.',
+        TOKEN_REQUIRED: 'Cloud requires a Bearer developer token.',
+        TOKEN_SCOPE_DENIED: 'This token requires execution or admin scope for CLI runs.',
+    };
+    const message = (status === 401 || status === 403) && code && authenticationMessages[code] ? authenticationMessages[code]
+        : status === 401 ? 'Cloud rejected authentication. Check the selected token and Cloud URL; this response does not confirm expiration.'
+            : status === 403 ? 'Workspace permission or feature policy rejected this request.'
+                : status === 413 ? 'The Cloud/proxy upload limit was exceeded; evidence remains local.'
+                    : status === 429 ? 'The Cloud request rate limit was reached.'
+                        : status && status >= 500 ? 'Cloud service failed; evidence remains local.'
+                            : status === 400 ? 'Cloud rejected the report schema; verify matching CLI and Cloud releases.'
+                                : 'Cloud could not be reached; verify the configured URL and network connection.';
+    return { status, code: code ? (0, redaction_1.redactText)(code, secrets) : undefined, message };
+}

package/dist/utils/projectPaths.d.ts

@@ -0,0 +1,11 @@
+export declare function projectPath(root: string, target: string): string;
+export declare function discoverFlows(target: string, projectRoot?: string): string[];
+export declare function flowIdentity(file: string, root?: string): string;
+export declare function videoFileName(identity: string): string;
+export declare function selectedFeatures<T extends {
+    scenarios: {
+        isOnly?: boolean;
+        steps: unknown[];
+    }[];
+}>(features: T[]): T[];
+export declare function artifactPrefix(identity?: string): string;

package/dist/utils/projectPaths.js

@@ -0,0 +1,90 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectPath = projectPath;
+exports.discoverFlows = discoverFlows;
+exports.flowIdentity = flowIdentity;
+exports.videoFileName = videoFileName;
+exports.selectedFeatures = selectedFeatures;
+exports.artifactPrefix = artifactPrefix;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+function projectPath(root, target) {
+    root = node_path_1.default.resolve(root);
+    target = node_path_1.default.resolve(root, target);
+    const inside = (base, value) => {
+        const relative = node_path_1.default.relative(base, value);
+        return relative !== '..' && !relative.startsWith(`..${node_path_1.default.sep}`) && !node_path_1.default.isAbsolute(relative);
+    };
+    if (!inside(root, target))
+        throw new Error(`Path must remain inside the project: ${target}`);
+    const realRoot = node_fs_1.default.realpathSync(root);
+    let parent = target;
+    const suffix = [];
+    while (true) {
+        try {
+            node_fs_1.default.lstatSync(parent);
+            break;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            suffix.unshift(node_path_1.default.basename(parent));
+            const next = node_path_1.default.dirname(parent);
+            if (next === parent)
+                throw error;
+            parent = next;
+        }
+    }
+    const real = node_path_1.default.join(node_fs_1.default.realpathSync(parent), ...suffix);
+    if (!inside(realRoot, real))
+        throw new Error(`Symlink escapes the project: ${target}`);
+    return target;
+}
+function discoverFlows(target, projectRoot = process.cwd()) {
+    const files = [];
+    const visited = new Set();
+    const visit = (item) => {
+        item = projectPath(projectRoot, item);
+        const real = node_fs_1.default.realpathSync(item);
+        if (visited.has(real))
+            return;
+        visited.add(real);
+        const stat = node_fs_1.default.statSync(item);
+        if (stat.isFile()) {
+            if (item.endsWith('.flow'))
+                files.push(item);
+            return;
+        }
+        if (!stat.isDirectory())
+            return;
+        for (const entry of node_fs_1.default.readdirSync(item, { withFileTypes: true }).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)) {
+            if (['node_modules', '.git', '.flowstride', 'flowstride-artifacts'].includes(entry.name))
+                continue;
+            visit(node_path_1.default.join(item, entry.name));
+        }
+    };
+    visit(target);
+    return files.sort((a, b) => Number(!a.endsWith('.first.flow')) - Number(!b.endsWith('.first.flow')) || (a < b ? -1 : a > b ? 1 : 0));
+}
+function flowIdentity(file, root) { return (root ? node_path_1.default.relative(root, file) : node_path_1.default.basename(file)).split(node_path_1.default.sep).join('/'); }
+function videoFileName(identity) {
+    if (!identity.includes('/') && identity.length < 180 && !identity.includes('%'))
+        return identity.replace(/\.flow$/, '') + '.webm';
+    const base = node_path_1.default.posix.basename(identity, '.flow').replace(/[^a-zA-Z0-9_.-]/g, '_').slice(0, 60);
+    return `${base}-${(0, node_crypto_1.createHash)('sha256').update(identity).digest('hex').slice(0, 16)}.webm`;
+}
+function selectedFeatures(features) {
+    if (!features.some(f => f.scenarios.some(s => s.isOnly)))
+        return features;
+    return features.map(f => ({ ...f, scenarios: f.scenarios.filter(s => s.isOnly) }));
+}
+function artifactPrefix(identity) {
+    if (!identity)
+        return '';
+    const safe = identity.replace(/[^a-zA-Z0-9_.-]/g, '_').slice(0, 100);
+    return safe + (identity.includes('/') || identity.length > 100 ? '-' + (0, node_crypto_1.createHash)('sha256').update(identity).digest('hex').slice(0, 12) : '') + '-';
+}

package/examples/native-game/flows/canvas.flow

@@ -0,0 +1,13 @@
+Feature: Native canvas game testing
+let game = "flowstride:game"
+Scenario: A tap changes game state and rendering
+Given "The game is ready"
+  flow.open "http://127.0.0.1:5189"
+  game.fixture {"name":"reset"}
+  game.snapshot {"name":"before","canvas":"#game"}
+When "The player taps the game"
+  game.tap {"canvas":"#game","x":0.5,"y":0.5}
+Then "The score and scene change"
+  game.expectState {"path":"score","equals":1}
+  game.expectVisual {"name":"before","canvas":"#game","minChange":0.9}
+  game.checkpoint {"name":"game-result","canvas":"#game"}

package/examples/native-game/flowstride.config.json

@@ -0,0 +1,12 @@
+{
+  "testDir": "flows",
+  "device": "phone",
+  "timeout": 5000,
+  "artifactsDir": "flowstride-artifacts",
+  "recordVideo": true,
+  "webServer": {
+    "command": "node server.mjs",
+    "url": "http://127.0.0.1:5189",
+    "timeout": 10000
+  }
+}

package/examples/native-game/server.mjs

@@ -0,0 +1,12 @@
+import http from 'node:http';
+import { registerGame } from 'flowstride/dist/game/bridge.js';
+const html = `<!doctype html><html><head><title>Flowstride native game fixture</title></head><body>
+<canvas id="game" width="300" height="200" style="touch-action:none"></canvas>
+<script>
+const canvas=document.querySelector('canvas'),context=canvas.getContext('2d');
+const state={score:0};
+function draw(){context.fillStyle=state.score?'blue':'red';context.fillRect(0,0,canvas.width,canvas.height);}
+canvas.onpointerdown=()=>{state.score++;draw();};draw();
+const register=${registerGame.toString()};register({readState:()=>state,testMode:true,fixtures:{reset:()=>{state.score=0;draw();}}});
+</script></body></html>`;
+http.createServer((_request,response)=>{response.setHeader('Content-Type','text/html');response.end(html);}).listen(5189,'127.0.0.1');