Development Workflow

Code Style

• No explanatory comments in code. TODO comments are allowed.
• Rust edition: 2024
• Rust file layout: mod declarations go at the very top of the file, then use statements below them. No blank lines between consecutive mod declarations, nor between consecutive use statements.
• Run cargo clippy and fix all warnings before committing.
• Run cargo fmt before committing.
• Tests must pass.

These rules apply across all crates in the workspace (see individual CLAUDE.md files in each crate).

Dev Cycle (Forte Project)

1. forte dev — starts the dev server (Vite HMR + Rust rebuild on change)
2. Make changes to rs/src/ or fe/src/
3. The dev server auto-rebuilds and reloads
4. Write tests and run them
5. cargo clippy && cargo fmt
6. forte build — verify the production build works

Running Tests

Rust tests

# From workspace root
cargo test

# Single crate
cargo test -p forte-sdk
cargo test -p fn0-doc-db

Async tests in forte-sdk / backend crates

Use #[forte_sdk::test] (not #[tokio::test]) for async tests in WASM-compiled crates:

#[forte_sdk::test]
async fn my_async_test() {
    // ...
}

This macro uses forte_sdk::runtime::block_on which is compatible with the WASI async runtime.

doc-db integration tests

doc-db and object-storage compile to wasm32-wasip2 for tests (configured in their .cargo/config.toml). Two prerequisites:

1. forte-test-runner in PATH — the configured WASM test runner. Install from the monorepo:

cargo install --path forte/test-runner

2. Running libSQL server:

docker-compose up -d

Then run the tests:

cargo test -p fn0-doc-db
cargo test -p fn0-object-storage

forte-sdk and other non-WASM crates do not require the test runner and run with the default host target.

Build Targets

All native Linux binaries are compiled using scripts/build-rust-linux-arm64-bin.sh <package> <out_dir>, which runs cargo build --release inside a rust:bookworm container. The repo is bind-mounted and target/ + cargo-registry live on persistent named Docker volumes (fn0-build-target, fn0-build-cargo-registry) to keep incremental compilation fast across runs. Do not replace this with a COPY-into-docker build flow — that would rebuild the full dependency graph on every source change.

Workspace Layout

The Cargo workspace root (/Cargo.toml) includes:

[workspace]
members = ["fn0/*", "forte/*", "doc-db", "object-storage"]
exclude = ["vendor/*", "forte/rs-to-ts", "fn0/control"]

forte/rs-to-ts and fn0/control are excluded from the workspace and must be built separately.

Code Generation (forte-codegen)

Code generation runs as part of cargo build via build.rs. If route_generated.rs looks wrong after adding/removing pages or actions, run:

cargo build  # inside rs/ or forte project root

Or forte build to regenerate everything including TypeScript types.

Never edit route_generated.rs, actions/mod.rs, admin/mod.rs, queue_task/mod.rs, or the FORTE-MANAGED block in lib.rs manually.

Release Process

Releases are managed via cargo-dist and GitHub Actions:

• publish.yml — triggers on push to main, runs cargo-release, creates version tags for forte-cli, fn0-cli, and forte-rs-to-ts
• release-release.yml — cargo-dist autogenerated; triggers on release/-namespaced version tags, builds release artifacts and creates GitHub releases for forte-cli and fn0-cli
• release-forte-rs-to-ts.yml — specialized release pipeline for forte-rs-to-ts

Version tags: forte-cli and fn0-cli use the cargo-dist release/ tag namespace (release/forte-cli-v0.3.37, release/fn0-cli-v0.1.5); forte-rs-to-ts keeps its own forte-rs-to-ts-v0.1.9 form. The namespace keeps forte-rs-to-ts tags out of cargo-dist's release-release.yml trigger.

Infrastructure

Infrastructure is managed in infra/:

• infra/pulumi/ — Pulumi IaC for cloud resources
• infra/cloud/ — Cloud provider configurations (AWS, OCI)
• infra/r2-worker/ — Cloudflare R2 worker for blob storage

Scaling configuration: scripts/scale-config.sh

Local Database

forte dev downloads and starts sqld automatically — no manual setup needed for Forte projects. For running doc-db tests directly, see setup.md.