feat: expose reusable Functions core
BLUF
Expose the canonical Functions implementation as @browserbasehq/sdk-functions/core and make bb functions a thin CLI adapter over it. Browse and future host CLIs can import one implementation instead of copying the Functions API/archive/runtime logic.
Root cause and design
The Functions HTTP API did not make a breaking change. The SDK/CLI implementation evolved—scaffold metadata/dependencies, project inference, archive validation, local runtime behavior, invocation/build polling—and Browse retained an older parallel copy.
This PR creates a headless core boundary:
- Core owns Functions API requests, polling, archives, scaffolding, local runtime protocol, and typed failures.
- Commander adapters own prompts/flags, human output, signals, and process exit behavior.
- Consumers import
@browserbasehq/sdk-functions/core; importing it does not execute the bundledbbCLI.
The public surface includes:
- Projects/archives:
createFunctionProject,createFunctionArchive,listFunctionArchiveEntries,validateFunctionArchiveSize, andMAX_FUNCTION_ARCHIVE_SIZE_BYTES. - Cloud operations:
publishFunction,getBuildStatus,invokeFunction, andgetInvocationStatus. - Local runtime:
startDevServerand its typed handle/options/log events. - Transport/config: shared project resolution, request/polling helpers, result types, and
FunctionsCoreErrorwith stable error codes.
Safety and project boundaries
- Archive creation does not run npm lifecycle scripts while materializing a lockfile.
- Symlinks are not followed into the archive, preventing files outside the project from being included.
- Archive size is enforced incrementally while streaming rather than after an unbounded in-memory buffer, and raw archive failures become typed
FunctionsCoreErrors. - Publish rejects entrypoints outside the project and entrypoints excluded by ignore rules.
- Scaffolded
.envfiles use mode0600on supported platforms. - A disconnected runtime
/nextrequest is removed from connection state instead of remaining falsely healthy.
Compatibility and package shape
@browserbasehq/sdk-functions/coreships ESM, CommonJS, and declarations from the existing package.- The current
@browserbasehq/sdk-functionsroot export andbbbinary remain intact. - This is a subpath export, not a physically separate npm package. Consumers avoid executing CLI code but still install the package's CLI dependency footprint. If footprint becomes material, a later release can split a physical core package without reintroducing duplicate implementations.
Review boundary
Review the reusable implementation and Commander-to-core adaptation here. The downstream Stagehand #2701 is a separate, top-of-stack V4 fast-follow containing only the Browse/Oclif adapters, dependency wiring, and host contract tests.
Current remote head: 097ad455f4af8ca2f4932da7641373d77963d2d1.
E2E test matrix
| Command / flow | Observed output | Confidence / sufficiency |
|---|---|---|
pnpm lint and build | Formatting, ESLint, typecheck, ESM/CJS bundles, and declarations passed | Proves the source and published entrypoints compile |
pnpm test | 66/66 tests passed | Covers core, safety boundaries, and Commander adapter contracts |
pnpm test:integration against the packed tarball | 58/58 tests passed, including ESM, CommonJS, declarations, retained CLI/dev/scaffold/manifest behavior, and a real TypeScript consumer compile | Proves packed package composition without relying on workspace links |
pnpm test:e2e with real Functions credentials on this exact head | 4/4 public starter templates packed, scaffolded, installed, published, built, and invoked | Exercises the real Functions service across every starter template |
| Exact downstream Browse pin | Frozen install; Stagehand + Browse build; lint/typecheck; 15/15 adapter contracts; 27 files/394 tests | Proves the core composes with the complete V4 CLI stack |
| Downstream live Browse flow | Local dev connected to Browserbase, invoked a managed browser against a public page, returned live data, and shut down successfully | Proves the Oclif host composes with the same runtime core |
Live validation used synthetic functions and public targets. Secrets, account identifiers, resource IDs, and connection URLs are intentionally omitted.
Release and rollout
This repository has CI but no automated npm release workflow. Because ./core is a new public API, the recommended release is 1.1.0:
- Merge this PR.
- Open and merge a dedicated version-bump PR updating
package.jsonandpnpm-lock.yamlto1.1.0. - From a clean trusted checkout of
main, run frozen install, lint, unit, packed integration, build, and pack checks. - Publish from the trusted npm release environment with normal registry authentication/OTP requirements.
- Verify
npm view @browserbasehq/sdk-functions@1.1.0 exports --jsonincludes./core, then smoke-import both module formats. - In downstream #2701, replace the exact commit pin with
^1.1.0, remove the temporary build allowance, regenerate the lockfile, and rerun the full matrix including fresh npm and pnpm scaffold live-cloud smokes.
Downstream #2701 is intentionally draft and must not be merged or published while it references the GitHub commit.