Improve v4 runtime env and test harness

Merged
MO
7mo ago
+261-192

Why

Small cleanup / improvements that I wanted for adding drizzle cleanly - doing drizzle work in a separate PR for clarity - this PR is just the small improvements.

What Changed

  • Use t3-env to parse env vars into a strongly typed object so the app can rely on defaults instead of carrying optional/null checks through the code.
    • Added a nested constants.ts to centralize shared constants and path segments in one place.
  • Run tests directly from source with tsx so we do not need compiled test output trees like dist/tests/test, which keeps the upcoming DB work cleaner.
  • Split server.ts into app.ts / server.ts split so Fastify app construction is cleanly testable and separate from process startup. This follows the official fastify demo best practice.
  • Replaced deprecated z.string().url() usages with z.url().
  • Turned Fastify’s built-in logger on so local startup is visible by default (will be replaced by flowlogger - didn't implement any custom logger)

Test plan

  • Added simple t3 env tests that check the discriminated union logic works

Summary by cubic

Make server-v4 runtime env type-safe and run node:test directly from source via tsx. Centralize Fastify app bootstrap and streamline the test harness for local/SEA/remote targets.

  • Refactors

    • Added src/app.ts to build the Fastify app, register OpenAPI, routes, health/readiness, and dev-only Swagger UI.
    • Introduced src/env.ts using @t3-oss/env-core; defaults BROWSERBASE_CONFIG_DIR to ~/.stagehand, PORT to 3000, NODE_ENV to development; added unit tests.
    • Added src/constants.ts to centralize shared constants (e.g., default config dir name).
    • Switched URL fields to z.url() in LLM and Page schemas.
    • Reworked test runner to execute .test.ts from packages/server-v4/test/** with --import=tsx; simplified path handling and reporter names; removed dist test build and tsconfig.tests.json.
    • Simplified scripts: added start; updated test scripts to source paths; updated turbo.json to drop build:esm-tests and ensure integration depends on build:server:dist; kept SEA support.
    • Bumped @t3-oss/env-core to ^0.13.11.

  • Migration

    • Start locally with pnpm --filter @browserbasehq/stagehand-server-v4 start (or dev).
    • Run tests from source: pnpm test:unit or pnpm test:integration. For SEA: STAGEHAND_SERVER_TARGET=sea pnpm test:integration (SEA build still required).
    • No more build:esm-tests; integration runs depend on build:server:dist automatically.