plum-e2e 2.9.1 → 2.9.3

package/README.md

@@ -79,26 +79,33 @@ Full documentation is available at:
 
 ## Command Reference
 
-| Command                       | Description                                                                                                                                |
-| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| `plum init`                   | Initialize a new project in the current folder                                                                                             |
-| `plum server start`           | Start the full UI stack via Docker                                                                                                         |
-| `plum server restart`         | Rebuild Docker images and restart the server without prompts                                                                               |
-| `plum server stop`            | Stop the server (data preserved)                                                                                                           |
-| `plum server reconfig`        | Re-enter server settings without starting                                                                                                  |
-| `plum update`                 | Update Plum, auto-restart whatever is running (server or node), and re-sync `tests/utils/browser.ts`/`hooks.ts` from the installed version |
-| `plum sync-scaffold`          | Re-sync `tests/utils/browser.ts`/`hooks.ts` from the installed Plum version without a full update (old copies are backed up, never lost)   |
-| `plum node start`             | Set up connectivity, start a runner node, and open the runner menu                                                                         |
-| `plum node restart`           | Stop, refresh dependencies, and restart the runner node                                                                                    |
-| `plum node stop`              | Stop the runner node started from this folder                                                                                              |
-| `plum node reconfig`          | Re-enter node settings and re-register                                                                                                     |
-| `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 `chromium` (default) or `firefox`                                                                                                   |
-| `plum run-test --help`        | Show usage for `run-test`                                                                                                                  |
-| `plum create-step`            | Interactively scaffold a new step definition                                                                                               |
-| `plum manage-runners`         | Open the interactive runner management menu                                                                                                |
+| Command                       | Description                                                                                                                                                |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `plum init`                   | Initialize a new project in the current folder                                                                                                             |
+| `plum server start`           | Start the full UI stack via Docker                                                                                                                         |
+| `plum server restart`         | Rebuild Docker images and restart the server without prompts                                                                                               |
+| `plum server stop`            | Stop the server (data preserved)                                                                                                                           |
+| `plum server reconfig`        | Re-enter server settings without starting                                                                                                                  |
+| `plum update`                 | Update Plum, then restart each registered server/node on this machine (asks before each, in an interactive shell)                                          |
+| `plum sync-scaffold`          | Check `tests/utils/browser.ts`/`hooks.ts` against Plum's recommended starter pattern; reports what's stale but changes nothing (rarely needed — see below) |
+| `plum sync-scaffold --force`  | Overwrite files reported stale by the above (previous version backed up first)                                                                             |
+| `plum node start`             | Set up connectivity, start a runner node, and open the runner menu                                                                                         |
+| `plum node restart`           | Stop, refresh dependencies, and restart the runner node                                                                                                    |
+| `plum node stop`              | Stop the runner node started from this folder                                                                                                              |
+| `plum node reconfig`          | Re-enter node settings and re-register                                                                                                                     |
+| `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 `chromium` (default) or `firefox`                                                                                                                   |
+| `plum run-test --help`        | Show usage for `run-test`                                                                                                                                  |
+| `plum create-step`            | Interactively scaffold a new step definition                                                                                                               |
+| `plum manage-runners`         | Open the interactive runner management menu                                                                                                                |
+
+---
+
+## `tests/utils/plum-modules/`
+
+`tests/utils/browser.ts` and `hooks.ts` are yours — customize them freely, they're never touched automatically. They import Plum's session recording from `tests/utils/plum-modules/`, which is regenerated from the installed Plum version before every run (`plum run-test`, `plum node start`, and every run triggered from the web UI), so recording fixes and features reach existing projects without any update step. Don't edit anything inside `plum-modules/` — it's overwritten on the next run.
 
 ---
 

package/backend/_scaffold/utils/browser.ts

@@ -15,12 +15,11 @@
  * along with Plum. If not, see https://www.gnu.org/licenses/.
  */
 
-// Thin pass-through to Plum's own recording wiring, kept inside the installed
-// Plum package rather than copied here — this file exists so page objects
-// have a stable `page()`/`context()` to import.
-import type { Page, BrowserContext } from 'playwright';
+import type { Page, BrowserContext, Browser } from 'playwright';
+import * as plum from './plum-modules/runtime';
 
