[CLI] Remove process.exit() from library APIs

[gcsecsey]

Motivation for the change, related issues

Summary

@wp-playground/cli can be used in two different ways:

1. As the wp-playground-cli command that a person runs in a terminal.
2. As a JavaScript library that another application imports and calls.

Those two uses need different error behavior. A standalone command may finish
by calling process.exit(). An imported library function should not: doing so
stops the entire Node.js process, including the application that called the
library. The caller cannot catch the error, retry the operation, or finish its
own cleanup.

This happened in WordPress Studio. Studio imports runCLI() and uses it to
start Playground in a child process. When Playground startup failed,
runCLI() called process.exit(1) before Studio could handle the failure.

This PR separates those responsibilities:

• Functions exported as the library API return results or throw errors.
• The standalone entry point in cli.ts decides when the command-line process
  should exit.

Fixes #3520.

Supersedes #3774, which proposes the same core runCLI() error-propagation fix
but does not include the broader entry-point separation and cleanup work here.

Related to Automattic/studio#2805 and its
review discussion.

Behavior before and after this PR

Situation	Before	After
An application calls runCLI() and startup fails	Playground prints the error and calls process.exit(1). The application cannot catch it.	runCLI() attempts cleanup and rejects its promise (an asynchronous error that normal try/catch can handle). The application can retry or report it.
parseOptionsAndRunCLI() finishes a one-shot command or reaches an explicitly handled validation exit	It calls process.exit().	It returns { exitCode }, and the caller decides what to do with that code.
A person runs the standalone CLI and startup fails	The process exits with code 1.	The process still exits with code 1. This responsibility now lives in cli.ts.
A running standalone CLI receives SIGINT (for example, Ctrl+C) or SIGTERM (a shutdown request)	Signal handling is registered by the library-oriented run-cli.ts module.	cli.ts disposes the server and then exits. A library consumer controls its own signal policy.
A library caller runs the php command	runCLI() calls process.exit() with PHP's exit code.	runCLI() returns the numeric exit code. The standalone CLI passes that code to process.exit().

For example, a library consumer can now handle a startup failure normally:

try {
	await using server = await runCLI({
		command: 'server',
		port: 9400,
	});
	// Use the server...
} catch (error) {
	// Report the error, choose another port, retry, etc.
}

The await using declaration automatically disposes the server when execution
leaves the try block.

Implementation details

Keep process termination in the standalone entry point

• Removed executable process.exit() calls from run-cli.ts library paths.
• cli.ts now translates library results into command-line behavior:
  • { exitCode } results become the process exit code.
  • Unexpected errors exit with code 1 after the error is reported.
  • SIGINT and SIGTERM dispose a running server before exiting with code 0.
• runCLI({ command: 'php' }) returns PHP's exit code instead of terminating
  the caller's process.

parseOptionsAndRunCLI() now returns a ParseCLIResult. There are two possible
result shapes:

• CLIExitResult: { exitCode: number } for validation failures and commands
  that finish without leaving a server running.
• CLIServerResult: an AsyncDisposable handle for a running server.

AsyncDisposable means the result has an asynchronous cleanup method at
result[Symbol.asyncDispose](). Callers may invoke it directly or use
await using where that syntax is supported.

Explicitly handled validation failures use CLIArgsValidationError. This
prevents an ordinary user mistake from being printed as an unexpected stack trace.
parseOptionsAndRunCLI() converts the error into { exitCode }.
CLIArgsValidationError is exported so a direct runCLI() caller can identify
it with instanceof and inspect its exitCode. For example, a direct caller
may receive this error when start --reset targets a site that Playground CLI
does not manage.

Clean up resources before returning an error

Removing process.exit() exposed an important second problem: a rejected
promise is not enough if workers or sockets are still open. Those resources can
keep Node.js running even after the caller has handled the error.

On each covered boot-failure path, runCLI() calls its shared cleanup routine.
That routine attempts to:

• Terminate spawned worker threads when boot fails, including the normal
  non-debug path.
• Close the HTTP server and all active connections.
• Remove the temporary Playground directory even when setup fails before
  WordPress boots.

startServer() also closes a socket that has already started listening when
onBind throws. If cleanup itself fails, the failure is logged without
replacing the original startup error; the caller still receives the startup
error.

