plum-e2e 1.2.4 → 1.3.1

package/backend/services/runnerService.js

@@ -0,0 +1,179 @@
+/*
+ * 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/.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const prisma = require('./prisma');
+
+// ---------------------------------------------------------------------------
+// Runner CRUD
+// ---------------------------------------------------------------------------
+
+const getAll = () => prisma.runner.findMany({ orderBy: { createdAt: 'asc' } });
+
+const create = ({ name, url, token, browser = 'chromium' }) =>
+	prisma.runner.create({ data: { name, url, token, browser } });
+
+const remove = (id) => prisma.runner.delete({ where: { id } });
+
+const update = (id, data) => prisma.runner.update({ where: { id }, data });
+
+const getById = (id) => prisma.runner.findUnique({ where: { id } });
+
+// ---------------------------------------------------------------------------
+// Connectivity
+// ---------------------------------------------------------------------------
+
+async function probe({ url, token }) {
+	const start = Date.now();
+	try {
+		const res = await fetch(`${url}/api/ping`, {
+			method: 'GET',
+			headers: { Authorization: `Bearer ${token}` },
+			signal: AbortSignal.timeout(5000)
+		});
+		return { ok: res.ok, latency: Date.now() - start };
+	} catch (e) {
+		return { ok: false, error: e.message };
+	}
+}
+
+async function ping(id) {
+	const runner = await getById(id);
+	if (!runner) return { ok: false, error: 'Runner not found' };
+	return probe({ url: runner.url, token: runner.token });
+}
+
+// ---------------------------------------------------------------------------
+// Remote execution
+// ---------------------------------------------------------------------------
+
+function collectTestFiles() {
+	const testsDir = path.resolve(process.cwd(), 'tests');
+	const files = {};
+
+	function walk(dir, rel) {
+		for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+			const fullPath = path.join(dir, entry.name);
+			const relPath = rel ? `${rel}/${entry.name}` : entry.name;
+			if (entry.isDirectory()) {
+				walk(fullPath, relPath);
+			} else {
+				files[relPath] = fs.readFileSync(fullPath, 'utf8');
+			}
+		}
+	}
+
+	if (fs.existsSync(testsDir)) walk(testsDir, '');
+	return files;
+}
+
+/**
+ * Fetches the raw cucumber JSON content from a finished remote node job.
+ * Returns the content string, or null on failure.
+ */
+async function fetchReportContent(runner, jobId, onLog) {
+	try {
+		const res = await fetch(`${runner.url}/api/report/${jobId}`, {
+			headers: { Authorization: `Bearer ${runner.token}` },
+			signal: AbortSignal.timeout(15000)
+		});
+		if (!res.ok) {
+			onLog(`[WARN] Could not fetch report from "${runner.name}": HTTP ${res.status}\n`);
+			return null;
+		}
+		const { content } = await res.json();
+		return content ?? null;
+	} catch (e) {
+		onLog(`[WARN] Could not fetch report from "${runner.name}": ${e.message}\n`);
+		return null;
+	}
+}
+
+/**
+ * Dispatches a test job to a remote runner node and polls until it finishes.
+ *
+ * @param {string} runnerId
+ * @param {{ tags: string, browser: string, workers: number }} jobParams
+ * @param {(log: string) => void} onLog   Called with each new log chunk
+ * @param {(exitCode: number, reportContent: string|null) => void} onDone
+ */
+async function dispatchAndPoll(runnerId, { tags, browser, workers }, onLog, onDone) {
+	const runner = await getById(runnerId);
+	if (!runner) {
+		onLog(`[ERROR] Runner ${runnerId} not found\n`);
+		onDone(1, null);
+		return;
+	}
+
+	let jobId;
+	try {
+		const res = await fetch(`${runner.url}/api/execute`, {
+			method: 'POST',
+			headers: {
+				'Content-Type': 'application/json',
+				Authorization: `Bearer ${runner.token}`
+			},
+			body: JSON.stringify({ tags, browser, workers, tests: collectTestFiles() }),
+			signal: AbortSignal.timeout(10000)
+		});
+		if (!res.ok) throw new Error(`HTTP ${res.status}`);
+		jobId = (await res.json()).jobId;
+	} catch (e) {
+		onLog(`[ERROR] Could not reach runner "${runner.name}": ${e.message}\n`);
+		onDone(1, null);
+		return;
+	}
+
+	onLog(`Connected to runner "${runner.name}" — job ${jobId}\n`);
+
+	let logOffset = 0;
+	const poll = setInterval(async () => {
+		try {
+			const res = await fetch(`${runner.url}/api/execute/${jobId}?offset=${logOffset}`, {
+				headers: { Authorization: `Bearer ${runner.token}` },
+				signal: AbortSignal.timeout(8000)
+			});
+			if (!res.ok) return;
+			const body = await res.json();
+
+			if (body.logs) {
+				onLog(body.logs);
+				logOffset += body.logs.length;
+			}
+
+			if (body.status === 'done' || body.status === 'error') {
+				clearInterval(poll);
+				const content = await fetchReportContent(runner, jobId, onLog);
+				onDone(body.exitCode ?? (body.status === 'done' ? 0 : 1), content);
+			}
+		} catch {
+			// transient polling error — keep trying
+		}
+	}, 2500);
+}
+
+module.exports = {
+	getAll,
+	create,
+	remove,
+	update,
+	getById,
+	probe,
+	ping,
+	dispatchAndPoll
+};

