plum-e2e 1.2.3 → 1.3.0

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');
@@ -161,35 +162,31 @@ switch (command) {
 		// Scaffold plum.plugins.json for user-managed dependencies
 		scaffoldPluginsFile();
 
-		// Create .vscode/settings.json and install Cucumber extension — only if VS Code is available
+		// Always create .vscode/settings.json for Cucumber extension config
 		{
-			let vscodeAvailable = false;
+			const vscodeSettingsPath = path.join(process.cwd(), '.vscode', 'settings.json');
+			if (!fs.existsSync(vscodeSettingsPath)) {
+				fs.mkdirSync(path.dirname(vscodeSettingsPath), { recursive: true });
+				fs.writeFileSync(
+					vscodeSettingsPath,
+					JSON.stringify(
+						{
+							'cucumber.glue': ['tests/step_definitions/**/*.ts'],
+							'cucumber.features': ['tests/features/**/*.feature']
+						},
+						null,
+						2
+					) + '\n',
+					'utf8'
+				);
+				console.log('✅ .vscode/settings.json created for Cucumber extension.\n');
+			} else {
+				console.log('⚠️  .vscode/settings.json already exists. Skipping.\n');
+			}
+
+			// Install extension via CLI only when the code command is available
 			try {
 				execSync('code --version', { stdio: 'ignore' });
-				vscodeAvailable = true;
-			} catch {}
-
-			if (vscodeAvailable) {
-				const vscodeSettingsPath = path.join(process.cwd(), '.vscode', 'settings.json');
-				if (!fs.existsSync(vscodeSettingsPath)) {
-					fs.mkdirSync(path.dirname(vscodeSettingsPath), { recursive: true });
-					fs.writeFileSync(
-						vscodeSettingsPath,
-						JSON.stringify(
-							{
-								'cucumber.glue': ['tests/step_definitions/**/*.ts'],
-								'cucumber.features': ['tests/features/**/*.feature']
-							},
-							null,
-							2
-						) + '\n',
-						'utf8'
-					);
-					console.log('✅ .vscode/settings.json created for Cucumber extension.\n');
-				} else {
-					console.log('⚠️  .vscode/settings.json already exists. Skipping.\n');
-				}
-
 				try {
 					execSync('code --install-extension cucumberopen.cucumber-official', { stdio: 'inherit' });
 					console.log('✅ Cucumber VS Code extension installed.\n');
@@ -198,8 +195,43 @@ switch (command) {
 						'⚠️  Could not install VS Code extension automatically. Install manually: cucumberopen.cucumber-official\n'
 					);
 				}
+			} catch {
+				console.log(
+					'ℹ️  Install the Cucumber VS Code extension manually: cucumberopen.cucumber-official\n'
+				);
+			}
+		}
+
+		// Scaffold tsconfig.json so VS Code resolves Plum's types without a local node_modules
+		{
+			const tsconfigPath = path.join(process.cwd(), 'tsconfig.json');
+			if (!fs.existsSync(tsconfigPath)) {
+				const backendModules = path.join(plumRoot, 'backend', 'node_modules').replace(/\\/g, '/');
+				const tsconfig = {
+					compilerOptions: {
+						target: 'ES2020',
+						module: 'CommonJS',
+						moduleResolution: 'node',
+						esModuleInterop: true,
+						strict: false,
+						skipLibCheck: true,
+						baseUrl: '.',
+						paths: {
+							playwright: [`${backendModules}/playwright`],
+							'@playwright/test': [`${backendModules}/@playwright/test`],
+							'@cucumber/cucumber': [`${backendModules}/@cucumber/cucumber`],
+							dotenv: [`${backendModules}/dotenv`],
+							chai: [`${backendModules}/chai`],
+							'chai-soft-assert': [`${backendModules}/chai-soft-assert`]
+						},
+						typeRoots: [`${backendModules}/@types`]
+					},
+					include: ['tests/**/*.ts']
+				};
+				fs.writeFileSync(tsconfigPath, JSON.stringify(tsconfig, null, 2) + '\n', 'utf8');
+				console.log('✅ tsconfig.json created for IDE type resolution.\n');
 			} else {
-				console.log('ℹ️  VS Code not detected — skipping .vscode setup.\n');
+				console.log('⚠️  tsconfig.json already exists. Skipping.\n');
 			}
 		}
 
@@ -212,52 +244,90 @@ 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 dev',
+					'   ```',
+					'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 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 dev @test-login-1   # run a single scenario',
+					'plum dev @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');
 			}
