flowstride 1.0.20 → 1.0.22

package/dist/ci/distribution.js

@@ -0,0 +1,134 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseShard = parseShard;
+exports.executionPlan = executionPlan;
+exports.mergeResults = mergeResults;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const projectPaths_1 = require("../utils/projectPaths");
+function parseShard(value) {
+    if (value === undefined)
+        return { index: 1, total: 1 };
+    const match = /^(\d+)\/(\d+)$/.exec(value);
+    if (!match)
+        throw new Error('shard must be index/total, e.g. 1/4.');
+    const index = Number(match[1]), total = Number(match[2]);
+    if (!Number.isSafeInteger(index) || !Number.isSafeInteger(total) || index < 1 || index > total || total > 256)
+        throw new Error('Shard index must be between 1 and total (maximum 256).');
+    return { index, total };
+}
+function executionPlan(target, config) {
+    const root = config?.projectRoot || process.cwd(), files = (0, projectPaths_1.discoverFlows)(target, root);
+    const flowRoot = node_fs_1.default.statSync(target).isDirectory() ? target : node_path_1.default.dirname(target);
+    const shard = parseShard(config?.shard);
+    const identity = (file) => (0, projectPaths_1.flowIdentity)(file, flowRoot);
+    const suiteHash = (0, node_crypto_1.createHash)('sha256').update(JSON.stringify(files.map(file => [identity(file), (0, node_crypto_1.createHash)('sha256').update(node_fs_1.default.readFileSync(file)).digest('hex')]))).digest('hex');
+    // Configuration affects compatibility, but only a hash leaves this process.
+    const configHash = (0, node_crypto_1.createHash)('sha256').update(JSON.stringify([require('../../package.json').name, require('../../package.json').version, config?.browser || 'chromium', config?.device || 'desktop', config?.browserOptions || {}, config?.retries || 0, config?.baseUrl || '', config?.timeout || 30000, config?.headless, config?.browserErrors, config?.failOnFlaky, config?.recordVideo, config?.trace, config?.har])).digest('hex');
+    let history = {};
+    if (config?.shardHistory) {
+        history = JSON.parse(node_fs_1.default.readFileSync((0, projectPaths_1.projectPath)(root, config.shardHistory), 'utf8'));
+        if (!history || Array.isArray(history) || typeof history !== 'object' || Object.values(history).some(value => typeof value !== 'number' || !Number.isFinite(value) || value < 0))
+            throw new Error('Shard history must map file names to nonnegative durations.');
+    }
+    const setup = files.filter(file => file.endsWith('.first.flow'));
+    const standard = files.filter(file => !file.endsWith('.first.flow'));
+    const bins = Array.from({ length: shard.total }, () => []), weights = bins.map(() => 0);
+    for (const file of [...standard].sort((a, b) => (history[identity(b)] ?? 1) - (history[identity(a)] ?? 1) || identity(a).localeCompare(identity(b)))) {
+        const index = weights.indexOf(Math.min(...weights));
+        bins[index].push(file);
+        weights[index] += history[identity(file)] ?? 1;
+    }
+    const assigned = new Set([...setup, ...bins[shard.index - 1]]);
+    return { files: files.filter(file => assigned.has(file)), allFiles: files.map(identity), setupFiles: setup.map(identity), suiteHash, configHash, shard, flowRoot };
+}
+function mergeResults(summaries, output = 'flowstride-merged') {
+    const root = process.cwd(), out = (0, projectPaths_1.projectPath)(root, output);
+    if (node_fs_1.default.existsSync(out))
+        throw new Error('Merge output already exists; choose a new directory.');
+    if (!summaries.length)
+        throw new Error('Provide one summary per shard.');
+    const inputs = summaries.map(file => { const absolute = (0, projectPaths_1.projectPath)(root, file); return { file: absolute, report: JSON.parse(node_fs_1.default.readFileSync(absolute, 'utf8')) }; });
+    const first = inputs[0].report;
+    if (first.protocol !== 1 || !first.distribution?.suiteHash)
+        throw new Error('Only native distributed reports can be merged.');
+    const total = first.distribution.shard.total, seen = new Set(), seenFiles = new Set(), setup = new Set(first.distribution.setupFiles);
+    const errors = [], steps = [], attempts = [], timings = {};
+    for (const { report } of inputs) {
+        const dist = report.distribution;
+        if (report.protocol !== 1 || report.engine !== first.engine || !dist || dist.suiteHash !== first.distribution.suiteHash || dist.configHash !== first.distribution.configHash || dist.shard.total !== total || JSON.stringify(dist.allFiles) !== JSON.stringify(first.distribution.allFiles) || JSON.stringify(dist.setupFiles) !== JSON.stringify(first.distribution.setupFiles))
+            throw new Error('Shards belong to different suites or browser configurations.');
+        const { index } = parseShard(`${dist.shard.index}/${dist.shard.total}`);
+        if (seen.has(index))
+            throw new Error('Duplicate shard.');
+        seen.add(index);
+        if (!['passed', 'failed', 'interrupted'].includes(report.status) || !Array.isArray(report.steps) || !Array.isArray(report.files) || !Array.isArray(report.errors))
+            throw new Error('Invalid shard report.');
+        if (!report.metrics || ['total', 'passed', 'failed', 'skipped', 'incomplete'].some(key => !Number.isSafeInteger(report.metrics[key]) || report.metrics[key] < 0) || report.metrics.passed + report.metrics.failed + report.metrics.skipped + report.metrics.incomplete !== report.metrics.total)
+            throw new Error('Inconsistent shard metrics.');
+        if (report.status === 'passed' && (report.errors.length || report.metrics.failed || report.metrics.incomplete || report.steps.some((step) => !['passed', 'skipped', 'not_tested'].includes(step.status))))
+            throw new Error('A passing shard contains failures or unfinished work.');
+        const duplicateSetup = new Set();
+        for (const file of report.files) {
+            if (!dist.allFiles.includes(file))
+                throw new Error('Unexpected file in shard.');
+            if (seenFiles.has(file)) {
+                if (!setup.has(file))
+                    throw new Error('File appears in more than one shard.');
+                duplicateSetup.add(file);
+            }
+            seenFiles.add(file);
+        }
+        for (const step of report.steps)
+            steps.push({ ...step, shard: index });
+        attempts.push(...(report.attempts || []).map((attempt) => ({ ...attempt, shard: index })));
+        errors.push(...report.errors.map((error) => `Shard ${index}: ${error}`));
+        for (const [file, duration] of Object.entries(report.timings || {}))
+            if (typeof duration === 'number' && duration >= 0)
+                timings[file] = Math.max(timings[file] || 0, duration);
+    }
+    if (seen.size !== total)
+        throw new Error(`Missing shards: expected ${total}, received ${seen.size}.`);
+    if (first.distribution.allFiles.some((file) => !seenFiles.has(file)))
+        throw new Error('Merged reports omit test files.');
+    const statuses = inputs.map(input => input.report.status), status = statuses.includes('interrupted') ? 'interrupted' : statuses.includes('failed') || errors.length ? 'failed' : 'passed';
+    const metrics = inputs.reduce((all, { report }) => { for (const key of ['total', 'passed', 'failed', 'skipped', 'incomplete']) {
+        const n = report.metrics?.[key];
+        if (!Number.isSafeInteger(n) || n < 0)
+            throw new Error('Invalid shard metrics.');
+        all[key] += n;
+    } return all; }, { total: 0, passed: 0, failed: 0, skipped: 0, incomplete: 0 });
+    // Preserve shard-level metrics (setup executes independently on each machine).
+    const merged = { protocol: 1, engine: first.engine, browser: first.browser, browsers: inputs.flatMap(({ report }) => (report.browsers || []).map((info) => ({ ...info, shard: report.distribution.shard.index }))), status, metrics, steps, attempts, errors, timings, files: [...seenFiles], duration: Math.max(...inputs.map(input => input.report.duration)), distribution: { ...first.distribution, merged: true, setupRunsPerShard: true } };
+    node_fs_1.default.mkdirSync(out, { recursive: true, mode: 0o700 });
+    try {
+        for (const { file, report } of inputs) {
+            const source = (0, projectPaths_1.projectPath)(root, node_path_1.default.join(node_path_1.default.dirname(file), node_path_1.default.basename(report.artifactsDir || '')));
+            if (!node_fs_1.default.existsSync(source) || !node_fs_1.default.statSync(source).isDirectory())
+                throw new Error('Shard evidence directory is missing. Preserve each summary alongside its run directory.');
+            const destination = node_path_1.default.join(out, `shard-${report.distribution.shard.index}`);
+            node_fs_1.default.mkdirSync(destination);
+            let bytes = 0;
+            for (const name of node_fs_1.default.readdirSync(source)) {
+                const item = (0, projectPaths_1.projectPath)(root, node_path_1.default.join(source, name)), stat = node_fs_1.default.lstatSync(item);
+                if (!stat.isFile() || stat.isSymbolicLink())
+                    throw new Error('Shard evidence must contain regular files only.');
+                bytes += stat.size;
+                if (bytes > 500 * 1024 * 1024)
+                    throw new Error('Shard evidence exceeds the 500 MiB merge limit.');
+                node_fs_1.default.copyFileSync(item, node_path_1.default.join(destination, name));
+            }
+        }
+        node_fs_1.default.writeFileSync(node_path_1.default.join(out, 'summary.json'), JSON.stringify(merged, null, 2));
+        node_fs_1.default.writeFileSync(node_path_1.default.join(out, 'timings.json'), JSON.stringify(timings, null, 2));
+        return merged;
+    }
+    catch (error) {
+        node_fs_1.default.rmSync(out, { recursive: true, force: true });
+        throw error;
+    }
+}

