# Contributing to Yardsort Thank you for being here. Bug reports, ideas, documentation fixes and code are all welcome, and small contributions are as appreciated as large ones. By taking part you agree to follow the [Code of Conduct](CODE_OF_CONDUCT.md). Contributions are licensed under the project's [GPL-3.0 license](LICENSE), apart from those to the remote server, `crates/server`, which are under its [AGPL-3.0 license](crates/server/LICENSE), and those to the phone app, `apps/mobile`, and its TypeScript protocol client, `packages/remote-client`, which are under their [MPL-2.0 license](apps/mobile/LICENSE) ([why](docs/design/30-open-source-and-managed.md)). ## Ways to help - **Report a bug** or **suggest a feature** — [open an issue](https://github.com/joaoh82/yardsort/issues/new/choose). - **Try it on your system.** Yardsort targets Linux, macOS and Windows; reports from real machines — especially Windows, and Linux desktops other than the author's — are gold. - **Add or correct a harness.** Agent CLIs change their flags often. If a built-in definition is out of date, a one-line fix in `src-tauri/src/harness.rs` helps everyone. - **Improve the docs.** If something confused you, it will confuse the next person. Not sure whether an idea fits? Open an issue first — it is cheaper than a pull request nobody expected. The [vision](docs/design/01-vision.md) and [roadmap](docs/design/05-roadmap.md) say where the project is heading and what it deliberately is not. ## Getting set up You need [Rust](https://rustup.rs) (stable), [Bun](https://bun.sh), git, [`just`](https://just.systems) (`cargo install just`) and Tauri's [system dependencies](https://tauri.app/start/prerequisites/) for your OS. ```sh git clone https://github.com/joaoh82/yardsort && cd yardsort just setup just dev ``` Useful while developing: | Command | Does | | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `just dev` | Run the app with hot reload. | | `just check` | Everything CI checks except the bindings: formatting, lints, types, all tests. | | `just test-rust` / `just test-web` | One side's tests; both take extra arguments. | | `just test-client` | The TypeScript protocol client's tests (`packages/remote-client`), against a real server and host it starts with Cargo. | | `just test-mobile` | The phone app's tests (`apps/mobile`): its logic against that same server, its screens under Jest. | | `just mobile-ios` | Build the phone app's development build onto an iPhone plugged into a Mac, and serve its code. See `apps/mobile/README.md`. | | `just fmt` | Format Rust and TypeScript. | | `just bindings-check` | Fail if the generated TypeScript bindings are stale. Run before pushing. | | `just lint-windows` | Clippy the PTY crates for Windows from any OS. | | `YARDSORT_DATA_DIR=/tmp/ys just dev` | Run against a throwaway database and settings file. A development build never uses your real ones: unset, it takes `dev.yardsort.app.development` beside them. | ## How the code is laid out ``` crates/pty-host/ Owns pseudo-terminals and the processes in them. No Tauri, no UI. Tested against real processes in real PTYs. crates/pty-ipc/ The wire between the app and the daemon that runs that host: framing, the server loop, and a client that is itself a TerminalHost. crates/remote-proto/ The remote protocol: versioned request, reply and terminal-frame types, their limits and validation. Data only — no transport, no listener. crates/remote-client/ A device's side of the server's HTTP API and relay: signing in through the browser, refreshing, devices, hosts, pairing and relay sockets. The app uses it as a host. crates/remote-host/ The host's outbound connector: keeps the link to the server's relay and answers each device on it from the core (remote::serve). The app runs it; a headless host will. crates/dashboard/ The host dashboard: a web page a computer serves to itself on 127.0.0.1, for setting it up from a browser. Its sign-in, its jobs, its tunnel and the page (ui/, plain files built into the program). `yardsort-host` and the app both serve it, each through the one trait it asks of them. Tested over real HTTP. packages/remote-client/ The same device's side in TypeScript, for the phone app: the protocol's types and their limits, signing in, pairing and relay channels. Its own Bun project, with no dependencies, under MPL-2.0. Tested against the Rust side's fixtures and a real server (crates/server/examples/stand-in.rs). apps/mobile/ The phone app: Expo, Expo Router, its screens in src/app/ and what they call in src/lib/. Its own Bun project, under MPL-2.0. See its README. crates/server/ The remote server: signing in through an OIDC provider, accounts, devices, migrations/ their credentials and the relay, kept in PostgreSQL and served over HTTP. Its own dev/ numbered SQL files, append-only like the core's; dev/ is the local fly/ environment (see "Working on the server"); fly/ is how staging runs on self-host/ Fly.io; self-host/ is the recipe for running it yourself. Dockerfile builds its image. crates/core/ Everything both clients share and no UI belongs in: the SQLite store, src/ git, projects, workspaces, settings, harnesses, workflow files, the launch environment, and finding or starting the daemon. No Tauri — linking the app's lib would drag WebKitGTK into a command-line tool. migrations/ Numbered SQL files. Never edit a shipped one — add a new one. src-tauri/ The Tauri app: the webview, the IPC commands, the file watcher, Assist, src/ updates, and the quit dialog. The core is re-exported under its own module names, so `crate::store` here is `yardsort_core::store`. The same binary is the daemon, run with --yardsort-daemon. src/ The React + TypeScript frontend. features/ One folder per area of the UI. stores/ Zustand stores. lib/ipc.ts The only module that talks to the core. lib/bindings.ts GENERATED from the Rust commands by tauri-specta. Never edit by hand. docs/ User documentation; docs/design/ holds architecture and planning. website/ The project website: its own Next.js app. It renders docs/ and CHANGELOG.md, so it has no copy of them. See website/README.md. ``` Two principles explain most design decisions — more in [architecture](docs/design/03-architecture.md): 1. **The frontend holds no truth.** State lives in the Rust core; the UI renders it and sends intents. Paths, for instance, never come from the webview. 2. **The terminal is the truth.** Agents run in a real PTY and their output is never parsed. Status, readiness and notifications all derive from _activity_, not content. 3. **The app is a client.** The terminals belong to the daemon, not the window, so closing the window is a disconnect — never a kill. ## Working on the server The remote server (`crates/server`, the `yardsort-server` binary) needs PostgreSQL and an identity provider to sign in with. Locally both run in Docker, so install Docker with Compose and make sure your user can reach it; nothing is installed on the machine itself. The server runs on the host, so a change rebuilds in seconds. | Command | What it does | | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `just server-up` | Starts PostgreSQL and a throwaway ZITADEL (`crates/server/dev/compose.yaml`), creates the server's app in ZITADEL, and writes the server's settings to `crates/server/dev/server.env.local`. | | `just server-run` | Runs the server against them at `http://127.0.0.1:8787`. | | `just server-sign-in` | Signs a pretend device in through your browser, as the app will, then lists devices, refreshes and revokes itself. Sign in as `developer@yardsort.test`, password `Yardsort-dev-1`. | | `just server-pair` | Stands in for a phone pairing with a host (`phone [SERVER] CODE`), or for a host showing a code (`host [SERVER]`). Signs in through your browser, as `just server-sign-in` does. `--relay` then reaches the host through the relay. | | `just client-pair` | The same pretend phone in TypeScript, through `packages/remote-client` alone (`[SERVER] CODE`, or the `yardsort://pair` link): pairs, watches a terminal through the relay, a shell first, `--type TEXT` types into it (one word through `just`; more with `bun tools/pair.ts` in the package), `--wait-for-revoke` waits for the channel to close and asks the server what was revoked. `devices [SERVER] [--revoke DEVICE]` lists the account's devices and revokes one. | | `just server-test` | The server's tests, with their PostgreSQL half against the local database. Plain `cargo test` skips that half when the containers are not up. | | `just server-image` | Builds the server's container image, `yardsort-server:dev` (`crates/server/Dockerfile`). | | `just server-e2e` | Runs that image against the containers, signs in through ZITADEL without a browser, revokes the account from inside the image, then pairs a pretend phone with a pretend host, which the relay tells of the phone asking, and the phone types into the host's program through the relay, then leaves its stream and resumes it, and hears of a program the host started and that ended. What CI's "Server end to end" job runs. Linux only. | | `just server-down` / `-reset` | Stops the containers; `reset` also forgets everything in them. | ZITADEL's admin console is at `http://127.0.0.1:8080/ui/console`, with the same sign-in. Every password and key in the development environment is a well-known value, and everything listens on `127.0.0.1` only: never reuse any of it anywhere reachable. Where the real server will run, and the accounts behind it, is [28](docs/design/28-remote-infrastructure.md). Staging deploys by hand, from Actions → **Deploy the server**, which the owner runs. Running the server yourself is [crates/server/self-host/README.md](crates/server/self-host/README.md). Each slice of the server ends with a smoke test a person runs, locally and on staging: [27 §19](docs/design/27-remote-r2.md#19--smoke-tests). To try the headless host on a real Linux server, with your phone, `scripts/test-box.sh` makes a throwaway one on Hetzner Cloud, builds your checkout there, and deletes it when you are done: [A test box for Remote](docs/test-box.md). ## Making a change 1. Branch from `main`. 2. Make the change, **with tests**. The bar: a test should fail without your change. Rust logic is tested against real git repositories and real processes, not mocks; UI is tested with Testing Library through what the user sees and does. 3. **Update the docs.** If behaviour a user can see changed, the [user guide](docs/README.md) changes in the same pull request. Docs that lag the app are treated as bugs. 4. Changed a Rust command or a type that crosses IPC? Run `cargo test` (or `just dev`) to regenerate `src/lib/bindings.ts`, and commit it. 5. `just check && just bindings-check`. 6. Open a pull request describing **what** changed and **why**, and how you tested it. Screenshots help for anything visual. CI runs the checks on Linux, macOS and Windows. Platform-specific failures are common in this codebase — that is what the matrix is for — so do not be discouraged by a red Windows run; the logs usually say exactly what differed. A ruleset on `main` requires all three `Check` jobs and `Website` to pass before a pull request merges, so `gh pr merge --auto` waits for them; `main` cannot be deleted or force-pushed. Repository admins can bypass it — which is what lets `just release` push its version commit and tag straight to `main`. ### Style - Rust: `rustfmt` and `clippy` with warnings as errors. TypeScript: Prettier and ESLint. - Comments explain **why**, not what. Match the density of the code around you. - Error messages are for users: say what happened and what they can do about it. - Anything that can destroy user work — deleting, archiving, overwriting — needs an explicit confirmation that names what will be lost, and a test that proves a "no" is respected. - App shortcuts go behind **Mod** (`⌘`, or `Ctrl+Shift`). Plain `Ctrl`+letter belongs to the program in the terminal — see [shortcuts](docs/guide/shortcuts.md). ### Commit messages A short imperative summary line, then — if it helps — a body explaining why. No particular convention is enforced. ## Releases Maintainers cut releases by pushing a version tag; see [docs/releasing.md](docs/releasing.md).