@@ -277,6 +347,18 @@ switch (command) {
 		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');
 
@@ -403,9 +485,67 @@ 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}`, {
+		execSync(`node "${createStepScript}"`, {
 			cwd: process.cwd(),
 			stdio: 'inherit',
 			env: {
@@ -419,10 +559,14 @@ 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('  dev                  Run tests locally without Docker');
+		console.log('  create-step          Interactively scaffold a new step definition');
 		console.log('\n--------------------------------------\n');
 }

package/docker-compose.node.yml

@@ -0,0 +1,59 @@
+#
+# 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/.
+#
+
+# Runner node — backend + postgres only, no frontend UI.
+# Start with: plum node start --token <secret> --primary http://primary:3001
+
+services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_DB: plum
+      POSTGRES_USER: plum
+      POSTGRES_PASSWORD: plum
+    volumes:
+      - node_postgres_data:/var/lib/postgresql/data
+    networks:
+      - node-network
+    healthcheck:
+      test: ['CMD-SHELL', 'pg_isready -U plum']
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+  backend:
+    build: ./backend
+    ports:
+      - '3001:3001'
+    environment:
+      DATABASE_URL: 'postgresql://plum:plum@postgres:5432/plum'
+      PLUM_MODE: 'node'
+    volumes:
+      - ./backend/reports:/app/reports
+      - ./backend/tests:/app/tests:rw
+    depends_on:
+      postgres:
+        condition: service_healthy
+    networks:
+      - node-network
+
+networks:
+  node-network:
+    driver: bridge
+
+volumes:
+  node_postgres_data:

package/docker-compose.yml

@@ -38,6 +38,8 @@ services:
       - '3001:3001'
     environment:
       DATABASE_URL: 'postgresql://plum:plum@postgres:5432/plum'
+    extra_hosts:
+      - 'host.docker.internal:host-gateway'
     volumes:
       - ./backend/reports:/app/reports
       - ./backend/tests:/app/tests:rw

package/frontend/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "plum-frontend",
 	"private": true,
-	"version": "1.2.1",
+	"version": "1.3.0",
 	"type": "module",
 	"scripts": {
 		"dev": "vite dev",
@@ -14,10 +14,7 @@
 		"@sveltejs/adapter-node": "^5.5.4",
 		"@sveltejs/kit": "^2.16.0",
 		"@sveltejs/vite-plugin-svelte": "^5.0.0",
-		"autoprefixer": "^10.4.20",
-		"postcss": "^8.5.1",
 		"svelte": "^5.0.0",
-		"tailwindcss": "^3.4.17",
 		"vite": "^6.0.0"
 	},
 	"dependencies": {

package/frontend/src/app.css

@@ -14,257 +14,23 @@ 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/.
 */
-
-@tailwind base;
-@tailwind components;
-@tailwind utilities;
-
-/* ── Design tokens ─────────────────────────────────────────────────────── */
-
-:root {
-	--bg: #fdfcfb;
-	--bg-subtle: #f7f6f4;
-	--bg-elevated: #ffffff;
-	--border: #e9e5df;
-	--text: #18160f;
-	--text-muted: #9c9185;
-	--accent: #5c1b87;
-	--accent-soft: #f3eaff;
-	--pass: #16a34a;
-	--pass-soft: #dcfce7;
-	--fail: #dc2626;
-	--fail-soft: #fee2e2;
-	--warn: #d97706;
-	--warn-soft: #fef3c7;
-	--terminal-bg: #0d0c08;
-	--terminal-text: #d6d0c8;
-
-	--font-display: 'Playfair Display', Georgia, serif;
-	--font-body: 'DM Sans', system-ui, -apple-system, sans-serif;
-
-	--ease-out: cubic-bezier(0.16, 1, 0.3, 1);
-	--duration-fast: 140ms;
-	--duration-base: 240ms;
-	--duration-slow: 400ms;
-
-	--radius-sm: 6px;
-	--radius-md: 10px;
-	--radius-lg: 16px;
-}
-
-[data-theme='dark'] {
-	--bg: #101009;
-	--bg-subtle: #1a1910;
-	--bg-elevated: #201f14;
-	--border: #2e2c1e;
-	--text: #f0ede6;
-	--text-muted: #706a5e;
-	--accent: #d0a5f5;
-	--accent-soft: #1b0d30;
-	--pass: #22c55e;
-	--pass-soft: #0d2118;
-	--fail: #f87171;
-	--fail-soft: #2d1010;
-	--warn: #fbbf24;
-	--warn-soft: #2a1f06;
-	--terminal-bg: #080807;
-	--terminal-text: #cbc5bd;
-}
-
-/* ── Reset ──────────────────────────────────────────────────────────────── */
-
-*,
-*::before,
-*::after {
-	box-sizing: border-box;
-	margin: 0;
-	padding: 0;
-}
-
-html {
-	scroll-behavior: smooth;
-}
-
-body {
-	font-family: var(--font-body);
-	font-weight: 300;
-	font-size: 1rem;
-	line-height: 1.65;
-	background-color: var(--bg);
-	background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='200' height='200'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.65' numOctaves='3' stitchTiles='stitch'/%3E%3CfeColorMatrix type='saturate' values='0'/%3E%3C/filter%3E%3Crect width='200' height='200' filter='url(%23n)' opacity='0.07'/%3E%3C/svg%3E");
-	background-size: 200px 200px;
-	color: var(--text);
-	transition:
-		background-color var(--duration-base) var(--ease-out),
-		color var(--duration-base) var(--ease-out);
-	-webkit-font-smoothing: antialiased;
-}
-
-h1 {
-	font-family: var(--font-display);
-	font-weight: 400;
-	line-height: 1.1;
-	letter-spacing: -0.015em;
-	color: var(--text);
-}
-
-h2,
-h3 {
-	font-family: var(--font-display);
-	font-weight: 400;
-	line-height: 1.2;
-	color: var(--text);
-}
-
-a {
-	color: inherit;
-	text-decoration: none;
-}
-
-button {
-	font-family: var(--font-body);
-}
-
-/* ── Global form styles ─────────────────────────────────────────────────── */
-
-.field {
-	display: flex;
-	flex-direction: column;
-	gap: 0.375rem;
-}
-
-.field-label {
-	display: flex;
-	justify-content: space-between;
-	font-size: 0.8125rem;
-	font-weight: 400;
-	color: var(--text-muted);
-}
-
-.field-hint {
-	font-size: 0.75rem;
-	color: var(--text-muted);
-}
-
-.field-input {
-	width: 100%;
-	padding: 0.6rem 0.875rem;
-	border: 1px solid var(--border);
-	border-radius: var(--radius-md);
-	background: var(--bg-subtle);
-	color: var(--text);
-	font-family: var(--font-body);
-	font-size: 0.875rem;
-	font-weight: 300;
-	outline: none;
-	transition:
-		border-color var(--duration-fast),
-		box-shadow var(--duration-fast);
-	appearance: none;
-}
-
-.field-input:focus {
-	border-color: var(--accent);
-	box-shadow: 0 0 0 3px var(--accent-soft);
-}
-
-.field-input:disabled {
-	opacity: 0.5;
-	cursor: not-allowed;
-}
-
-.field-input::placeholder {
-	color: var(--text-muted);
-}
-
-/* ── Global table ───────────────────────────────────────────────────────── */
-
-.data-table {
-	width: 100%;
-	border-collapse: collapse;
-	font-size: 0.875rem;
-}
-
-.data-table th {
-	text-align: left;
-	padding: 0.5rem 1rem;
-	font-family: var(--font-body);
-	font-weight: 500;
-	font-size: 0.7rem;
-	letter-spacing: 0.07em;
-	text-transform: uppercase;
-	color: var(--text-muted);
-	border-bottom: 1px solid var(--border);
-}
-
-.data-table td {
-	padding: 0.875rem 1rem;
-	border-bottom: 1px solid var(--border);
-	color: var(--text);
-	vertical-align: middle;
-}
-
-.data-table tbody tr:last-child td {
-	border-bottom: none;
-}
-
-/* ── Card ───────────────────────────────────────────────────────────────── */
-
-.card {
-	background: var(--bg-elevated);
-	border: 1px solid var(--border);
-	border-radius: var(--radius-lg);
-	padding: 1.5rem;
-	transition:
-		background var(--duration-base) var(--ease-out),
-		border-color var(--duration-base) var(--ease-out);
-}
-
-.card-title {
-	font-family: var(--font-display);
-	font-size: 1.25rem;
-	font-weight: 400;
-	color: var(--text);
-	margin-bottom: 0.25rem;
-}
-
-.card-subtitle {
-	font-size: 0.8125rem;
-	color: var(--text-muted);
-	margin-bottom: 1.25rem;
-}
-
-/* ── Alert ──────────────────────────────────────────────────────────────── */
-
-.alert {
-	display: flex;
-	align-items: center;
-	gap: 0.625rem;
-	padding: 0.75rem 1rem;
-	border-radius: var(--radius-md);
-	font-size: 0.875rem;
-	font-weight: 400;
-}
-
-.alert-success {
-	background: var(--pass-soft);
-	color: var(--pass);
-}
-
-.alert-error {
-	background: var(--fail-soft);
-	color: var(--fail);
-}
-
-/* ── Animations ─────────────────────────────────────────────────────────── */
-
-@keyframes fadeUp {
-	from {
-		opacity: 0;
-		transform: translateY(10px);
-	}
-	to {
-		opacity: 1;
-		transform: translateY(0);
-	}
-}
+/*
+ * 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/.
+ */
+
+@import '$lib/styles/tokens.css';
+@import '$lib/styles/reset.css';
+@import '$lib/styles/global.css';