STG-1746 Add SEA --version flag

[monadoid]

why

The SEA binary needs a lightweight way to report the commit and timestamp it was built from.

what changed

Added a --version path that prints build metadata baked into the SEA binary during build.

[changeset-bot]

🦋 Changeset detected

Latest commit: 692903e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@browserbasehq/stagehand-server-v3	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[cubic-dev-ai]

No issues found across 4 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant User
    participant SEA as SEA Binary Entry
    participant Core as Stagehand Core
    participant Server as Stagehand Server

    Note over SEA: Build-time: Commit metadata injected via esbuild 'define'

    User->>SEA: Run binary (e.g., ./stagehand --version)
    
    SEA->>SEA: NEW: Normalize process.argv

    alt NEW: Includes --version
        SEA-->>User: NEW: Output baked-in commit SHA & timestamp
        Note right of SEA: Process exits (0)
    else Standard Execution
        SEA->>Core: CHANGED: Lazy/Dynamic import package
        
        alt Supervisor Mode (--supervisor)
            SEA->>Core: Run shutdown supervisor
        else Server Mode
            SEA->>SEA: Set BROWSERBASE_FLOW_LOGS=1
            SEA->>Server: CHANGED: Lazy/Dynamic import server.js
            Server->>Server: Initialize and start server
        end
    end

    Note over SEA,Server: NEW: Turbo cache disabled for builds to ensure fresh metadata injection

Loading

_{Re-trigger cubic}

[cubic-dev-ai]

No issues found across 4 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant Build as Build Script
    participant Git as Git
    participant CI as CI Environment
    participant Bundle as Bundle Generator
    participant SEA as SEA Binary

    Note over Build,SEA: SEA Binary Build & Version Flag Flow

    Build->>Git: execFileSync(["rev-parse", "HEAD"])
    Git-->>Build: commit hash

    Build->>Git: execFileSync(["show", "-s", "--format=%cI", commit])
    Git-->>Build: ISO 8601 timestamp

    alt CI build (GITHUB_SHA set)
        Build->>CI: read GITHUB_SHA env var
        CI-->>Build: commit SHA
    else Local build (no GITHUB_SHA)
        Build->>Git: fallback to git rev-parse
    end

    Build->>Build: construct seaVersion string<br/>(commit + timestamp)
    Build->>Build: define __STAGEHAND_SERVER_VERSION__

    Build->>Bundle: esbuild build with define: seaBuildDefine
    Bundle->>Bundle: inject versionOutput into SEA template
    Bundle-->>Build: bundled CJS file

    Build->>Build: read bundle, create single-executable-app blob
    Build->>Build: inject versionOutput variable

    Note over Build: SEA binary contains versionOutput

    User->>SEA: ./binary --version
    SEA->>SEA: parse process.argv
    alt --version flag present
        SEA->>SEA: log versionOutput
        SEA-->>User: commit + timestamp
        SEA->>SEA: process.exit(0)
    else --supervisor flag
        SEA->>SEA: dynamic import stagehand
        SEA->>SEA: run supervisor
    else no flags
        SEA->>SEA: dynamic import stagehand
        SEA->>SEA: dynamic import server.js
        SEA->>SEA: start Stagehand server
    end

Loading

_{Re-trigger cubic}

[cubic-dev-ai]

No issues found across 3 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant Builder as Build Script<br/>(build-sea.ts)
    participant Git as Git Repo
    participant ESBuild as ESBuild Bundler
    participant SEA as SEA Binary<br/>(stagehand-server)
    participant Node as Node.js Runtime

    Note over Builder,Node: SEA Build Pipeline (build-sea.ts)

    Builder->>Git: execFileSync(["rev-parse", "HEAD"])
    Git-->>Builder: buildCommit (SHA)
    Builder->>Git: execFileSync(["show", "-s", "--format=%cI", buildCommit])
    Git-->>Builder: timestamp (ISO 8601)
    Builder->>Builder: Construct seaVersion string: "commit: {SHA}\ntimestamp: {ISO}"
    Builder->>Builder: Define esbuild define: __STAGEHAND_SERVER_VERSION__ = seaVersion

    alt CJS Bundle Build
        Builder->>ESBuild: build({ define: { __STAGEHAND_SERVER_VERSION__ } })
        ESBuild-->>Builder: CJS bundle with replaced constant
    else ESM Bundle Build
        Builder->>ESBuild: build({ define: { __STAGEHAND_SERVER_VERSION__ } })
        ESBuild-->>Builder: ESM bundle with replaced constant
    end

    Builder->>Builder: Create SEA injection script
    Note over Builder: Injects versionOutput = seaVersion as string literal

    Note over Builder,SEA: Runtime — SEA Binary Execution

    User->>SEA: stagehand-server --version
    SEA->>Node: process.argv parsing
    SEA->>SEA: Check if --version in argv
    alt --version flag present
        SEA->>Node: console.log(__STAGEHAND_SERVER_VERSION__)
        Note over SEA: Outputs previously baked-in build metadata
        SEA->>Node: process.exit(0)
    else --version flag absent
        SEA->>Node: import("@browserbasehq/stagehand")
        Node-->>SEA: Stagehand module
        SEA->>Node: __internalMaybeRunShutdownSupervisorFromArgv(argv)
        alt Supervisor mode
            SEA->>Node: Return early (supervisor started elsewhere)
        else Normal server start
            SEA->>Node: process.env.BROWSERBASE_FLOW_LOGS = "1"
            SEA->>Node: import("./server.js")
            Node-->>SEA: Stagehand server started
        end
    end

Loading

_{Re-trigger cubic}