flowstride 1.0.19 → 1.0.20-rc.2

package/NATIVE_CI.md

@@ -0,0 +1,155 @@
+# Native CI and browser-game candidate
+
+This candidate adds native CI and game APIs to both engines. Managed Cloud
+execution remains retired. Existing npm OSS / private Pro archive distribution
+and fallback remain supported. Naija Throne's current runner is unchanged;
+its migration is a separate acceptance step. Native CI uses protocol 1.
+The public CLI selects compatible Pro engines or logs the reason and falls back
+to OSS. Older Pro CLIs may own the npm binary and do not understand the new
+commands; install both candidates when testing the Pro path.
+
+The candidates pin Playwright 1.59.1 in both engines; the native install command
+installs that engine's matching Chromium.
+
+## Local candidate check
+
+Use a disposable project first. Install the OSS archive, then the Pro archive if
+needed. Both candidates must be installed for testing the new Pro path. The
+currently hosted Cloud download still serves the existing release; this local
+candidate does not change that endpoint or its archive.
+
+```sh
+npm install --save-dev /absolute/path/flowstride-1.0.20-rc.2.tgz
+# Optional: install the local matching Pro candidate after project dependencies.
+npm install --no-save /absolute/path/flowstride-pro-1.0.15-rc.1.tgz
+npx --no-install flowstride install
+npx --no-install flowstride run --ci
+```
+
+Pro continues to require your normal valid developer credentials for licensed
+features. Installing Pro uses `--no-save`: another `npm ci` can remove it. Keep
+project dependency installation before Pro installation. An installed Pro package
+can own `node_modules/.bin/flowstride`; both that entry point and the public OSS
+entry point must be covered when checking fallback.
+
+The sample in `examples/native-game` uses a tiny local canvas game. Copy its
+files into a disposable project containing the installed candidates, then run
+the command above. `server.mjs` is the game fixture's HTTP server; it contains no
+Flowstride runner, adapter, worker, or CI orchestration code. A real application
+uses its normal development/start command instead.
+
+## Configuration
+
+`flowstride.config.json` supports `testDir`, `baseUrl`, `timeout`, `device`
+(`desktop`, `phone`, `landscape`), optional `viewport`, `pluginsDir`,
+`artifactsDir`, `recordVideo` (boolean), `browserErrors` (`fail` or `record`), and
+`webServer` (`command`, local readiness `url`, optional `cwd` and `timeout`).
+Malformed configuration and unsafe output paths fail before execution.
+
+Native CI is selected by `--ci` or a recognized CI environment. It runs without
+a dashboard server, returns nonzero for failed/incomplete/crashed execution,
+and writes latest `summary.json`/`junit.xml` reports at the configured artifact
+root. Media and attachments go into a unique run directory referenced by the
+summary, so local reruns retain history without mixing evidence.
+SIGINT/SIGTERM produce interrupted results. The run owns its optional local
+server and refuses an already-serving readiness URL.
+
+Cloud reporting is off by default in native CI. `cloudSync: true` explicitly
+allows existing authenticated reporting; its existing server-side security and
+storage limitations still apply. Normal interactive reporting and the restored
+Cloud URL overrides remain separate from retired managed execution.
+
+`npx flowstride ci init github` generates a workflow explicitly, never during
+installation, and refuses to overwrite it. It assumes an npm project with a
+committed lockfile. Other package managers and monorepos can use the composite
+action's install-command and working-directory inputs. The composite action is
+in the OSS repository's `action/` directory and becomes remotely usable only
+once that source is pushed. Pin its commit when configuring a consumer workflow.
+Pro jobs pass a developer token as a secret; dependency installation precedes
+Pro login/install, matching-browser installation, execution, and artifact upload.
+
+## Native game actions
+
+Register the built-in alias with `let game = "flowstride:game"`. It requires no
+custom plugin file. Available actions:
+
+- `tap`: canvas selector, x/y; relative coordinates by default, or `unit: "pixels"`.
+- `drag`/`swipe`: canvas, from/to coordinates, optional duration and input type.
+- `key`: key name and optional hold duration.
+- `checkpoint`: named screenshot, optionally of one canvas.
+- `snapshot` and `expectVisual`: canvas comparison with explicit minChange/maxChange.
+- `state`/`expectState`: exposed state, optional dotted path and expected equals.
+- `snapshotState`/`expectPreserved`: compare selected state across actions/reloads.
+- `fixture`: a named fixture registered by the application in explicit test mode.
+- `select`: a stable object ID resolved by the game bridge, then real pointer input.
+
+Visual checks establish pixel differences, not gameplay correctness; pair them
+with state or UI assertions. Mobile profiles emulate Chromium devices, not
+physical phones. Touch dragging currently uses Chromium CDP.
+
+For a generic browser game, import `registerGame` from
+`flowstride/dist/game/bridge.js` and supply readState and optional test-only
+fixtures. The function manages the browser bridge; no global setup is required
+in the test runner.
+
+## Three.js integration
+
+Import `registerThreeGame` from `flowstride/dist/game/three-bridge.js` in the game
+bundle. Register the live scene, camera, canvas, the application's own Vector3
+and Raycaster constructors, and an optional objects map keyed by stable IDs.
+Alternatively, assign `userData.flowstrideId` to scene objects. Optional local
+pick points use `userData.flowstridePickPoint: [x, y, z]`.
+
+The bridge projects the live object and raycasts the live scene; hidden,
+occluded, off-screen, covered or non-pickable objects fail explicitly. It creates
+no renderer or animation loop. Dispose the bridge when the scene is replaced.
+
+Optional `readState` provides observable state. `fixtures` are available only
+when the application explicitly registers with `testMode: true`; use that
+setting in dedicated test builds, never public production builds. Naija Throne
+still defines campaign-specific fixtures/rules, using these supported APIs.
+
+Custom plugins now receive `sdk.game`, `sdk.browser.page()`, and `sdk.run`
+(device, artifact directory and attach method), alongside the existing SDK.
+They need no global bridge or internal Flowstride class imports.
+
+## Validation before release
+
+Build both packages and run `npm run test:native`. For the optional live Three.js
+fixture set `FLOWSTRIDE_THREE_BUILD` to a Three.js build directory containing
+three.module.js and three.core.js. OSS CLI handoff tests use
+`FLOWSTRIDE_PRO_SOURCE` pointing at the built Pro package.
+
+Run the real archive install/handoff harness against both candidates, including
+missing/broken Pro and revoked-token fallback. Validate GitHub's Linux execution,
+real licensed download and Naija Throne migration after local acceptance.
+No push, npm publication, Cloud archive replacement or Naija Throne migration
+is performed by building these candidates.
+
+## Candidate acceptance automation
+
+The repository's `Native CI acceptance` workflow tests Node 22 and 24 on Linux.
+It uses a checksum-pinned archive in `.github/fixtures`, checks its compiled engine
+against a fresh build, checks referenced dashboard assets, then installs that exact
+archive in a clean consumer. It exercises native browser installation, passing and
+deliberately failing game execution, media, server cleanup and workflow preservation.
+It also runs the native source suite, including delayed uploads and cancellation.
+The Pro archive belongs only in the private Pro repository.
+
+These jobs do not publish npm packages, replace the hosted Pro archive, deploy
+Cloud, or migrate application repositories. Native Cloud reporting stays opt-in.
+Qualification covers Chromium and emulated desktop/phone/landscape profiles.
+Physical Android/iOS devices, Safari/Firefox and other game engines are outside
+this candidate's verified support scope. Real Cloud licensing, reporting and
+video storage require a separate live acceptance run.
+
+## OSS npm preview release
+
+OSS `1.0.20-rc.2` requires Node.js 22.12.0+. Publish the verified archive under
+`next`; install with `npm install --save-dev flowstride@next` after publication.
+Use the release archive and checksum rather than rebuilding from a dirty checkout.
+The matching local Pro candidate remains `1.0.15-rc.1`; hosted Pro remains
+`1.0.14`. Complete authentication before reinstalling the local Pro candidate.
+The unchanged dashboard bundle is reused from the previously qualified rc.1
+archive; the engine is rebuilt from this source. The release input manifest
+records both that archive's checksum and the merged base commit.

