plum-e2e 1.1.1 → 1.2.1

package/backend/services/cronService.js

@@ -15,113 +15,103 @@
  * along with Plum. If not, see https://www.gnu.org/licenses/.
  */
 
-const fs = require('fs');
-const path = require('path');
 const cron = require('node-cron');
 const { spawn } = require('child_process');
+const prisma = require('./prisma');
 
-const CRON_JOBS_FILE = path.join(__dirname, '../config/cron-jobs.json');
-let cronJobs = {};
+const scheduledJobs = {};
+let _io = null;
 
-const loadCronJobs = () => {
-	if (fs.existsSync(CRON_JOBS_FILE)) {
-		cronJobs = JSON.parse(fs.readFileSync(CRON_JOBS_FILE, 'utf8'));
+const setSocketIO = (io) => {
+	_io = io;
+};
 
-		// Schedule all loaded cron jobs and store only necessary data in memory
-		Object.keys(cronJobs).forEach((taskName) => {
-			const { cronExpression, tags } = cronJobs[taskName];
-			const scheduledCronJob = cron.schedule(cronExpression, () => {
-				console.log(`Running new task: ${taskName}`);
+function scheduleJob(taskName, cronExpression, tags, workers) {
+	if (scheduledJobs[taskName]) {
+		scheduledJobs[taskName].stop();
+		delete scheduledJobs[taskName];
+	}
 
-				const task = spawn('npm', ['run', 'test'], {
-					env: { ...process.env, TAG: tags, TRIGGER: taskName }
-				});
+	scheduledJobs[taskName] = cron.schedule(cronExpression, () => {
+		console.log(`Running scheduled task: ${taskName}`);
+		if (_io) _io.emit('cron-start', { taskName });
 
-				task.stdout.on('data', (data) => console.log(data.toString()));
-				task.stderr.on('data', (data) => console.error(data.toString()));
-				task.on('close', (code) => console.log(`Task ${taskName} finished with code ${code}`));
-			});
+		const env = { ...process.env, TAG: tags, TRIGGER: taskName };
+		if (workers && workers > 1) env.PARALLEL = String(workers);
 
-			// Store the reference to the cron job only in memory
-			cronJobs[taskName].cronJob = scheduledCronJob;
+		const task = spawn('npm', ['run', 'test'], { env });
+		task.stdout.on('data', (data) => console.log(data.toString()));
+		task.stderr.on('data', (data) => console.error(data.toString()));
+		task.on('close', (code) => {
+			console.log(`Task ${taskName} finished with code ${code}`);
+			if (_io) _io.emit('cron-done', { taskName, code });
 		});
+	});
+}
+
+const init = async () => {
+	const jobs = await prisma.cronJob.findMany();
+	for (const job of jobs) {
+		scheduleJob(job.taskName, job.cronExpression, job.tags, job.workers);
 	}
+	console.log(`⏰ Scheduled ${jobs.length} cron job(s) from database`);
 };
 
-const saveCronJobs = () => {
-	// Save only cron job data (not the reference to the cron job object) to the file
-	const cronJobsData = Object.keys(cronJobs).reduce((acc, taskName) => {
-		const { cronExpression, tags } = cronJobs[taskName];
-		acc[taskName] = { cronExpression, tags }; // Exclude the cronJob reference
-		return acc;
-	}, {});
-
-	fs.writeFileSync(CRON_JOBS_FILE, JSON.stringify(cronJobsData, null, 2), 'utf8');
+const reload = async () => {
+	for (const name of Object.keys(scheduledJobs)) {
+		scheduledJobs[name].stop();
+		delete scheduledJobs[name];
+	}
+	await init();
 };
 
-const getAllCronJobs = () =>
-	Object.keys(cronJobs).map((taskName) => ({
-		taskName,
-		cronExpression: cronJobs[taskName].cronExpression,
-		tags: cronJobs[taskName].tags
-	}));
+const getAllCronJobs = async () => {
+	return prisma.cronJob.findMany({ orderBy: { createdAt: 'asc' } });
+};
 
-const addCronJob = ({ cronExpression, taskName, tags }) => {
+const addCronJob = async ({ taskName, cronExpression, tags, workers }) => {
 	if (!cronExpression || !taskName || !tags) {
 		return { status: 400, message: 'Missing required parameters' };
 	}
-
-	cronJobs[taskName] = { cronExpression, tags };
-	saveCronJobs();
-	loadCronJobs(); // Re-load and schedule the new cron job
+	const job = await prisma.cronJob.create({
+		data: { taskName, cronExpression, tags, workers: workers ?? 1 }
+	});
+	scheduleJob(job.taskName, job.cronExpression, job.tags, job.workers);
 	return { status: 201, message: `Cron job ${taskName} added` };
 };
 
-const removeCronJob = (taskName) => {
-	if (!cronJobs[taskName]) {
-		return { status: 404, message: `Cron job ${taskName} not found` };
-	}
+const removeCronJob = async (taskName) => {
+	const job = await prisma.cronJob.findUnique({ where: { taskName } });
+	if (!job) return { status: 404, message: `Cron job ${taskName} not found` };
 
-	// Stop the cron job before removing
-	cronJobs[taskName].cronJob.stop();
+	if (scheduledJobs[taskName]) {
+		scheduledJobs[taskName].stop();
+		delete scheduledJobs[taskName];
+	}
 
-	delete cronJobs[taskName];
-	saveCronJobs();
-	loadCronJobs(); // Re-load and re-schedule cron jobs without the removed one
+	await prisma.cronJob.delete({ where: { taskName } });
 	return { status: 200, message: `Cron job ${taskName} deleted` };
 };
 
-const updateCronJob = (taskName, { cronExpression, tags }) => {
-	if (!cronJobs[taskName]) {
-		return { status: 404, message: `Cron job ${taskName} not found` };
-	}
-
-	// Stop the old cron job
-	cronJobs[taskName].cronJob.stop();
-
-	// Update the cron job with new values
-	cronJobs[taskName] = { cronExpression, tags };
-
-	// Reschedule the updated cron job and store the reference
-	const scheduledCronJob = cron.schedule(cronExpression, () => {
-		console.log(`Running updated task: ${taskName}`);
-
-		const task = spawn('npm', ['run', 'test'], {
-			env: { ...process.env, TAG: tags, TRIGGER: taskName }
-		});
+const updateCronJob = async (taskName, { cronExpression, tags, workers }) => {
+	const job = await prisma.cronJob.findUnique({ where: { taskName } });
+	if (!job) return { status: 404, message: `Cron job ${taskName} not found` };
 
-		task.stdout.on('data', (data) => console.log(data.toString()));
-		task.stderr.on('data', (data) => console.error(data.toString()));
-		task.on('close', (code) => console.log(`Task ${taskName} finished with code ${code}`));
+	const updated = await prisma.cronJob.update({
+		where: { taskName },
+		data: { cronExpression, tags, workers: workers ?? 1 }
 	});
 
-	// Store the new cron job reference in memory
-	cronJobs[taskName].cronJob = scheduledCronJob;
-
-	saveCronJobs(); // Save the updated cron jobs to file (excluding cron job references)
+	scheduleJob(updated.taskName, updated.cronExpression, updated.tags, updated.workers);
 	return { status: 200, message: `Cron job ${taskName} updated` };
 };
 
-loadCronJobs(); // Initial load and scheduling of cron jobs
-
-module.exports = { getAllCronJobs, addCronJob, removeCronJob, updateCronJob };
+module.exports = {
+	init,
+	reload,
+	getAllCronJobs,
+	addCronJob,
+	removeCronJob,
+	updateCronJob,
+	setSocketIO
+};

package/backend/{routes/schedules.routes.js → services/prisma.js}

@@ -15,18 +15,8 @@
  * along with Plum. If not, see https://www.gnu.org/licenses/.
  */
 
-const express = require('express');
-const router = express.Router();
-const scheduleService = require('../services/scheduleService');
+const { PrismaClient } = require('@prisma/client');
 
-/* -----------------------------------------------------
- *                    Get Schedules
- *  Description:
- * 		Get all schedules from schedules/
- * ------------------------------------------------------ */
-router.get('/', (req, res) => {
-	const schedules = scheduleService.getAllSchedules();
-	res.json({ schedules });
-});
+const prisma = new PrismaClient();
 
-module.exports = router;
+module.exports = prisma;

package/backend/services/reportService.js

@@ -17,29 +17,36 @@
 
 const fs = require('fs');
 const path = require('path');
+const prisma = require('./prisma');
 
 const REPORTS_DIR = path.join(__dirname, '../reports');
 
-const getAllReports = () => {
-	const files = fs.readdirSync(REPORTS_DIR);
-	const jsonFiles = files.filter(
-		(f) => f.endsWith('.json') && (f.startsWith('PASS_') || f.startsWith('FAIL_'))
-	);
-	return jsonFiles.sort((a, b) => {
-		const at = fs.statSync(path.join(REPORTS_DIR, a)).mtime;
-		const bt = fs.statSync(path.join(REPORTS_DIR, b)).mtime;
-		return bt - at;
-	});
+const getAllReports = async () => {
+	return prisma.report.findMany({ orderBy: { createdAt: 'desc' } });
+};
+
+const getLatestReport = async () => {
+	const report = await prisma.report.findFirst({ orderBy: { createdAt: 'desc' } });
+	return report ? report.fileName : null;
 };
 
-const getLatestReport = () => {
-	const files = getAllReports();
-	return files.length ? files[0] : null;
+const saveReport = async ({ fileName, status, tags, triggerType, runners }) => {
+	let cronJobId = null;
+	const builtInTriggers = ['manual-trigger', 'command-line-trigger', 'undefined'];
+	if (triggerType && !builtInTriggers.includes(triggerType)) {
+		const job = await prisma.cronJob.findUnique({ where: { taskName: triggerType } });
+		if (job) cronJobId = job.id;
+	}
+	return prisma.report.upsert({
+		where: { fileName },
+		create: { fileName, status, tags, triggerType: triggerType || 'undefined', runners, cronJobId },
+		update: {}
+	});
 };
 
 const getReportDetail = (fileName) => {
 	const filePath = path.join(REPORTS_DIR, fileName);
-	if (!filePath.startsWith(REPORTS_DIR)) return null; // path traversal guard
+	if (!filePath.startsWith(REPORTS_DIR)) return null;
 	if (!fs.existsSync(filePath)) return null;
 
 	let raw;
@@ -58,11 +65,11 @@ const getReportDetail = (fileName) => {
 			const failedStepIndex = visibleSteps.findLastIndex((s) => s.result?.status === 'failed');
 
 			const steps = visibleSteps.map((step, index) => ({
-					keyword: step.keyword.trim(),
-					name: step.name ?? '',
-					status: step.result?.status ?? 'pending',
-					duration: Math.round((step.result?.duration ?? 0) / 1_000_000), // ns → ms
-					error: step.result?.error_message ?? null,
+				keyword: step.keyword.trim(),
+				name: step.name ?? '',
+				status: step.result?.status ?? 'pending',
+				duration: Math.round((step.result?.duration ?? 0) / 1_000_000),
+				error: step.result?.error_message ?? null,
 				screenshot:
 					step.embeddings?.find((e) => e.mime_type === 'image/png')?.data ??
 					(index === failedStepIndex ? hookScreenshots[0]?.data : null) ??
@@ -97,4 +104,25 @@ const getReportDetail = (fileName) => {
 	return { features };
 };
 
-module.exports = { getAllReports, getLatestReport, getReportDetail };
+const deleteReport = async (fileName) => {
+	await prisma.report.delete({ where: { fileName } });
+	const filePath = path.join(REPORTS_DIR, fileName);
+	if (fs.existsSync(filePath)) fs.unlinkSync(filePath);
+};
+
+const deleteReports = async (fileNames) => {
+	await prisma.report.deleteMany({ where: { fileName: { in: fileNames } } });
+	for (const fileName of fileNames) {
+		const filePath = path.join(REPORTS_DIR, fileName);
+		if (fs.existsSync(filePath)) fs.unlinkSync(filePath);
+	}
+};
+
+module.exports = {
+	getAllReports,
+	getLatestReport,
+	saveReport,
+	getReportDetail,
+	deleteReport,
+	deleteReports
+};

package/backend/services/settingsService.js

@@ -0,0 +1,36 @@
+/*
+ * 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 prisma = require('./prisma');
+
+const getProject = async () => {
+	let project = await prisma.project.findUnique({ where: { id: 1 } });
+	if (!project) {
+		project = await prisma.project.create({ data: { id: 1, name: '', logoUrl: '' } });
+	}
+	return project;
+};
+
+const updateProject = async ({ name, logoUrl }) => {
+	return prisma.project.upsert({
+		where: { id: 1 },
+		create: { id: 1, name: name ?? '', logoUrl: logoUrl ?? '' },
+		update: { name: name ?? '', logoUrl: logoUrl ?? '' }
+	});
+};
+
+module.exports = { getProject, updateProject };

package/bin/plum.js

@@ -18,6 +18,7 @@
 
 import { execSync } from 'child_process';
 import fs from 'fs';
+import os from 'os';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import fse from 'fs-extra';
@@ -55,6 +56,70 @@ IS_HEADLESS=false
 	console.log('✅ .env file created with default values.\n');
 }
 
+// Scaffold plum.plugins.json if it doesn't exist yet
+function scaffoldPluginsFile() {
+	const pluginsPath = path.join(process.cwd(), 'plum.plugins.json');
+	if (fs.existsSync(pluginsPath)) {
+		console.log('⚠️  plum.plugins.json already exists. Skipping.\n');
+		return;
+	}
+	const content = {
+		'//': 'Add npm packages your tests depend on. Plum installs them automatically before each run.',
+		'// example':
+			'To add a package: put its name and version under "dependencies", e.g. "@faker-js/faker": "^9.0.0"',
+		dependencies: {}
+	};
+	fs.writeFileSync(pluginsPath, JSON.stringify(content, null, 2) + '\n', 'utf8');
+	console.log('✅ plum.plugins.json created. Add npm packages here to extend your tests.\n');
+}
+
+// Install user plugins listed in plum.plugins.json into the backend
+function installPlugins() {
+	const pluginsPath = path.join(process.cwd(), 'plum.plugins.json');
+	if (!fs.existsSync(pluginsPath)) return;
+
+	let plugins;
+	try {
+		plugins = JSON.parse(fs.readFileSync(pluginsPath, 'utf8'));
+	} catch {
+		console.log('⚠️  Could not parse plum.plugins.json. Skipping plugin install.\n');
+		return;
+	}
+
+	const deps = plugins.dependencies ?? {};
+	const packages = Object.entries(deps).map(([name, version]) => `${name}@${version}`);
+	if (packages.length === 0) return;
+
+	console.log(`📦 Installing plugins: ${packages.join(', ')}\n`);
+	execSync(`npm install ${packages.join(' ')}`, {
+		cwd: path.join(plumRoot, 'backend'),
+		stdio: 'inherit'
+	});
+}
+
+// Ensure user's .gitignore contains Plum-generated entries
+function ensureGitignore() {
+	const gitignorePath = path.join(process.cwd(), '.gitignore');
+	const plumEntries = ['reports/'];
+	const plumBlock = `\n# Plum (auto-generated)\n${plumEntries.join('\n')}\n`;
+
+	if (!fs.existsSync(gitignorePath)) {
+		fs.writeFileSync(gitignorePath, plumBlock.trimStart(), 'utf8');
+		console.log('✅ .gitignore created with Plum entries.\n');
+		return;
+	}
+
+	const existing = fs.readFileSync(gitignorePath, 'utf8');
+	const missing = plumEntries.filter((e) => !existing.includes(e));
+	if (missing.length === 0) {
+		console.log('⚠️  .gitignore already contains Plum entries. Skipping.\n');
+		return;
+	}
+
+	fs.appendFileSync(gitignorePath, `\n# Plum (auto-generated)\n${missing.join('\n')}\n`);
+	console.log('✅ .gitignore updated with Plum entries.\n');
+}
+
 // Function to copy .env file from root to backend
 function copyEnvFile() {
 	try {
@@ -91,32 +156,112 @@ switch (command) {
 		// Create .env file with default values
 		createEnvFile();
 
-		// Create .vscode/settings.json for Cucumber extension step linkage
-		const vscodeSettingsPath = path.join(process.cwd(), '.vscode', 'settings.json');
-		if (!fs.existsSync(vscodeSettingsPath)) {
-			fs.mkdirSync(path.dirname(vscodeSettingsPath), { recursive: true });
-			const vscodeSettings = JSON.stringify(
-				{
-					'cucumber.glue': ['tests/step_definitions/**/*.ts'],
-					'cucumber.features': ['tests/features/**/*.feature']
-				},
-				null,
-				2
-			);
-			fs.writeFileSync(vscodeSettingsPath, vscodeSettings, 'utf8');
-			console.log('✅ .vscode/settings.json created for Cucumber extension.\n');
-		} else {
-			console.log('⚠️  .vscode/settings.json already exists. Skipping.\n');
+		// Create or update .gitignore with Plum-generated paths
+		ensureGitignore();
+
+		// Scaffold plum.plugins.json for user-managed dependencies
+		scaffoldPluginsFile();
+
+		// Create .vscode/settings.json and install Cucumber extension — only if VS Code is available
+		{
+			let vscodeAvailable = false;
+			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');
+				} catch {
+					console.log(
+						'⚠️  Could not install VS Code extension automatically. Install manually: cucumberopen.cucumber-official\n'
+					);
+				}
+			} else {
+				console.log('ℹ️  VS Code not detected — skipping .vscode setup.\n');
+			}
 		}
 
-		// Install Cucumber VS Code extension
-		try {
-			execSync('code --install-extension cucumberopen.cucumber-official', { stdio: 'inherit' });
-			console.log('✅ Cucumber VS Code extension installed.\n');
-		} catch {
-			console.log(
-				'⚠️  Could not install VS Code extension automatically. Install manually: cucumberopen.cucumber-official\n'
-			);
+		// Create README.md in user's project if one doesn't exist
+		{
+			const userReadmePath = path.join(process.cwd(), 'README.md');
+			if (!fs.existsSync(userReadmePath)) {
+				const readmeContent = [
+					'# My Tests',
+					'',
+					'Powered by [Plum](https://github.com/silverlunah/plum) — Playwright + Cucumber.',
+					'',
+					'## 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 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 |',
+					'',
+					'## Test Structure',
+					'',
+					'```',
+					'tests/',
+					'  features/          — Gherkin .feature files',
+					'  step_definitions/  — TypeScript step implementations',
+					'  pages/             — Page Object Models',
+					'  utils/             — Browser setup, hooks, helpers',
+					'```',
+					'',
+					'Tags are used to filter which tests to run:',
+					'',
+					'```gherkin',
+					'@suite-login',
+					'Feature: Login',
+					'',
+					'  @test-login-1',
+					'  Scenario: User can log in',
+					'    Given I am on the login page',
+					'    ...',
+					'```',
+					'',
+					'```bash',
+					'plum dev @test-login-1   # single scenario',
+					'plum dev @suite-login    # whole suite',
+					'```'
+				].join('\n');
+				fs.writeFileSync(userReadmePath, readmeContent + '\n', 'utf8');
+				console.log('✅ README.md created with command reference.\n');
+			} else {
+				console.log('⚠️  README.md already exists. Skipping.\n');
+			}
 		}
 
 		// Initialize project
@@ -128,7 +273,7 @@ switch (command) {
 		});
 
 		console.log(
-			'🟣  Plum is now ready!\n\n Scaffold test cases are included in the `tests/` folder.\n For more information about Cucumber, visit: https://cucumber.io/\n\n - To start the server, run:\n `plum start` \n\n - If you are developing locally, run:\n `plum dev <@tag/blank if you want to run all tests>`'
+			'🟣  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`'
 		);
 		console.log('--------------------------------------\n');
 		break;
@@ -141,13 +286,32 @@ switch (command) {
 		// Copy .env file from root to backend
 		copyEnvFile();
 
-		// Copy config from package root to user's project dir so Docker can mount it
-		const userConfigPath = path.join(process.cwd(), '.plum', 'config');
+		// Merge user plugins into backend/package.json before Docker build
+		{
+			const userPluginsPath = path.join(process.cwd(), 'plum.plugins.json');
+			if (fs.existsSync(userPluginsPath)) {
+				try {
+					const userPlugins = JSON.parse(fs.readFileSync(userPluginsPath, 'utf8'));
+					const backendPkgPath = path.join(plumRoot, 'backend', 'package.json');
+					const backendPkg = JSON.parse(fs.readFileSync(backendPkgPath, 'utf8'));
+					const pluginDeps = userPlugins.dependencies ?? {};
+					if (Object.keys(pluginDeps).length > 0) {
+						backendPkg.dependencies = { ...backendPkg.dependencies, ...pluginDeps };
+						fs.writeFileSync(backendPkgPath, JSON.stringify(backendPkg, null, '\t') + '\n', 'utf8');
+						console.log(`📦 Merged plugins into backend: ${Object.keys(pluginDeps).join(', ')}\n`);
+					}
+				} catch {
+					console.log('⚠️  Could not read plum.plugins.json. Skipping plugin merge.\n');
+				}
+			}
+		}
+
+		// Copy config to ~/.plum/config so Docker can mount it without polluting the project
+		const userConfigPath = path.join(os.homedir(), '.plum', 'config');
 		fse.copySync(path.join(plumRoot, 'backend', 'config'), userConfigPath);
 
 		// Convert Windows paths to safe format
 		const userTestsAbs = path.resolve(process.cwd(), 'tests').replace(/\\/g, '/');
-		const userModulesAbs = path.resolve(process.cwd(), 'node_modules').replace(/\\/g, '/');
 		const userReportsAbs = path.resolve(process.cwd(), 'reports').replace(/\\/g, '/');
 		const userConfigAbs = userConfigPath.replace(/\\/g, '/');
 
@@ -158,15 +322,14 @@ switch (command) {
 			'    volumes:',
 			`      - "${userReportsAbs}:/app/reports"`,
 			`      - "${userConfigAbs}:/app/config"`,
-			`      - "${userTestsAbs}:/app/tests"`,
-			`      - "${userModulesAbs}:/app/tests/node_modules"`
+			`      - "${userTestsAbs}:/app/tests"`
 		].join('\n');
 
 		fs.writeFileSync(overrideFilePath, overrideYAML + '\n', 'utf8');
 		console.log('✅ docker-compose.override.yml written');
 
-		// Run docker compose
-		execSync('docker compose up', {
+		// Run docker compose (--build picks up any plugin or config changes)
+		execSync('docker compose up --build', {
 			cwd: plumRoot,
 			stdio: 'inherit'
 		});
@@ -204,6 +367,9 @@ switch (command) {
 			stdio: 'inherit'
 		});
 
+		// Install user-defined plugins from plum.plugins.json
+		installPlugins();
+
 		console.log('Running `npx playwright install`...');
 
 		execSync('npx playwright install', {
@@ -232,6 +398,17 @@ switch (command) {
 		break;
 	}
 
+	case 'stop':
+		console.log('--------------------------------------\n');
+		console.log('🛑 Stopping Plum...');
+		execSync('docker compose down', {
+			cwd: plumRoot,
+			stdio: 'inherit'
+		});
+		console.log('✅ Plum stopped. Your data is preserved in the database volume.\n');
+		console.log('--------------------------------------\n');
+		break;
+
 	case 'create-step': {
 		const createStepScript = path.join(plumRoot, 'backend', 'config', 'scripts', 'create-step.mjs');
 		execSync(`node ${createStepScript}`, {
@@ -247,6 +424,11 @@ switch (command) {
 
 	default:
 		console.log('--------------------------------------\n');
-		console.log('Usage: plum <init|start|dev|create-step>');
-		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('\n--------------------------------------\n');
 }