flowstride 1.0.19 → 1.0.20-rc.2

package/dist/ci/runtime.js

@@ -0,0 +1,190 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runNativeCI = runNativeCI;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const promises_1 = require("node:timers/promises");
+const lexer_1 = require("../parser/lexer");
+const parser_1 = require("../parser/parser");
+function listFlows(target) {
+    const stat = node_fs_1.default.statSync(target);
+    if (stat.isFile())
+        return target.endsWith('.flow') ? [target] : [];
+    return node_fs_1.default.readdirSync(target).filter(name => name.endsWith('.flow')).sort().map(name => node_path_1.default.join(target, name));
+}
+function safeName(name) { return name.replace(/[^a-zA-Z0-9_.-]/g, '_').slice(0, 150); }
+function xml(value) { return String(value).replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, '').replace(/[<>&"']/g, char => ({ '<': '&lt;', '>': '&gt;', '&': '&amp;', '"': '&quot;', "'": '&apos;' }[char])); }
+async function runNativeCI(worker, orchestrator, target, config, engine) {
+    const started = Date.now();
+    const artifactRoot = config.artifactsDir;
+    node_fs_1.default.mkdirSync(artifactRoot, { recursive: true });
+    const directory = node_fs_1.default.mkdtempSync(node_path_1.default.join(artifactRoot, 'run-'));
+    config.artifactsDir = directory;
+    const steps = new Map();
+    const completed = new Set();
+    const errors = [];
+    let expected = 0;
+    let files = [];
+    let server;
+    let interrupted = false;
+    const interrupt = () => { interrupted = true; worker.abort(); orchestrator.abort?.(); };
+    const event = (data) => {
+        if (!data?.payload)
+            return;
+        const p = data.payload;
+        if (data.type === 'LOG_EVENT' && p.status === 'error') {
+            const active = [...steps.values()].reverse().find(step => step.fileName === p.fileName && step.status === 'running');
+            if (active)
+                active.error = p.details?.rawError || p.summary;
+        }
+        if (data.type === 'STEP_UPDATE' || data.type === 'STEP_ADD') {
+            const key = `${p.fileName}:${p.id}`;
+            steps.set(key, { ...steps.get(key), ...p, screenshot: undefined });
+            if (p.status === 'failed' && typeof p.screenshot === 'string') {
+                const match = p.screenshot.match(/^data:image\/(png|jpeg);base64,(.+)$/s) || (/^[A-Za-z0-9+/=\r\n]+$/.test(p.screenshot) ? ['', 'jpeg', p.screenshot] : null);
+                if (match)
+                    node_fs_1.default.writeFileSync(node_path_1.default.join(directory, `${safeName(p.fileName)}-${safeName(p.id)}.${match[1] === 'jpeg' ? 'jpg' : 'png'}`), Buffer.from(match[2], 'base64'));
+            }
+        }
+        if (data.type === 'FILE_COMPLETE' || data.type === 'FILE_FAILED')
+            completed.add(p.fileName);
+        if (data.type === 'FILE_FAILED' && ![...steps.values()].some(step => step.fileName === p.fileName && step.status === 'failed'))
+            errors.push(`${p.fileName}: ${p.error || 'Execution failed'}`);
+        if (data.type === 'BROWSER_ERROR' && config.browserErrors !== 'record')
+            errors.push(`Browser: ${p.message}`);
+        if (data.type === 'WORKER_ERROR')
+            errors.push(p.message || 'Worker failed');
+    };
+    // Modern orchestrators forward child-process events here; the worker listener
+    // also supports older compatible Pro packages. Step maps make duplicates harmless.
+    config.onRunEvent = event;
+    if (orchestrator.nativeEventProtocol !== 1)
+        worker.on('worker_event', event);
+    process.on('SIGINT', interrupt);
+    process.on('SIGTERM', interrupt);
+    try {
+        files = listFlows(target);
+        if (!files.length)
+            throw new Error('No .flow tests found.');
+        for (const file of files) {
+            const features = new parser_1.Parser(new lexer_1.Lexer(node_fs_1.default.readFileSync(file, 'utf8')).tokenise()).parse();
+            expected += features.reduce((n, feature) => n + feature.scenarios.reduce((m, scenario) => m + scenario.steps.length, 0), 0);
+        }
+        if (!expected)
+            throw new Error('No executable test steps found.');
+        if (config.webServer) {
+            const settings = config.webServer;
+            const probe = async () => { try {
+                return (await fetch(settings.url, { signal: AbortSignal.timeout(1000) })).ok;
+            }
+            catch {
+                return false;
+            } };
+            if (await probe())
+                throw new Error('webServer readiness URL is already serving; refusing to test an unowned server.');
+            const output = node_fs_1.default.openSync(node_path_1.default.join(directory, 'web-server.log'), 'a');
+            try {
+                server = (0, node_child_process_1.spawn)(settings.command, { cwd: settings.cwd, shell: true, detached: process.platform !== 'win32', stdio: ['ignore', output, output] });
+            }
+            finally {
+                node_fs_1.default.closeSync(output);
+            }
+            let spawnError;
+            server.on('error', error => { spawnError = error; });
+            const deadline = Date.now() + (settings.timeout ?? 30000);
+            while (!(await probe())) {
+                if (interrupted)
+                    throw new Error('Run interrupted during server startup.');
+                if (spawnError)
+                    throw spawnError;
+                if (server.exitCode !== null || server.signalCode !== null)
+                    throw new Error('webServer exited before readiness.');
+                if (Date.now() > deadline)
+                    throw new Error('webServer readiness timed out.');
+                await (0, promises_1.setTimeout)(100);
+            }
+        }
+        if (interrupted)
+            throw new Error('Run interrupted before execution.');
+        const ok = await orchestrator.start(target);
+        if (ok === false && ![...steps.values()].some(step => step.status === 'failed'))
+            errors.push('Engine reported a failed run.');
+    }
+    catch (error) {
+        errors.push(error instanceof Error ? error.message : String(error));
+    }
+    finally {
+        try {
+            await worker.shutdown();
+        }
+        catch (error) {
+            errors.push(`Cleanup failed: ${String(error)}`);
+        }
+        try {
+            await orchestrator.close?.();
+        }
+        catch (error) {
+            errors.push(`Orchestrator cleanup failed: ${String(error)}`);
+        }
+        if (server?.pid) {
+            const stop = (signal) => { try {
+                process.kill(process.platform === 'win32' ? server.pid : -server.pid, signal);
+            }
+            catch (error) {
+                if (error.code !== 'ESRCH')
+                    errors.push(`Server cleanup: ${error.message}`);
+            } };
+            stop('SIGTERM');
+            await Promise.race([new Promise(resolve => server.once('exit', () => resolve())), (0, promises_1.setTimeout)(1000)]);
+            // Terminate remaining descendants even if the shell exited first.
+            stop('SIGKILL');
+        }
+        worker.off('worker_event', event);
+        delete config.onRunEvent;
+        process.off('SIGINT', interrupt);
+        process.off('SIGTERM', interrupt);
+    }
+    if (interrupted)
+        errors.push('Run interrupted.');
+    const results = [...steps.values()];
+    const terminal = results.filter(step => ['passed', 'failed', 'skipped', 'not_tested'].includes(step.status));
+    const incomplete = Math.max(0, expected - terminal.length);
+    for (const file of files)
+        if (!completed.has(node_path_1.default.basename(file)))
+            errors.push(`Incomplete file: ${node_path_1.default.basename(file)}`);
+    if (results.some(step => !['passed', 'failed', 'skipped', 'not_tested'].includes(step.status)))
+        errors.push('Unfinished test steps.');
+    if (terminal.length > expected)
+        errors.push('Engine produced an unexpected step count.');
+    const metrics = { total: expected, passed: results.filter(s => s.status === 'passed').length,
+        failed: results.filter(s => s.status === 'failed').length, skipped: results.filter(s => ['skipped', 'not_tested'].includes(s.status)).length, incomplete };
+    const result = { protocol: 1, engine, status: interrupted ? 'interrupted' : errors.length || metrics.failed || incomplete ? 'failed' : 'passed',
+        duration: Date.now() - started, artifactsDir: directory, files: files.map(file => node_path_1.default.basename(file)), steps: results, errors, metrics };
+    // Existing workers finalize videos into these locations. Copy only run files,
+    // never the project directory or credentials.
+    if (config.recordVideo !== false)
+        for (const file of files) {
+            for (const folder of ['artifacts', 'mock-cloud']) {
+                const video = node_path_1.default.join(process.cwd(), '.flowstride', folder, node_path_1.default.basename(file, '.flow') + '.webm');
+                if (node_fs_1.default.existsSync(video) && node_fs_1.default.statSync(video).mtimeMs >= started) {
+                    node_fs_1.default.copyFileSync(video, node_path_1.default.join(directory, node_path_1.default.basename(video)));
+                    break;
+                }
+            }
+        }
+    config.artifactsDir = artifactRoot;
+    node_fs_1.default.writeFileSync(node_path_1.default.join(artifactRoot, 'summary.json'), JSON.stringify(result, null, 2));
+    const cases = results.map(step => `<testcase classname="${xml(step.fileName)}" name="${xml(step.description || step.id)}">${step.status === 'failed' ? `<failure message="${xml(step.error || 'Test step failed')}"/>` : ['skipped', 'not_tested'].includes(step.status) ? '<skipped/>' : ''}</testcase>`);
+    for (const error of errors)
+        cases.push(`<testcase name="execution"><error message="${xml(error)}"/></testcase>`);
+    if (incomplete)
+        cases.push(`<testcase name="completion"><failure message="${incomplete} incomplete steps"/></testcase>`);
+    node_fs_1.default.writeFileSync(node_path_1.default.join(artifactRoot, 'junit.xml'), `<?xml version="1.0"?><testsuite name="Flowstride" tests="${cases.length}" failures="${metrics.failed + (incomplete ? 1 : 0)}" errors="${errors.length}" skipped="${metrics.skipped}">${cases.join('')}</testsuite>`);
+    if (process.env.GITHUB_STEP_SUMMARY)
+        node_fs_1.default.appendFileSync(process.env.GITHUB_STEP_SUMMARY, `\n### Flowstride · ${config.device}\nResult: **${result.status}** (${engine})\n\nPassed: ${metrics.passed}; failed: ${metrics.failed}; skipped: ${metrics.skipped}; incomplete: ${metrics.incomplete}.\n`);
+    return result;
+}

package/dist/cli/commands/run.js

@@ -34,6 +34,8 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runAction = runAction;
+const config_1 = require("../../ci/config");
+const runtime_1 = require("../../ci/runtime");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const dotenv = __importStar(require("dotenv"));
@@ -69,12 +71,8 @@ async function runAction(targetPath, options) {
             console.log(`[Environment]: Loaded default .env file`);
         }
     }
-    const isCI = !!(process.env.CI ||
-        process.env.GITHUB_ACTIONS ||
-        process.env.GITLAB_CI ||
-        process.env.CIRCLECI ||
-        process.env.JENKINS_URL ||
-        process.env.FLOWSTRIDE_API_KEY);
+    const config = (0, config_1.loadNativeConfig)(root, options);
+    const isCI = !!config.ci;
     if (isCI) {
         console.log("\n[CI/CD]: Environment detected. Engaging Smart Automation Behaviors...");
     }
@@ -84,39 +82,13 @@ async function runAction(targetPath, options) {
         process.exit(1);
     }
     console.log(`\n[Flowstride]: Starting execution suite at "${resolvedPath}"...`);
-    const configPath = path.resolve(root, "flowstride.config.json");
-    let localConfig = {};
-    if (fs.existsSync(configPath)) {
-        try {
-            const fileContent = fs.readFileSync(configPath, "utf-8");
-            localConfig = JSON.parse(fileContent);
-            console.log(`[Config]: Loaded project configuration from flowstride.config.json`);
-        }
-        catch (e) {
-            console.warn(`[Warning]: Could not parse flowstride.config.json: ${e.message}`);
-        }
-    }
-    const config = {
-        headless: isCI
-            ? true
-            : options.headed
-                ? false
-                : (localConfig.headless ?? true),
-        timeout: localConfig.timeout ?? 30000,
-        bail: options.bail ?? localConfig.bail ?? false,
-        baseUrl: process.env.BASE_URL ?? localConfig.baseUrl,
-        defaultDialogBehavior: isCI
-            ? "dismiss"
-            : (localConfig.defaultDialogBehavior ?? "dismiss"),
-        pluginsDir: localConfig.pluginsDir,
-    };
     if (isCI) {
         console.log(`   > Headless Mode: ${config.headless ? "Forced ON" : "OFF"}`);
         console.log(`   > Dialog Protection: ${(config.defaultDialogBehavior || "dismiss").toUpperCase()}`);
         console.log(`   > Artifact Auto-Staging: ENABLED\n`);
     }
-    let workerCount = options.workers ? parseInt(options.workers, 10) : 1;
-    if (isNaN(workerCount) || workerCount < 1) {
+    let workerCount = options.workers ? Number(options.workers) : 1;
+    if (!Number.isSafeInteger(workerCount) || workerCount < 1) {
         console.error(`\n[Error]: Invalid worker count "${options.workers}". Must be an integer greater than 0.`);
         process.exit(1);
     }
@@ -126,6 +98,8 @@ async function runAction(targetPath, options) {
         console.log(`[Warning]: Auto-capping to ${maxSafeWorkers} workers to prevent system thrashing and crashes.\n`);
         workerCount = maxSafeWorkers;
     }
+    if (config.manifest?.maxWorkers !== undefined && config.manifest.maxWorkers !== 'unlimited')
+        workerCount = Math.min(workerCount, config.manifest.maxWorkers);
     const web = new playwright_1.WebAdapter(config);
     const api = new undici_1.ApiAdapter(config);
     const store = new temporary_store_1.TemporaryStore();
@@ -144,6 +118,8 @@ async function runAction(targetPath, options) {
         try {
             const proWorkerModule = await import((0, url_1.pathToFileURL)(proWorkerPath).href);
             const proOrchModule = await import((0, url_1.pathToFileURL)(proOrchPath).href);
+            if (config.ci && proOrchModule.FlowOrchestrator.nativeCIProtocol !== 1)
+                throw new Error('Installed Pro engine does not support native CI protocol 1; install the matching Pro candidate.');
             ActiveFlowWorker = proWorkerModule.FlowWorker;
             ActiveFlowOrchestrator = proOrchModule.FlowOrchestrator;
             engineMode = "Enterprise (Pro)";
@@ -155,6 +131,11 @@ async function runAction(targetPath, options) {
     console.log(`\n[Engine]: Booting Flowstride in ${engineMode} mode...`);
     const worker = new ActiveFlowWorker(config, web, api, store, sessions, pluginManager);
     const orchestrator = new ActiveFlowOrchestrator(worker, workerCount, config);
+    if (isCI) {
+        const result = await (0, runtime_1.runNativeCI)(worker, orchestrator, resolvedPath, config, engineMode);
+        console.log(`[Flowstride]: ${result.status}; reports: ${config.artifactsDir}`);
+        process.exit(result.status === 'passed' ? 0 : result.status === 'interrupted' ? 130 : 1);
+    }
     try {
         await orchestrator.start(resolvedPath);
         console.log("\n[Flowstride]: Execution suite completed successfully.");

package/dist/cli/index.js

@@ -37,10 +37,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+const config_1 = require("../ci/config");
+const init_1 = require("../ci/init");
 const commander_1 = require("commander");
 const run_1 = require("./commands/run");
 const report_1 = require("./commands/report");
-const init_1 = require("./commands/init");
+const init_2 = require("./commands/init");
 const open_1 = require("./commands/open");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
@@ -54,12 +56,12 @@ const API_BASE = process.env.FLOWSTRIDE_API_URL || "https://cloud.flowstride.io"
 program
     .name("flowstride")
     .description("Flowstride: The Enterprise Flow-First Automation CLI")
-    .version("1.0.19");
+    .version("1.0.20-rc.2");
 program
     .command("init")
     .description("Initialise a new Flowstride workspace in the current directory")
     .action(async () => {
-    await (0, init_1.initAction)();
+    await (0, init_2.initAction)();
 });
 program
     .command("login")
@@ -271,11 +273,17 @@ program
     .option("--headed", "Run browser in headed mode")
     .option("--headless", "Run browser in headless mode")
     .option("--workers <number>", "Number of parallel workers to spawn (Pro feature)")
+    .option('--ci', 'Run without a dashboard and write CI reports')
+    .option('--device <profile>', 'desktop, phone, or landscape')
+    .option('--config <file>', 'Path to the Flowstride configuration')
+    .option('--env <name>', 'Environment profile')
     .action(async (targetPath, options) => {
     if (typeof targetPath === "object") {
         options = targetPath;
         targetPath = undefined;
     }
+    if (options.ci)
+        process.env.FLOWSTRIDE_NATIVE_CI = '1';
     let token = process.env.FLOWSTRIDE_TOKEN || null;
     let forceOS = false;
     const localCredentialsPath = path.join(process.cwd(), ".flowstride", "credentials.json");
@@ -326,6 +334,19 @@ program
             else if (response.ok) {
                 const data = await response.json();
                 const tier = data.tier.toUpperCase();
+                if ((0, config_1.loadNativeConfig)(process.cwd(), options).ci && fs.existsSync(nodeModulesPath)) {
+                    const workspaceResponse = await fetch(`${API_BASE}/api/workspace/status`, {
+                        headers: { Authorization: `Bearer ${token}` },
+                    });
+                    if (!workspaceResponse.ok)
+                        forceOS = await handleOfflinePrompt();
+                    else {
+                        const workspaceData = await workspaceResponse.json();
+                        options.manifest = workspaceData.manifest;
+                        options.workspaceId = workspaceData.workspace?._id;
+                        options.isCloudSyncActive = true;
+                    }
+                }
                 if (tier === "PERSONAL") {
                     console.log(chalk_1.default.yellow(`🟡 [OS]: [${data.workspaceName}] (Tier: PERSONAL)`));
                 }
@@ -344,7 +365,7 @@ program
     if (options.headed) {
         options.headless = false;
     }
-    const resolvedTargetPath = targetPath ? targetPath : "./flows";
+    const resolvedTargetPath = targetPath || (0, config_1.loadNativeConfig)(process.cwd(), options).testDir;
     const strictUiFlowsDir = path.resolve(process.cwd(), resolvedTargetPath);
     if (!fs.existsSync(strictUiFlowsDir)) {
         console.error(`\n[ERROR]: Could not find ${strictUiFlowsDir}.`);
@@ -352,11 +373,17 @@ program
         process.exit(1);
     }
     options.forceOS = forceOS;
+    if (!forceOS && token) {
+        options.machineToken = token;
+        const file = fs.existsSync(localCredentialsPath) ? localCredentialsPath : globalCredentialsPath;
+        if (!options.workspaceId && fs.existsSync(file))
+            options.workspaceId = JSON.parse(fs.readFileSync(file, 'utf8')).workspaceId;
+    }
     await (0, run_1.runAction)(strictUiFlowsDir, options);
 });
 async function handleOfflinePrompt() {
     console.log(chalk_1.default.yellow("🛜 OFFLINE: Unable to reach Flowstride Cloud. Enterprise Sync paused."));
-    if (process.env.CI || process.env.FLOWSTRIDE_TOKEN) {
+    if (process.env.CI || process.env.FLOWSTRIDE_NATIVE_CI || process.env.FLOWSTRIDE_TOKEN) {
         console.log(chalk_1.default.yellow("⚠️ CI/CD Environment: Automatically falling back to OS Engine."));
         return true;
     }
@@ -381,4 +408,16 @@ program
     .action(async () => {
     await (0, open_1.openAction)();
 });
+program.command('install')
+    .description('Install Chromium matching this Flowstride engine')
+    .option('--with-deps', 'Install operating-system browser dependencies')
+    .action((options) => {
+    const { execFileSync } = require('node:child_process');
+    execFileSync(process.execPath, [path.join(path.dirname(require.resolve('playwright/package.json')), 'cli.js'), 'install', ...(options.withDeps ? ['--with-deps'] : []), 'chromium'], { stdio: 'inherit', env: { ...process.env, PLAYWRIGHT_SKIP_BROWSER_GC: '1' } });
+});
+program.command('ci')
+    .description('Set up native Flowstride CI')
+    .command('init <provider>')
+    .description('Generate a GitHub Actions workflow without overwriting existing files')
+    .action((provider) => (0, init_1.initCI)(provider));
 program.parse(process.argv);

package/dist/game/bridge.d.ts

@@ -0,0 +1,13 @@
+/** Register observable state and explicitly test-only fixtures in a browser game. */
+export interface GameBridgeOptions {
+    readState?: () => unknown;
+    locate?: (id: string) => {
+        x: number;
+        y: number;
+    };
+    testMode?: boolean;
+    fixtures?: Record<string, (data: unknown) => unknown>;
+}
+export declare function registerGame(options: GameBridgeOptions): {
+    dispose(): void;
+};

package/dist/game/bridge.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerGame = registerGame;
+function registerGame(options) {
+    if (typeof window === 'undefined')
+        throw new Error('Game bridges must be registered in the browser.');
+    if (typeof options.readState !== 'function' && typeof options.locate !== 'function')
+        throw new Error('A game bridge requires readState or locate.');
+    const bridge = { readState: options.readState, locate: options.locate,
+        testMode: options.testMode === true,
+        fixtures: options.testMode === true ? options.fixtures || {} : {} };
+    window.__FLOWSTRIDE_GAME__ = bridge;
+    return { dispose() { if (window.__FLOWSTRIDE_GAME__ === bridge)
+            delete window.__FLOWSTRIDE_GAME__; } };
+}

package/dist/game/sdk.d.ts

@@ -0,0 +1,27 @@
+import type { Page } from 'playwright';
+import type { FlowstrideConfig } from '../types';
+export declare class GameSDK {
+    private page;
+    private config;
+    private snapshots;
+    private states;
+    constructor(page: () => Page, config: FlowstrideConfig);
+    private timeout;
+    private bridgeReady;
+    private point;
+    private touch;
+    tap(options: any): Promise<void>;
+    drag(options: any): Promise<void>;
+    swipe(options: any): Promise<void>;
+    key(options: any): Promise<void>;
+    checkpoint(options: any): Promise<string>;
+    snapshot(options: any): Promise<void>;
+    private difference;
+    expectVisual(options: any): Promise<number>;
+    state(options?: any): Promise<any>;
+    expectState(options: any): Promise<void>;
+    snapshotState(options: any): Promise<void>;
+    expectPreserved(options: any): Promise<void>;
+    fixture(options: any): Promise<any>;
+    select(options: any): Promise<void>;
+}