feat: expose reusable Functions core

[shrey150]

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 bundled bb CLI.

The public surface includes:

• Projects/archives: createFunctionProject, createFunctionArchive, listFunctionArchiveEntries, validateFunctionArchiveSize, and MAX_FUNCTION_ARCHIVE_SIZE_BYTES.
• Cloud operations: publishFunction, getBuildStatus, invokeFunction, and getInvocationStatus.
• Local runtime: startDevServer and its typed handle/options/log events.
• Transport/config: shared project resolution, request/polling helpers, result types, and FunctionsCoreError with 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 .env files use mode 0600 on supported platforms.
• A disconnected runtime /next request is removed from connection state instead of remaining falsely healthy.

Compatibility and package shape

• @browserbasehq/sdk-functions/core ships ESM, CommonJS, and declarations from the existing package.
• The current @browserbasehq/sdk-functions root export and bb binary 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:

1. Merge this PR.
2. Open and merge a dedicated version-bump PR updating package.json and pnpm-lock.yaml to 1.1.0.
3. From a clean trusted checkout of main, run frozen install, lint, unit, packed integration, build, and pack checks.
4. Publish from the trusted npm release environment with normal registry authentication/OTP requirements.
5. Verify npm view @browserbasehq/sdk-functions@1.1.0 exports --json includes ./core, then smoke-import both module formats.
6. 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.