Skip to content
horsiedocshorsie.dev

Developing horsie

Issues, bug reports and pull requests are all welcome. The repository is blossomstack/horsie, dual-licensed Apache-2.0 or MIT.

Sign the CLA first

Section titled “Sign the CLA first”

Before a first pull request can be merged you need to sign the CLA. A bot comments on the PR with a link; signing takes a moment and covers every future contribution across the organisation. You keep the copyright to everything you write.

The licence is dual Apache-2.0 / MIT today, and the CLA keeps the door open to changing that later without tracking down every past contributor.

Build it

Section titled “Build it”
Terminal window
make build-cli      # the `horsie` binary and its `horsie-runtime` child
make build-server   # `horsie-server`
make build          # the whole workspace
make web            # the web UI dev server
make help           # every target

The three binaries are independent: horsie spawns the sibling horsie-runtime per session, and horsie-server is the standalone server.

Run the gate

Section titled “Run the gate”
Terminal window
make check   # cargo fmt --check, clippy -D warnings, cargo test --workspace

That is the same gate CI runs. Two things to know about running it:

  • Format before clippy. A formatting failure aborts the run, so a clippy fix that is badly formatted looks like a clippy failure the second time.
  • Iterate narrowly. cargo test -p <crate> --lib while working; the whole workspace suite once before pushing. A change to an HTTP route is not verified by -p horsie-server alone — the integration tests and the web e2e suite call those routes too.

The web client is installed with bun, not npm:

Terminal window
cd clients/web && bun install --frozen-lockfile

Generated files

Section titled “Generated files”

Wire and protocol types are generated by fluorite from the schemas under crates/models/fluorite/. Edit the schema, never the generated Rust or TypeScript.

A schema change regenerates two trees — clients/web/src/generated and clients/ts/src/generated. CI guards one of them, so regenerate both and commit both, or the other drifts.

Terminal window
make ts-types

Code conventions

Section titled “Code conventions”

Production code denies unwrap, expect, panic and wildcard match arms; tests opt out per file.

CLAUDE.md at the repository root carries the full design philosophy and the conventions that explain why the code looks the way it does. Read it before a non-trivial change.

Documentation

Section titled “Documentation”

Docs are part of the same repository and the same review. A change that alters behaviour changes its pages in the same pull request.

How to write and structure them is Writing docs.