From fd519ab254270e10c190d0f207d05acf0b1aea3f Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 10 May 2026 08:27:19 +0000 Subject: [PATCH] docs(make): align local cargo commands with CI's jarvis-desktop exclusion `cargo check/clippy/test --workspace` fail on Linux without WebKitGTK + GObject system libs because `jarvis-desktop` (Tauri) pulls in `gdk-sys`. Linux CI has worked around this with `--exclude jarvis-desktop` since the crate landed; the Makefile and CLAUDE.md / AGENTS.md command snippets still advertised the unflagged commands, so a fresh dev box hits a confusing pkg-config failure on first `make check`. - Makefile: thread `WORKSPACE_EXCLUDE ?= --exclude jarvis-desktop` through `lint` and `test` (and therefore `check`). Override with `WORKSPACE_EXCLUDE=` on a machine with the GTK toolchain installed. - CLAUDE.md / AGENTS.md: update the `## Commands` block and the "Clippy is the gate" rule to match CI verbatim, with one paragraph explaining why and pointing at the Makefile escape hatch. No code change; no functional behaviour change. --- AGENTS.md | 23 ++++++++++++++++------- CLAUDE.md | 23 ++++++++++++++++------- Makefile | 13 +++++++++++-- 3 files changed, 43 insertions(+), 16 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9fca036..c4facc4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -37,14 +37,22 @@ member crates always reference deps as `foo.workspace = true`. New crates go und ## Commands ```bash -cargo check --workspace -cargo clippy --workspace --all-targets -- -D warnings # CI gate -cargo test --workspace -cargo test -p harness-core message:: # filter by path -cargo run -p jarvis # needs OPENAI_API_KEY +cargo check --workspace --exclude jarvis-desktop +cargo clippy --workspace --all-targets --exclude jarvis-desktop -- -D warnings # CI gate +cargo test --workspace --exclude jarvis-desktop +cargo test -p harness-core message:: # filter by path +cargo run -p jarvis # needs OPENAI_API_KEY cargo build --release -p jarvis ``` +`--exclude jarvis-desktop` matches Linux CI: the Tauri crate needs +WebKitGTK + GObject system libs (`libgtk-3-dev`, `libwebkit2gtk-4.1-dev`, +`librsvg2-dev`) that aren't installed on a stock dev box. Drop the flag +once you've installed the GTK toolchain locally, or use the `Makefile` +targets (`make check` / `make lint` / `make test`) which apply the +exclusion automatically — override with `WORKSPACE_EXCLUDE=` on a fully +provisioned machine. + Env vars consumed by the `jarvis` binary: `OPENAI_API_KEY` (required unless `--mcp-serve` is passed), `JARVIS_MODEL` (default `gpt-4o-mini`), `OPENAI_BASE_URL`, `JARVIS_ADDR` (default `0.0.0.0:7001`), @@ -240,8 +248,9 @@ not read `std::env`. New tools, providers, or middlewares get registered here. `anyhow` freely. - **Errors:** library code uses `thiserror`-derived `Error` in `harness-core`; provider errors get wrapped in `Error::Provider(String)` rather than leaking `reqwest::Error`. -- **Clippy is the gate.** `cargo clippy --workspace --all-targets -- -D warnings` must - pass; the existing code is clean against it. +- **Clippy is the gate.** `cargo clippy --workspace --all-targets --exclude jarvis-desktop -- -D warnings` + must pass; the existing code is clean against it. CI runs the same command + (see `.github/workflows/rust.yml`); `make lint` wraps it. - **Streaming lives on its own method.** `LlmProvider::complete_stream` is a parallel entry point to `complete`; don't retrofit `complete`'s return type. New providers can skip it — the default impl returns a stream that calls diff --git a/CLAUDE.md b/CLAUDE.md index dd3dbf4..342da1b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -56,14 +56,22 @@ member crates always reference deps as `foo.workspace = true`. New crates go und ## Commands ```bash -cargo check --workspace -cargo clippy --workspace --all-targets -- -D warnings # CI gate -cargo test --workspace -cargo test -p harness-core message:: # filter by path -cargo run -p jarvis # needs OPENAI_API_KEY +cargo check --workspace --exclude jarvis-desktop +cargo clippy --workspace --all-targets --exclude jarvis-desktop -- -D warnings # CI gate +cargo test --workspace --exclude jarvis-desktop +cargo test -p harness-core message:: # filter by path +cargo run -p jarvis # needs OPENAI_API_KEY cargo build --release -p jarvis ``` +`--exclude jarvis-desktop` matches Linux CI: the Tauri crate needs +WebKitGTK + GObject system libs (`libgtk-3-dev`, `libwebkit2gtk-4.1-dev`, +`librsvg2-dev`) that aren't installed on a stock dev box. Drop the flag +once you've installed the GTK toolchain locally, or use the `Makefile` +targets (`make check` / `make lint` / `make test`) which apply the +exclusion automatically — override with `WORKSPACE_EXCLUDE=` on a fully +provisioned machine. + Env vars consumed by the `jarvis` binary: `JARVIS_PROVIDER` (`openai` (default), `openai-responses`, `anthropic`, `google`, `codex`, `kimi`, or `ollama`), `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` / `GOOGLE_API_KEY` / @@ -978,8 +986,9 @@ are usually marketing / human-PR docs, not agent guidance. `anyhow` freely. - **Errors:** library code uses `thiserror`-derived `Error` in `harness-core`; provider errors get wrapped in `Error::Provider(String)` rather than leaking `reqwest::Error`. -- **Clippy is the gate.** `cargo clippy --workspace --all-targets -- -D warnings` must - pass; the existing code is clean against it. +- **Clippy is the gate.** `cargo clippy --workspace --all-targets --exclude jarvis-desktop -- -D warnings` + must pass; the existing code is clean against it. CI runs the same command + (see `.github/workflows/rust.yml`); `make lint` wraps it. - **Streaming lives on its own method.** `LlmProvider::complete_stream` is a parallel entry point to `complete`; don't retrofit `complete`'s return type. New providers can skip it — the default impl returns a stream that calls diff --git a/Makefile b/Makefile index ad2d0e7..55c3ee1 100644 --- a/Makefile +++ b/Makefile @@ -23,6 +23,15 @@ IMAGE ?= jarvis:local WEB_DIR := apps/jarvis-web WEB_DIST := $(WEB_DIR)/dist +# `jarvis-desktop` is a Tauri shell that requires WebKitGTK + GObject system +# libs on Linux (libgtk-3-dev, libwebkit2gtk-4.1-dev, librsvg2-dev, ...). +# Linux CI excludes it (see .github/workflows/rust.yml) so the default +# workspace targets stay buildable on a stock Ubuntu box without the GTK +# toolchain. Mirror the exclusion here so `make check` matches CI. +# Override `WORKSPACE_EXCLUDE=` (empty) on a machine with the GTK deps +# installed to lint / test the desktop crate too. +WORKSPACE_EXCLUDE ?= --exclude jarvis-desktop + # --------------------------------------------------------------------------- # Help # --------------------------------------------------------------------------- @@ -66,11 +75,11 @@ fmt: ## Format Rust code (rustfmt) .PHONY: lint lint: ## Clippy with -D warnings (CI gate) - $(CARGO) clippy --workspace --all-targets -- -D warnings + $(CARGO) clippy --workspace --all-targets $(WORKSPACE_EXCLUDE) -- -D warnings .PHONY: test test: ## Run the workspace test suite - $(CARGO) test --workspace + $(CARGO) test --workspace $(WORKSPACE_EXCLUDE) .PHONY: check check: lint test ## Run clippy + tests, what CI runs