Separately, mount failures now include the host path, virtual filesystem path,
and root cause. This keeps the message useful to callers that only display
error.message.

Keep command-line errors readable

For normal CLI use, an unexpected error now prints one concise line, for
example:

Error: listen EADDRINUSE: address already in use :::12345

The raw error and full debug details remain available with --debug.

Resetting a site that is not managed by Playground CLI is treated as an
expected validation failure. The user sees the existing guidance, while a
library caller receives a catchable error with an exit code.

Breaking changes for library consumers

Important

These are public API changes for applications that import
@wp-playground/cli. People who only run the wp-playground-cli command are
not required to change how they invoke the command.

• runCLI({ command: 'php' }) now resolves to number instead of void. The
  number is PHP's exit code.
• The general runCLI() return type now includes number.
• A startup failure from runCLI() rejects after attempting cleanup instead of
  terminating the process.
• parseOptionsAndRunCLI() returns ParseCLIResult. Errors that are not
  converted into explicit exit results are reported and rethrown instead of
  causing an internal process.exit().
• parseOptionsAndRunCLI() no longer installs SIGINT or SIGTERM handlers.
  A library application that starts a server is responsible for deciding how
  its process handles signals and when it disposes the server.

The successful result from runCLI({ command: 'server' | 'start' }) is
unchanged: it still exposes .server, .serverUrl, .playground, and
[Symbol.asyncDispose].

Compatibility review

In July 2026, I searched GitHub for known public consumers of the library API.
This is a point-in-time lower bound because private repositories do not appear
in public code search. That review did not identify a public consumer expected
to break at its currently declared dependency version.

Known public consumers checked

Consumer	Installed version	Expected effect
Automattic/wp-codebox	^3.1.35	Improvement. It already replaces process.exit() with a thrown error. This change makes that workaround unnecessary and allows its EADDRINUSE retry logic to work.
bgrgicak/wp-tester	3.0.15 exactly	Unaffected at its current version. After an upgrade, startup failures become catchable instead of terminating the test process.
juanma-wp/users-headless-nextjs-playground	1.1.2 exactly	Unaffected at its current version. Its existing try/catch will work as intended after an upgrade.
n3f/link-preview-cards	^2.0.4	Unaffected at its current major version. After an upgrade, an unhandled startup rejection would still end the process with a failure, but callers should add explicit error handling.
pfaciana/wp-now-playwright-testing	^1.2.2	Unaffected at its current major version. After an upgrade, it must own graceful signal cleanup if it relies on that behavior.
siteorigin/siteorigin-tests-common	^2.0.16	Unaffected at its current major version. Its existing try/finally structure already expects the call to throw.

All six consumers use the server command, so the php return-type change does
not affect them. Coordinate separately with private consumers that are not
visible through GitHub search.

Testing Instructions (or ideally a Blueprint)

Automated checks run for this change:

npm exec -- nx run playground-cli:test-playground-cli
npm exec -- nx run playground-cli:typecheck
npm exec -- nx run playground-cli:lint

The CLI test target passes all 186 tests, and the PR checks pass on Linux,
macOS, and Windows. Coverage includes:

• Catchable startup and port-conflict errors.
• Structured results for every command type.
• Worker termination and socket cleanup after startup failures.
• Concise normal error output and debug-only details.
• SIGINT and SIGTERM cleanup in the standalone entry point.

Manual checks:

1. Occupy a port, start the standalone CLI on that port, and confirm it prints
   one concise error and exits with code 1. Repeat with --debug and confirm
   the additional details are shown.
2. Import runCLI() from another Node.js program, trigger a startup failure,
   and confirm the program can catch the error and continue running.
3. Start the standalone CLI, send SIGINT or SIGTERM, and confirm it cleans
   up before exiting successfully.

[Copilot]

Pull request overview

Note

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

This PR changes the CLI error-handling behavior so that library consumers of runCLI() receive thrown errors instead of having their process terminated via process.exit(1).

Changes:

• Replace process.exit(1) calls in run-cli.ts and worker-thread-v2.ts with thrown errors.
• Move final process.exit(1) behavior to the CLI entrypoint (cli.ts).
• Update the “port already in use” test to assert a rejected promise instead of mocking process.exit.

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	Converts error exits to thrown errors in parseOptionsAndRunCLI()/runCLI() and replaces an exit-on-reset path with a thrown error.
packages/playground/cli/src/cli.ts	Ensures standalone CLI still exits with code 1 by catching parseOptionsAndRunCLI() rejection.
packages/playground/cli/src/blueprints-v2/worker-thread-v2.ts	Converts mount failure from stderr+exit to a thrown error with cause.
packages/playground/cli/tests/run-cli.spec.ts	Updates port-in-use test from exit-mocking to rejection assertion; small formatting change.

