@nouhouari/conductor-e2e 0.0.0-stage → 0.1.8

package/CHANGELOG.md

@@ -0,0 +1,228 @@
+# Changelog
+
+All notable changes to this project will be documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Fixed
+
+- **`release-java.yml` no longer fails after a successful Central publish** — bumped `central-publishing-maven-plugin` 0.7.0 → 0.11.0. 0.7.0 could not parse the `warnings` field the Central Portal now returns while polling deployment status, so the job failed even though `conductor-java 0.2.0` was published.
+
+## [conductor-e2e 0.1.8] — 2026-10-02
+
+### Fixed
+
+- **npmjs.org publish actually targets npmjs.org** — the second `setup-node` step in `release.yml` and `release-mcp.yml` now sets `scope: '@nouhouari'`. Without it, the `@nouhouari:registry=https://npm.pkg.github.com/` line written by the GitHub Packages step survived and overrode `--registry`, so the "Publish to npmjs.org" step re-published to GitHub Packages with the npm token and failed with E401. `conductor-e2e` 0.1.7 and `conductor-mcp` 0.2.1/0.2.2 therefore never reached npmjs.org; 0.1.8 and 0.2.3 are the first versions there.
+
+## [conductor-java 0.2.0] — 2026-10-02
+
+### Changed
+
+- **Published to Maven Central under a new groupId** — the Java port is now `io.github.nouhouari.conductor:conductor-core` (was `com.nouhouari.conductor`, GitHub Packages only). Consumers no longer need a `<repositories>` entry or a `read:packages` token. Java package names (`com.nouhouari.conductor.*`) are unchanged.
+- **`release-java.yml` publishes to Maven Central** — on `java-v*` tags it verifies the tag matches `java/pom.xml` (and refuses `-SNAPSHOT`), builds and tests `conductor-core`, attaches its jars to a GitHub Release, and runs `mvn -P release deploy`. Needs the `MAVEN_CENTRAL_USERNAME`, `MAVEN_CENTRAL_PASSWORD`, `MAVEN_GPG_PRIVATE_KEY` and `MAVEN_GPG_PASSPHRASE` repository secrets.
+- `java/pom.xml` gained the metadata Central requires (url, license, developers, scm) and a `release` profile: sources + javadoc jars, GPG signing, and `central-publishing-maven-plugin`. The GitHub Packages `<distributionManagement>` was removed.
+
+### Added
+
+- **CI coverage for the Java port** — `ci.yml` gained a `java` job (temurin JDK 21) that builds and unit-tests `conductor-core`, compiles `conductor-example`'s step definitions and page objects, and runs a Cucumber JVM `--dry-run` over `example/features` with the real glue so undefined/ambiguous steps fail the build. The example's suites need real browsers/devices and are never executed on a hosted runner.
+- `java/README.md` gained a "CI & Releasing" section.
+
+## [conductor-mcp 0.2.3] — 2026-10-02
+
+### Changed
+
+- `init_project` pins `@nouhouari/conductor-e2e` `^0.1.8`, the first version published to npmjs.org.
+- `bin` path normalised to `dist/cli.js` (npm was auto-correcting `./dist/cli.js` on publish).
+
+- **Java projects resolve `conductor-core` from Maven Central** — `init_project` with `language: "java"` now generates a `pom.xml` depending on `io.github.nouhouari.conductor:conductor-core:0.2.0`, with no GitHub Packages `<repositories>` block or `~/.m2/settings.xml` token step.
+- **Docs: npm install** — `mcp/README.md` now installs `@nouhouari/conductor-mcp` from the public npm registry; the GitHub Packages `.npmrc` / `read:packages` setup is no longer required.
+
+## [conductor-e2e 0.1.7] — 2026-10-01
+
+### Changed
+
+- **Release workflow publishes to npmjs.org** — `release.yml` now publishes `@nouhouari/conductor-e2e` to the public npm registry (via the `NPM_TOKEN` repository secret) in addition to GitHub Packages.
+- **Idempotent release publishes** — publish steps in `release.yml` and `release-mcp.yml` skip versions already present on the target registry, so a partially failed release can be re-run.
+
+## [conductor-mcp 0.2.2] — 2026-10-01
+
+### Changed
+
+- Re-release to publish `@nouhouari/conductor-mcp` to npmjs.org with the idempotent release workflow.
+
+## [conductor-mcp 0.2.1] — 2026-09-04
+
+### Changed
+
+- **Release workflow publishes to npmjs.org** — `release-mcp.yml` now publishes `@nouhouari/conductor-mcp` to the public npm registry (via the `NPM_TOKEN` repository secret) in addition to GitHub Packages, so `npx @nouhouari/conductor-mcp` works without a GitHub Packages `.npmrc`.
+
+- **Docs: GitHub Copilot CLI wire-up for `conductor-mcp`** — `mcp/README.md` and `docs/USER_GUIDE.md` now document the `~/.copilot/mcp-config.json` entry (including the Copilot-specific `"type": "stdio"` and `"tools"` allow-list) alongside the existing Claude Code / Cursor / Continue instructions. The user guide's setup snippet was also corrected to the published package name `@nouhouari/conductor-mcp` and now notes the GitHub Packages `.npmrc` requirement and Java target-project support.
+
+## [conductor-java 0.1.0] — 2026-07-30
+
+First release of the Java port. Published to GitHub Packages as `com.nouhouari.conductor:conductor-core`.
+
+### Added
+
+- **`conductor-core`** — Java/Cucumber-JVM/Playwright port of the framework, developed alongside the TypeScript implementation and driving the *same* Gherkin feature files under `example/features`.
+  - `ConductorWorld` with lazily-instantiated drivers, shared test data, and picocontainer-based injection into step definitions.
+  - Drivers: `WebDriver` (Playwright), `ApiDriver` (Playwright `APIRequestContext`), `MaestroDriver` (Maestro CLI), `JavaFxDriver` (fxagent HTTP API), `FlutterDesktopDriver` (Dart VM service), and the abstract `DatabaseDriver`.
+  - Tag-driven Cucumber-JVM hooks mirroring the TS `@web` / `@mobile` / `@flutter-desktop` / `@database` lifecycle, plus `BasePage`.
+  - YAML `ConfigLoader` with the TS precedence order (`config/default.yml` → `config/local-overrides.yml` → `config/${TEST_ENV}.yml` → environment variables) and the same env-var names.
+- **`conductor-example`** (not published) — ported step definitions and page objects, plus one JUnit 5 `@Suite` class per platform tag, the Java equivalent of `example/cucumber.js`'s named profiles.
+
+### Notes
+
+- Validated end-to-end against the real apps, no mocks: `ApiSuiteTest` 8/8, `WebSuiteTest` 9/9, `DesktopSuiteTest` 8/8, `FlutterDesktopSuiteTest` 5/5, `MobileSuiteTest` 8/8, `CrossPlatformSuiteTest` 10/10.
+- `JavaFxDriver` targets `fxagent.jar` v1.0.0 (package `com.hin.fxagent`); waits are polled client-side via `POST /api/v1/elements/query` because the agent's `/elements/wait` cannot express `hidden`/absent states.
+- The `RemoteScenarioFetcher` / `conductor-fetch-features` CLI equivalent is intentionally not ported.
+
+## [conductor-mcp 0.2.0] — 2026-07-30
+
+### Added
+
+- **Java project support** — every project-aware tool now detects whether the working directory belongs to a TypeScript project (`cucumber.js`) or a Java/Maven project (`pom.xml` + Cucumber glue under `src/test/java`) and adapts accordingly. When both are found, the closest project to the working directory wins.
+  - `list_steps` parses `@Given` / `@When` / `@Then` annotations in `.java` sources.
+  - `list_page_objects` parses Java page-object classes and their public methods.
+  - `scaffold_step_def` / `scaffold_page_object` emit Java sources into the resolved glue and page packages.
+  - `dry_run_scenario` runs the Cucumber JVM CLI (`mvn test-compile` → `dependency:build-classpath` → `io.cucumber.core.cli.Main --dry-run`) and reports undefined/ambiguous steps. The CLI is used instead of `mvn test` because JUnit Platform suite `@ConfigurationParameter` values override `-D` system properties.
+  - `get_conductor_api` accepts `language: "java"` and returns the Java API surface for all 8 surfaces.
+- **`init_project` accepts `language: "java"`** — bootstraps a Maven project (pom, JUnit Platform suites, `conductor.yml`, sample feature/step-def/page object, README, `.gitignore`) with configurable `groupId`, `artifactId` and `basePackage`. The `flutter-desktop` platform is now selectable.
+
+### Fixed
+
+- **`wait_for_desktop_element` with `state: "hidden"` (or `disabled`) always errored** — it called the fxagent `POST /api/v1/elements/wait` endpoint, which returns HTTP 500 when nothing matches the selector, making "wait for this to disappear" impossible. The tool now polls `POST /api/v1/elements/query` client-side and reports the last-seen element on timeout. Supported states: `visible`, `hidden`, `enabled`, `disabled`, `exists`.
+
+## [0.1.6] — 2026-06-21
+
+### Added
+
+- **Remote scenario sourcing** — opt-in mode to run Cucumber scenarios fetched from the requ scenario API (`GET /api/scenarios`) instead of the local `features/` folder. The local filesystem flow is unchanged and remains the default.
+  - `fetchScenarios()` / `reconstructFeatureFiles()` (exported from `src/scenarios/RemoteScenarioFetcher.ts`) — fetch scenarios with server-side filters (`project`, `story`, `requirement`, `phase`, `mode`, `tags`, `feature`, `q`, `valid`) and reconstruct them into `.feature` files grouped by feature, recovering feature-level tags, inserting `Background:`, and preserving `Examples:`.
+  - `conductor-fetch-features` bin (`src/scenarios/cli.ts`) — prefetch step that writes the reconstructed features to disk.
+  - New optional `remoteScenarios` config block with `REMOTE_SCENARIOS_*` env-var overrides.
+  - Example: new `remote` cucumber profile and `fetch:remote` / `test:remote` / `test:remote:dry` scripts.
+- **New exported types**: `RemoteScenariosConfig`, `RemoteScenariosFilters`, `RemoteScenarioSummary`, `ReconstructResult`
+
+## [conductor-mcp 0.1.6] — 2026-06-21
+
+### Added
+
+- **`init_project` scaffolds the remote scenario mode (opt-in)** — newly bootstrapped projects now include the `remote` cucumber profile, the `fetch:remote` / `test:remote` / `test:remote:dry` scripts, a commented `REMOTE_SCENARIOS_*` section in `.env.example`, `.remote-features/` in `.gitignore`, and a "Remote Scenarios" section in the README. Local feature files remain the default; the remote profile is inert until `npm run test:remote` is run. No new init parameter or prompt.
+- Bootstrapped projects now depend on `@nouhouari/conductor-e2e@^0.1.6` (provides the `conductor-fetch-features` bin used by `fetch:remote`).
+
+## [0.1.5] — 2026-06-19
+
+### Added
+
+- **`FlutterDesktopDriver`** — 9 new methods expanding the gesture and query API:
+  - `doubleTap(finder, timeoutMs?)` — double-tap gesture (`double_tap` command)
+  - `longPress(finder, timeoutMs?)` — long-press gesture (`long_press` command)
+  - `scroll(finder, dx, dy, durationMs?, frequency?, timeoutMs?)` — scroll a `Scrollable` widget by pixel offset
+  - `scrollIntoView(finder, alignment?, timeoutMs?)` — scroll until a widget is visible; `alignment` 0.0 = top, 0.5 = center, 1.0 = bottom
+  - `clearText(finder, timeoutMs?)` — clear a text field (enables text-entry emulation, taps to focus, sends empty string)
+  - `isVisible(finder, timeoutMs?)` → `boolean` — non-throwing visibility probe; returns `true`/`false` instead of throwing (default probe timeout 500 ms)
+  - `getOffset(finder, offsetType?, timeoutMs?)` → `{ dx, dy }` — get widget screen coordinates (`get_offset` command); `offsetType`: `'topLeft' | 'topRight' | 'bottomLeft' | 'bottomRight' | 'center'`
+  - `waitForCondition(condition, timeoutMs?)` — wait for the app to reach a quiescent state, the Flutter equivalent of `page.waitForLoadState()`; conditions: `'NoPendingFrames'`, `'NoTransientCallbacks'`, `'FirstFrameRasterized'`
+  - `setFrameSync(enabled, timeoutMs?)` — pause/resume Flutter's frame-sync during heavy animations, mirrors disabling CSS transitions in web tests
+- **`FlutterDesktopDriver.connect(vmServiceUrl, timeoutMs?)`** — connect to an already-running Flutter app via its Dart VM service URL, without spawning a process. Enables use on Android (after `adb forward`), iOS (after `iproxy`), and Windows/Linux desktop. Accepts both HTTP (`http://localhost:PORT/TOKEN/`) and WebSocket (`ws://localhost:PORT/TOKEN/ws`) form. `isLaunched` now returns `true` after `connect()` as well as `launch()`.
+- **New exported types**: `OffsetType`, `Offset`, `WaitCondition`
+- **Example step definitions** for all new `FlutterDesktopDriver` methods
+
+## [conductor-mcp 0.1.4] — 2026-06-19
+
+### Added
+
+- **`@nouhouari/conductor-mcp`**: Added `flutter` API surface to the built-in reference (`get_api_reference`, `list_steps` surface filter). Documents the full `FlutterDesktopDriver` public API — lifecycle (`launch`, `connect`, `close`), finders, gesture/interaction methods (`tap`, `doubleTap`, `longPress`, `enterText`, `clearText`, `scroll`, `scrollIntoView`), query methods (`getText`, `getOffset`, `isVisible`), wait methods (`waitFor`, `waitForAbsent`, `waitForCondition`), and advanced utilities (`requestData`, `setFrameSync`, `takeScreenshot`). Also documents the `@flutter-desktop` tag hook and `FlutterDesktopConfig`. Updated the `world` surface to include the `flutterDesktop` and `isFlutterDesktopLaunched` getters.
+
+## [conductor-mcp 0.1.2] — 2026-06-19
+
+### Changed
+
+- **`@nouhouari/conductor-mcp`**: Renamed package from `conductor-mcp` to `@nouhouari/conductor-mcp` and switched registry from npm to GitHub Packages. Consumers should update their install command to `npm install @nouhouari/conductor-mcp` and configure `@nouhouari:registry=https://npm.pkg.github.com` in their `.npmrc`.
+
+## [0.1.3] — 2026-06-19
+
+### Changed
+
+- **`conductor-e2e`**: Renamed package to `@nouhouari/conductor-e2e` and switched registry from npm to GitHub Packages. Update installs to `npm install @nouhouari/conductor-e2e` with `@nouhouari:registry=https://npm.pkg.github.com` in `.npmrc`.
+
+### Added
+
+- **`FlutterDesktopDriver`** — new TypeScript driver that launches a Flutter macOS `.app` binary, connects to its Dart VM service via WebSocket, and issues `ext.flutter.driver` JSON-RPC commands. Public API: `launch()`, `close()`, `tap(finder)`, `enterText(finder, text)`, `getText(finder)`, `waitFor(finder)`, `waitForAbsent(finder)`, `requestData(message)`, `takeScreenshot(name)`.
+- **`requestData()` action dispatch pattern** — primary mechanism for invoking app-side actions (toggle, edit, delete, etc.) via `enableFlutterDriverExtension`. Bypasses `hitTestable()` which never resolves for widgets inside a `ListView` on macOS desktop.
+- **`@flutter-desktop` tag** — new tag-driven hook that logs driver availability before the scenario and takes a failure screenshot + closes the driver after. Lives in `src/hooks/flutterDesktop.hooks.ts`.
+- **`FlutterDesktopConfig`** — new config key controlling the macOS `.app` binary path, Dart VM service port, and screenshot output directory.
+- **`apps/mobile/lib/main_test.dart`** — Flutter test entry point that wires `enableFlutterDriverExtension` to the action registry via JSON dispatch.
+- **`apps/mobile/lib/driver_actions.dart`** — app-side action registry for `toggleTodo`, `editTodoTitle`, `deleteTodo`, `setDialogText`, `refresh`, and `waitUntilLoaded`.
+- **macOS `DebugProfile.entitlements`** — adds `network.client` entitlement so the sandboxed profile build can reach the local API server.
+- **Flutter Desktop example scenarios** — feature file, step definitions, cucumber profile (`flutter-desktop`), and `npm run test:flutter-desktop` script covering home screen, create, toggle, edit, and delete (5 scenarios / 24 steps).
+- **`flutter:build:macos` script** — builds the Flutter macOS app in profile mode with `main_test.dart` as the entry point and injects `API_BASE_URL` and `DISABLE_SWIPE_GESTURES` dart-defines.
+
+### Fixed
+
+- macOS sandbox blocked outgoing HTTP from the profile build (missing `network.client` entitlement).
+- Race condition between `initState _loadTodos()` and test setup — resolved via `waitUntilLoaded` requestData action.
+- Flutter driver touch events do not fire `onPressed` on macOS desktop — bypassed via `requestData`.
+- `TestTextInput` mock `_client` is null on macOS — text is now set directly on the controller.
+
+## [conductor-mcp 0.1.1] — 2026-05-29
+
+### Fixed
+
+- **conductor-mcp**: Quote handling in `scaffold_page_object`, `scaffold_step_def`, and `scaffold_maestro_flow`. Locator selectors like `role=textbox[name='Title']`, step patterns containing apostrophes (`I don't see {string}`), and Maestro values containing `"` were dropped verbatim into single-quoted JS literals or YAML scalars, producing broken source. All three sites now use `JSON.stringify`, which selects the quote style and escapes special characters. Fixes #1.
+
+### Added
+
+- **conductor-mcp@0.1.0** — Model Context Protocol (stdio) server for AI-assisted E2E test authoring. Exposes 12 tools across discovery (list steps, page objects, flows, features), scaffolding (bootstrap new projects, create features/steps/pages/flows), and validation (dry-run scenarios). Lets Claude Code, Cursor, and Continue users bootstrap a Conductor project or add tests without leaving their editor. Versioned independently on `mcp-v*` tag prefix.
+- **conductor-mcp**: Discovery/scaffolding/validation tools now accept an optional `projectPath` argument so the AI can point the server at a specific Conductor project. When omitted, `resolveProjectContext` now also walks **down** one level through common subdirs (`tests/`, `e2e/`, `e2e-conductor/`, `qa/`, …) — makes the server usable in monorepos where the test project lives below the workspace root.
+- **conductor-mcp**: Bootstrap template `cucumber.js` now includes the `summary` formatter alongside `progress-bar`, so a failing run prints the actual error instead of three opaque lines.
+- **conductor-mcp**: Scaffolded `api.steps.ts` now ships a working `POST` example demonstrating the correct `ApiDriver.post(url, body, options?)` signature — preempts users reaching for the Playwright `{ data: ... }` shape.
+- **conductor-mcp**: `scaffold_step_def` now derives parameter identifiers correctly via a three-tier strategy: (1) explicit `paramNames` if supplied, (2) **TypeScript AST walk** of the body — parses with `ts.createSourceFile` and classifies each `Identifier` by its parent node, so property keys in object literals (`{ email: ... }`), member-access names (`account.email`), declarations (`const`/`let`/`var`/parameters/destructuring), labels, and type-position references are all correctly excluded; shorthand property assignments (`{ password }`) are recognized as references; (3) generic `value`/`value2`/`count` as last resort. The earlier regex heuristic mistook property keys for references and dropped identifiers inside template-literal interpolations — both blockers reported in dogfood. `typescript` is now a runtime dep of `conductor-mcp` (added to the published package).
+- **conductor-mcp**: `scaffold_page_object` accepts per-method `body` (in addition to `signature`), so users can ship working method implementations instead of `// TODO` stubs. The renderer no longer adds `async` to methods with non-Promise return types like `Locator`, fixing TS2326 errors on common page-object patterns.
+- **conductor-mcp**: Scaffolded `tsconfig.json` now includes `"DOM"` in `lib`, so step definitions reaching `localStorage` / `Storage` / `Window` via `page.evaluate(...)` type-check correctly.
+- **conductor-mcp**: Scaffolded `cucumber.js` now loads `support/**/*.ts` between the framework hooks and step definitions, and `init_project` scaffolds a `support/timeout.ts` that bumps Cucumber's default 5-second step timeout to 30 seconds — fixes spurious timeouts on real browser/app/HTTP steps.
+- **conductor-mcp**: `init_project.includeSamples` now defaults to `false`. The previous `true` default left placeholder `example.feature` files in every project, surfacing as undefined-scenario noise in `npm test`. Real scenarios should come from `scaffold_feature` / `scaffold_step_def`. Set `includeSamples: true` explicitly only when the user wants a runnable demo.
+- **conductor-mcp**: `init_project` accepts an optional `webBaseUrl` so the user's target URL ends up in `.env.example` directly. The tool description teaches the AI to ask the user for this during setup; if no URL is provided, the project uses `http://localhost:3000` as a safe default.
+- **conductor-mcp**: New tool `remove_samples` — deletes the bootstrap placeholder files (`example.feature`, sample step-defs, `ExamplePage.ts`, sample Maestro flows). Only deletes files whose content is byte-equivalent to the original sample, so user edits are preserved (pass `force: true` to override). Optional `platforms` arg restricts the scope. Empty directories left behind are removed too. Total tool count is now **13**.
+
+## [0.1.2] — 2026-05-29
+
+### Changed
+
+- **`conductor-e2e`**: `loadConfig()` now calls `import 'dotenv/config'` at module load, so a project's `.env` file is read automatically. Previously the scaffold wrote `.env.example` and the README referenced it, but nothing actually loaded it.
+- **`conductor-e2e`**: Default `api.baseUrl` is now `http://localhost:3000` (no `/api` suffix). Step definitions write the full path including any `/api/...` prefix, avoiding the previous `/api/api/...` collision. `.env.example` updated accordingly. **Migration**: if your step defs wrote `${baseUrl}/todos` expecting `/api/` to be baked into baseUrl, prepend `/api/` to those URLs (or set `API_BASE_URL=http://localhost:3000/api` in your `.env` to keep the old behavior).
+
+### Added
+
+- **`conductor-e2e`**: `dotenv` is now a runtime dependency.
+
+## [0.1.1] — 2026-05-29
+
+### Changed
+
+- **Renamed npm package from `conductor` to `conductor-e2e`.** The name `conductor` is taken on the npm registry by an unrelated project; v0.1.0 was tagged but could not be published. v0.1.1 is the first version published to npm. Consumers should `npm install conductor-e2e` and import from `'conductor-e2e'`.
+
+## [0.1.0] — 2026-05-29
+
+### Added
+
+- `ConductorWorld` — Cucumber `World` subclass that lazily instantiates web/api/maestro/desktop/database drivers
+- `WebDriver` — Playwright browser lifecycle (chromium / firefox / webkit), failure screenshots
+- `ApiDriver` — Playwright `APIRequestContext` wrapper, optional cookie sharing with web context
+- `MaestroDriver` — spawns Maestro CLI for Flutter / native mobile testing; live stdout streaming via `DEBUG_MAESTRO`; auto-retry with `--reinstall-driver` on gRPC `UNAVAILABLE`; adb-based screenshots
+- `JavaFxDriver` integration via `javafx-driver@^0.2.2` for desktop JavaFX app automation
+- `DatabaseDriver` — abstract class; users register their own adapter via `world.setDb(adapter)`
+- `BasePage` — Playwright page object base class with `navigate()`, `waitForLoad()`, `getTitle()`
+- Tag-driven hooks: `@web`, `@mobile`, `@desktop`, `@database`, `@cross-platform`
+- Environment config system with overlays (`default` / `dev` / `staging`) and env var overrides (`WEB_BASE_URL`, `API_BASE_URL`, `HEADLESS`, `BROWSER`, `MAESTRO_DEVICE`)
+- Pino-based structured logger
+- `retry()` helper with fixed/exponential backoff
+- Allure reporting integration via `allure-cucumberjs`
+- Example project (`example/`) demonstrating web + API + mobile + desktop + cross-platform scenarios
+- Sample apps under test (`apps/mobile`, `apps/desktop`, `apps/server`)
+- GitHub Actions CI (build, type-check, dry-run scenarios)
+- GitHub Actions release pipeline (tag-triggered, builds, creates GitHub release, publishes to npm with provenance)
+- [User Guide](docs/USER_GUIDE.md) covering project bootstrap, configuration, all platforms, Allure, CI/CD, troubleshooting

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nourreddine Houari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,139 @@
-# Temporary Holding Version
+# Conductor
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/nouhouari/conductor/actions/workflows/ci.yml/badge.svg)](https://github.com/nouhouari/conductor/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/conductor-e2e.svg?label=conductor-e2e)](https://www.npmjs.com/package/conductor-e2e)
+[![npm version](https://img.shields.io/npm/v/conductor-mcp.svg?label=conductor-mcp)](https://www.npmjs.com/package/conductor-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+A multi-platform E2E test framework where **one Cucumber scenario** can drive a **web browser**, a **REST API**, a **Flutter mobile app**, a **Flutter desktop app** (macOS), a **JavaFX desktop app**, and a **database** — all from TypeScript.
+
+```gherkin
+@cross-platform
+Scenario: Todo created on web appears on the Flutter mobile app
+  Given I am on the todo web application
+  When I log in as "user@example.com" with password "secret"
+  And I create a todo titled "E2E Cross Platform"
+  Then the todo "E2E Cross Platform" appears on the web dashboard
+  And the API should return the todo "E2E Cross Platform" with status "open"
+  And the Flutter app should display "E2E Cross Platform" in the todo list
+```
+
+## Stack
+
+| Concern | Technology |
+|---|---|
+| BDD runner | [`@cucumber/cucumber`](https://github.com/cucumber/cucumber-js) v11 |
+| Web automation | [Playwright](https://playwright.dev) |
+| API testing | Playwright `APIRequestContext` |
+| Mobile automation | [Maestro CLI](https://maestro.mobile.dev) (Flutter / native) |
+| Desktop automation (Flutter) | Dart VM service / `ext.flutter.driver` JSON-RPC (macOS) |
+| Desktop automation (JavaFX) | [`javafx-driver`](https://www.npmjs.com/package/javafx-driver) |
+| Database | Plugin interface (bring your own adapter) |
+| Reporting | [Allure](https://allurereport.org/) (`allure-cucumberjs`) |
+
+## Quick Start
+
+```bash
+npm install conductor-e2e
+```
+
+See the [**User Guide**](docs/USER_GUIDE.md) for a step-by-step walkthrough of bootstrapping a new E2E project from scratch.
+
+## Why Conductor?
+
+Most E2E frameworks pick one platform. When your product lives on multiple platforms — a web dashboard, a mobile app, a REST API, a desktop client — you end up with **N parallel test suites** that can't share scenarios, page objects, or data lifecycle.
+
+Conductor unifies them behind a single [`ConductorWorld`](src/world/ConductorWorld.ts):
+
+```typescript
+async function (this: ConductorWorld) {
+  await this.web.launch();                        // Playwright browser
+  await this.page.goto('/login');                 // active page
+  await this.api.post('/todos', { title: ... });  // shared HTTP client
+  await this.maestro.runOrThrow('verify-todo');           // Flutter mobile flow
+  await this.flutterDesktop.tap('addButton');             // Flutter desktop (macOS)
+  await this.fx.locator('#save-btn').click();             // JavaFX desktop
+  await this.db.query('SELECT ...');              // your adapter
+}
+```
+
+Drivers are lazily instantiated. Tag-driven hooks manage their lifecycle:
+
+| Tag | Effect |
+|---|---|
+| `@web` / `@cross-platform` | Launches browser, screenshots failures, closes |
+| `@mobile` / `@cross-platform` | Targets the configured Maestro device |
+| `@flutter-desktop` | Launches Flutter macOS app, screenshots failures, closes |
+| `@desktop` / `@cross-platform` | Launches JavaFX app via agent JAR, closes |
+| `@database` / `@cross-platform` | Connects DB before, disconnects after |
+
+## Project Structure
+
+```
+conductor/
+├── src/                   Framework library
+│   ├── drivers/           WebDriver, ApiDriver, MaestroDriver, DatabaseDriver
+│   ├── hooks/             Tag-driven Before/After hooks
+│   ├── pages/             BasePage to extend
+│   ├── world/             ConductorWorld (Cucumber World subclass)
+│   └── support/           Logger, retry helpers
+├── config/                Environment configs (default/dev/staging)
+├── example/               Working multi-platform example project
+├── apps/                  Sample apps under test
+│   ├── mobile/            Flutter todo app (Android + macOS desktop)
+│   ├── desktop/           JavaFX todo app
+│   └── server/            Express server + web UI + REST API
+├── docs/                  User guide, API docs
+└── docker-compose.yml     PostgreSQL for the example server
+```
+
+## Running the Example
+
+```bash
+# 1. Start PostgreSQL + Express server
+docker compose up -d
+cd apps/server && npm start &
+
+# 2. Run all scenarios except mobile (no device required)
+cd example
+npx cucumber-js --tags 'not @mobile' \
+  --require-module ts-node/register \
+  --require-module tsconfig-paths/register \
+  --require '../src/hooks/index.ts' \
+  --require 'step-definitions/**/*.ts' \
+  --format progress --format allure-cucumberjs/reporter \
+  features/**/*.feature
+
+# 3. Open the Allure report
+npm run report && npm run report:open
+```
+
+For mobile, Flutter Desktop, and JavaFX desktop, see [docs/USER_GUIDE.md](docs/USER_GUIDE.md).
+
+### Flutter Desktop (macOS)
+
+```bash
+# Build the test entry point (from repo root)
+npm run flutter:build:macos
+
+# Run Flutter Desktop scenarios
+cd example
+npm run test:flutter-desktop
+```
+
+The build uses `lib/main_test.dart` as the entry point (which wires `enableFlutterDriverExtension`) and sets `DISABLE_SWIPE_GESTURES=true` to enable the AppBar Add button and the app-side action registry used by `requestData()`.
+
+## Documentation
+
+- [**User Guide**](docs/USER_GUIDE.md) — bootstrap a new E2E project, write scenarios, run tests
+- [**conductor-mcp**](mcp/README.md) — AI-assisted test authoring for GitHub Copilot CLI, Claude Code, Cursor, Continue
+- [**Architecture**](CLAUDE.md) — framework internals (driver lifecycle, hooks, config)
+- [Example project README](example/README.md) — guided tour of the working example
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE) © Nourreddine Houari

package/config/environments/default.ts

@@ -0,0 +1,41 @@
+import type { EnvironmentConfig } from '../types';
+
+export const defaultConfig: EnvironmentConfig = {
+  name: 'default',
+  web: {
+    baseUrl: 'http://localhost:3000',
+    headless: true,
+    browserName: 'chromium'
+  },
+  api: {
+    baseUrl: 'http://localhost:3000',
+    defaultCredentials: { username: 'test@example.com', password: 'password' },
+    timeoutMs: 30000
+  },
+  mobile: {
+    flowsDir: 'flows/mobile',
+    timeoutMs: 120000
+  },
+  database: {
+    enabled: false
+  },
+  desktop: {
+    agentJar: require('path').resolve(__dirname, '../../apps/desktop/agent/fxagent.jar'),
+    defaultTimeoutMs: 10000,
+    screenshotDir: 'reports/screenshots'
+  },
+  flutterDesktop: {
+    appPath: require('path').resolve(
+      __dirname,
+      '../../apps/mobile/build/macos/Build/Products/Profile/todoapp.app/Contents/MacOS/todoapp'
+    ),
+    defaultTimeoutMs: 10000,
+    launchTimeoutMs: 30000,
+    screenshotDir: 'reports/screenshots'
+  },
+  remoteScenarios: {
+    baseUrl: 'http://localhost:8788/api',
+    outputDir: '.remote-features',
+    filters: {}
+  }
+};

package/config/environments/dev.ts

@@ -0,0 +1,16 @@
+import type { EnvironmentConfig } from '../types';
+
+export const devConfig: Partial<EnvironmentConfig> = {
+  name: 'dev',
+  web: {
+    baseUrl: 'http://localhost:3000',
+    headless: false,
+    browserName: 'chromium',
+    slowMo: 100
+  },
+  api: {
+    baseUrl: 'http://localhost:3000/api',
+    defaultCredentials: { username: 'dev@example.com', password: 'devpassword' },
+    timeoutMs: 60000
+  }
+};

package/config/environments/staging.ts

@@ -0,0 +1,15 @@
+import type { EnvironmentConfig } from '../types';
+
+export const stagingConfig: Partial<EnvironmentConfig> = {
+  name: 'staging',
+  web: {
+    baseUrl: 'https://staging.example.com',
+    headless: true,
+    browserName: 'chromium'
+  },
+  api: {
+    baseUrl: 'https://staging.example.com/api',
+    defaultCredentials: { username: 'staging@example.com', password: 'stagingpassword' },
+    timeoutMs: 45000
+  }
+};

package/config/index.ts

@@ -0,0 +1,70 @@
+import 'dotenv/config';
+
+import { defaultConfig } from './environments/default';
+import type { EnvironmentConfig } from './types';
+
+function loadConfig(): EnvironmentConfig {
+  const env = process.env.TEST_ENV ?? 'default';
+  let base = defaultConfig;
+
+  if (env !== 'default') {
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const envModule = require(`./environments/${env}`);
+      const envConfig = envModule[`${env}Config`] as EnvironmentConfig;
+      base = deepMerge(base, envConfig);
+    } catch {
+      // fall back to default
+    }
+  }
+
+  // env-var overrides
+  if (process.env.WEB_BASE_URL) base.web.baseUrl = process.env.WEB_BASE_URL;
+  if (process.env.API_BASE_URL) base.api.baseUrl = process.env.API_BASE_URL;
+  if (process.env.HEADLESS) base.web.headless = process.env.HEADLESS !== 'false';
+  if (process.env.BROWSER) base.web.browserName = process.env.BROWSER as EnvironmentConfig['web']['browserName'];
+  if (process.env.MAESTRO_DEVICE) base.mobile.deviceId = process.env.MAESTRO_DEVICE;
+  if (process.env.FLUTTER_DESKTOP_APP_PATH && base.flutterDesktop) {
+    base.flutterDesktop.appPath = process.env.FLUTTER_DESKTOP_APP_PATH;
+  }
+  if (process.env.FLUTTER_DESKTOP_VM_PORT && base.flutterDesktop) {
+    base.flutterDesktop.vmServicePort = Number(process.env.FLUTTER_DESKTOP_VM_PORT);
+  }
+
+  if (base.remoteScenarios) {
+    const rs = base.remoteScenarios;
+    if (process.env.REMOTE_SCENARIOS_URL) rs.baseUrl = process.env.REMOTE_SCENARIOS_URL;
+    if (process.env.REMOTE_SCENARIOS_PROJECT) rs.project = process.env.REMOTE_SCENARIOS_PROJECT;
+    if (process.env.REMOTE_SCENARIOS_OUTPUT_DIR) rs.outputDir = process.env.REMOTE_SCENARIOS_OUTPUT_DIR;
+    rs.filters = rs.filters ?? {};
+    if (process.env.REMOTE_SCENARIOS_STORY) rs.filters.story = process.env.REMOTE_SCENARIOS_STORY;
+    if (process.env.REMOTE_SCENARIOS_REQUIREMENT) rs.filters.requirement = process.env.REMOTE_SCENARIOS_REQUIREMENT;
+    if (process.env.REMOTE_SCENARIOS_PHASE) rs.filters.phase = process.env.REMOTE_SCENARIOS_PHASE;
+    if (process.env.REMOTE_SCENARIOS_MODE) {
+      rs.filters.mode = process.env.REMOTE_SCENARIOS_MODE as 'cumulative' | 'strict';
+    }
+    if (process.env.REMOTE_SCENARIOS_TAGS) rs.filters.tags = process.env.REMOTE_SCENARIOS_TAGS;
+    if (process.env.REMOTE_SCENARIOS_FEATURE) rs.filters.feature = process.env.REMOTE_SCENARIOS_FEATURE;
+    if (process.env.REMOTE_SCENARIOS_Q) rs.filters.q = process.env.REMOTE_SCENARIOS_Q;
+    if (process.env.REMOTE_SCENARIOS_VALID) rs.filters.valid = process.env.REMOTE_SCENARIOS_VALID === 'true';
+  }
+
+  return base;
+}
+
+function deepMerge<T>(base: T, override: Partial<T>): T {
+  const result = { ...base };
+  for (const key of Object.keys(override ?? {}) as (keyof T)[]) {
+    const ov = override[key];
+    if (ov !== null && typeof ov === 'object' && !Array.isArray(ov)) {
+      result[key] = deepMerge(result[key] as object, ov as object) as T[typeof key];
+    } else if (ov !== undefined) {
+      result[key] = ov as T[typeof key];
+    }
+  }
+  return result;
+}
+
+export const config = loadConfig();
+export { loadConfig };
+export type { EnvironmentConfig };

package/config/types.ts

@@ -0,0 +1,94 @@
+export interface WebConfig {
+  baseUrl: string;
+  headless: boolean;
+  browserName: 'chromium' | 'firefox' | 'webkit';
+  slowMo?: number;
+  viewport?: { width: number; height: number };
+}
+
+export interface ApiConfig {
+  baseUrl: string;
+  defaultCredentials: { username: string; password: string };
+  timeoutMs?: number;
+}
+
+export interface MobileConfig {
+  deviceId?: string;
+  flowsDir: string;
+  timeoutMs: number;
+  maestroBin?: string;
+}
+
+export interface DatabaseConfig {
+  enabled: boolean;
+}
+
+export interface DesktopConfig {
+  agentJar: string;
+  javaBin?: string;
+  agentPort?: number;
+  agentHost?: string;
+  defaultTimeoutMs?: number;
+  pollIntervalMs?: number;
+  screenshotDir?: string;
+  jvmArgs?: string[];
+}
+
+export interface FlutterDesktopConfig {
+  /** Absolute path to the built executable (.app bundle on macOS, .exe on Windows). */
+  appPath: string;
+  /** Per-action timeout, ms. Default 10_000. */
+  defaultTimeoutMs?: number;
+  /** How long to wait for the VM service URL to appear on stdout. Default 30_000. */
+  launchTimeoutMs?: number;
+  /** Optional fixed VM service port (passed via --vm-service-port=). Default: ephemeral. */
+  vmServicePort?: number;
+  /** Extra CLI args appended after the executable. */
+  extraArgs?: string[];
+  /** Environment variables added to the spawned process. */
+  env?: Record<string, string>;
+  /** Where failure screenshots are written. Default 'reports/screenshots'. */
+  screenshotDir?: string;
+}
+
+export interface RemoteScenariosFilters {
+  /** Story id or comma-separated ids (match any), e.g. "US-007". */
+  story?: string;
+  /** Requirement id or comma-separated ids; resolved via its stories, e.g. "REQ-001". */
+  requirement?: string;
+  /** Phase id; restricts to in-scope scenarios, e.g. "P1". */
+  phase?: string;
+  /** Phase resolution mode. Default 'cumulative'. */
+  mode?: 'cumulative' | 'strict';
+  /** Cucumber tag expression, e.g. "@smoke and not @wip". */
+  tags?: string;
+  /** Exact feature name. */
+  feature?: string;
+  /** Case-insensitive substring over name/feature/content. */
+  q?: string;
+  /** Filter by gherkin validity. */
+  valid?: boolean;
+}
+
+export interface RemoteScenariosConfig {
+  /** Base URL of the requ scenario API, e.g. "http://localhost:8788/api". */
+  baseUrl: string;
+  /** Project slug (required when the API has >1 project loaded). */
+  project?: string;
+  /** Server-side filters passed to GET /api/scenarios. */
+  filters?: RemoteScenariosFilters;
+  /** Directory where reconstructed .feature files are written. Default '.remote-features'. */
+  outputDir: string;
+}
+
+export interface EnvironmentConfig {
+  name: string;
+  web: WebConfig;
+  api: ApiConfig;
+  mobile: MobileConfig;
+  database: DatabaseConfig;
+  desktop?: DesktopConfig;
+  flutterDesktop?: FlutterDesktopConfig;
+  /** Optional: source cucumber scenarios from the requ scenario API instead of local files. */
+  remoteScenarios?: RemoteScenariosConfig;
+}

package/dist/config/environments/default.d.ts

@@ -0,0 +1,3 @@
+import type { EnvironmentConfig } from '../types';
+export declare const defaultConfig: EnvironmentConfig;
+//# sourceMappingURL=default.d.ts.map

package/dist/config/environments/default.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"default.d.ts","sourceRoot":"","sources":["../../../config/environments/default.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAElD,eAAO,MAAM,aAAa,EAAE,iBAsC3B,CAAC"}