plum-e2e 1.3.1 → 1.3.3

package/CLAUDE.md

@@ -5,7 +5,7 @@
 - **Frontend**: SvelteKit 5, port 5173. ESM, no TypeScript.
 - **Backend**: Express + Socket.io, port 3001. CommonJS (`require`/`module.exports`).
 - **Database**: PostgreSQL via Prisma ORM (`backend/services/prisma.js`).
-- **Infrastructure**: Docker Compose. `docker-compose.yml` (standard), `docker-compose.node.yml` (multi-node).
+- **Infrastructure**: Docker Compose (`docker-compose.yml`) for the server stack. Runner nodes run as a bare `PLUM_MODE=node` Node process (started by `plum node start` / the dev `manage-runners` script), not via Docker.
 
 ---
 

package/README.md

@@ -16,7 +16,7 @@
 ## Requirements
 
 - [Node.js](https://nodejs.org) v18 or higher
-- [Docker](https://www.docker.com) — required for `plum server start` and `plum node start`
+- [Docker](https://www.docker.com) — required for `plum server start` (the web UI stack). Runner nodes (`plum node start`) run as a plain Node process and **do not need Docker**.
 
 ---
 
@@ -103,10 +103,34 @@ or the shorthand:
 plum start
 ```
 
-Once running, open **http://localhost:5173** in your browser.
+The first time you run it, Plum asks a few questions (press Enter to accept the default shown in parentheses):
+
+| Prompt                 | Default                   | What it sets                                                            |
+| ---------------------- | ------------------------- | ----------------------------------------------------------------------- |
+| **App URL (BASE_URL)** | from your `.env`          | The URL Playwright opens at the start of every test                     |
+| **Headless?**          | `No`                      | Whether browsers run hidden                                             |
+| **Backend port**       | `3001`                    | Host port for the API                                                   |
+| **Frontend (UI) port** | `5173`                    | Host port for the web UI                                                |
+| **Primary public URL** | `http://<your-ip>:<port>` | The address you give runner nodes (see [Runner Setup](#4-runner-setup)) |
+
+Your answers are saved to `.plum-server.json`, so the next `plum server start` reuses them without asking. When it finishes, open the UI at the frontend port it prints (default **http://localhost:5173**).
 
 > Docker must be running before you use this command. Plum builds and starts the backend, database, and UI automatically.
 
+**Skip the prompts** by passing flags (handy for CI):
+
+```bash
+plum server start --base-url https://your-app.com --headless true --backend-port 3001 --frontend-port 5173
+```
+
+### Change settings later
+
+```bash
+plum server reconfig
+```
+
+Re-asks every question and saves your answers **without** starting the stack. Run `plum server start` afterwards to apply them.
+
 ### Stop
 
 ```bash
@@ -270,31 +294,69 @@ plum run-test --browser firefox          # run in a specific browser
 
 ## 4. Runner Setup
 
-Runners are additional machines that can execute tests in parallel alongside the primary server. This lets you distribute a large test suite across multiple nodes.
+Runners are additional machines that execute tests in parallel alongside the primary server, letting you distribute a large suite across many nodes. A node runs as a plain Node process — **no Docker required**.
 
-### Add a local runner node
+### Start a runner node
 
 On the machine that will act as a runner, navigate to your Plum project and run:
 
 ```bash
-plum node start --token your-secret-token
+plum node start
 ```
 
-| Flag      | Description                                                                     |
-| --------- | ------------------------------------------------------------------------------- |
-| `--token` | A secret token the primary server must send to authenticate. Keep this private. |
+Plum asks a few questions and then **registers the node with your server automatically** — you don't need to add anything in the UI by hand:
+
+| Prompt             | Default                   | What it sets                                                         |
+| ------------------ | ------------------------- | -------------------------------------------------------------------- |
+| **Primary URL**    | last used                 | The server this node registers with (e.g. `http://192.168.1.5:3001`) |
+| **Local port**     | `3001`                    | The port this node process listens on                                |
+| **Advertised URL** | `http://<your-ip>:<port>` | The address the **server** uses to reach this node                   |
+| **Runner name**    | `node-<random>`           | The name shown in the UI                                             |
+| **Browser**        | `chromium`                | Default browser for this node                                        |
+| **Auth token**     | auto-generated            | Shared secret; press Enter to keep the generated one                 |
 
-> The runner starts a Docker container on port `3001` by default. Make sure Docker is running.
+When it registers, Plum prints a details card with the assigned **id**, **token**, and **url**, then boots the node (Ctrl+C to stop). Settings are saved to `.plum-node.json`, so re-running reuses them and never creates a duplicate.
 
-### Register the runner in the UI
+**Skip the prompts** with flags (handy for CI or scripted nodes):
 
-Once the node is running:
+```bash
+plum node start --primary http://192.168.1.5:3001 --port 3001 --name ci-node-1
+```
+
+| Flag               | Description                                                                              |
+| ------------------ | ---------------------------------------------------------------------------------------- |
+| `--primary <url>`  | Server to auto-register with. Omit to only print the details for manual entry.           |
+| `--url <url>`      | Address the server calls back. Defaults to `<lan-ip>:<port>`; pass a domain to override. |
+| `--port <n>`       | Local HTTP port the node listens on (default `3001`).                                    |
+| `--token <secret>` | Auth token. Auto-generated and saved if omitted.                                         |
+| `--name <name>`    | Runner name shown in the UI.                                                             |
+| `--browser <name>` | `chromium` (default), `firefox`, or `webkit`.                                            |
+
+#### Nodes behind a domain or reverse proxy
+
+`--url` is the address the **server** calls back and is used exactly as given, while `--port` is the local port the node listens on. So a node behind an HTTPS reverse proxy is:
+
+```bash
+plum node start --primary https://plum.example.com --url https://node1.example.com --port 3001
+```
+
+The server reaches the node at `https://node1.example.com`; the proxy forwards to the node on port `3001`. The advertised `--url` must be reachable from the server.
+
+### Change settings later
+
+```bash
+plum node reconfig
+```
+
+Re-asks every question, re-registers with the primary, and prints the updated card — **without** starting the node. Run `plum node start` afterwards to launch it.
+
+### Register manually (fallback)
+
+If you run `plum node start` without a reachable `--primary`, Plum prints the node's **name, url, and token** instead. Add it by hand:
 
 1. Open the Plum UI at **http://localhost:5173**
 2. Go to **Settings → Runners**
-3. Click **Add Runner** and enter the node's URL, token, and a name
-
-The runner will appear in the UI and can be selected when triggering tests.
+3. Click **Add Runner** and paste the node's URL, token, and name
 
 ### Stop a runner node
 
@@ -302,22 +364,26 @@ The runner will appear in the UI and can be selected when triggering tests.
 plum node stop
 ```
 
+Stops the node started from the current folder.
+
 ---
 
 ## Command Reference
 
-| Command                       | Description                                              |
-| ----------------------------- | -------------------------------------------------------- |
-| `plum init`                   | Initialize a new project in the current folder           |
-| `plum server start`           | Start the full UI stack via Docker (alias: `plum start`) |
-| `plum server stop`            | Stop the server and preserve data (alias: `plum stop`)   |
-| `plum run-test`               | Run all tests locally without Docker                     |
-| `plum run-test @tag`          | Run tests matching a tag                                 |
-| `plum run-test --parallel N`  | Run tests across N parallel workers                      |
-| `plum run-test --browser <b>` | Run in a specific browser (chromium/firefox/webkit)      |
-| `plum create-step`            | Interactively scaffold a new step definition             |
-| `plum node start --token <t>` | Start a runner node on this machine                      |
-| `plum node stop`              | Stop the runner node                                     |
+| Command                       | Description                                                             |
+| ----------------------------- | ----------------------------------------------------------------------- |
+| `plum init`                   | Initialize a new project in the current folder                          |
+| `plum server start`           | Start the full UI stack via Docker, interactively (alias: `plum start`) |
+| `plum server reconfig`        | Re-enter server settings (URL, ports) without starting                  |
+| `plum server stop`            | Stop the server and preserve data (alias: `plum stop`)                  |
+| `plum run-test`               | Run all tests locally without Docker                                    |
+| `plum run-test @tag`          | Run tests matching a tag                                                |
+| `plum run-test --parallel N`  | Run tests across N parallel workers                                     |
+| `plum run-test --browser <b>` | Run in a specific browser (chromium/firefox/webkit)                     |
+| `plum create-step`            | Interactively scaffold a new step definition                            |
+| `plum node start`             | Start a runner node (interactive) and auto-register it with the server  |
+| `plum node reconfig`          | Re-enter node settings + re-register, without starting                  |
+| `plum node stop`              | Stop the runner node started from this folder                           |
 
 ---
 
@@ -379,6 +445,14 @@ npm run create-test
 
 Interactive prompt that creates a new `.feature` file, page object, and step definition file from a template — ready for you to implement.
 
+**Manage runner nodes:**
+
+```bash
+npm run manage-runners
+```
+
+One interactive menu to **add** a new runner (registers it with the primary and optionally starts it), and to **start / stop / restart / ping** the local node processes it manages. In dev the primary runs in Docker and nodes run as bare host processes, reached via `host.docker.internal`. PIDs are tracked in `.runners.local.json` and logs go to `backend/logs/` so you can manage nodes across terminal sessions.
+
 ### Test file locations
 
 ```

package/backend/app.js

@@ -28,20 +28,17 @@ app.use(express.json());
 app.use('/screenshots', express.static(SCREENSHOTS_DIR));
 
 // Routes
-const testRoutes = require('./routes/tests.routes');
-const reportRoutes = require('./routes/reports.routes');
-const cronRoutes = require('./routes/cron.routes');
-const settingsRoutes = require('./routes/settings.routes');
-const backupRoutes = require('./routes/backup.routes');
-const runnerRoutes = require('./routes/runners.routes');
 const nodeRoutes = require('./routes/node.routes');
-
-app.use('/tests', testRoutes);
-app.use('/reports', reportRoutes);
-app.use('/cron-jobs', cronRoutes);
-app.use('/settings', settingsRoutes);
-app.use('/backup', backupRoutes);
-app.use('/runners', runnerRoutes);
 app.use('/api', nodeRoutes);
 
+// Primary-mode routes — skipped when running as a runner node (no DB available)
+if (process.env.PLUM_MODE !== 'node') {
+	app.use('/tests', require('./routes/tests.routes'));
+	app.use('/reports', require('./routes/reports.routes'));
+	app.use('/cron-jobs', require('./routes/cron.routes'));
+	app.use('/settings', require('./routes/settings.routes'));
+	app.use('/backup', require('./routes/backup.routes'));
+	app.use('/runners', require('./routes/runners.routes'));
+}
+
 module.exports = app;

package/backend/config/scripts/run-tests.js

@@ -16,6 +16,8 @@
  */
 
 const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
 const pc = require('picocolors');
 
 const parallelIdx = process.argv.indexOf('--parallel');
@@ -25,28 +27,68 @@ const runners = parallel || process.env.REPORT_RUNNERS || '1';
 const tag = process.env.TAG || process.argv.slice(2).find((a) => a.startsWith('@'));
 const browser = process.env.BROWSER || 'chromium';
 
+const reportFile = path.resolve(process.cwd(), 'reports', 'cucumber_report.json');
+
+// Wipe any previous report so a crashed/empty run can never return stale results.
+try {
+	fs.rmSync(reportFile, { force: true });
+} catch {}
+
 let testExitCode = 0;
 
 try {
 	const testsRoot = (process.env.TESTS_ROOT || 'tests').replace(/\\/g, '/');
 
+	// Dispatched tests run from an external dir (e.g. a temp dir on a node) that has
+	// no node_modules of its own — point Node at the backend's modules so imports
+	// like 'playwright' and '@cucumber/cucumber' resolve.
+	const nodeModulesPath = path.resolve(__dirname, '..', '..', 'node_modules');
+
 	const baseCommand = [
 		'npx',
 		'cross-env',
 		`BROWSER=${browser}`,
 		'TS_NODE_TRANSPILE_ONLY=true',
 		'cucumber-js',
-		`${testsRoot}/features/**/*.feature`,
-		'--require-module',
-		'ts-node/register',
-		'--require',
-		`${testsRoot}/utils/hooks.ts`,
-		'--require',
-		`${testsRoot}/step_definitions/**/*.ts`,
-		'--format',
-		'json:reports/cucumber_report.json'
+		`${testsRoot}/features/**/*.feature`
 	];
 
+	// A dispatched run executes test files in a temp dir on a runner node. The node's
+	// own working directory ships a cucumber.json whose `require` globs point at the
+	// node's *local* tests/ — and cucumber merges config-file `require` additively with
+	// the CLI ones, so every step would match two definitions (local + dispatched) and
+	// run as "ambiguous": never executing, reporting zero duration. Point cucumber at a
+	// self-contained config inside the dispatched dir so the node's own cucumber.json is
+	// skipped entirely (an explicit --config disables auto-discovery of the cwd file).
+	if (process.env.TESTS_ROOT) {
+		const testsRootAbs = path.resolve(testsRoot);
+		const configPath = path.join(testsRootAbs, 'cucumber.json');
+		fs.writeFileSync(
+			configPath,
+			JSON.stringify({
+				default: {
+					requireModule: ['ts-node/register'],
+					require: [
+						`${testsRootAbs}/utils/hooks.ts`.replace(/\\/g, '/'),
+						`${testsRootAbs}/step_definitions/**/*.ts`.replace(/\\/g, '/')
+					]
+				}
+			})
+		);
+		baseCommand.push('--config', path.relative(process.cwd(), configPath).replace(/\\/g, '/'));
+	} else {
+		baseCommand.push(
+			'--require-module',
+			'ts-node/register',
+			'--require',
+			`${testsRoot}/utils/hooks.ts`,
+			'--require',
+			`${testsRoot}/step_definitions/**/*.ts`
+		);
+	}
+
+	baseCommand.push('--format', 'json:reports/cucumber_report.json');
+
 	if (tag) {
 		baseCommand.push('--tags', `"${tag}"`);
 	}
@@ -56,7 +98,15 @@ try {
 	}
 
 	const cucumberCommand = baseCommand.join(' ');
-	execSync(cucumberCommand, { stdio: 'inherit' });
+	execSync(cucumberCommand, {
+		stdio: 'inherit',
+		env: {
+			...process.env,
+			NODE_PATH: process.env.NODE_PATH
+				? `${nodeModulesPath}${path.delimiter}${process.env.NODE_PATH}`
+				: nodeModulesPath
+		}
+	});
 } catch (error) {
 	// Cucumber exits non-zero when scenarios fail — preserve it so callers see the real result.
 	testExitCode = error.status ?? 1;

package/backend/lib/nodeRegister.js

@@ -0,0 +1,101 @@
+/*
+ * This file is part of Plum.
+ *
+ * Plum is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Plum is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with Plum. If not, see https://www.gnu.org/licenses/.
+ */
+
+/**
+ * Helpers for the operator-facing `plum node` flow: generate a node auth token,
+ * guess a reachable address, persist the node's identity, and self-register the
+ * node with a primary Plum server.
+ *
+ * Uses only Node builtins (os/crypto/fetch) so it runs before backend deps are
+ * installed and can be imported from the published `bin/plum.js`.
+ */
+
+const os = require('os');
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const CONFIG_FILENAME = '.plum-node.json';
+
+function generateToken() {
+	return crypto.randomBytes(24).toString('hex');
+}
+
+/** First non-internal IPv4 address, or 'localhost' if none is found. */
+function detectLanIp() {
+	for (const addrs of Object.values(os.networkInterfaces())) {
+		for (const addr of addrs ?? []) {
+			if (addr.family === 'IPv4' && !addr.internal) return addr.address;
+		}
+	}
+	return 'localhost';
+}
+
+function configPath(dir) {
+	return path.join(dir, CONFIG_FILENAME);
+}
+
+function loadNodeConfig(dir) {
+	try {
+		return JSON.parse(fs.readFileSync(configPath(dir), 'utf8'));
+	} catch {
+		return {};
+	}
+}
+
+function saveNodeConfig(dir, cfg) {
+	fs.writeFileSync(configPath(dir), JSON.stringify(cfg, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * Registers the node with the primary, reusing an existing runner whose name+url
+ * match instead of creating a duplicate.
+ *
+ * @returns {Promise<{ id: string, reused: boolean }>}
+ * @throws {Error} when the primary is unreachable or rejects the request
+ */
+async function registerWithPrimary({ primary, name, url, token, browser }) {
+	const base = primary.replace(/\/$/, '');
+
+	let existing = null;
+	const listRes = await fetch(`${base}/runners`, { signal: AbortSignal.timeout(10000) });
+	if (!listRes.ok) throw new Error(`primary returned HTTP ${listRes.status} listing runners`);
+	const { runners = [] } = await listRes.json();
+	existing = runners.find((r) => r.name === name && r.url === url) ?? null;
+	if (existing) return { id: existing.id, reused: true };
+
+	const res = await fetch(`${base}/runners`, {
+		method: 'POST',
+		headers: { 'Content-Type': 'application/json' },
+		body: JSON.stringify({ name, url, token, browser }),
+		signal: AbortSignal.timeout(10000)
+	});
+	const body = await res.json().catch(() => ({}));
+	if (!res.ok || body.error) {
+		throw new Error(body.error || `primary returned HTTP ${res.status}`);
+	}
+	return { id: body.runner.id, reused: false };
+}
+
+module.exports = {
+	CONFIG_FILENAME,
+	generateToken,
+	detectLanIp,
+	loadNodeConfig,
+	saveNodeConfig,
+	registerWithPrimary
+};

package/backend/lib/runnerProcess.js

@@ -0,0 +1,180 @@
+/*
+ * This file is part of Plum.
+ *
+ * Plum is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Plum is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with Plum. If not, see https://www.gnu.org/licenses/.
+ */
+
+/**
+ * Lifecycle helpers for local node-runner processes.
+ *
+ * A runner is registered in the primary DB, but the actual worker is an
+ * independent `PLUM_MODE=node` process. This module starts those processes
+ * detached (so they outlive the launching terminal) and tracks their PIDs in a
+ * small JSON registry so a later CLI invocation can stop or restart them.
+ *
+ * Only runners whose URL points at this machine can be controlled here.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawn, execSync } = require('child_process');
+
+const BACKEND_DIR = path.resolve(__dirname, '..');
+const SERVER_PATH = path.join(BACKEND_DIR, 'server.js');
+const REGISTRY_PATH = path.join(BACKEND_DIR, '.runners.local.json');
+const LOGS_DIR = path.join(BACKEND_DIR, 'logs');
+
+const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '::1', 'host.docker.internal']);
+
+function loadRegistry() {
+	try {
+		return JSON.parse(fs.readFileSync(REGISTRY_PATH, 'utf8'));
+	} catch {
+		return {};
+	}
+}
+
+function saveRegistry(registry) {
+	fs.writeFileSync(REGISTRY_PATH, JSON.stringify(registry, null, 2), 'utf8');
+}
+
+// Signal 0 performs the OS-level permission/existence check without actually
+// delivering a signal — the portable way to ask "is this pid alive?".
+function isAlive(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function isLocalUrl(url) {
+	try {
+		return LOCAL_HOSTS.has(new URL(url).hostname);
+	} catch {
+		return false;
+	}
+}
+
+function parsePort(url) {
+	try {
+		return new URL(url).port || '3001';
+	} catch {
+		return '3001';
+	}
+}
+
+/** Drops registry entries whose process has died and persists the result. */
+function pruneDead(registry = loadRegistry()) {
+	let changed = false;
+	for (const [id, entry] of Object.entries(registry)) {
+		if (!entry?.pid || !isAlive(entry.pid)) {
+			delete registry[id];
+			changed = true;
+		}
+	}
+	if (changed) saveRegistry(registry);
+	return registry;
+}
+
+/** 'running' if this manager owns a live process for the runner, else 'stopped'. */
+function statusOf(id, registry = loadRegistry()) {
+	const entry = registry[id];
+	return entry?.pid && isAlive(entry.pid) ? 'running' : 'stopped';
+}
+
+/**
+ * Ensures a local node can actually run tests: backend dependencies must be
+ * installed and the Playwright browser binaries present. A node with neither
+ * starts fine but every scenario fails at the browser-launch hook. Idempotent —
+ * npm install is skipped when node_modules already exists, and `playwright
+ * install` no-ops when the browser is already downloaded.
+ *
+ * npm/npx are .cmd shims on Windows, so these must run through a shell.
+ *
+ * stdin is left as 'ignore' (not inherited): these installers only need to
+ * print progress, and letting them touch stdin corrupts the raw-mode state of
+ * an interactive prompt running in the same terminal (the caller's menu would
+ * wedge after the install finishes).
+ */
+function prepareEnv(browser) {
+	const stdio = ['ignore', 'inherit', 'inherit'];
+	if (!fs.existsSync(path.join(BACKEND_DIR, 'node_modules'))) {
+		execSync('npm install', { cwd: BACKEND_DIR, stdio, shell: true });
+	}
+	const target = browser && browser !== 'all' ? ` ${browser}` : '';
+	execSync(`npx playwright install${target}`, { cwd: BACKEND_DIR, stdio, shell: true });
+}
+
+/**
+ * Spawns a detached node-mode server for the given runner and records its pid.
+ * Returns the registry entry.
+ */
+function startNode({ id, port, token }) {
+	fs.mkdirSync(LOGS_DIR, { recursive: true });
+	const logFile = path.join(LOGS_DIR, `runner-${id}.log`);
+	const out = fs.openSync(logFile, 'a');
+
+	const child = spawn(process.execPath, [SERVER_PATH], {
+		cwd: BACKEND_DIR,
+		env: { ...process.env, NODE_TOKEN: token, PLUM_MODE: 'node', PORT: String(port) },
+		detached: true,
+		stdio: ['ignore', out, out],
+		windowsHide: true
+	});
+	child.unref();
+	fs.closeSync(out);
+
+	const registry = loadRegistry();
+	const entry = { pid: child.pid, port: String(port), logFile, startedAt: Date.now() };
+	registry[id] = entry;
+	saveRegistry(registry);
+	return entry;
+}
+
+/**
+ * Stops the managed process for a runner. Returns true if a live process was
+ * signalled, false if nothing was running.
+ */
+function stopNode(id) {
+	const registry = loadRegistry();
+	const entry = registry[id];
+	let signalled = false;
+	if (entry?.pid && isAlive(entry.pid)) {
+		try {
+			process.kill(entry.pid, 'SIGTERM');
+			signalled = true;
+		} catch {}
+	}
+	delete registry[id];
+	saveRegistry(registry);
+	return signalled;
+}
+
+module.exports = {
+	BACKEND_DIR,
+	LOGS_DIR,
+	REGISTRY_PATH,
+	loadRegistry,
+	saveRegistry,
+	isAlive,
+	isLocalUrl,
+	parsePort,
+	pruneDead,
+	statusOf,
+	prepareEnv,
+	startNode,
+	stopNode
+};