---

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

[brandonpayton]

Thanks for submitting this PR, @gcsecsey! This change makes sense to me, and I think it would be good to go further to remove all process.exit() calls from run-cli.ts exports. That way, the run-cli module exports are consistent, and we can know that all process.exit() calls are handled by cli.ts instead.

In addition, I think it is better to explicitly return nonzero exit codes, where possible, instead of throwing in the case of all errors. This way, control flow remains explicit, and the return types reflect more of the possible results. Where possible, exceptions should be exceptional. They are not meant to be an implicit result type.

So I had Claude make the above changes and add tests for the different return value possibilities. I pushed the changes but will have to finish reviewing them tomorrow or on Monday.

[gcsecsey]

Thanks for submitting this PR, @gcsecsey! This change makes sense to me, and I think it would be good to go further to remove all process.exit() calls from run-cli.ts exports. That way, the run-cli module exports are consistent, and we can know that all process.exit() calls are handled by cli.ts instead.

In addition, I think it is better to explicitly return nonzero exit codes, where possible, instead of throwing in the case of all errors. This way, control flow remains explicit, and the return types reflect more of the possible results. Where possible, exceptions should be exceptional. They are not meant to be an implicit result type.

So I had Claude make the above changes and add tests for the different return value possibilities. I pushed the changes but will have to finish reviewing them tomorrow or on Monday.

Thank you for making these changes @brandonpayton! I also addressed the smaller feedbacks from copilot in the meantime.

[JanJakes]

This is looking good overall. The process.exit() removal and explicit result-returning shape make sense, and the existing CLI lint/typecheck/tests are green.

Before approval, please check the inline server-cleanup issue and rebase this PR onto the latest trunk.

[gcsecsey]

Hey @brandonpayton and @JanJakes, I refreshed the branch against trunk and resolved the conflicts. This should be ready for another review.

[brandonpayton]

Claude had some concerns about this. I had it create fixes for the two bugs, but I'm not convinced the fixes use tge right approach. It needs a closer look. For now here are the concerns:

--

Code review — gcsecsey/php-error-server-restart

High-effort review of the CLI boot/exit refactor. Three findings survived verification; all in packages/playground/cli.

1. 🔴 Boot-failure cleanup regression — leaks worker threads, consumers hang

packages/playground/cli/src/start-server.ts:91 (root cause also spans start-server.ts:98, run-cli.ts:1719)

Removing runCLI's .catch(process.exit(1)) safety net means a non-debug startup error no longer tears the process down. When boot fails inside onBind, run-cli.ts rethrows without calling disposeCLI (that only ran in the debug branch). startServer's new catch closes only the listening HTTP socket and rethrows — the already-spawned Node worker_threads are never terminated.

Failure scenario: A downstream consumer (Studio / wp-env / Telex) does await runCLI({command:'server', blueprint: <broken>, verbosity: not 'debug'}) and catches the rejection to continue. The orphaned worker threads keep the event loop alive and the process never exits. Previously the removed .catch called process.exit(1) and tore everything down.

Status: ✅ Fixed in e338ce236 — dispose on the non-debug path before rethrowing.

2. 🟠 Breaking change to the exported runCLI('php') contract

packages/playground/cli/src/run-cli.ts:1682

runCLI for command: 'php' now returns a number instead of calling process.exit. This changes the public API's exit contract for programmatic callers.

Failure scenario: A consumer using await using cli = await runCLI({command:'php', ...}) now receives a plain number, which isn't disposable → TypeError: Symbol.asyncDispose is not a function at scope exit. A caller that relied on the process exiting no longer terminates.

Status: Intentional design change (entry point calls process.exit as a hard cutoff to avoid hanging on open handles; covered by a test). Not fixed in code — needs a breaking-change callout in the PR description per the repo's backwards-compat policy.

3. 🟡 Unmanaged-site reset dumps a stack trace over the friendly message

packages/playground/cli/src/run-cli.ts:1912

