This page provides technical instructions for setting up the executor development environment, running the monorepo's various host applications, and executing the test suites.
The executor repository is a TypeScript monorepo managed by Bun and Turbo. It utilizes Effect for functional programming and Vitest for testing.
To set up a fresh checkout or worktree, run the bootstrap script. This script handles dependency installation and initial build steps required for the packages to reference each other correctly.
Sources: package.json33 AGENTS.md5-6
| Command | Description |
|---|---|
bun install | Installs dependencies and updates the bun.lock file. |
bun run lint | Runs oxlint across the codebase to ensure code quality. package.json45 |
bun run typecheck | Runs tsc (via tsgo) to verify types across all packages. package.json42 |
bun run format | Formats the codebase using oxfmt. package.json51 |
The monorepo contains several host environments that compose the shared SDK and API layers.
The CLI can be run in development mode, which points to a local data directory for its SQLite database and configuration.
Sources: package.json37 apps/cli/package.json5-7
To run the local development server (excluding Desktop and Cloud variants), use the dev command. This boots the local API server and the Vite-based frontend.
Sources: package.json35
The desktop application requires a sidecar build (the CLI daemon) before it can be started in development.
Sources: package.json36 apps/desktop/package.json10-11
Running the cloud host locally involves wrangler, portless for proxying, and a local pglite database.
Sources: apps/cloud/package.json7-10
The following diagram illustrates how the bootstrap and dev commands interact with the monorepo structure to prepare the environment.
Sources: package.json33-41 AGENTS.md68-78
Executor uses Vitest for unit/integration tests and Playwright for E2E scenarios.
Tests are located within individual packages and apps. Use turbo to run tests across the monorepo or vitest for specific files. Never use bun test as the codebase relies on Effect Vitest features.
Sources: package.json38 AGENTS.md10-12
The e2e directory contains a specialized test runner that can target different host environments (Cloud, Self-host, Local).
Sources: package.json39 e2e/package.json8-13
For tests requiring upstream APIs (e.g., Google, GitHub, Microsoft), the codebase uses @executor-js/emulate. These are wire-level stateful emulators that provide real OpenAPI specs and record requests for assertions.
Sources: AGENTS.md27-37
The following diagram maps the logical "Getting Started" actions to the specific scripts and entities in the codebase.
Sources: package.json32-42 e2e/package.json7 AGENTS.md68
| Path | Purpose |
|---|---|
scripts/bootstrap.ts | Entry point for repository initialization. package.json33 |
apps/cli/src/main.ts | Entry point for the CLI host. apps/cli/package.json6 |
e2e/scripts/ | Utilities for managing E2E ports and test summaries. e2e/package.json15-16 |
bun.lock | Dependency lockfile for the entire workspace. bun.lock1 |
AGENTS.md | Core principles and development standards. AGENTS.md1 |
Sources: package.json33 apps/cli/package.json6 e2e/package.json15-16 AGENTS.md1
Refresh this wiki