-const runtime = require(process.env.PLUM_RUNTIME_PATH as string);
+export const page = (): Page => plum.page();
+export const context = (): BrowserContext => plum.context();
+export const browser = (): Browser => plum.browser();
 
-export const page = (): Page => runtime.page();
-export const context = (): BrowserContext => runtime.context();
+// Add your own page/context helpers below.

package/backend/_scaffold/utils/hooks.ts

@@ -15,9 +15,9 @@
  * along with Plum. If not, see https://www.gnu.org/licenses/.
  */
 
-// Thin pass-through to Plum's own recording wiring, kept inside the installed
-// Plum package rather than copied here.
-require(process.env.PLUM_RUNTIME_PATH as string).registerHooks();
+import * as plum from './plum-modules/runtime';
+
+plum.registerHooks();
 
 // Add your own custom Before/After/BeforeStep hooks below — Cucumber runs
 // every registered hook, so these run alongside Plum's own.

package/backend/_scaffold/utils/plum-modules/README.md

@@ -0,0 +1,24 @@
+# Do not edit this folder
+
+Everything under `plum-modules/` is regenerated from the installed Plum version before every test run — any change you make here is silently overwritten the next time you run `plum run-test`, `plum node start`, or trigger a run from the web UI.
+
+This is what gives you Plum's session recording (rrweb) and reporting hooks. Use it from your own `tests/utils/browser.ts` and `hooks.ts`:
+
+```ts
+import * as plum from './plum-modules/runtime';
+
+export const page = () => plum.page();
+export const context = () => plum.context();
+export const browser = () => plum.browser();
+```
+
+```ts
+import * as plum from './plum-modules/runtime';
+
+plum.registerHooks();
+
+// Add your own Before/After/BeforeStep hooks below — Cucumber runs every
+// registered hook, so yours run alongside Plum's.
+```
+
+If you need something from here that isn't exported, don't copy the file — ask, since it's meant to be extended, not forked.

package/backend/{lib/plumTestRuntime.js → _scaffold/utils/plum-modules/runtime.ts}

@@ -1,20 +1,29 @@
 /*
  * This file is part of Plum.
- * Licensed under the MIT License. See LICENSE file in the project root for details.
+ *
+ * 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/.
  */
 
-// The actual implementation behind tests/utils/browser.ts and hooks.ts.
-// Customer test projects only get a thin pass-through to this module (see
-// backend/_scaffold/utils/) — keeping the real wiring here means every
-// `npm install -g plum-e2e@latest` picks up fixes/changes immediately,
-// without needing to re-sync anything into an existing customer project.
+// DO NOT EDIT — see README.md in this directory. Plum overwrites this whole
+// folder before every run, so any change here is silently discarded.
 
-const fs = require('fs');
-const path = require('path');
-const zlib = require('zlib');
-const dotenv = require('dotenv');
-const { chromium, firefox, webkit } = require('playwright');
-const { Before, After, BeforeStep } = require('@cucumber/cucumber');
+import { chromium, firefox, webkit, Browser, BrowserContext, Page } from 'playwright';
+import { Before, After, BeforeStep, ITestCaseHookParameter } from '@cucumber/cucumber';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as zlib from 'zlib';
+import dotenv from 'dotenv';
 
 dotenv.config();
 
@@ -31,19 +40,29 @@ const RECORD_BUNDLE_PATH = path.join(
 	'record.umd.min.cjs'
 );
 
-let _browser;
-let _context;
-let _page;
+interface TabRecording {
+	tabId: string;
+	tabIndex: number;
+	events: unknown[];
+	openedAt: number;
+	closedAt: number | null;
+	liveFlushedCount: number;
+}
+
+let _browser: Browser;
+let _context: BrowserContext;
+let _page: Page;
 let _liveRRwebCounter = 0;
-let _liveRRwebTimer = null;
-let _tabs = new Map();
+let _liveRRwebTimer: ReturnType<typeof setInterval> | null = null;
+let _tabs: Map<Page, TabRecording> = new Map();
 let _tabCounter = 0;
 let _workerId = 1;
 
