Surfaces the embedder API gbrowser (phoenix) needs to consume gstack as a
submodule, and gates module-load side effects so the file is safe to
import without auto-starting a daemon.
Changes to browse/src/server.ts:
- AUTH_TOKEN now honors process.env.AUTH_TOKEN (trimmed) before falling
back to crypto.randomUUID(). Whitespace-only values are rejected so the
security boundary can't be silently weakened.
- New exported types: ServerConfig and ServerHandle. ServerConfig documents
the full factory contract (authToken, browsePort, idleTimeoutMs, config,
browserManager, chromiumProfile, xvfb, proxyBridge, startTime, beforeRoute).
ServerHandle documents the return shape (fetchLocal, fetchTunnel,
shutdown, stopListeners). Caller-owned lifecycle annotations on xvfb and
proxyBridge prevent double-close bugs from surprise ownership.
- New exported function: resolveConfigFromEnv() builds a ServerConfig-shaped
object from process.env for CLI use. Embedders construct their own
ServerConfig explicitly.
- start() is now exported. Embedders can call it with env vars set as a
v1 escape hatch until full buildFetchHandler extraction lands.
- Signal handlers (SIGINT, SIGTERM, Windows exit, uncaughtException,
unhandledRejection) and the auto-kickoff at module bottom are now wrapped
in `if (import.meta.main)`. CLI path is unchanged. Embedders register
their own handlers.
- shutdown() and emergencyCleanup() now call cleanSingletonLocks(
resolveChromiumProfile()) instead of inline path+loop. Single
implementation, defensive guard, honors per-workspace CHROMIUM_PROFILE.
New tests:
- browse/test/server-no-import-side-effects.test.ts: spawns a fresh Bun
subprocess that imports server.ts, asserts no signal handlers registered,
no state-dir populated. Guards the core refactor invariant from
regression.
- browse/test/server-factory.test.ts: 12 tests covering AUTH_TOKEN env
behavior (honored, whitespace-rejected, trimmed), preserved exports
(TUNNEL_COMMANDS, canDispatchOverTunnel), and ServerConfig/ServerHandle
type compatibility.
Deferred to follow-up PR: full buildFetchHandler extraction that hoists
the 13 module-level mutables + helpers into a factory closure. Phoenix
can ship v0.6.0.0 against the start()+env surface today; the cleaner
factory comes next.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Garry Tan