Skip to content

platform-support.md

Latest commit

 

History

History
223 lines (181 loc) · 9.76 KB

platform-support.md

File metadata and controls

223 lines (181 loc) · 9.76 KB
Raw

Platform Support

Supported host environments

  • macOS persistent host
  • Linux persistent host
  • Windows via Ubuntu on WSL2
  • Windows 11 x64 native host (alpha)

Minimum runtime: Node.js 22.19, enforced by install-machine.sh and the root engines field. Lowering the floor needs its own test pass.

Tested npm package runtimes:

  • Node.js 22.19 or newer in the Node.js 22 release line
  • Node.js 24 LTS
  • Node.js 26 Current

Newer release lines are not blocked. install-machine.sh gates on the 22.19 floor only, so a release line we have not tested yet still installs rather than failing hard on the day it ships. The bb-app npm engines field lists the tested lines, which npm surfaces as a warning rather than an install failure.

Windows has two host paths. Inside WSL2 the Linux stack runs unchanged:

  • all bb processes run inside the same Ubuntu WSL2 distro
  • Node.js, Git, provider CLIs, and pnpm for source-development flows are installed inside WSL2
  • local project paths use Linux-style absolute paths from inside WSL2

The native Windows host is alpha. It runs from the Windows desktop installer or npx bb-app in PowerShell or CMD:

  • Git for Windows is required; bb uses its Git and its bash for environment setup and teardown scripts
  • project paths are drive-letter paths such as C:\Users\me\repo; UNC paths are refused
  • terminals run PowerShell 7 when installed, otherwise Windows PowerShell
  • a Windows machine can be added to another server from Settings → Machines with the PowerShell command; its daemon runs in the signed-in user's session
  • the server cannot be moved to a Windows machine

Mobile app

apps/mobile is the iOS and Android client for a bb server. It runs no agents, host daemon, or plugins itself: it loads the server's web app and adds native screens for pairing, saved servers, device settings, and push registration. Install it from Settings → Mobile (iOS TestFlight or the Android APK; see configuration.md).

  • Direct mode takes any http(s):// URL the phone can reach. It is unauthenticated, the same trust model as a browser on a LAN; iOS allows plain http:// only for LAN IPs and .local names, so Tailscale hosts need Serve HTTPS.
  • bb connect mode pairs the phone as a connect machine; see multiple-devices.md.
  • Push notifications need the server to reach exp.host and a bb connect or HTTPS profile; a plain-HTTP direct profile cannot register.
  • Phones have no host daemon, so local editor integration, "Open in …", and the native folder picker are unavailable; the remote path browser works. Provider sign-in still needs a terminal on the host.
  • Web CSS and plugin themes apply to the loaded web app; native screens use the built-in palettes. Desktop browser automation needs a desktop host.

Support Boundaries

Supported product flows

  • npx bb-app
  • npx --package bb-app bb ...
  • source checkout package startup with pnpm start, pnpm start:worktree, or pnpm start:worktree-remote
  • source checkout validation with pnpm install, pnpm build, pnpm exec turbo run typecheck, and pnpm exec turbo run test
  • app + server + host-daemon startup on supported persistent-host OSes
  • local-path project creation and update in the app
  • unmanaged environments
  • managed worktree environments
  • provider runtime startup where the provider itself supports the host environment
  • npx bb-app package startup on supported npm package runtimes
  • npx --package bb-app bb ... CLI execution through the published package

Command ownership and mode selection

  • @bb/config is the only source of dev/prod defaults.
  • Repo-root source-development commands such as pnpm start, pnpm bb, pnpm bb:dev, and pnpm reset are thin wrappers around local packages and scripts.
  • Those wrappers set NODE_ENV explicitly so ambient shell state does not change which bb instance they target.
  • Explicit BB_* values override the NODE_ENV-selected defaults.
  • Process-to-process handoff, such as daemon-injected CLI environment, must use explicit BB_* values for the exact target instance instead of relying on mode defaults.

WSL2-specific expectations

  • Run npx bb-app, source checkout commands such as pnpm install, pnpm dev, pnpm bb:dev, and host-daemon commands from a WSL2 shell, not from native Windows terminals.
  • Repositories inside the WSL filesystem are recommended for best behavior.
  • /mnt/c/... mounted paths are deliberately supported so WSL2 users can keep working with existing Windows checkouts instead of relocating every repo into the WSL filesystem, but they are a tradeoff: slower filesystem I/O and weaker file-watching behavior than the WSL filesystem.
  • A machine that reported macOS, Linux, or WSL refuses Windows drive-letter paths at the app/server boundary so unsupported input fails clearly. Use the /mnt/c/... form from inside WSL2. A machine that reported Windows refuses POSIX paths the same way.