package/dist/ci/init.d.ts

@@ -1 +1,4 @@
-export declare function initCI(provider: string): void;
+export declare function initCI(provider: string, options?: {
+    browsers?: string;
+    shards?: string;
+}): void;

package/dist/ci/init.js

@@ -7,15 +7,26 @@ exports.initCI = initCI;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const config_1 = require("./config");
-function initCI(provider) {
+function initCI(provider, options = {}) {
     if (provider !== 'github')
         throw new Error('Supported provider: github.');
+    const browsers = (options.browsers || 'chromium').split(',');
+    const shards = Number(options.shards || 1);
+    if (!browsers.length || new Set(browsers).size !== browsers.length || browsers.some(browser => !['chromium', 'firefox', 'webkit'].includes(browser)))
+        throw new Error('Choose unique browser names separated by commas.');
+    if (!Number.isSafeInteger(shards) || shards < 1 || shards > 256)
+        throw new Error('shards must be 1..256.');
+    const matrix = browsers.length > 1 || shards > 1;
+    const strategy = matrix ? `\n    strategy:\n      fail-fast: false\n      matrix:\n        browser: ${JSON.stringify(browsers)}\n        shard: ${JSON.stringify(Array.from({ length: shards }, (_, index) => index + 1))}` : '';
+    const selection = matrix ? ' --browser ${{ matrix.browser }} --shard ${{ matrix.shard }}/' + shards : browsers[0] !== 'chromium' ? ' --browser ' + browsers[0] : '';
+    const install = matrix ? ' ${{ matrix.browser }}' : ' ' + browsers[0];
+    const artifact = matrix ? 'flowstride-results-${{ matrix.browser }}-${{ matrix.shard }}' : 'flowstride-results';
     const file = node_path_1.default.resolve('.github/workflows/flowstride.yml');
     if (node_fs_1.default.existsSync(file))
         throw new Error('Flowstride workflow already exists; it was not overwritten.');
     const artifacts = node_path_1.default.relative(process.cwd(), (0, config_1.loadNativeConfig)(process.cwd(), {}).artifactsDir);
     const parent = node_path_1.default.dirname(file);
     node_fs_1.default.mkdirSync(parent, { recursive: true });
-    node_fs_1.default.writeFileSync(file, `name: Flowstride\non:\n  push:\n  pull_request:\n  workflow_dispatch:\npermissions:\n  contents: read\njobs:\n  test:\n    runs-on: ubuntu-latest\n    timeout-minutes: 20\n    steps:\n      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262\n        with:\n          persist-credentials: false\n      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020\n        with:\n          node-version: 24\n          cache: npm\n      - run: npm ci\n      - name: Install matching browser dependencies\n        run: npx --no-install flowstride install --with-deps\n      - name: Run native Flowstride\n        run: npx --no-install flowstride run --ci\n      - name: Retain test evidence\n        if: always()\n        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02\n        with:\n          name: flowstride-results\n          path: ${JSON.stringify(artifacts + "/")}\n          retention-days: 14\n`, { flag: 'wx' });
+    node_fs_1.default.writeFileSync(file, `name: Flowstride\non:\n  push:\n  pull_request:\n  workflow_dispatch:\npermissions:\n  contents: read\njobs:\n  test:\n    runs-on: ubuntu-latest\n    timeout-minutes: 20${strategy}\n    steps:\n      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262\n        with:\n          persist-credentials: false\n      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020\n        with:\n          node-version: 24\n          cache: npm\n      - run: npm ci\n      - name: Install matching browser dependencies\n        run: npx --no-install flowstride install --with-deps${install}\n      - name: Run native Flowstride\n        run: npx --no-install flowstride run --ci${selection}\n      - name: Retain test evidence\n        if: always()\n        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02\n        with:\n          name: ${artifact}\n          path: ${JSON.stringify(artifacts + "/")}\n          retention-days: 14\n`, { flag: 'wx' });
     console.log(`Created ${file}. Commit it when ready. This template uses the project-locked Flowstride installation.`);
 }

package/dist/ci/runtime.js

@@ -4,6 +4,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runNativeCI = runNativeCI;
+const assertion_result_1 = require("../reporting/assertion_result");
+const distribution_1 = require("./distribution");
 const node_crypto_1 = require("node:crypto");
 const projectPaths_1 = require("../utils/projectPaths");
 const node_fs_1 = __importDefault(require("node:fs"));
@@ -20,6 +22,11 @@ async function runNativeCI(worker, orchestrator, target, config, engine) {
     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 plan = (0, distribution_1.executionPlan)(target, config);
+    const browsers = new Map();
+    const attempts = [];
+    const attemptSteps = new Map();
+    const timings = {};
     const steps = new Map();
     const completed = new Set();
     const errors = [];
@@ -34,8 +41,18 @@ async function runNativeCI(worker, orchestrator, target, config, engine) {
         if (!data?.payload)
             return;
         const p = data.payload;
+        if (data.type === 'BROWSER_INFO')
+            browsers.set(p.fileName, { ...p });
         if (data.type === 'BAIL')
             bailed = true;
+        if (data.type === 'SCENARIO_ATTEMPT')
+            attemptSteps.set(p.fileName, []);
+        if (data.type === 'SCENARIO_RESULT')
+            attempts.push({ ...p, steps: [...(attemptSteps.get(p.fileName) || [])] });
+        if (data.type === 'FILE_COMPLETE' || data.type === 'FILE_FAILED')
+            timings[p.fileName] = p.duration;
+        if (data.type === 'STEP_UPDATE')
+            attemptSteps.get(p.fileName)?.push({ ...p, screenshot: undefined });
         if (data.type === 'LOG_EVENT' && p.status === 'error') {
             const active = [...steps.values()].reverse().find(step => step.fileName === p.fileName && step.status === 'running');
             if (active)
@@ -69,9 +86,9 @@ async function runNativeCI(worker, orchestrator, target, config, engine) {
     process.on('SIGINT', interrupt);
     process.on('SIGTERM', interrupt);
     try {
-        files = (0, projectPaths_1.discoverFlows)(target, config.projectRoot || process.cwd());
+        files = plan.files;
         config.flowRoot = node_fs_1.default.statSync(target).isDirectory() ? target : node_path_1.default.dirname(target);
-        if (!files.length)
+        if (!plan.allFiles.length)
             throw new Error('No .flow tests found.');
         for (const file of files) {
             const features = (0, projectPaths_1.selectedFeatures)(new parser_1.Parser(new lexer_1.Lexer(node_fs_1.default.readFileSync(file, 'utf8')).tokenise()).parse());
@@ -83,7 +100,7 @@ async function runNativeCI(worker, orchestrator, target, config, engine) {
                     }
             expected += features.reduce((n, feature) => n + feature.scenarios.reduce((m, scenario) => m + scenario.steps.length, 0), 0);
         }
-        if (!expected)
+        if (files.length && !expected)
             throw new Error('No executable test steps found.');
         if (config.webServer) {
             const settings = config.webServer;
@@ -175,8 +192,10 @@ async function runNativeCI(worker, orchestrator, target, config, engine) {
         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 = { cloudSync: config.cloudSyncResult, protocol: 1, engine, status: interrupted ? 'interrupted' : errors.length || metrics.failed || incomplete ? 'failed' : 'passed',
-        duration: Date.now() - started, artifactsDir: directory, files: files.map(file => (0, projectPaths_1.flowIdentity)(file, config.flowRoot)), steps: results, errors, metrics };
+    if (config.failOnFlaky && attempts.some(attempt => attempt.flaky))
+        errors.push('Flaky scenarios are configured to fail CI.');
+    const result = { cloudSync: config.cloudSyncResult, browser: config.browser || 'chromium', browsers: [...browsers.values()], protocol: 1, engine, status: interrupted ? 'interrupted' : errors.length || metrics.failed || incomplete ? 'failed' : 'passed',
+        duration: Date.now() - started, artifactsDir: directory, files: files.map(file => (0, projectPaths_1.flowIdentity)(file, config.flowRoot)), steps: results, errors, metrics, attempts, timings, distribution: { ...plan, files: undefined, flowRoot: undefined } };
     // Existing workers finalize videos into these locations. Copy only run files,
     // never the project directory or credentials.
     if (config.recordVideo !== false)
@@ -190,8 +209,9 @@ async function runNativeCI(worker, orchestrator, target, config, engine) {
             }
         }
     config.artifactsDir = artifactRoot;
+    node_fs_1.default.writeFileSync(node_path_1.default.join(artifactRoot, 'timings.json'), JSON.stringify(timings, null, 2));
     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>`);
+    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/>' : ''}${step.assertion ? `<system-out>${xml((0, assertion_result_1.assertionText)(step.assertion))}</system-out>` : ''}</testcase>`);
     for (const error of errors)
         cases.push(`<testcase name="execution"><error message="${xml(error)}"/></testcase>`);
     if (incomplete)
@@ -199,5 +219,12 @@ async function runNativeCI(worker, orchestrator, target, config, engine) {
     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`);
+    if (process.env.GITHUB_STEP_SUMMARY) {
+        const failures = results.filter(step => step.status === 'failed').map(step => `<details><summary>${xml(step.commandLabel || step.command || 'Step')} · ${xml(step.fileName)}</summary><pre>${xml(step.error || (step.assertion ? (0, assertion_result_1.assertionText)(step.assertion) : 'Failed without an adapter diagnostic.'))}</pre></details>`);
+        for (const error of errors)
+            failures.push(`<pre>${xml(error)}</pre>`);
+        if (failures.length)
+            node_fs_1.default.appendFileSync(process.env.GITHUB_STEP_SUMMARY, '\n' + failures.join('\n') + '\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 runtime_failure_1 = require("../../reporting/runtime_failure");
+const compatibility_1 = require("../../native/compatibility");
 const projectPaths_1 = require("../../utils/projectPaths");
 const config_1 = require("../../ci/config");
 const runtime_1 = require("../../ci/runtime");
@@ -121,12 +123,16 @@ async function runAction(targetPath, options) {
             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.');
+            if ((0, compatibility_1.needsNativeBrowserProtocol)(resolvedPath, config) && (proWorkerModule.FlowWorker.nativeBrowserProtocol !== 2 || proOrchModule.FlowOrchestrator.nativeBrowserProtocol !== 2))
+                throw new Error('Installed Cloud engine does not support these native browser capabilities. Install the matching Cloud archive; this run will use OS fallback.');
+            if ((0, compatibility_1.needsNativeBrowserProtocol)(resolvedPath, config) && (proWorkerModule.FlowWorker.nativeAssertionProtocol !== 1 || proOrchModule.FlowOrchestrator.nativeAssertionProtocol !== 1))
+                throw new Error('Installed Cloud engine predates structured assertion reporting; this run will use OS fallback. Install the matching Cloud archive to update.');
             ActiveFlowWorker = proWorkerModule.FlowWorker;
             ActiveFlowOrchestrator = proOrchModule.FlowOrchestrator;
             engineMode = "Enterprise (Pro)";
         }
         catch (err) {
-            console.warn(`\n[Warning]: Found @flowstride/pro but failed to boot it. Falling back to Open Source engine. (${err.message})`);
+            console.warn(`\n[Warning]: Found @flowstride/pro but failed to boot it. Falling back to Open Source engine. (${(0, runtime_failure_1.runtimeFailure)("run.setup", { path: resolvedPath }, err, { file: resolvedPath })})`);
         }
     }
     console.log(`\n[Engine]: Booting Flowstride in ${engineMode} mode...`);
@@ -137,9 +143,16 @@ async function runAction(targetPath, options) {
         console.log(`[Flowstride]: ${result.status}; reports: ${config.artifactsDir}`);
         process.exit(result.status === 'passed' ? 0 : result.status === 'interrupted' ? 130 : 1);
     }
+    const previousRunEvent = config.onRunEvent;
+    config.onRunEvent = event => {
+        previousRunEvent?.(event);
+        if (event.type === 'RUN_COMPLETE')
+            process.exitCode = event.payload?.status === 'success' ? 0 : ['aborted', 'interrupted'].includes(event.payload?.status) ? 130 : 1;
+    };
     try {
-        await orchestrator.start(resolvedPath);
-        console.log("\n[Flowstride]: Execution suite completed successfully.");
+        const isSuccess = await orchestrator.start(resolvedPath);
+        process.exitCode = isSuccess ? 0 : 1;
+        console.log(isSuccess ? "\n[Flowstride]: Execution suite completed successfully." : "\n[Flowstride]: Execution suite failed.");
         if (isCI) {
             const artifactsDir = path.resolve(root, "flowstride-artifacts");
             if (!fs.existsSync(artifactsDir)) {
@@ -154,7 +167,7 @@ async function runAction(targetPath, options) {
         }
     }
     catch (error) {
-        console.error("\n[Fatal Error]:", error.message);
+        console.error("\n[Fatal Error]:", (0, runtime_failure_1.runtimeFailure)("run.setup", { path: resolvedPath }, error, { file: resolvedPath }));
         if (isCI) {
             console.log(`[CI Alert]: Terminating pipeline with exit code 1 to block deployment.`);
         }

package/dist/cli/index.js

@@ -37,6 +37,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+const distribution_1 = require("../ci/distribution");
+const projectPaths_1 = require("../utils/projectPaths");
 const cloud_1 = require("../utils/cloud");
 const cloudSession_1 = require("./utils/cloudSession");
 const config_1 = require("../ci/config");
@@ -63,7 +65,7 @@ let API_BASE = (0, cloud_1.cloudApiBase)(process.env);
 program
     .name("flowstride")
     .description("Flowstride: The Enterprise Flow-First Automation CLI")
-    .version("1.0.20");
+    .version(require("../../package.json").version);
 program
     .command("init")
     .description("Initialise a new Flowstride workspace in the current directory")
@@ -258,6 +260,10 @@ program
     .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('--browser <engine>', 'chromium, firefox, or webkit')
+    .option('--shard <index/total>', 'Run one deterministic CI shard, e.g. 1/4')
+    .option('--shard-history <file>', 'Use merged timing history for shard balancing')
+    .option('--update-baselines', 'Explicitly update ARIA baselines locally')
     .option('--config <file>', 'Path to the Flowstride configuration')
     .option('--env <name>', 'Environment profile')
     .action(async (targetPath, options) => {
@@ -394,15 +400,28 @@ program
     await (0, open_1.openAction)();
 });
 program.command('install')
-    .description('Install Chromium matching this Flowstride engine')
+    .description('Install browsers matching this Flowstride engine')
+    .argument('[browsers...]', 'chromium, firefox, or webkit')
     .option('--with-deps', 'Install operating-system browser dependencies')
-    .action((options) => {
+    .action((browsers, options) => {
+    if (browsers.some(browser => !['chromium', 'firefox', 'webkit'].includes(browser)))
+        throw new Error('Unknown browser.');
     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' } });
+    execFileSync(process.execPath, [path.join(path.dirname(require.resolve('playwright/package.json')), 'cli.js'), 'install', ...(options.withDeps ? ['--with-deps'] : []), ...(browsers.length ? browsers : ['chromium'])], { stdio: 'inherit', env: { ...process.env, PLAYWRIGHT_SKIP_BROWSER_GC: '1' } });
+    console.log(`[Browsers]: Matching binaries installed: ${(browsers.length ? browsers : ['chromium']).join(', ')}. Use run --browser <engine> to select one.`);
 });
 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));
+    .option('--browsers <names>', 'Comma-separated browser matrix', 'chromium')
+    .option('--shards <total>', 'Number of CI machines per browser', '1')
+    .action((provider, options) => (0, init_1.initCI)(provider, options));
+program.command('merge <summaries...>')
+    .description('Merge complete native shard results and evidence')
+    .option('--output <directory>', 'New project directory for merged results', 'flowstride-merged')
+    .action((summaries, options) => { const result = (0, distribution_1.mergeResults)(summaries, options.output); console.log(`Merged Flowstride result: ${result.status}`); process.exitCode = result.status === 'passed' ? 0 : 1; });
+program.command('trace <file>')
+    .description('Open a local Playwright trace without uploading it')
+    .action((file) => { const { execFileSync } = require('node:child_process'); const local = (0, projectPaths_1.projectPath)(process.cwd(), file); execFileSync(process.execPath, [path.join(path.dirname(require.resolve('playwright/package.json')), 'cli.js'), 'show-trace', local], { stdio: 'inherit' }); });
 program.parse(process.argv);

package/dist/cli/manual_server/workspace_server.js

@@ -37,6 +37,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.startManualWorkspaceServer = startManualWorkspaceServer;
+const localWorkspace_1 = require("../../security/localWorkspace");
 const projectPaths_1 = require("../../utils/projectPaths");
 const security_1 = require("../../manual/security");
 const http = __importStar(require("http"));
@@ -44,6 +45,72 @@ const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
 const ws_1 = require("ws");
 const chalk_1 = __importDefault(require("chalk"));
+/** Complete local persistence before publishing a usable media URL. */
+function receiveManualUpload(req, res, filePath, maxSize, limitMessage, onSaved, onChunk) {
+    let size = 0;
+    let saved = false;
+    let failure;
+    const output = fs.createWriteStream(filePath);
+    const sendFailure = () => {
+        if (!res.destroyed && !res.writableEnded && !res.headersSent) {
+            res.writeHead(failure?.status || 500, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: failure?.message || 'Upload stream failed' }));
+        }
+    };
+    const fail = (status, message) => {
+        if (saved || failure)
+            return;
+        failure = { status, message };
+        output.destroy();
+        // Drain the rejected request without buffering it so the error can be sent.
+        req.resume();
+    };
+    output.on('error', () => fail(500, 'Upload stream failed'));
+    output.once('close', () => {
+        if (saved)
+            return;
+        // An early destroy may race the asynchronous file open. Cleanup belongs
+        // after close, when a partial file can no longer be recreated or written.
+        try {
+            fs.unlinkSync(filePath);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                console.warn('[Upload]: Could not remove a partial media file.');
+        }
+        sendFailure();
+    });
+    output.once('finish', () => {
+        if (failure)
+            return;
+        saved = true;
+        Promise.resolve().then(() => onSaved(size)).catch(() => {
+            failure = { status: 500, message: 'Upload completion failed' };
+            sendFailure();
+        });
+    });
+    req.on('data', (chunk) => {
+        if (failure || saved)
+            return;
+        size += chunk.length;
+        if (size > maxSize) {
+            fail(413, limitMessage);
+            return;
+        }
+        onChunk?.(chunk);
+        if (!output.write(chunk)) {
+            req.pause();
+            output.once('drain', () => { if (!failure)
+                req.resume(); });
+        }
+    });
+    req.once('end', () => { if (!failure)
+        output.end(); });
+    req.once('aborted', () => fail(400, 'Upload aborted'));
+    req.once('error', () => fail(500, 'Upload stream failed'));
+    res.once('close', () => { if (!res.writableFinished)
+        fail(400, 'Upload aborted'); });
+}
 async function startManualWorkspaceServer() {
     const cliInstallPath = path.resolve(__dirname, "../../..");
     const uiDistPath = path.join(cliInstallPath, "src", "ui", "dist");
@@ -74,9 +141,18 @@ async function startManualWorkspaceServer() {
         ".webm": "video/webm",
     };
     const httpServer = http.createServer(async (req, res) => {
-        res.setHeader("Access-Control-Allow-Origin", "*");
-        res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
-        res.setHeader("Access-Control-Allow-Headers", "Content-Type, X-File-Extension");
+        const origin = typeof req.headers.origin === 'string' ? req.headers.origin : undefined;
+        const fetchSite = typeof req.headers['sec-fetch-site'] === 'string' ? req.headers['sec-fetch-site'] : undefined;
+        if (!(0, localWorkspace_1.isLocalWorkspaceRequest)(req.headers.host, origin, req.socket.localPort, fetchSite)) {
+            res.writeHead(403, { 'Content-Type': 'text/plain' });
+            res.end('Forbidden');
+            return;
+        }
+        if (origin)
+            res.setHeader('Access-Control-Allow-Origin', origin);
+        res.setHeader('Vary', 'Origin');
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type, X-File-Extension');
         if (req.method === "OPTIONS") {
             res.writeHead(204);
             return res.end();
@@ -95,43 +171,11 @@ async function startManualWorkspaceServer() {
             }
             const safeFilename = `media_${Date.now()}_${Math.random().toString(36).substring(2, 9)}${ext.toLowerCase()}`;
             const filePath = (0, projectPaths_1.projectPath)(process.cwd(), path.join(mediaDir, safeFilename));
-            const MAX_SIZE = 104857600;
-            let uploadedSize = 0;
-            let isAborted = false;
-            const writeStream = fs.createWriteStream(filePath);
-            req.on("data", (chunk) => {
-                if (isAborted)
-                    return;
-                uploadedSize += chunk.length;
-                if (uploadedSize > MAX_SIZE) {
-                    isAborted = true;
-                    writeStream.destroy();
-                    if (fs.existsSync(filePath))
-                        fs.unlinkSync(filePath);
-                    res.writeHead(413, { "Content-Type": "application/json" });
-                    res.end(JSON.stringify({ error: "Payload Too Large. Max size is 100MB." }));
-                }
-                else {
-                    writeStream.write(chunk);
-                }
-            });
-            req.on("end", () => {
-                if (isAborted)
-                    return;
-                writeStream.end();
+            receiveManualUpload(req, res, filePath, 104857600, 'Payload Too Large. Max size is 100MB.', (uploadedSize) => {
                 console.log(chalk_1.default.blue(`\n[Reference Uploaded]: Securely saved ${safeFilename} (${(uploadedSize / 1024 / 1024).toFixed(2)} MB)`));
-                res.writeHead(200, { "Content-Type": "application/json" });
+                res.writeHead(200, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({ url: `/media/${safeFilename}` }));
             });
-            req.on("error", (err) => {
-                if (!isAborted) {
-                    writeStream.destroy();
-                    if (fs.existsSync(filePath))
-                        fs.unlinkSync(filePath);
-                    res.writeHead(500, { "Content-Type": "application/json" });
-                    res.end(JSON.stringify({ error: "Upload stream failed" }));
-                }
-            });
             return;
         }
         if (req.method === "DELETE" && pathname === "/api/media") {
@@ -216,44 +260,12 @@ async function startManualWorkspaceServer() {
             }
             const safeFilename = `defect_${Date.now()}_${Math.random().toString(36).substring(2, 9)}${ext.toLowerCase()}`;
             const filePath = (0, projectPaths_1.projectPath)(process.cwd(), path.join(defectMediaDir, safeFilename));
-            const MAX_SIZE = 41943040; // Capped at 40MB
-            let uploadedSize = 0;
-            let isAborted = false;
-            const writeStream = fs.createWriteStream(filePath);
-            req.on("data", (chunk) => {
-                if (isAborted)
-                    return;
-                uploadedSize += chunk.length;
-                if (uploadedSize > MAX_SIZE) {
-                    isAborted = true;
-                    writeStream.destroy();
-                    if (fs.existsSync(filePath))
-                        fs.unlinkSync(filePath);
-                    res.writeHead(413, { "Content-Type": "application/json" });
-                    res.end(JSON.stringify({ error: "Payload Too Large. Max size is 40MB." }));
-                }
-                else {
-                    writeStream.write(chunk);
-                }
-            });
-            req.on("end", async () => {
-                if (isAborted)
-                    return;
-                writeStream.end();
+            receiveManualUpload(req, res, filePath, 41943040, 'Payload Too Large. Max size is 40MB.', () => {
                 const finalUrl = `/defect_media/${safeFilename}`;
                 console.log(chalk_1.default.green(`\n[Vault Success]: Defect Media secured locally at -> ${finalUrl}`));
-                res.writeHead(200, { "Content-Type": "application/json" });
+                res.writeHead(200, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({ url: finalUrl }));
             });
-            req.on("error", (err) => {
-                if (!isAborted) {
-                    writeStream.destroy();
-                    if (fs.existsSync(filePath))
-                        fs.unlinkSync(filePath);
-                    res.writeHead(500, { "Content-Type": "application/json" });
-                    res.end(JSON.stringify({ error: "Upload stream failed" }));
-                }
-            });
             return;
         }
         if (req.method === "DELETE" && pathname === "/api/defect-media") {
@@ -727,7 +739,11 @@ async function startManualWorkspaceServer() {
             }
         }
     });
-    const wss = new ws_1.WebSocketServer({ server: httpServer });
+    const wss = new ws_1.WebSocketServer({
+        server: httpServer,
+        verifyClient: (info) => Boolean(info.origin) &&
+            (0, localWorkspace_1.isLocalWorkspaceRequest)(info.req.headers.host, info.origin, info.req.socket.localPort, typeof info.req.headers['sec-fetch-site'] === 'string' ? info.req.headers['sec-fetch-site'] : undefined),
+    });
     wss.on("connection", (ws) => {
         ws.send(JSON.stringify({ type: "CLI_CONTEXT", payload: { command: "open" } }));
         ws.on("error", (err) => {
@@ -738,7 +754,7 @@ async function startManualWorkspaceServer() {
         console.error(chalk_1.default.red(`\n[Error]: Failed to start manual workspace server: ${e.message}`));
         process.exit(1);
     });
-    httpServer.listen(0, async () => {
+    httpServer.listen(0, '127.0.0.1', async () => {
         try {
             const address = httpServer.address();
             const port = typeof address === "object" && address !== null ? address.port : null;
@@ -746,7 +762,7 @@ async function startManualWorkspaceServer() {
                 console.error(chalk_1.default.red("\n[Error]: Could not bind to an available port."));
                 process.exit(1);
             }
-            const localUrl = `http://localhost:${port}`;
+            const localUrl = `http://127.0.0.1:${port}`;
             console.log(chalk_1.default.yellow(`\n[Workspace]: Manual Design server running at ${localUrl}`));
             const { default: open } = await import("open");
             await open(localUrl);