package/backend/websockets/socketHandler.js

@@ -16,37 +16,178 @@
  */
 
 const { spawn } = require('child_process');
+const runnerService = require('../services/runnerService');
+const reportService = require('../services/reportService');
+const { TRIGGER_TYPE, BUILT_IN_RUNNER_ID, TRIGGER_REMOTE } = require('../constants/triggers');
+const { getTestIdsForTag, chunkTests, buildTagExpression } = require('../lib/testChunker');
+const { readCucumberReportFile } = require('../lib/reportFilename');
 
 const socketHandler = (io) => {
 	io.on('connection', (socket) => {
 		console.log('WebSocket connection established');
-		socket.on('run-test', (testID, workers) => {
-			const tag = testID ? `${testID}` : '';
-			const runnerCount = Number(workers) > 1 ? Number(workers) : 1;
-			const env = {
-				...process.env,
-				TAG: tag,
-				TRIGGER: 'manual-trigger',
-				REPORT_RUNNERS: String(runnerCount)
-			};
-			if (workers && workers > 1) env.PARALLEL = String(workers);
 
-			const testProcess = spawn('npm', ['run', 'test'], { env, shell: true });
+		// Track processes spawned for this socket connection so we can cancel them
+		const activeProcs = new Set();
 
-			testProcess.stdout.on('data', (data) => {
-				socket.emit('log', data.toString());
-			});
+		socket.on('run-test', async (payload, legacyWorkers) => {
+			let tag, workers, browser, runners;
+			if (typeof payload === 'string') {
+				tag = payload;
+				workers = Number(legacyWorkers) > 1 ? Number(legacyWorkers) : 1;
+				browser = 'chromium';
+				runners = [BUILT_IN_RUNNER_ID];
+			} else {
+				tag = payload.tag ?? '';
+				workers = Number(payload.workers) > 1 ? Number(payload.workers) : 1;
+				browser = payload.browser ?? 'chromium';
+				runners =
+					Array.isArray(payload.runners) && payload.runners.length > 0
+						? payload.runners
+						: [BUILT_IN_RUNNER_ID];
+			}
 
-			testProcess.stderr.on('data', (data) => {
-				socket.emit('log', `[ERROR] ${data.toString()}`);
-			});
+			const isSingleBuiltIn = runners.length === 1 && runners[0] === BUILT_IN_RUNNER_ID;
 
-			testProcess.on('close', (code) => {
-				socket.emit('log', `\nTest finished with code ${code}`);
-				socket.emit('done', code);
-			});
+			if (isSingleBuiltIn) {
+				runBuiltIn(io, socket, activeProcs, tag, workers, browser);
+			} else {
+				runDistributed(io, socket, activeProcs, tag, workers, browser, runners);
+			}
+		});
+
+		socket.on('cancel-test', () => {
+			if (activeProcs.size === 0) return;
+			for (const proc of activeProcs) {
+				try {
+					proc.kill('SIGTERM');
+				} catch {}
+			}
+			activeProcs.clear();
+			socket.emit('log', '\n[CANCELLED] Test run cancelled by user.\n');
+			socket.emit('done', 130);
 		});
 	});
 };
 
+// ---------------------------------------------------------------------------
+// Single built-in runner
+// ---------------------------------------------------------------------------
+
+function runBuiltIn(io, socket, activeProcs, tag, workers, browser) {
+	const env = {
+		...process.env,
+		TAG: tag,
+		TRIGGER: TRIGGER_TYPE.MANUAL,
+		REPORT_RUNNERS: String(workers),
+		BROWSER: browser
+	};
+	if (workers > 1) env.PARALLEL = String(workers);
+
+	const proc = spawn('npm', ['run', 'test'], { env, shell: true });
+	activeProcs.add(proc);
+
+	proc.stdout.on('data', (d) => socket.emit('log', d.toString()));
+	proc.stderr.on('data', (d) => socket.emit('log', `[ERROR] ${d.toString()}`));
+
+	proc.on('close', (code) => {
+		activeProcs.delete(proc);
+		socket.emit('log', `\nTest finished with code ${code}`);
+		socket.emit('done', code);
+		// Notify all connected clients that a new report is available
+		io.emit('report-ready');
+	});
+}
+
+// ---------------------------------------------------------------------------
+// Distributed (multi-runner) path
+// ---------------------------------------------------------------------------
+
+async function runDistributed(io, socket, activeProcs, tag, workers, browser, runnerIds) {
+	const allIds = getTestIdsForTag(tag);
+	const chunks = chunkTests(allIds, runnerIds.length);
+
+	const laneInfos = await Promise.all(
+		runnerIds.map(async (id) => {
+			if (id === BUILT_IN_RUNNER_ID) return { id, name: 'Built-in', dbId: null };
+			const r = await runnerService.getById(id);
+			return { id, name: r?.name ?? id, dbId: r?.id ?? null };
+		})
+	);
+
+	socket.emit(
+		'runner-lanes-init',
+		laneInfos.map((l, i) => ({ id: l.id, name: l.name, testCount: (chunks[i] || []).length }))
+	);
+
+	const total = runnerIds.length;
+	const collectedReports = new Array(total).fill(null);
+	let doneCount = 0;
+	let overallCode = 0;
+
+	function onLaneDone(idx, laneId, code, reportContent) {
+		if (code !== 0) overallCode = code;
+		collectedReports[idx] = reportContent;
+		socket.emit('runner-lane-status', { id: laneId, status: code === 0 ? 'done' : 'error' });
+		doneCount++;
+
+		if (doneCount === total) {
+			socket.emit('log', `\nAll runners finished (exit ${overallCode})`);
+			socket.emit('done', overallCode);
+
+			reportService
+				.saveCombinedReport({
+					reports: collectedReports,
+					runners: laneInfos,
+					overallCode,
+					tag,
+					triggerType: TRIGGER_TYPE.MANUAL,
+					browser
+				})
+				.then(() => io.emit('report-ready'))
+				.catch((e) => console.error('[runner] Failed to save combined report:', e.message));
+		}
+	}
+
+	for (let i = 0; i < runnerIds.length; i++) {
+		const lane = laneInfos[i];
+		const chunkTag = chunks[i]?.length > 0 ? buildTagExpression(chunks[i]) : tag;
+
+		if (lane.id === BUILT_IN_RUNNER_ID) {
+			const env = {
+				...process.env,
+				TAG: chunkTag,
+				TRIGGER: TRIGGER_REMOTE,
+				BROWSER: browser,
+				REPORT_RUNNERS: String(workers),
+				PLUM_MODE: 'node'
+			};
+			if (workers > 1) env.PARALLEL = String(workers);
+
+			const proc = spawn('npm', ['run', 'test'], { env, shell: true });
+			activeProcs.add(proc);
+
+			proc.stdout.on('data', (d) =>
+				socket.emit('runner-lane-log', { id: lane.id, log: d.toString() })
+			);
+			proc.stderr.on('data', (d) =>
+				socket.emit('runner-lane-log', { id: lane.id, log: `[ERROR] ${d.toString()}` })
+			);
+
+			const idx = i;
+			proc.on('close', (code) => {
+				activeProcs.delete(proc);
+				onLaneDone(idx, lane.id, code, readCucumberReportFile());
+			});
+		} else {
+			const idx = i;
+			runnerService.dispatchAndPoll(
+				lane.id,
+				{ tags: chunkTag, browser, workers },
+				(log) => socket.emit('runner-lane-log', { id: lane.id, log }),
+				(code, content) => onLaneDone(idx, lane.id, code, content)
+			);
+		}
+	}
+}
+
 module.exports = socketHandler;

package/bin/plum.js

@@ -25,6 +25,7 @@ import fse from 'fs-extra';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const command = process.argv[2];
+const subcommand = process.argv[3];
 const plumRoot = path.resolve(__dirname, '..');
 const userTestsPath = path.join(process.cwd(), 'tests');
 const scaffoldTestsPath = path.join(plumRoot, 'backend', '_scaffold');
@@ -99,7 +100,7 @@ function installPlugins() {
 // Ensure user's .gitignore contains Plum-generated entries
 function ensureGitignore() {
 	const gitignorePath = path.join(process.cwd(), '.gitignore');
-	const plumEntries = ['reports/'];
+	const plumEntries = ['.env', 'reports/'];
 	const plumBlock = `\n# Plum (auto-generated)\n${plumEntries.join('\n')}\n`;
 
 	if (!fs.existsSync(gitignorePath)) {
@@ -243,52 +244,91 @@ switch (command) {
 					'',
 					'Powered by [Plum](https://github.com/silverlunah/plum) — Playwright + Cucumber.',
 					'',
+					'## Getting Started',
+					'',
+					"Your project is ready. Here's what to do next:",
+					'',
+					"1. **Open `.env`** and set `BASE_URL` to your application's URL.",
+					'2. **Run the example tests** to confirm everything works:',
+					'   ```bash',
+					'   plum run-test',
+					'   ```',
+					'3. **Write your first test** — edit a file in `tests/features/` or generate a step:',
+					'   ```bash',
+					'   plum create-step',
+					'   ```',
+					'4. **Start the full UI** (requires Docker) to trigger tests and view reports in the browser:',
+					'   ```bash',
+					'   plum start',
+					'   ```',
+					'   Then open **http://localhost:5173**.',
+					'',
+					'---',
+					'',
 					'## Commands',
 					'',
 					'| Command | Description |',
-					'|---|---|',
-					'| `plum dev` | Run all tests locally |',
-					'| `plum dev @tag` | Run tests matching a tag |',
-					'| `plum dev --parallel N` | Run tests across N parallel workers |',
-					'| `plum start` | Start the full UI via Docker (`http://localhost:5173`) |',
+					'| --- | --- |',
+					'| `plum run-test` | Run all tests locally |',
+					'| `plum run-test @tag` | Run tests matching a tag |',
+					'| `plum run-test --parallel N` | Run tests across N parallel workers |',
+					'| `plum run-test --browser firefox` | Run in a specific browser (chromium/firefox/webkit) |',
+					'| `plum start` | Start the full UI via Docker |',
+					'| `plum stop` | Stop the server |',
 					'| `plum create-step` | Interactively generate a new step definition |',
 					'',
+					'---',
+					'',
 					'## Configuration',
 					'',
 					'| File | Purpose |',
-					'|---|---|',
-					'| `.env` | Set `BASE_URL` and `IS_HEADLESS` |',
-					'| `plum.plugins.json` | Add extra npm packages for your tests |',
+					'| --- | --- |',
+					'| `.env` | Set `BASE_URL` (your app) and `IS_HEADLESS` (`true`/`false`) |',
+					'| `plum.plugins.json` | Add extra npm packages your tests need |',
+					'',
+					'---',
 					'',
 					'## Test Structure',
 					'',
 					'```',
 					'tests/',
-					'  features/          — Gherkin .feature files',
+					'  features/          — Gherkin .feature files (write your scenarios here)',
 					'  step_definitions/  — TypeScript step implementations',
 					'  pages/             — Page Object Models',
-					'  utils/             — Browser setup, hooks, helpers',
+					'  utils/             — Browser setup, hooks, shared helpers',
 					'```',
 					'',
-					'Tags are used to filter which tests to run:',
+					'Each scenario needs a unique tag so you can run it by itself:',
 					'',
 					'```gherkin',
 					'@suite-login',
 					'Feature: Login',
 					'',
 					'  @test-login-1',
-					'  Scenario: User can log in',
+					'  Scenario: User can log in with valid credentials',
 					'    Given I am on the login page',
-					'    ...',
+					'    When I enter valid credentials',
+					'    Then I should see the dashboard',
 					'```',
 					'',
 					'```bash',
-					'plum dev @test-login-1   # single scenario',
-					'plum dev @suite-login    # whole suite',
-					'```'
+					'plum run-test @test-login-1   # run a single scenario',
+					'plum run-test @suite-login    # run the whole suite',
+					'```',
+					'',
+					'---',
+					'',
+					'## Cucumber & Gherkin Resources',
+					'',
+					'New to Cucumber? These links will get you up to speed quickly:',
+					'',
+					'- [Gherkin syntax reference](https://cucumber.io/docs/gherkin/reference/) — Feature files, Scenarios, Given/When/Then, tags, Scenario Outlines',
+					'- [Step definitions guide](https://cucumber.io/docs/cucumber/step-definitions/) — Connecting Gherkin steps to TypeScript code',
+					'- [Playwright docs](https://playwright.dev/docs/intro) — Browser automation API used inside page objects',
+					'- [Plum documentation](https://github.com/silverlunah/plum) — Full README and reference'
 				].join('\n');
 				fs.writeFileSync(userReadmePath, readmeContent + '\n', 'utf8');
-				console.log('✅ README.md created with command reference.\n');
+				console.log('✅ README.md created with quick-start guide.\n');
 			} else {
 				console.log('⚠️  README.md already exists. Skipping.\n');
 			}
@@ -303,11 +343,23 @@ switch (command) {
 		});
 
 		console.log(
-			'🟣  Plum is now ready!\n\n Scaffold test cases are in `tests/`.\n Add extra npm packages to `plum.plugins.json`.\n\n - Run tests locally:\n   `plum dev` or `plum dev @tag`\n\n - Start the full UI (requires Docker):\n   `plum start`\n\n - Generate a step:\n   `plum create-step`'
+			'🟣  Plum is now ready!\n\n Scaffold test cases are in `tests/`.\n Add extra npm packages to `plum.plugins.json`.\n\n - Run tests locally:\n   `plum run-test` or `plum run-test @tag`\n\n - Start the full UI (requires Docker):\n   `plum start`\n\n - Generate a step:\n   `plum create-step`'
 		);
 		console.log('--------------------------------------\n');
 		break;
 
+	case 'server':
+		if (subcommand === 'stop') {
+			console.log('--------------------------------------\n');
+			console.log('🛑 Stopping Plum server...');
+			execSync('docker compose down', { cwd: plumRoot, stdio: 'inherit' });
+			console.log('✅ Plum server stopped. Your data is preserved.\n');
+			console.log('--------------------------------------\n');
+			break;
+		}
+	// fall through to start for 'plum server start' or 'plum server'
+	// intentional fall-through
+
 	case 'start':
 		console.log('--------------------------------------\n');
 
@@ -361,20 +413,30 @@ switch (command) {
 		console.log('--------------------------------------\n');
 		break;
 
-	case 'dev': {
+	case 'run-test': {
 		console.log('--------------------------------------\n');
-		console.log('🚀 Running Plum in Development Mode...');
+		console.log('🚀 Running tests locally...');
 
 		// Copy .env file from root to backend
 		copyEnvFile();
 
-		const devArgs = process.argv.slice(3);
-		const parallelIdx = devArgs.indexOf('--parallel');
-		const parallelArg = parallelIdx !== -1 ? devArgs[parallelIdx + 1] : null;
-		const tagArg = devArgs.find((a) => a.startsWith('@')) ?? null;
+		const runArgs = process.argv.slice(3);
+		const parallelIdx = runArgs.indexOf('--parallel');
+		const parallelArg = parallelIdx !== -1 ? runArgs[parallelIdx + 1] : null;
+		const browserIdx = runArgs.indexOf('--browser');
+		const browserArg = browserIdx !== -1 ? runArgs[browserIdx + 1] : null;
+		const tagArg = runArgs.find((a) => a.startsWith('@')) ?? null;
 		const userTestsPath = path.resolve(process.cwd(), 'tests');
 		const backendTestsPath = path.join(plumRoot, 'backend', 'tests');
 
+		const validBrowsers = ['chromium', 'firefox', 'webkit'];
+		if (browserArg && !validBrowsers.includes(browserArg)) {
+			console.error(
+				`✗ Invalid browser "${browserArg}". Choose one of: ${validBrowsers.join(', ')}`
+			);
+			process.exit(1);
+		}
+
 		// Copy user tests into backend
 		if (fs.existsSync(userTestsPath)) {
 			console.log('📦 Syncing your tests...\n');
@@ -407,6 +469,7 @@ switch (command) {
 		console.log('Running `npm run test` with:');
 		console.log('TAG =', tagArg ?? '');
 		console.log('PARALLEL =', parallelArg ?? 'off');
+		console.log('BROWSER =', browserArg ?? 'chromium');
 		console.log('TRIGGER =', 'command-line-trigger');
 
 		execSync('npm run test', {
@@ -416,7 +479,8 @@ switch (command) {
 				...process.env,
 				TAG: tagArg ?? '',
 				TRIGGER: 'command-line-trigger',
-				...(parallelArg ? { PARALLEL: parallelArg } : {})
+				...(parallelArg ? { PARALLEL: parallelArg } : {}),
+				...(browserArg ? { BROWSER: browserArg } : {})
 			}
 		});
 		console.log('--------------------------------------\n');
@@ -434,6 +498,64 @@ switch (command) {
 		console.log('--------------------------------------\n');
 		break;
 
+	case 'node': {
+		if (subcommand === 'stop') {
+			console.log('--------------------------------------\n');
+			console.log('🛑 Stopping Plum node...');
+			execSync('docker compose -f docker-compose.node.yml down', {
+				cwd: plumRoot,
+				stdio: 'inherit'
+			});
+			console.log('✅ Plum node stopped.\n');
+			console.log('--------------------------------------\n');
+			break;
+		}
+
+		// 'plum node start' — parse --token and --primary flags
+		const nodeArgs = process.argv.slice(3);
+		const tokenIdx = nodeArgs.indexOf('--token');
+		const nodeToken = tokenIdx !== -1 ? nodeArgs[tokenIdx + 1] : process.env.NODE_TOKEN || '';
+		const primaryIdx = nodeArgs.indexOf('--primary');
+		const primaryUrl = primaryIdx !== -1 ? nodeArgs[primaryIdx + 1] : process.env.PRIMARY_URL || '';
+
+		console.log('--------------------------------------\n');
+		console.log('🚀 Starting Plum node (runner mode)...');
+		if (!nodeToken) {
+			console.log(
+				'⚠️  No --token provided. The node will accept requests without authentication.\n'
+			);
+		}
+
+		// Build override for node mode
+		const userReportsAbs = path.resolve(process.cwd(), 'reports').replace(/\\/g, '/');
+		const nodeOverridePath = path.join(plumRoot, 'docker-compose.node-override.yml');
+
+		const nodeOverride = [
+			'services:',
+			'  backend:',
+			'    volumes:',
+			`      - "${userReportsAbs}:/app/reports"`,
+			'    environment:',
+			`      NODE_TOKEN: "${nodeToken}"`,
+			`      PRIMARY_URL: "${primaryUrl}"`,
+			'      PLUM_MODE: "node"'
+		].join('\n');
+
+		fs.writeFileSync(nodeOverridePath, nodeOverride + '\n', 'utf8');
+
+		copyEnvFile();
+
+		execSync(
+			'docker compose -f docker-compose.node.yml -f docker-compose.node-override.yml up --build',
+			{
+				cwd: plumRoot,
+				stdio: 'inherit'
+			}
+		);
+		console.log('--------------------------------------\n');
+		break;
+	}
+
 	case 'create-step': {
 		const createStepScript = path.join(plumRoot, 'backend', 'config', 'scripts', 'create-step.mjs');
 		execSync(`node "${createStepScript}"`, {
@@ -450,10 +572,17 @@ switch (command) {
 	default:
 		console.log('--------------------------------------\n');
 		console.log('Usage: plum <command>\n');
-		console.log('  init          Set up a new Plum project');
-		console.log('  start         Start the full UI stack via Docker');
-		console.log('  stop          Stop Docker containers (data is preserved)');
-		console.log('  dev           Run tests locally without Docker');
-		console.log('  create-step   Interactively scaffold a new step definition');
+		console.log('  init                 Set up a new Plum project');
+		console.log('  server start         Start the full UI stack via Docker  (alias: plum start)');
+		console.log('  server stop          Stop the server  (alias: plum stop)');
+		console.log('  node start           Start a runner node (no UI, receives remote jobs)');
+		console.log('    --token <secret>   Auth token the primary must send');
+		console.log('    --primary <url>    URL of the primary Plum server');
+		console.log('  node stop            Stop the runner node');
+		console.log('  run-test             Run tests locally without Docker');
+		console.log('    @tag               Run only tests matching a tag');
+		console.log('    --parallel <n>     Run across n parallel workers');
+		console.log('    --browser <name>   chromium | firefox | webkit (default: chromium)');
+		console.log('  create-step          Interactively scaffold a new step definition');
 		console.log('\n--------------------------------------\n');
 }