Replacing process.exit(1) with a plain thrown Error in expandStartCommandArgs routes this expected validation case through parseOptionsAndRunCLI's unexpected-error catch, which does console.error(e) (full stack trace) plus the duplicated bold guidance message.

Failure scenario: playground start --reset against an externally-mounted (non-~/.wordpress-playground/sites) directory previously showed a clean red guidance block + exit 1. Now the guidance is buried under a raw stack trace.

Status: ✅ Fixed in cc5271fc6 — throw CLIArgsValidationError(1) so the clean-exit path handles it.

---

Refuted during verification (5)

For transparency, these candidates were raised by finders but rejected by the verify pass: SIGINT/SIGTERM dangling-listener concerns in cli.ts (×2), the worker-thread-v2.ts mountResources throw concerns (×2), and a claimed close-snippet duplication in start-server.ts.

---

[gcsecsey]

@brandonpayton Thanks for flagging these. I took a closer look, and got Claude to reimplement the two fixes locally:

1. 🔴 Worker-thread leak on boot failure — valid, and dropping runCLI’s .catch(process.exit(1)) was the right call. It exposed that onBind’s non-debug catch rethrew without calling disposeCLI(). So the spawned worker_threads were never terminated and a library caller that catches the rejection keeps its event loop alive. Fixed by always disposing before rethrowing. Added a regression test that fails boot after the worker spawns and asserts terminate() runs — confirmed it fails without the fix. → 5d83b44

2. 🟠 runCLI no longer calls process.exit — this is intentional, no code change needed. I'll add a callout to the PR description.

3. 🟡 Stack trace over the friendly reset message — valid, and I think this is the approach you weren’t sure about. Throwing CLIArgsValidationError does fix the CLI output (clean exit, no stack), but the wrinkle is that sentinel was documented as “never exposed to callers,” and expandStartCommandArgs runs inside the public runCLI() export — so a direct library caller doing runCLI({command:'start', reset:true}) would get it, with an empty message. So I gave the sentinel a real message and relaxed its doc: the CLI still exits cleanly, and a library caller now gets a meaningful error instead of an empty one. → 7da57c5

For #3, I went with reusing the sentinel + message, rather than introducing a dedicated user-facing error type. Start is really CLI-oriented so the exposure risk is low, but happy to switch to a distinct error type if you’d prefer it be more explicit. WDYT?

[JanJakes]

Cleaning up my PRs, I figured out #2880 may depend on this one.

[brandonpayton]

Pushed a follow-up commit addressing review feedback:

• Clean single-line error output for ordinary failures (port in use, missing blueprint, bad mount); full stack trace retained behind --debug.
• Fixed a temp-dir leak on pre-boot failures (temp-dir setup now runs under disposeCLI()).
• Exported CLIArgsValidationError so library callers can instanceof-check it and read exitCode.
• A disposeCLI() failure during teardown no longer masks the original boot error.
• Tightened the error-path test assertions to specific messages.

Also refreshed the PR description: dropped the stale worker-thread-v2.ts reference, documented the four bundled hardening changes, and reworked the Breaking-changes section — it's technically breaking (function signatures), but a survey of the known public library-API consumers found none break in practice (five are pinned below 3.x; the one whose caret would pull it in, wp-codebox, actually benefits — the change fixes its EADDRINUSE retry loop).

playground-cli: 180/180 tests pass; lint + typecheck clean.

[brandonpayton]

I took a look and left some notes for Codex to address. This is close.

[brandonpayton]

I reviewed these changes manually, and the CI tests are passing. This should be ready to go.

I'm planning to run some brief manual tests in the morning to double-check and then merge. If anybody else wants to do the same and merge before then, please feel free. 🫡

[brandonpayton]

I tested the server, start, and php commands locally, and they seem to be working well. Let's merge. Thanks again, @gcsecsey!

[brandonpayton]

I just noticed that the title and description could be updated to be clearer. I think the latest there is probably from an agent update I requested. Will request more readability and clarity and see what it does.

[gcsecsey]

Thank you for bringing it over the finish line @brandonpayton, and for updating the description. To accommodate these changes in Studio, could you also help us cut a new release that includes them? Thanks!

[brandonpayton]

@gcsecsey Glad to help! We had some hiccups with the release, but there is now a new release that should contain these changes.