Docker CLI: scope parallel .env handling to type=dev, exclude e2e (#49160)

The hybrid tools/docker/.env machinery added in #48643 (read parallel keys
as a base layer, conflict warnings, append-on-`up --name` persistence) gated
its read block on `up` and its persist block on `up --name`, but neither
checked `argv.type === 'dev'`.

The E2E framework runs `jetpack docker --type e2e --name t1 up -d`
(tools/e2e-commons/bin/e2e-env.sh), which sets argv.name. So running the
E2Es in a plain checkout wrote COMPOSE_PROJECT_NAME=jetpack_t1 and the
PORT_* keys into tools/docker/.env — reported in
#48643 (comment).

That pollution cascades: a subsequent bare `jetpack docker up` (type=dev)
reads the polluted .env, infers argv.name='t1' via augmentArgvFromEnvFile,
and silently brings the dev container up as jetpack_t1 on the E2E ports.

Fix: add an exported `shouldManageParallelEnv( argv )` predicate
(`type === 'dev' && _[1] === 'up'`) and gate both the read/conflict block
and the persist block through it — mirroring resolveDevCloneSource being
"correct on its own terms". E2E now neither reads parallel keys from nor
writes them to the shared .env, and uses its own 8889 default port. The
buildEnv/process-env path is untouched, so E2E's own container behavior is
unchanged.

Adds a shouldManageParallelEnv describe block (4 cases incl. the e2e
regression). tools/cli suite: 156 passed, 3 skipped.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: CGastrell

tools/cli/commands/docker.js

@@ -343,6 +343,21 @@ export const applyUpdateEnv = ( filePath, conflicts ) => {
 	return updated;
 };
 
+/**
+ * Whether the hybrid tools/docker/.env parallel-instance machinery (reading keys as a base
+ * layer, conflict warnings, append-on-`up --name` persistence) applies to this invocation.
+ *
+ * Scoped to `up` on `type === 'dev'`. The e2e flow runs `docker --type e2e --name t1 up`,
+ * which sets argv.name but manages its own fixed ports and project name — it must neither
+ * read parallel keys from nor write them to the shared .env. Keeping the gate here (rather
+ * than only inline at the call sites) mirrors resolveDevCloneSource being "correct on its
+ * own terms" and makes the e2e exclusion unit-testable.
+ *
+ * @param {object} argv - Yargs argv.
+ * @return {boolean} true when parallel-env reads/writes should run.
+ */
+export const shouldManageParallelEnv = argv => argv.type === 'dev' && argv._[ 1 ] === 'up';
+
 /**
  * Decides which source instance to clone the DB from when bringing up a dev container, if any.
  *
@@ -810,7 +825,10 @@ const defaultDockerCmdHandler = async argv => {
 	// surface conflicts as warnings (or rewrite when --update-env is set), and persist
 	// parallel-instance keys after a successful `up --name`. See tools/docker/README.md
 	// § "Parallel development environments" for the full precedence + semantics.
-	if ( argv._[ 1 ] === 'up' ) {
+	// Scoped via shouldManageParallelEnv (`up` + `type === 'dev'`): the e2e flow runs with a
+	// fixed `--name t1` and manages its own ports, so it must neither read parallel keys from
+	// nor write them to the shared tools/docker/.env.
+	if ( shouldManageParallelEnv( argv ) ) {
 		const flagSnapshot = snapshotFlagArgv( argv );
 		const fileEnv = readEnvFile();
 		augmentArgvFromEnvFile( argv, fileEnv );
@@ -901,7 +919,9 @@ const defaultDockerCmdHandler = async argv => {
 	// Persist parallel-instance config to .env on `up --name`. Idempotent: only appends
 	// keys that aren't already in the file (Strategy B). Skipped for the primary
 	// `jetpack_dev` flow (no --name) so the main checkout's .env is never written to.
-	if ( argv._[ 1 ] === 'up' && argv.name ) {
+	// Also skipped for non-dev types: the e2e flow always passes `--name t1`, but it
+	// must not write COMPOSE_PROJECT_NAME/PORT_* into the shared tools/docker/.env.
+	if ( shouldManageParallelEnv( argv ) && argv.name ) {
 		const written = persistParallelEnv( envOpts );
 		if ( written.length ) {
 			console.log(

tools/cli/tests/unit/commands/docker.test.js

@@ -37,6 +37,7 @@ const {
 	detectEnvConflicts,
 	persistParallelEnv,
 	applyUpdateEnv,
+	shouldManageParallelEnv,
 	PARALLEL_ENV_KEYS,
 } = await import( '../../../commands/docker.js' );
 
@@ -197,6 +198,34 @@ describe( 'resolveDevCloneSource', () => {
 	} );
 } );
 
+describe( 'shouldManageParallelEnv', () => {
+	test( 'true for `up` on the default dev type', () => {
+		expect( shouldManageParallelEnv( { type: 'dev', _: [ 'docker', 'up' ] } ) ).toBe( true );
+	} );
+
+	test( 'true for `up --name` on dev', () => {
+		expect(
+			shouldManageParallelEnv( { type: 'dev', name: 'feature', _: [ 'docker', 'up' ] } )
+		).toBe( true );
+	} );
+
+	// Regression: the e2e framework runs `docker --type e2e --name t1 up -d`. Before the
+	// type gate, that --name leaked COMPOSE_PROJECT_NAME/PORT_* into the shared
+	// tools/docker/.env of a plain checkout. See PR #48643 review follow-up.
+	test( 'false for the e2e flow (--type e2e --name t1 up)', () => {
+		expect( shouldManageParallelEnv( { type: 'e2e', name: 't1', _: [ 'docker', 'up' ] } ) ).toBe(
+			false
+		);
+	} );
+
+	test( 'false for non-up commands on dev', () => {
+		expect( shouldManageParallelEnv( { type: 'dev', _: [ 'docker', 'down' ] } ) ).toBe( false );
+		expect(
+			shouldManageParallelEnv( { type: 'dev', name: 'feature', _: [ 'docker', 'clean' ] } )
+		).toBe( false );
+	} );
+} );
+
 describe( 'normalizeProjectShortName', () => {
 	test( 'lowercases mixed-case input', () => {
 		expect( normalizeProjectShortName( 'Feature' ) ).toBe( 'feature' );