[CLI] Add --workers=<n|auto> flag to configure worker thread count

[pento]

Motivation for the change, related issues

The Playground CLI hardcodes the number of request-handling worker threads to 6 (chosen to match HTTP/1.1's per-origin browser connection limit). That's fine for a single browser, but it caps multi-client workloads — parallel Playwright contexts, load tests, fanning e2e suites — at six in-flight requests, which is too few on modern hosts.

The old --experimental-multi-worker flag that let users override this was deprecated and its value is now silently ignored, and the pre-hardcoding default of cpus - 1 was dropped along with it. There's no way to turn the dial back up.

Implementation details

Adds a new --workers=<n|auto> flag:

• A positive integer sets an explicit worker count.
• auto uses max(1, os.cpus().length - 1) — restores the old pre-hardcoding default.
• When the flag is absent, the default is min(6, max(1, cpus - 1)): preserves today's 6-worker behavior on machines with ≥7 cores, shrinks on small hosts so we don't spawn more workers than cores. The Math.max(1, ...) guard covers single-core hosts and restricted environments where os.cpus() returns an empty array.
• Validation happens in yargs coerce: rejects 0, negatives, non-integers, and any non-auto string with a clear error message, routed through the existing .fail() handler.

The resolver is a small exported pure function (resolveWorkerCount) so the min/max/cpu logic is unit-testable without spinning up a server.

--experimental-multi-worker stays parsed-but-ignored — existing invocations don't break — but now emits a one-line logger.warn pointing users at --workers.

Docs updated in both packages/playground/cli/README.md and the Docusaurus CLI reference page.

Breaking changes

None. The default worker count is unchanged on typical dev machines (≥7 cores → still 6). On hosts with 1–6 cores the default drops to cpus - 1, which is a behavior change on small hosts but strictly safer (we were previously spawning more workers than cores there).

Testing Instructions (or ideally a Blueprint)

Unit tests (fast, no server spawn):

npx nx run playground-cli:test-playground-cli --testNamePattern="resolveWorkerCount|worker count"

All 14 new tests should pass: default, explicit number, --workers=1 (single-worker bootstrap), --workers=auto, invalid 0, invalid abc, deprecation warning for --experimental-multi-worker, plus 7 unit tests stubbing os.cpus() to cover the min/max/empty-array edges.

Manual smoke:

# Explicit count — server prints "(12 workers)"
npx nx dev playground-cli server --workers=12

# auto — uses cpus-1
npx nx dev playground-cli server --workers=auto

# default — min(6, cpus-1)
npx nx dev playground-cli server

# Deprecated flag still works, now warns
npx nx dev playground-cli server --experimental-multi-worker=4

# Validation
npx nx dev playground-cli server --workers=0      # exits 1 with clear error
npx nx dev playground-cli server --workers=abc    # exits 1 with clear error

Multi-client verification (the motivating use case):

# Start with more than 6 workers
npx nx dev playground-cli server --workers=16 &

# Fire >6 concurrent requests; throughput should scale past the old 6-worker ceiling
seq 1 32 | xargs -P32 -I{} curl -s -o /dev/null -w "%{time_total}\n" http://127.0.0.1:9400/

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds a new --workers=<n|auto> CLI flag to control the number of request-handling worker threads, restoring an “auto” mode and keeping the existing 6-worker default behavior on larger hosts.

Changes:

• Introduces --workers parsing/validation in the CLI and a pure resolveWorkerCount() helper.
• Adds unit/integration-style tests covering defaults, auto, explicit counts, invalid values, and the deprecated flag warning.
• Updates CLI documentation to describe --workers and deprecate --experimental-multi-worker.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
packages/playground/cli/src/run-cli.ts	Adds --workers option, deprecation warning, and resolveWorkerCount() implementation
packages/playground/cli/tests/run-cli.spec.ts	Adds coverage for worker resolution logic and CLI flag behavior
packages/playground/cli/README.md	Documents new --workers flag and deprecates --experimental-multi-worker
packages/docs/site/docs/developers/05-local-development/04-wp-playground-cli.md	Updates Docusaurus CLI reference with --workers and deprecation note

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[mho22]

Thanks @pento for this great pull request.

There's still a test that won't stop failing but I am pretty sure this isn't related to this PR. So we're almost good!

I discussed with @brandonpayton and we agreed on warning users on a minimal amount of workers in order for certain blueprints to work. Something like :

const targetWorkerCount = resolveWorkerCount(args.workers);

if (targetWorkerCount < 6) {
    logger.warn(
        `Worker count is below the safe threshold (6). ` +
        `This may increase the likelihood of deadlock` +
        `due to workers blocking on file locks.`
    );
}

What do you think?

[pento]

Thanks for the feedback, @mho22!

The failing test suite seemed to be the same as was failing in other PRs when I created this one, so I didn't investigate. trunk looks to be passing now, so I've merged that to see if it helps. If it's still failing, I'll investigate further.

I think a warning could be useful, though I'm leaning towards only showing it if the user has deliberately set the worker count to less than 6. If the count has been restricted by the number of cores available, there's not really much they can do, making it a warning that can't be actioned.

[pento]

I've investigated the error further. The macos worker has 3 cores, so this PR creates 2 workers: this is triggering the issue that #3494 addresses. I've been able to reproduce the error locally, and confirm that applying #3494 fixes it.

[chubes4]

#3494 also fixes: Automattic/studio#3116

[mho22]

@pento Briliant. Thanks for the contribution.