Development Setup

Prerequisites

• Rust 1.88+ (rustup update stable)
• Bun — frontend package manager
• FFmpeg — required for local testing
• just — task runner

Node.js is not required. Alchemist uses Bun for all frontend tooling.

Clone and run

git clone https://github.com/bybrooklyn/alchemist.git
cd alchemist
just install        # macOS / Linux bootstrap
just install-w      # Windows bootstrap
just dev            # supported on macOS, Linux, and Windows

Common tasks

just install        # macOS / Linux bootstrap
just install-w      # Windows bootstrap
just check          # supported on macOS, Linux, and Windows
just test           # cargo test
just test-e2e       # Playwright reliability suite
just mac-check      # native/mac Swift package check, macOS only
just db-reset       # wipe dev DB, keep config
just db-reset-all   # wipe DB and config (re-triggers wizard)
just bump <version> # bump version in all repo version files
just update <version> # full guarded release flow (Unix-first)

Native macOS client

The SwiftUI companion app is isolated under native/mac. Use the repo-level just recipes rather than ad hoc Swift commands:

just mac-build
just mac-test
just mac-check
just mac-run
just mac-run-bundled

just mac-run-bundled builds and stages the Rust daemon as native/mac/.artifacts/alchemistd, then launches the SwiftUI app with ALCHEMIST_DAEMON_PATH set for bundled-mode testing.

Windows contributor support

Windows contributor support covers the core path:

• just install-w
• just dev
• just check

The following remain Unix-first for now:

• broader just utility recipes such as database and Docker helpers
• release-oriented guarded flows such as just update
• full Playwright contributor parity outside the documented manual verification path

Frontend only

cd web
bun install --frozen-lockfile
bun run dev         # dev server on :4321
bun run typecheck   # TypeScript check
bun run build       # production build

Backend only

cargo run           # starts on :3000, or the next free port if 3000 is busy
cargo clippy -- -D warnings
cargo fmt

Use ALCHEMIST_SERVER_PORT=<port> cargo run to require a specific port. Startup prints an INFO line with the exact http://127.0.0.1:<port> link to open.