Contributing

Welcome to PilotDeck development. This guide covers local setup, workflow, and project conventions.

Development Setup

Requirements

Dependency	Version
macOS	Sonoma (14) or later
Node.js	v18+, v22 recommended
npm	v9+
Git	latest
TypeScript	v5.9+, installed in the project

Clone and Initialize

git clone https://github.com/OpenBMB/PilotDeck.git
cd PilotDeck

npm install
npm run build

cd ui
npm install
npm run build
cd ..

Development Mode

npm run dev

npm run dev runs scripts/dev-launcher.mjs and performs:

1. predev hook to initialize config files
2. Gateway Server with hot reload
3. Web UI dev server with Vite HMR

You can also start components separately:

# Terminal 1: Gateway Server with tsx hot reload
npm run server

# Terminal 2: UI Bridge server
npm --prefix ui run server

# Terminal 3: Web UI dev server
npm --prefix ui run client

# Or use concurrently
npm --prefix ui run dev:concurrent

Coding Standards

TypeScript

• Use strict TypeScript (strict: true)
• Prefer type over interface where consistent with local style
• Use export type {} for type-only exports
• Use .js extensions in ESM import paths

// Recommended
import { createGateway, type Gateway } from "../gateway/index.js";

// Avoid
import { createGateway, Gateway } from "../gateway/index";

Module Boundaries

Each src/<module>/ directory exposes public API through index.ts.

注意 · Warning

• Do not import another module's internal files directly.
• Do not create circular dependencies.
• Keep dependency direction from higher-level modules to lower-level modules.

Naming

Category	Convention	Example
File name	PascalCase for classes/components, camelCase for utilities	RouterRuntime.ts, decideScenario.ts
Class/type	PascalCase	SessionRouter, RouterDecision
Function	camelCase	createGateway, loadPilotConfig
Constant	UPPER_SNAKE_CASE	DEFAULT_PILOT_HOME
Directory	kebab-case	always-on, pilot-config

Git Workflow

Branch	Purpose
main	stable trunk
feature/<name>	feature work
fix/<name>	bug fixes
refactor/<name>	refactors

Commit messages use semantic format:

<type>(<scope>): <description>

feat(router): add custom router plugin support
fix(gateway): handle WebSocket reconnection timeout
docs(config): update YAML schema documentation
test(router): add TokenSaver decision unit tests

Build

npm run build
npm --prefix ui run build
npm --prefix ui run typecheck

PR Checklist

1. 1
   Backend builds locally

   npm run build

2. 2
   Tests pass

   npm test

3. 3
   UI typecheck passes when relevant

   npm --prefix ui run typecheck

4. 4
   Docs are updated

   If you changed config schema, CLI commands, or public APIs, update related docs.