-const page = () => _page;
-const context = () => _context;
+export const page = (): Page => _page;
+export const context = (): BrowserContext => _context;
+export const browser = (): Browser => _browser;
 
-function tabIdForIndex(index) {
+function tabIdForIndex(index: number): string {
 	return index === 0 ? 'main' : `tab-${index + 1}`;
 }
 
@@ -52,9 +71,9 @@ function tabIdForIndex(index) {
 // timestamps are a poor proxy for how long it stayed relevant. Real
 // open/close times let the replay UI line multiple tabs up on one timeline
 // without guessing from event gaps.
-function attachRecorder(pg) {
+function attachRecorder(pg: Page): void {
 	const tabIndex = _tabCounter++;
-	const recording = {
+	const recording: TabRecording = {
 		tabId: tabIdForIndex(tabIndex),
 		tabIndex,
 		events: [],
@@ -68,7 +87,7 @@ function attachRecorder(pg) {
 	});
 }
 
-async function setup() {
+export async function setup(): Promise<void> {
 	const isHeadless = process.env.IS_HEADLESS?.toLowerCase() !== 'false';
 	const browserName = (process.env.BROWSER || 'chromium').toLowerCase();
 	const browserType =
@@ -87,7 +106,7 @@ async function setup() {
 	// Context-level exposeBinding/addInitScript apply to every page in the
 	// context automatically — current and future (popups, target=_blank tabs) —
 	// so recording setup never races a new tab's first navigation.
-	await _context.exposeBinding('__plumEmitRRwebEvent', (source, eventJson) => {
+	await _context.exposeBinding('__plumEmitRRwebEvent', (source, eventJson: string) => {
 		const recording = source.page && _tabs.get(source.page);
 		if (!recording) return;
 		try {
@@ -101,11 +120,14 @@ async function setup() {
 		// addInitScript runs in every frame, including hidden ad/tracking iframes.
 		// Recordings are tracked per-Page, so an unguarded sub-frame session would
 		// corrupt the tab's event stream with bogus 0x0 "about:blank" entries.
+		// @ts-ignore
 		if (window.self !== window.top) return;
+		// @ts-ignore
 		if (window.rrwebRecord) {
+			// @ts-ignore
 			window.rrwebRecord.record({
-				emit: (event) => {
-					// exposed by BrowserContext.exposeBinding above
+				emit: (event: unknown) => {
+					// @ts-ignore — exposed by BrowserContext.exposeBinding above
 					window.__plumEmitRRwebEvent(JSON.stringify(event));
 				}
 			});
@@ -124,7 +146,7 @@ async function setup() {
 
 // Sends only what's newly arrived since the last tick, per tab, so the live
 // viewer gets a steady trickle instead of the full buffer growing unbounded.
-function flushLiveRRwebEvents() {
+function flushLiveRRwebEvents(): void {
 	const ssDir = process.env.PLUM_SS_DIR;
 	if (!ssDir) return;
 	for (const recording of _tabs.values()) {
@@ -148,13 +170,17 @@ function flushLiveRRwebEvents() {
 	}
 }
 
-// Injects a labeled rrweb custom event at the current recording timestamp so
-// the replay UI can show which step was running at any point in the timeline.
-async function markStepStart(stepName) {
+/**
+ * Injects a labeled rrweb custom event at the current recording timestamp so
+ * the replay UI can show which step was running at any point in the timeline.
+ */
+export async function markStepStart(stepName: string): Promise<void> {
 	if (!_page) return;
 	try {
 		await _page.evaluate((name) => {
+			// @ts-ignore — rrwebRecord is injected by the record.umd.min.cjs bundle
 			if (window.rrwebRecord?.record?.addCustomEvent) {
+				// @ts-ignore
 				window.rrwebRecord.record.addCustomEvent('step', { name });
 			}
 		}, stepName);
@@ -164,10 +190,14 @@ async function markStepStart(stepName) {
 	}
 }
 
-// Flushes every tab's buffered rrweb events (one per opened tab/popup) as a
-// gzip-compressed Cucumber attachment, tagged with the mime type Plum's
-// server looks for.
-async function flushRecordings(attach) {
+/**
+ * Flushes every tab's buffered rrweb events (one per opened tab/popup) as a
+ * gzip-compressed Cucumber attachment, tagged with the mime type Plum's
+ * server looks for.
+ */
+export async function flushRecordings(
+	attach: (data: Buffer, mime: string) => Promise<void>
+): Promise<void> {
 	if (_liveRRwebTimer) {
 		clearInterval(_liveRRwebTimer);
 		_liveRRwebTimer = null;
@@ -207,17 +237,17 @@ async function flushRecordings(attach) {
 	}
 }
 
-async function teardown() {
+export async function teardown(): Promise<void> {
 	await _browser?.close();
 }
 
 // Pickle steps carry no keyword (Cucumber normalizes Given/When/Then/And/But
 // away during Gherkin → Pickle compilation) — recover it by walking the
 // gherkinDocument for the AST node the pickle step was compiled from.
-function resolveStepKeyword(gherkinDocument, pickleStep) {
+function resolveStepKeyword(gherkinDocument: any, pickleStep: any): string {
 	const astNodeId = pickleStep?.astNodeIds?.[0];
 	if (!astNodeId) return '';
-	const steps = [];
+	const steps: any[] = [];
 	for (const child of gherkinDocument?.feature?.children ?? []) {
 		if (child.background) steps.push(...child.background.steps);
 		if (child.scenario) steps.push(...child.scenario.steps);
@@ -229,17 +259,25 @@ function resolveStepKeyword(gherkinDocument, pickleStep) {
 	return steps.find((s) => s.id === astNodeId)?.keyword?.trim() ?? '';
 }
 
-// Registers Plum's own Before/BeforeStep/After hooks. Call once from the
-// project's own tests/utils/hooks.ts — Cucumber supports multiple Before/After
-// hooks, so a customer's own hooks can still be added alongside this.
-function registerHooks() {
-	Before(async ({ pickle }) => {
+/**
+ * Registers Plum's own Before/BeforeStep/After hooks. Call once from your
+ * own tests/utils/hooks.ts — Cucumber supports multiple Before/After hooks,
+ * so your own hooks can still be added alongside this.
+ */
+export function registerHooks(): void {
+	Before(async ({ pickle }: ITestCaseHookParameter) => {
 		const tags = pickle.tags.map((t) => t.name).join(' ');
 		console.log(`\n▶ ${pickle.name}${tags ? `  ${tags}` : ''}`);
 		await setup();
 	});
 
-	BeforeStep(async function ({ pickleStep, gherkinDocument }) {
+	BeforeStep(async function ({
+		pickleStep,
+		gherkinDocument
+	}: {
+		pickleStep: any;
+		gherkinDocument: any;
+	}) {
 		const keyword = resolveStepKeyword(gherkinDocument, pickleStep);
 		const text = pickleStep?.text ?? '';
 		await markStepStart(keyword ? `${keyword} ${text}` : text);
@@ -250,13 +288,3 @@ function registerHooks() {
 		await teardown();
 	});
 }
-
-module.exports = {
-	page,
-	context,
-	setup,
-	teardown,
-	flushRecordings,
-	markStepStart,
-	registerHooks
-};

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

@@ -29,6 +29,19 @@ let testExitCode = 0;
 
 try {
 	const testsRoot = (process.env.TESTS_ROOT || 'tests').replace(/\\/g, '/');
+	const testsRootAbsForSync = path.isAbsolute(testsRoot)
+		? testsRoot
+		: path.resolve(process.cwd(), testsRoot);
+
+	// tests/utils/browser.ts and hooks.ts import Plum's recording wiring from
+	// here — always overwritten from whatever Plum version is actually running
+	// this script, so it's never stale and never something a customer can
+	// accidentally lose track of by not re-running an update command. Safe to
+	// force unconditionally: nothing customer-owned ever lives in this folder.
+	const plumModulesSrc = path.join(__dirname, '..', '..', '_scaffold', 'utils', 'plum-modules');
+	const plumModulesDest = path.join(testsRootAbsForSync, 'utils', 'plum-modules');
+	fs.rmSync(plumModulesDest, { recursive: true, force: true });
+	fs.cpSync(plumModulesSrc, plumModulesDest, { recursive: true });
 
 	// 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
@@ -112,11 +125,7 @@ try {
 			// When running from a temp dir there is no tsconfig.json above it, so
 			// ts-node falls back to defaults that may conflict with the Node version.
 			// Point it at the backend tsconfig explicitly.
-			...(execCwd && { TS_NODE_PROJECT: path.resolve(__dirname, '..', '..', 'tsconfig.json') }),
-			// tests/utils/browser.ts and hooks.ts are a thin pass-through to this —
-			// an absolute path works the same whether cwd is backend/ (local run) or
-			// a temp dir with no relation to backend/ (a dispatched node run).
-			PLUM_RUNTIME_PATH: path.resolve(__dirname, '..', '..', 'lib', 'plumTestRuntime.js')
+			...(execCwd && { TS_NODE_PROJECT: path.resolve(__dirname, '..', '..', 'tsconfig.json') })
 		}
 	});
 } catch (error) {

package/backend/services/reportService.js

@@ -11,9 +11,8 @@ const { isScheduledTrigger, normaliseTrigger } = require('../constants/triggers'
 const { DEFAULT_BROWSER } = require('../constants/defaults');
 const { REPORT_STATUS } = require('../constants/jobStatus');
 
-// Matched by string literal in backend/tests/utils/browser.ts (flushRecordings) —
-// the two runtimes don't share a module, mirroring how 'image/png' is already
-// duplicated between the two files.
+// Matched by string literal in backend/_scaffold/utils/plum-modules/runtime.ts
+// (flushRecordings) — the two runtimes don't share a module.
 const RRWEB_MIME_TYPE = 'application/x-plum-rrweb+json';
 // Small, always-attached marker (independent of whether any tab actually
 // recorded events) so a scenario's worker is always recoverable for grouping,

package/bin/plum.js

@@ -62,25 +62,57 @@ function scaffoldPluginsFile() {
 	clack.log.success('plum.plugins.json created.');
 }
 
-// Files under tests/ that are Plum's own wiring rather than customer content —
-// `plum init` only writes these once, so a project scaffolded before a Plum
-// upgrade keeps running whatever version shipped at init time (e.g. an old
-// screenshot-based browser.ts after Plum has moved to rrweb recording) unless
-// something explicitly re-syncs them. Never touches customer-owned files
-// (features/, pages/, step_definitions/, utils/constants.ts, utils/utils.ts).
+// Files under tests/ that Plum's own scaffold originally wrote — `plum init`
+// only writes these once, so a project scaffolded before a Plum upgrade keeps
+// running whatever version shipped at init time (e.g. an old screenshot-based
+// browser.ts after Plum has moved to rrweb recording) unless something
+// explicitly re-syncs them.
+//
+// These are also exactly the files real projects most often rewrite entirely
+// with their own setup/teardown/cleanup logic — a project's browser.ts can
+// end up exporting things Plum's own template never did (extra page-object
+// helpers, auth header routing, multi-context session handling), which other
+// files in that project then import and depend on. A blind overwrite of a
+// file like that doesn't just discard "unsupported edits" — it silently
+// breaks every file that imports what used to be there, and can disable
+// cleanup logic another system relies on for a clean state. A backup makes
+// that recoverable, but "recoverable after your suite breaks" is still a bad
+// default, so this never overwrites unless explicitly told to.
 const INFRA_SCAFFOLD_FILES = ['utils/browser.ts', 'utils/hooks.ts'];
 
-// Re-syncs INFRA_SCAFFOLD_FILES from the installed Plum version's scaffold
-// into an existing tests/ directory, backing up anything it overwrites so a
-// customer's own edits to these files (unsupported, but possible) aren't
-// silently lost.
-function syncScaffoldInfraFiles(testsDir) {
+// Nothing customer-owned ever lives here — it's the same folder run-tests.js
+// force-refreshes before every test run — so unlike INFRA_SCAFFOLD_FILES this
+// is always safe to overwrite unconditionally, no diffing or backup needed.
+// Re-syncing it here too (not just at test-run time) means `plum update` /
+// `plum sync-scaffold` alone are enough to leave a project actually working,
+// without requiring a test run first.
+const PLUM_MANAGED_DIR = 'utils/plum-modules';
+
+function syncPlumModulesDir(testsDir) {
+	const src = path.join(scaffoldTestsPath, PLUM_MANAGED_DIR);
+	const dest = path.join(testsDir, PLUM_MANAGED_DIR);
+	if (!fs.existsSync(src)) return;
+	fs.rmSync(dest, { recursive: true, force: true });
+	fse.copySync(src, dest);
+}
+
+// Reports which INFRA_SCAFFOLD_FILES differ from the installed Plum version's
+// scaffold. With force:true, re-syncs them into the tests/ directory,
+// backing up whatever it overwrites — otherwise this never touches a file,
+// only reports on it, since diffing alone can't tell "untouched and stale"
+// apart from "extensively customized to depend on this exact content."
+// Always re-syncs PLUM_MANAGED_DIR regardless of force, since that part is
+// never customer-owned.
+function syncScaffoldInfraFiles(testsDir, { force = false } = {}) {
 	if (!fs.existsSync(testsDir)) {
 		clack.log.warn(`No \`tests/\` folder found at ${testsDir} — skipping scaffold sync.`);
 		return;
 	}
 
-	let updated = 0;
+	syncPlumModulesDir(testsDir);
+
+	let changed = 0;
+	let stale = 0;
 	for (const relPath of INFRA_SCAFFOLD_FILES) {
 		const src = path.join(scaffoldTestsPath, relPath);
 		const dest = path.join(testsDir, relPath);
@@ -90,16 +122,50 @@ function syncScaffoldInfraFiles(testsDir) {
 		const latest = fs.readFileSync(src, 'utf8');
 		if (current === latest) continue;
 
+		// A file that already imports plum-modules/runtime has adopted the
+		// current pattern and will keep differing from the bare scaffold
+		// forever once a customer adds their own code around it — that's
+		// expected and not something to warn about every time. Only a file
+		// that never picked up the import at all needs pointing somewhere.
+		const alreadyWired = current.includes('plum-modules/runtime');
+
+		if (!force) {
+			stale++;
+			if (alreadyWired) {
+				clack.log.info(
+					`${relPath} is customized but already wired to plum-modules/ — nothing to do.`
+				);
+				continue;
+			}
+			clack.log.warn(
+				`${relPath} doesn't import Plum's recording wiring — reports for this project won't ` +
+					`include session replay until it's added. This file is never auto-overwritten, so add it ` +
+					`yourself:\n` +
+					(relPath === 'utils/hooks.ts'
+						? `    Near the top of tests/${relPath}:\n` +
+							`      import * as plum from './plum-modules/runtime';\n` +
+							`      plum.registerHooks();\n` +
+							`    Keep your own Before/After/BeforeStep hooks below that line — Cucumber runs every registered hook.`
+						: `    Near the top of tests/${relPath}:\n` +
+							`      import * as plum from './plum-modules/runtime';\n` +
+							`    Then point your helpers at it, e.g.:\n` +
+							`      export const page = () => plum.page();\n` +
+							`      export const context = () => plum.context();\n` +
+							`      export const browser = () => plum.browser();`)
+			);
+			continue;
+		}
+
 		const backupPath = `${dest}.bak-${Date.now()}`;
 		fs.copyFileSync(dest, backupPath);
 		fs.copyFileSync(src, dest);
-		updated++;
+		changed++;
 		clack.log.success(
 			`Updated ${relPath} (previous version backed up to ${path.basename(backupPath)})`
 		);
 	}
 
-	if (updated === 0) {
+	if (changed === 0 && stale === 0) {
 		clack.log.info('Test scaffold wiring is already up to date.');
 	}
 }
@@ -553,9 +619,31 @@ async function serverUpdate() {
 	// logic no matter how new the just-installed files on disk actually are.
 	for (const dir of getInstalls('server')) {
 		if (!fs.existsSync(path.join(dir, '.plum-server.json'))) continue;
+
+		// Runs before the restart confirm below, and regardless of its answer —
+		// this only ever touches plum-modules/ (never customer-owned, see
+		// syncScaffoldInfraFiles) plus a warn-only check on browser.ts/hooks.ts,
+		// so there's nothing here that restarting the server is a prerequisite
+		// for, or that declining the restart should skip.
 		if (fs.existsSync(path.join(dir, 'tests'))) {
 			syncScaffoldInfraFiles(path.join(dir, 'tests'));
 		}
+
+		// This registry is global to the machine, not scoped to the directory
+		// `plum update` was run from — an unrelated project on the same machine
+		// as a registered server would otherwise silently boot that server's
+		// Docker stack. Ask first whenever there's someone to ask; a
+		// non-interactive run (CI, cron, systemd) has no one to ask and keeps
+		// the previous unconditional behavior.
+		if (interactiveAllowed()) {
+			const proceed = await clack.confirm({
+				message: `Found a registered server at ${dir} — restart it?`,
+				initialValue: true
+			});
+			if (clack.isCancel(proceed)) cancelAndExit();
+			if (!proceed) continue;
+		}
+
 		clack.log.step(`Rebuilding server at ${dir}…`);
 		try {
 			execSync('plum server restart', { stdio: 'inherit', cwd: dir });
@@ -568,9 +656,24 @@ async function serverUpdate() {
 	for (const dir of getInstalls('node')) {
 		const nodeCfg = loadNodeConfig(dir);
 		if (!nodeCfg.id) continue;
+
+		// Same reasoning as the server loop above: runs regardless of whether
+		// the restart below gets confirmed.
 		if (fs.existsSync(path.join(dir, 'tests'))) {
 			syncScaffoldInfraFiles(path.join(dir, 'tests'));
 		}
+
+		// This registry spans the whole machine, not just the directory
+		// `plum update` was run from.
+		if (interactiveAllowed()) {
+			const proceed = await clack.confirm({
+				message: `Found a registered node at ${dir} — restart it?`,
+				initialValue: true
+			});
+			if (clack.isCancel(proceed)) cancelAndExit();
+			if (!proceed) continue;
+		}
+
 		// Always attempt the restart rather than gating on the local PID
 		// registry: that registry goes stale (manager restarts, pre-existing
 		// installs from before this tracking existed, etc.), and skipping the
@@ -1141,11 +1244,13 @@ switch (command) {
 		await serverUpdate();
 		break;
 
-	case 'sync-scaffold':
+	case 'sync-scaffold': {
 		clack.intro(pc.bgMagenta(pc.white('  🟣 Plum — Sync Test Scaffold  ')));
-		syncScaffoldInfraFiles(userTestsPath);
+		const force = anyFlags(process.argv.slice(3), ['--force']);
+		syncScaffoldInfraFiles(userTestsPath, { force });
 		clack.outro(pc.green('Done.'));
 		break;
+	}
 
 	case 'run-test': {
 		const runHelpArgs = process.argv.slice(3);
@@ -1353,10 +1458,13 @@ switch (command) {
 		console.log('  server stop          Stop the server (data preserved)');
 		console.log('  server reconfig      Re-enter server settings without starting');
 		console.log(
-			'  update               Update Plum, restart whichever is running (server/node), and re-sync tests/ wiring'
+			'  update               Update Plum, restart whichever is running (server/node), and check tests/ wiring for updates'
+		);
+		console.log(
+			'  sync-scaffold        Check browser.ts/hooks.ts in tests/ against the installed Plum version'
 		);
 		console.log(
-			'  sync-scaffold        Re-sync browser.ts/hooks.ts in tests/ from the installed Plum version'
+			'    --force            Overwrite files that differ (previous version backed up first)'
 		);
 		console.log('  node start           Start a runner node (interactive), then open runner menu');
 		console.log('    --primary <url>    Primary Plum server to auto-register with');

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "plum-e2e",
-	"version": "2.9.1",
+	"version": "2.9.3",
 	"repository": {
 		"type": "git",
 		"url": "https://github.com/silverlunah/plum.git"