Windows drive-letter paths

Native Windows hosts use drive-letter paths for projects and workspaces:

  • A drive-letter path such as C:\Users\me\repo is stored in one spelling: upper-case drive letter, backslash separators, and no trailing separator. c:/Users/me/repo/ names the same project.
  • Windows paths are compared without regard to case, so C:\src\Repo and C:\src\repo are one project source and one environment. POSIX paths stay case-sensitive.
  • UNC network paths (\\server\share\repo) are refused; map the share to a drive letter.
  • Paths relative to a workspace stay /-separated in the API on every platform.

Maintainer-only or best-effort surfaces

  • workspace-owned QA helpers under tests/qa/
  • dev restart internals that are not part of the shipped product path
  • source-development flows (pnpm dev, pnpm bb:dev) on native Windows

Dependency Policy

We are standardizing on a small set of cross-platform packages:

  • cross-env
    • portable environment injection in package scripts
  • rimraf
    • portable recursive cleanup in package scripts
  • cross-spawn
    • shared subprocess launch for portability-sensitive runtime paths
  • open
    • OS-specific file/URL opening behind a repo-local helper

We are explicitly not adopting:

  • shx
    • we prefer small Node scripts for copy/create-directory logic
  • generic path helper libraries
    • node:path is sufficient
  • generic filesystem helper libraries
    • fs/promises is sufficient

Native npm dependencies

The npm package keeps native add-ons as runtime dependencies instead of bundling one platform-specific .node binary into bb's JavaScript artifacts. This lets npm install the correct native artifacts on the target machine for packages such as better-sqlite3 and @parcel/watcher.

Known failure modes remain the normal native-addon ones:

  • changing Node versions after install without reinstalling or rebuilding
  • copying node_modules across operating systems, CPU architectures, or libc variants
  • disabling package lifecycle scripts
  • running on a platform where no prebuild exists and no local build toolchain is available

The recovery path after a Node/runtime change is to reinstall the package or rebuild the native dependency, for example npm rebuild better-sqlite3.

Setup Hook Policy

  • The supported setup hook is POSIX .bb-env-setup.sh.
  • The supported teardown hook is POSIX .bb-env-teardown.sh.
  • The same shell-based hook contract is used across macOS, Linux, and WSL2.
  • On native Windows bb runs the same scripts with the bash that Git for Windows installs, found through git var GIT_SHELL_PATH, with that directory first on PATH so the script's standard tools resolve. Without Git for Windows the hook fails with a message naming it.
  • No parallel .bb-env-setup.ts product-path mechanism is supported.
  • The .worktreeinclude copy step runs no shell. It works on every platform, including native Windows.

Line Ending Policy

  • The repository enforces LF checkout for supported text files via .gitattributes.
  • Supported Linux and WSL2 flows must work with those repository rules applied.
  • A native Windows checkout of this repository must keep those LF rules; the Windows CI jobs build and package from such a checkout.

CI And Validation

  • GitHub Actions uses Ubuntu as the required support gate for build, typecheck, lint, test, and Linux smoke coverage.
  • Full build, typecheck, lint, and test checks run on Ubuntu with Node.js 22 only.
  • Pull requests run the bb-app tarball smoke on Ubuntu and macOS with Node.js 22, validating the packed npm artifact through npx --package.
  • Pushes to main and manually dispatched CI runs also run the bb-app tarball smoke on Ubuntu and macOS with Node.js 24 and 26.
  • Branch protection should require Checks (ubuntu-latest, Node 22.x), Package Smoke (ubuntu-latest, Node 22.x), and Package Smoke (macos-latest, Node 22.x). The Node.js 24 and 26 compatibility smoke jobs do not run on pull requests and should not be configured as required PR checks.
  • Native Windows CI runs on every pull request, described in windows-ci.md: the host package tests with lint and typecheck, the remaining test suites in seven shards, and an app smoke that boots bb-app, runs the bb-app tarball smoke, packages the desktop app, and smoke tests the packaged app.
  • apps/mobile typecheck, lint, and unit tests run inside the Ubuntu Checks and the Tests (packages-*) jobs like every other workspace package. The iOS simulator Maestro flows run in Mobile E2E (.github/workflows/mobile-e2e.yml) on the macOS runner only when a pull request carries the mobile-e2e label, nightly on main, or on manual dispatch; they are not a required check.