package/README.md

@@ -6,6 +6,34 @@ Flowstride OS combines the human-readable structure of Behavior-Driven Developme
 
 [Documentation](https://docs.flowstride.io/)
 
+## Native CI and game testing preview — 1.0.20-rc.2
+
+This is an opt-in preview intended for the npm `next` tag. The default stable
+release remains available through `latest`. After the preview is published:
+
+```sh
+npm install --save-dev flowstride@next
+npx --no-install flowstride install
+npx --no-install flowstride run --ci
+```
+
+Node.js 22.12.0+ is required; acceptance covers the minimum version and current
+Node.js 22/24 on Linux, plus Node.js 24 on macOS. The preview adds native CI
+exit codes, JSON/JUnit reports, videos/screenshots, device profiles, explicit
+GitHub workflow generation, and supported canvas/Three.js testing APIs.
+See [native CI setup](NATIVE_CI.md) and [release notes](RELEASE_NOTES.md).
+
+For this preview, use OSS alone or manually install the matching private Pro
+`1.0.15-rc.1` candidate after project dependencies. Normal Cloud login still
+serves Pro `1.0.14`; signing in afterward can replace the preview's Pro package,
+and that older CLI does not support the new native commands. Cloud reporting
+and video-storage defects remain open. Native CI keeps Cloud reporting off by
+default. Managed Cloud execution remains retired.
+
+This release qualifies Chromium desktop and emulated phone/landscape profiles
+and browser-game fixtures. It does not establish physical-phone, Safari,
+Firefox, other game-engine, or complete application-game coverage.
+
 ---
 
 ## Why Flowstride?
@@ -21,7 +49,7 @@ Traditional E2E frameworks force you to choose between highly technical code (wh
 
 ## Installation & Quick Start
 
-Flowstride requires Node.js 18 or higher.
+Flowstride requires Node.js 22.12.0 or higher. Use a current patched Node.js 22 or 24 release.
 
 **1. Install globally (or as a dev dependency in your project):**
 
@@ -71,41 +99,20 @@ npx flowstride login
 
 ---
 
-## Privacy & Data Security
-
-Flowstride is designed with a **zero-trust, local-first architecture**. Whether you are testing internal microservices, staging environments, or production APIs, your sensitive data, PHI, and credentials remain strictly on your infrastructure.
-
-### Open Source Core: 100% Local Isolation
-
-The Open Source version of Flowstride operates entirely as an ephemeral, local execution engine.
-
-- **Air-Gapped Execution:** Flowstride does not "phone home." The OS runner executes strictly on your local machine or within your private CI/CD pipeline. There is no external Flowstride database storing your test payloads or network logs.
-
-- **Ephemeral Memory:** Flowstride is inherently stateless. API request headers, response bodies, and DOM snapshots exist only in Node.js RAM during execution. The millisecond the execution process terminates, all memory is wiped.
-
-- **The DevTools Analogy:** Our network interception works natively within Playwright's browser context routing. It is fundamentally identical to opening the Chrome DevTools "Network" tab locally. We do not act as an external Man-In-The-Middle (MITM) proxy.
-
-- **Opt-In Local State:** Artifacts saved to disk—such as execution videos (`.flowstride/mock-cloud/`) or explicitly persisted browser states (`.flowstride/sessions/`)—are written strictly to your local file system to mirror the functionality of tools like Postman. _(Note: We strongly recommend adding `.flowstride/` to your `.gitignore` to prevent accidental credential commits)._
-
-### Flowstride Enterprise: Secure Cloud Telemetry
-
-For teams using Flowstride Enterprise to aggregate multi-flow metrics, we maintain a strict metadata-only boundary.
-
-- **Metadata, Not Payloads:** When cloud sync is active, Flowstride routes only execution metadata to your team's dashboard (e.g., Workspace ID, execution duration, total steps, and pass/fail tallies). **Zero bytes** of request headers, bearer tokens, or JSON bodies are ever transmitted to Flowstride Cloud.
-
-- **Deep Debugging Stays Local:** The rich, interactive visual dashboard, including the JSON explorer and API Replay tools, runs on a dynamic, locally bound port on your machine. You get the UI of a modern cloud app with the security of a local binary.
-
-### CI/CD Leak Protection & Terminal Hygiene
-
-Standard testing frameworks do dump failing API requests, and response bodies directly into the terminal so developers can debug them. In a CI/CD environment, this is a massive security liability, as those secrets are permanently burned into plaintext Jenkins, GitHub Actions, or GitLab CI logs.
-
-Flowstride completely neutralizes this threat by architecturally separating execution output from diagnostic telemetry:
+## Execution data and Cloud integration
 
-1. **Clean Standard Output (`stdout`):** Flowstride's terminal output only displays high-level, human-readable BDD execution steps (e.g., `✔ Given "User lands on home page"` or `✖ Action Failed`). No JSON request bodies, `cURL` strings, or bearer tokens are ever printed to the terminal console.
+Tests run on your machine or CI runner. Native CI writes reports, screenshots,
+videos and attachments to the configured local artifact directory. Interactive
+API diagnostics are available in the local dashboard. These outputs can contain
+application data or credentials; automatic redaction is not guaranteed.
 
-2. **WebSocket Isolation:** All sensitive raw network data (payloads, headers, and responses) is emitted _exclusively_ over a secure, ephemeral WebSocket connection directly to the developer's local UI dashboard.
+Cloud login/licensing, FlowMail OTP retrieval and explicitly enabled Cloud
+reporting contact their configured services. Native CI leaves Cloud reporting
+off unless `cloudSync: true` is explicitly configured. Existing Cloud reporting
+and storage limitations remain documented in the preview release notes.
 
-3. **Total Evaporation:** Because CI/CD runners only capture `stdout` text and do not connect to local WebSockets, your highly sensitive diagnostic data simply evaporates the moment the pipeline execution ends. Your pipeline logs remain 100% free of plaintext secrets.
+Use test credentials, keep runtime state and artifacts out of source control,
+and choose CI artifact access and retention appropriate to the test data.
 
 ---
 

package/RELEASE_NOTES.md

@@ -0,0 +1,40 @@
+# Flowstride 1.0.20-rc.2 — npm preview
+
+Publish channel: `next`. This preview does not move `latest` and does not publish
+or replace the private Pro engine. The matching Pro candidate is `1.0.15-rc.1`.
+
+## Changes since rc.1
+
+- Require Node.js 22.12.0+ and align package, lockfile, CLI version and guides.
+- Add an explicit preview publication configuration targeting the public npm
+  registry and `next`, plus matching CLI-version/engine metadata checks.
+- Clarify preview installation, native CI/game scope and Cloud/Pro limitations.
+- Replace absolute privacy guarantees in the README with the actual data flow.
+- Rebuild the engine from the merged OSS source; reuse the unchanged dashboard
+  from the checksum-verified rc.1 archive. No runner or game behaviour changes.
+
+## Native features inherited from rc.1
+
+`flowstride run --ci`, `flowstride install [--with-deps]`,
+`flowstride ci init github`, supported plugin/game SDKs, canvas/Three.js bridges,
+Chromium desktop/phone/landscape profiles, JSON/JUnit reports and failure media,
+safe file-chooser handling and interrupted-run cleanup.
+
+## Known limits
+
+Cloud login still downloads Pro 1.0.14, which does not support these native
+commands. Test OSS alone, or authenticate first and then manually install the
+matching local Pro candidate. Project dependency installation can remove a
+no-save Pro package; install Pro afterward. Public-CLI native fallback remains
+available for absent, broken or incompatible Pro engines.
+
+Live Cloud reporting and video-storage issues are unresolved. Native CI keeps
+reporting off by default; this preview does not enable the retired managed
+runner. Application-specific game rules/fixtures remain application code.
+Physical phones, Safari/Firefox and other game engines are not qualified.
+
+## Publication
+
+Only the verified OSS archive should be published. Use the `next` tag explicitly;
+then verify `flowstride@next` and reinstall from npm in a disposable consumer.
+No npm publication is performed while preparing this candidate.

package/dist/adapters/web/playwright.d.ts

@@ -2,6 +2,7 @@ import { Page } from "playwright";
 import { FlowstrideConfig } from "../../types";
 export declare class WebAdapter {
     private config;
+    pageErrors: string[];
     private browser;
     private context;
     private page;

package/dist/adapters/web/playwright.js

@@ -37,6 +37,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WebAdapter = void 0;
+const playwright_1 = require("playwright");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const playwright_extra_1 = require("playwright-extra");
@@ -44,6 +45,7 @@ const puppeteer_extra_plugin_stealth_1 = __importDefault(require("puppeteer-extr
 playwright_extra_1.chromium.use((0, puppeteer_extra_plugin_stealth_1.default)());
 class WebAdapter {
     config;
+    pageErrors = [];
     browser = null;
     context = null;
     page = null;
@@ -75,20 +77,23 @@ class WebAdapter {
         }
         this.browser = await playwright_extra_1.chromium.launch({
             headless: this.config.headless,
+            // Native CI finalizes videos before closing the browser on cancellation.
+            ...(this.config.ci ? { handleSIGINT: false, handleSIGTERM: false } : {}),
             args: launchArgs,
         });
         const videoDir = path.join(process.cwd(), ".flowstride", "videos");
         if (!fs.existsSync(videoDir))
             fs.mkdirSync(videoDir, { recursive: true });
-        const customUserAgent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36";
+        const profile = this.config.device === 'phone' || this.config.device === 'landscape'
+            ? { ...playwright_1.devices['Pixel 7'], viewport: this.config.device === 'landscape' ? { width: 844, height: 390 } : { width: 390, height: 844 } }
+            : { viewport: { width: 1280, height: 800 }, userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36' };
+        const viewport = this.config.viewport || profile.viewport;
         this.context = await this.browser.newContext({
-            viewport: null,
-            userAgent: customUserAgent,
-            recordVideo: {
-                dir: videoDir,
-                size: { width: 1280, height: 800 },
-            },
+            ...profile, viewport,
+            ...(this.config.recordVideo === false ? {} : { recordVideo: { dir: videoDir, size: viewport } }),
         });
+        this.pageErrors = [];
+        this.context.on('page', page => page.on('pageerror', error => this.pageErrors.push(error.message)));
         this.context.on("dialog", async (dialog) => {
             if (this.dialogHandler) {
                 await this.dialogHandler(dialog);
@@ -479,10 +484,10 @@ class WebAdapter {
             await targetLoc.evaluate((node) => node.blur());
             let actualValue = "";
             try {
-                actualValue = await targetLoc.inputValue({ timeout: 500 });
+                actualValue = await targetLoc.inputValue({ timeout: this.config.timeout });
             }
             catch {
-                actualValue = (await targetLoc.textContent({ timeout: 500 })) || "";
+                actualValue = (await targetLoc.textContent({ timeout: this.config.timeout })) || "";
             }
             const cleanActual = actualValue.replace(/[^a-zA-Z0-9]/g, "");
             const cleanExpected = value.replace(/[^a-zA-Z0-9]/g, "");
@@ -614,11 +619,10 @@ class WebAdapter {
             throw new Error(`File Upload Error: Could not find the file at "${absolutePath}". Please ensure the file exists in your project directory.`);
         }
         try {
-            const fileChooserPromise = this.page.waitForEvent("filechooser", {
-                timeout: 5000,
-            });
-            await targetLoc.click();
-            const fileChooser = await fileChooserPromise;
+            const [fileChooser] = await Promise.all([
+                this.page.waitForEvent('filechooser', { timeout: this.config.timeout }),
+                targetLoc.click({ timeout: this.config.timeout }),
+            ]);
             await fileChooser.setFiles(absolutePath);
         }
         catch (e) {

package/dist/ci/config.d.ts

@@ -0,0 +1,3 @@
+import type { FlowstrideConfig } from '../types';
+export declare function isCIEnvironment(): boolean;
+export declare function loadNativeConfig(root: string, options: Record<string, any>): FlowstrideConfig;

package/dist/ci/config.js

@@ -0,0 +1,76 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isCIEnvironment = isCIEnvironment;
+exports.loadNativeConfig = loadNativeConfig;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+function isCIEnvironment() {
+    return ['FLOWSTRIDE_NATIVE_CI', 'CI', 'GITHUB_ACTIONS', 'GITLAB_CI', 'CIRCLECI', 'JENKINS_URL', 'FLOWSTRIDE_API_KEY']
+        .some(key => !!process.env[key] && process.env[key] !== 'false' && process.env[key] !== '0');
+}
+function loadNativeConfig(root, options) {
+    const file = node_path_1.default.join(root, options.config || 'flowstride.config.json');
+    let input = {};
+    if (node_fs_1.default.existsSync(file)) {
+        input = JSON.parse(node_fs_1.default.readFileSync(file, 'utf8'));
+        if (!input || typeof input !== 'object' || Array.isArray(input))
+            throw new Error('Flowstride configuration must be an object.');
+    }
+    else if (options.config)
+        throw new Error(`Configuration not found: ${file}`);
+    const config = { ...input, timeout: input.timeout ?? 30000, headless: input.headless ?? true,
+        ci: !!options.ci || isCIEnvironment(), device: options.device ?? input.device ?? 'desktop',
+        artifactsDir: input.artifactsDir ?? 'flowstride-artifacts', testDir: input.testDir ?? 'flows',
+        defaultDialogBehavior: input.defaultDialogBehavior ?? 'dismiss',
+        recordVideo: input.recordVideo ?? true, browserErrors: input.browserErrors ?? 'fail',
+        isCloudSyncActive: options.isCloudSyncActive ?? false, machineToken: options.machineToken ?? null,
+        workspaceId: options.workspaceId ?? null, manifest: options.manifest ?? null };
+    if (config.ci && input.cloudSync !== true)
+        config.isCloudSyncActive = false;
+    if (options.headless || config.ci)
+        config.headless = true;
+    else if (options.headed)
+        config.headless = false;
+    if (process.env.BASE_URL)
+        config.baseUrl = process.env.BASE_URL;
+    if (!Number.isSafeInteger(config.timeout) || config.timeout < 1)
+        throw new Error('timeout must be a positive integer.');
+    if (!['desktop', 'phone', 'landscape'].includes(config.device))
+        throw new Error('device must be desktop, phone, or landscape.');
+    for (const key of ['headless', 'recordVideo', 'bail'])
+        if (config[key] !== undefined && typeof config[key] !== 'boolean')
+            throw new Error(`${key} must be boolean.`);
+    if (!['fail', 'record'].includes(config.browserErrors))
+        throw new Error('browserErrors must be fail or record.');
+    for (const key of ['artifactsDir', 'testDir', 'pluginsDir']) {
+        if (config[key] === undefined)
+            continue;
+        if (typeof config[key] !== 'string' || !config[key].trim())
+            throw new Error(`${key} must be a nonempty path.`);
+        const resolved = node_path_1.default.resolve(root, config[key]);
+        const relative = node_path_1.default.relative(root, resolved);
+        if ((key === 'artifactsDir' && !relative) || relative === '..' || relative.startsWith(`..${node_path_1.default.sep}`) || node_path_1.default.isAbsolute(relative))
+            throw new Error(`${key} must be a directory inside the project.`);
+        config[key] = resolved;
+    }
+    if (config.viewport && (!Number.isSafeInteger(config.viewport.width) || config.viewport.width < 1 || !Number.isSafeInteger(config.viewport.height) || config.viewport.height < 1))
+        throw new Error('viewport requires positive integer width and height.');
+    if (config.webServer) {
+        const server = config.webServer;
+        if (typeof server.command !== 'string' || !server.command.trim() || typeof server.url !== 'string')
+            throw new Error('webServer requires command and url.');
+        const url = new URL(server.url);
+        if (!['http:', 'https:'].includes(url.protocol) || !['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))
+            throw new Error('webServer readiness URL must use local HTTP(S).');
+        if (server.timeout !== undefined && (!Number.isSafeInteger(server.timeout) || server.timeout < 1))
+            throw new Error('webServer.timeout must be positive.');
+        server.cwd = node_path_1.default.resolve(root, server.cwd || '.');
+        const relative = node_path_1.default.relative(root, server.cwd);
+        if (relative === '..' || relative.startsWith(`..${node_path_1.default.sep}`) || node_path_1.default.isAbsolute(relative))
+            throw new Error('webServer.cwd must be inside the project.');
+    }
+    return config;
+}

package/dist/ci/deadline.d.ts

@@ -0,0 +1,2 @@
+/** Bound asynchronous plugin work while observing late rejections safely. */
+export declare function withDeadline<T>(operation: Promise<T> | T, timeout: number): Promise<T>;

package/dist/ci/deadline.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withDeadline = withDeadline;
+/** Bound asynchronous plugin work while observing late rejections safely. */
+async function withDeadline(operation, timeout) {
+    let timer;
+    try {
+        return await Promise.race([Promise.resolve(operation), new Promise((_resolve, reject) => {
+                timer = setTimeout(() => reject(new Error(`Flowstride step exceeded its ${timeout}ms timeout.`)), timeout);
+            })]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}

package/dist/ci/init.d.ts

@@ -0,0 +1 @@
+export declare function initCI(provider: string): void;

package/dist/ci/init.js

@@ -0,0 +1,21 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+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) {
+    if (provider !== 'github')
+        throw new Error('Supported provider: github.');
+    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' });
+    console.log(`Created ${file}. Commit it when ready. This template uses the project-locked Flowstride installation.`);
+}

package/dist/ci/runtime.d.ts

@@ -0,0 +1,19 @@
+import type { FlowstrideConfig } from '../types';
+export interface NativeRunResult {
+    protocol: 1;
+    engine: string;
+    status: 'passed' | 'failed' | 'interrupted';
+    duration: number;
+    artifactsDir: string;
+    files: string[];
+    steps: any[];
+    errors: string[];
+    metrics: {
+        total: number;
+        passed: number;
+        failed: number;
+        skipped: number;
+        incomplete: number;
+    };
+}
+export declare function runNativeCI(worker: any, orchestrator: any, target: string, config: FlowstrideConfig, engine: string): Promise<NativeRunResult>;