Skip to content

feat(cli): run a managed background preview in every launch mode - #3310

Draft
miguel-heygen wants to merge 1 commit into
cli-preview-json-lifecyclefrom
cli-preview-background-modes
Draft

feat(cli): run a managed background preview in every launch mode#3310
miguel-heygen wants to merge 1 commit into
cli-preview-json-lifecyclefrom
cli-preview-background-modes

Conversation

@miguel-heygen

Copy link
Copy Markdown
Collaborator

--background was rejected outside the embedded preview server. It now re-execs the CLI in foreground, which makes it mode-agnostic by construction: whichever server the child resolves to serves the config endpoint the readiness probe looks for.

--foreground is its counterpart, for a non-interactive shell that wants to stay attached. A bare launch keeps the same promise it always had — attached in an interactive terminal, managed in an agent session.

An existing hole this exposed

Local-studio mode runs Vite with the studio package as its working directory and needs that package's own Vite config, which the published tarball does not carry. Resolving the package was treated as proof the mode was usable, so a project with an npm-installed studio took a path that can never come up — previously a clear error, now a ten-second silent timeout once background routes through it.

The predicate becomes "can this studio actually be served", so a published install falls back to embedded mode, which works. Publishing the studio's Vite config is a packaging change worth doing separately.

Over the line budget

~1.2k changed lines against the convention's 1k. The overage is one command file and its tests carrying one invariant, and the seam that would split it further runs through a single request-handling function — a split there produces two PRs neither of which starts a preview on its own. Flagging rather than hiding it.

Verifying

Start with --background --json and confirm ready: true, then --status, then --stop, and confirm the port is free and the session record removed. Conflicting lifecycle flags produce one failure envelope.

Stack

Last of four on the preview side, based on u5-preview-json-contract. Retarget to main before merging.

@miguel-heygen
miguel-heygen force-pushed the cli-preview-json-lifecycle branch from 3a42f81 to eea3af8 Compare August 18, 2026 05:26
@miguel-heygen
miguel-heygen force-pushed the cli-preview-background-modes branch from 2b839c3 to 5aa3257 Compare August 18, 2026 05:28
`--background` was rejected outside the embedded server. It now re-execs the
CLI in foreground, which makes it mode-agnostic by construction: whichever
server the child resolves to serves the config endpoint the readiness probe
looks for. `--foreground` is its counterpart, for a non-interactive shell that
wants to stay attached, and a bare launch keeps the same promise — attached in
an interactive terminal, managed in an agent session.

That generalization exposed an existing hole. Local-studio mode runs Vite with
the studio package as its cwd and needs that package's own Vite config, which
the published tarball does not carry, but resolving the package was treated as
proof the mode was usable. An npm-installed studio therefore took a path that
can never come up — previously a clear error, now a ten-second silent timeout.
The predicate becomes "can this studio actually be served", so a published
install falls back to embedded mode, which works.

Over the 1k line budget at ~1.3k. The overage is one command file and its
tests carrying one invariant, and the seam that would split it further is
inside a single request-handling function — a split there would produce two
PRs neither of which starts a preview on its own.
@miguel-heygen
miguel-heygen force-pushed the cli-preview-background-modes branch from 5aa3257 to 14fb447 Compare August 18, 2026 05:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant