From e7ab4fe5ce6efd89b9cf3c308f1cb2af31b5fa65 Mon Sep 17 00:00:00 2001
From: Adrian Moldovan <3854374+adimoldovan@users.noreply.github.com>
Date: Tue, 1 Sep 2026 19:03:34 +0300
Subject: [PATCH] Build/Test Tools: Correct local environment failure handling.

Backport of [63416] to the 6.9 branch.

`start.js` and `docker.js` report success when Docker Compose fails to start,
exits non-zero, or is killed. Propagate the exit status, and keep SIGINT as
cancellation for interactive commands.

The `.env` half of [63416] is omitted. This branch already copies the
configuration synchronously, from [62871].
---
 tools/local-env/scripts/docker.js | 11 ++++++++++-
 tools/local-env/scripts/start.js  | 13 ++++++++++++-
 2 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/tools/local-env/scripts/docker.js b/tools/local-env/scripts/docker.js
index c7b11f0058424..ce71a4c075cd6 100644
--- a/tools/local-env/scripts/docker.js
+++ b/tools/local-env/scripts/docker.js
@@ -38,4 +38,13 @@ const returns = spawnSync(
 	{ stdio: 'inherit' }
 );
 
-process.exit( returns.status );
+if ( returns.error ) {
+	console.error( `Could not run Docker Compose. ${ returns.error.message }` );
+} else if ( returns.signal && returns.signal !== 'SIGINT' ) {
+	console.error( `Docker Compose was terminated by ${ returns.signal }.` );
+}
+
+// `status` is null when Docker could not be spawned at all, or was killed by a signal. SIGINT is
+// how a long-running command such as `env:logs` is normally ended, so it is not a failure worth an
+// npm error block. Every other signal means the command was killed before it finished.
+process.exit( returns.signal === 'SIGINT' ? 0 : ( returns.status ?? 1 ) );
diff --git a/tools/local-env/scripts/start.js b/tools/local-env/scripts/start.js
index 332897bb9812f..0261a2ade874e 100644
--- a/tools/local-env/scripts/start.js
+++ b/tools/local-env/scripts/start.js
@@ -35,7 +35,7 @@ if ( process.env.LOCAL_PHP_MEMCACHED === 'true' ) {
 	containers.push( 'memcached' );
 }
 
-spawnSync(
+const up = spawnSync(
 	'docker',
 	[
 		'compose',
@@ -48,6 +48,17 @@ spawnSync(
 	{ stdio: 'inherit' }
 );
 
+// No signal is exempt here, unlike in `docker.js`: `env:start` runs `composer update -W` next, and
+// that must not run against containers that never came up.
+if ( up.status !== 0 ) {
+	const reason = up.signal ? `It was terminated by ${ up.signal }.` : up.error?.message ?? '';
+
+	console.error( `Could not start the Docker containers. ${ reason }`.trim() );
+
+	// `status` is null when Docker could not be spawned at all, or was killed by a signal.
+	process.exit( up.status ?? 1 );
+}
+
 // If Docker Toolbox is being used, we need to manually forward LOCAL_PORT to the Docker VM.
 if ( process.env.DOCKER_TOOLBOX_INSTALL_PATH ) {
 	// VBoxManage is added to the PATH on every platform except Windows.