Skip to content

development.md

Latest commit

 

History

History
117 lines (93 loc) · 5.93 KB

development.md

File metadata and controls

117 lines (93 loc) · 5.93 KB
Raw

Development

This page summarizes how to set up a Bitlab development environment and which commands match which release artifact.

Requirements

Tool Version Why
Bun 1.3.14+ Workspace, runtime, builds (bun.lock)
Node ≥ 18 (Bun ships it for fallbacks) TypeScript toolchain
Python 3.12 Document-tool smoke tests
uv latest compatible for development; 0.10.6 in desktop release builds Runs document-tool smoke tests and prepares assets; packaged artifacts bundle their target-platform binary
Git any modern version pre-commit-style checks via husky are opt-in

bun is the only workspace linker; npm/yarn are not used to install dependencies because bun.lock is the source of truth.

First-time setup

git clone https://github.com/limboinf/bitlab-agent.git
cd bitlab
bun install --frozen-lockfile
bun run validate:dev

If you have to add or upgrade a dependency, edit the appropriate package.json, run bun install (without --frozen-lockfile) to refresh bun.lock, and re-run bun install --frozen-lockfile to confirm deterministic resolution.

Workspace layout

apps/
  electron/    # Electron desktop (main, preload, renderer, Browser pane)
  webui/       # Loads the same renderer through a browser adapter
  website/     # Static bilingual product website (Astro)
packages/
  core/                # Stable DTOs, AgentEvent, error codes
  shared/              # Config, credentials, prompts, Skills, theme, i18n
  ui/                  # React primitives, markdown/code/doc renderers
  server-core/         # Transport, RPC, SessionManager, runtime
  server/              # Headless BITLAB_SERVER_TOKEN server
  pi-agent-server/     # Pi SDK subprocess (Bun, JSONL on stdio)
  session-tools-core/  # Plan / Skill / mini LLM / browser / session info / list
docs/                  # English-language documentation
docs/zh/               # Chinese translation
scripts/               # Dev / build / lint / audit
migration/             # Migration plan, audit, UI history

apps/online-docs is intentionally outside the workspace globs.

Common commands

Goal Command
Install dependencies (CI-mode) bun install --frozen-lockfile
Quick offline install bun install --force (rare, recovers a broken lockfile)
Run Electron in dev (vite + electron) bun run electron:dev
Run Electron from a prebuilt apps/electron/dist/ bun run electron:start
Start the headless server with the WebUI dev bundle bun run server:dev:webui
Start the product website bun run website:dev
Build the product website bun run website:build
Production headless server (WebUI bundled, Pi built) bun run server:prod
Build the Pi subprocess bun run server:build:subprocess
Build a dev-signed macOS arm64 .app bun run electron:dist:dev:mac
Run all unit + isolated tests bun run test
Validate (typecheck + tests + shared suite + doc tool smoke + lint) bun run validate:ci
Lint English/Chinese locale parity bun run lint:i18n:parity
Sort locales bun run sort-locales (check-only: bun run lint:i18n:sorted)

Isolate the config directory

The configuration root defaults to ~/.bitlab but can be redirected for parallel development or isolated tests:

BITLAB_CONFIG_DIR=/tmp/bitlab-dev bun run server:dev:webui

BITLAB_CONFIG_DIR is read once at module-load (packages/shared/src/config/paths.ts) and influences every downstream path (workspaces, credentials, logs, tool icons). Tests inject the env var explicitly; they do not create files in $HOME.

Useful environment variables

Variable Default Effect
BITLAB_CONFIG_DIR ~/.bitlab Override the configuration root (also called the "data directory")
BITLAB_SERVER_TOKEN — Required bearer token for headless server RPC auth
BITLAB_RPC_HOST / BITLAB_RPC_PORT 127.0.0.1 / 9100 Server bind address / port
BITLAB_RPC_TLS_CERT / _KEY / _CA — Enable wss:// with PEM-encoded cert/key; CA is optional
BITLAB_HEALTH_PORT 0 (off) Bind a sidecar HTTP health endpoint
BITLAB_APP_ROOT repo root (dev) Where the server reads bundled assets
BITLAB_RESOURCES_PATH same as app root Override the resources directory
BITLAB_BUNDLED_ASSETS_ROOT unset Dev-only override that points the headless server at apps/electron resources
BITLAB_IS_PACKAGED false Set to true inside production builds
BITLAB_VERSION package.json#version Override the reported server version
BITLAB_DEBUG unset Enable extra debug logging
BITLAB_WEBUI_DIR unset Enable WebUI assets on the RPC port
BITLAB_WEBUI_PASSWORD / _SECURE_COOKIE / _WS_URL unset WebUI login password, cookie Secure flag override, and browser-side ws:// URL
BITLAB_PI_MODEL_API unset Interceptor-level Pi model hint
BITLAB_UV / BITLAB_BUN / BITLAB_NODE unset Override script runtimes; packaged launchers normally inject absolute bundled paths, while development may fall back to PATH
BITLAB_DEV_RUNTIME unset Set to 1 to skip code-signing during local packaging

Conventions

  • Reuse existing package boundaries and naming before adding new abstractions.
  • Reference checkouts (craft-agents-oss, echo, xagent) are read-only; never commit changes to them.
  • Every module change ships with its tests and a documentation update.
  • Run git diff --check before commit and confirm the changed files are only what you intended.

Clean-worktree validation pattern

When working on a detached or fresh worktree, dependencies are not hoisted by default:

bun install --force --frozen-lockfile
bun run validate:ci

This combination has passed Bitlab's full gate on a clean checkout (see migration/migration-features.md, "最终验证结果"). Audio/screen-recording permissions are not required because the gate never starts a GUI.