Merge remote-tracking branch 'origin/main' into initial_revisions

* origin/main:
  Add desktop Home feed (#12)
  Add desktop Playwright e2e harness (#11)
  Update desktop icon and persist window state (#9)
  feat: add channel creation flow (#8)
  Improve message markdown display and formatting (#7)
  feat(desktop): connect chat to relay (#6)
  docs(readme): clarify desktop setup (#4)
  feat: add desktop app (#3)

# Conflicts:
#	crates/sprout-test-client/tests/e2e_rest_api.rs

Author: tlongwell-block

.github/workflows/ci.yml

@@ -8,19 +8,181 @@ env:
   CARGO_TERM_COLOR: always
 
 jobs:
-  check:
+  rust-lint:
+    name: Rust Lint
     runs-on: ubuntu-latest
     timeout-minutes: 30
+    permissions:
+      contents: read
     steps:
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
-      - uses: dtolnay/rust-toolchain@631a55b12751854ce901bb631d5902ceb48146f7 # stable
+      - uses: cashapp/activate-hermit@e49f5cb4dd64ff0b0b659d1d8df499595451155a # v1
+      - uses: Swatinem/rust-cache@ad397744b0d591a723ab90405b7247fac0e6b8db # v2
+      - name: Format check
+        run: just fmt-check
+      - name: Clippy
+        run: just clippy
+
+  unit-tests:
+    name: Unit Tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: cashapp/activate-hermit@e49f5cb4dd64ff0b0b659d1d8df499595451155a # v1
+      - uses: Swatinem/rust-cache@ad397744b0d591a723ab90405b7247fac0e6b8db # v2
+      - name: Unit tests
+        run: just test-unit
+
+  desktop:
+    name: Desktop
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: cashapp/activate-hermit@e49f5cb4dd64ff0b0b659d1d8df499595451155a # v1
+      - uses: Swatinem/rust-cache@ad397744b0d591a723ab90405b7247fac0e6b8db # v2
         with:
-          components: rustfmt, clippy
+          workspaces: desktop/src-tauri
+      - name: Install Tauri dependencies (Linux)
+        env:
+          DEBIAN_FRONTEND: noninteractive
+        run: |
+          sudo apt-get update \
+            -o Acquire::Retries=3 \
+            -o Acquire::http::Timeout=30 \
+            -o Acquire::https::Timeout=30
+          sudo apt-get install -y --no-install-recommends \
+            -o Acquire::Retries=3 \
+            -o Acquire::http::Timeout=30 \
+            -o Acquire::https::Timeout=30 \
+            -o DPkg::Lock::Timeout=120 \
+            build-essential \
+            curl \
+            file \
+            libayatana-appindicator3-dev \
+            libgtk-3-dev \
+            librsvg2-dev \
+            libssl-dev \
+            libwebkit2gtk-4.1-dev \
+            libxdo-dev \
+            patchelf \
+            wget
+      - name: Install desktop dependencies
+        run: just desktop-install-ci
+      - name: Install Playwright Chromium
+        run: cd desktop && pnpm exec playwright install --with-deps chromium
+      - name: Desktop lint and format
+        run: just desktop-check
+      - name: Desktop build
+        run: just desktop-build
+      - name: Desktop smoke e2e
+        run: cd desktop && pnpm exec playwright test --project=smoke
+      - name: Desktop Tauri check
+        run: just desktop-tauri-check
+      - name: Upload desktop e2e artifacts
+        if: failure()
+        uses: actions/upload-artifact@65462800fd760344b1a7b4382951275a0abb4808 # v4
+        with:
+          name: desktop-e2e-artifacts
+          path: |
+            desktop/playwright-report
+            desktop/test-results
+          if-no-files-found: ignore
+
+  desktop-e2e-integration:
+    name: Desktop E2E Integration
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: cashapp/activate-hermit@e49f5cb4dd64ff0b0b659d1d8df499595451155a # v1
       - uses: Swatinem/rust-cache@ad397744b0d591a723ab90405b7247fac0e6b8db # v2
-      - run: cargo fmt --all -- --check
-      - run: cargo clippy --workspace --all-targets -- -D warnings
-      - run: cargo test --workspace
-      - run: cargo install cargo-audit --locked
-      - run: cargo audit --ignore RUSTSEC-2023-0071 --ignore RUSTSEC-2024-0384
-      - run: cargo install cargo-deny --locked
-      - run: cargo deny check
+        with:
+          workspaces: desktop/src-tauri
+      - name: Install desktop dependencies
+        run: just desktop-install-ci
+      - name: Install Playwright Chromium
+        run: cd desktop && pnpm exec playwright install --with-deps chromium
+      - name: Desktop build
+        run: just desktop-build
+      - name: Start integration services
+        run: docker compose up -d
+      - name: Wait for integration services
+        run: |
+          wait_healthy() {
+            local service="$1"
+            local container="$2"
+            for attempt in $(seq 1 60); do
+              status=$(docker inspect --format='{{.State.Health.Status}}' "${container}" 2>/dev/null || echo "not_found")
+              if [ "${status}" = "healthy" ]; then
+                echo "${service} is healthy"
+                return 0
+              fi
+              sleep 2
+            done
+            docker logs "${container}" || true
+            return 1
+          }
+          wait_healthy "MySQL" "sprout-mysql"
+          wait_healthy "Redis" "sprout-redis"
+          wait_healthy "Typesense" "sprout-typesense"
+      - name: Build relay
+        run: cargo build -p sprout-relay
+      - name: Start relay
+        run: |
+          nohup env \
+            DATABASE_URL=mysql://sprout:sprout_dev@localhost:3306/sprout \
+            REDIS_URL=redis://localhost:6379 \
+            TYPESENSE_URL=http://localhost:8108 \
+            TYPESENSE_API_KEY=sprout_dev_key \
+            RELAY_URL=ws://localhost:3000 \
+            SPROUT_BIND_ADDR=0.0.0.0:3000 \
+            SPROUT_REQUIRE_AUTH_TOKEN=false \
+            ./target/debug/sprout-relay > /tmp/sprout-relay.log 2>&1 &
+          echo $! > /tmp/sprout-relay.pid
+          for attempt in $(seq 1 60); do
+            if ! kill -0 "$(cat /tmp/sprout-relay.pid)" 2>/dev/null; then
+              cat /tmp/sprout-relay.log
+              exit 1
+            fi
+            status_code=$(curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:3000/api/channels || true)
+            if [ "${status_code}" != "000" ]; then
+              exit 0
+            fi
+            sleep 1
+          done
+          cat /tmp/sprout-relay.log
+          exit 1
+      - name: Seed desktop e2e data
+        run: bash scripts/setup-desktop-test-data.sh
+      - name: Desktop relay-backed e2e
+        run: cd desktop && pnpm exec playwright test --project=integration
+      - name: Upload desktop integration artifacts
+        if: failure()
+        uses: actions/upload-artifact@65462800fd760344b1a7b4382951275a0abb4808 # v4
+        with:
+          name: desktop-e2e-integration-artifacts
+          path: |
+            desktop/playwright-report
+            desktop/test-results
+            /tmp/sprout-relay.log
+          if-no-files-found: ignore
+
+  security:
+    name: Security
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: cashapp/activate-hermit@e49f5cb4dd64ff0b0b659d1d8df499595451155a # v1
+      - name: Dependency policy
+        run: cargo-deny check

.gitignore

@@ -21,6 +21,11 @@ Thumbs.db
 # Scratch / working files (AI reviews, notes, drafts)
 .scratch/
 
+# Playwright artifacts
+playwright-report/
+test-results/
+blob-report/
+
 # sqlx offline query data (generated, not portable)
 .sqlx/
 

CONTRIBUTING.md

@@ -39,8 +39,11 @@ unacceptable behavior to **conduct@sprout-relay.org**.
 | Tool | Version | Notes |
 |------|---------|-------|
 | Rust | 1.88+ | Install via [rustup](https://rustup.rs/) |
+| Node.js | 24+ | Required for desktop app commands and `just ci` |
+| pnpm | 10+ | Required for desktop app commands and `just ci` |
 | Docker | 24+ | For MySQL, Redis, Typesense |
 | `just` | latest | Task runner — `cargo install just` |
+| `lefthook` | latest | Optional; run `lefthook install` for local Git hooks |
 | `sqlx-cli` | latest | Optional; `just migrate` falls back to `docker exec` |
 
 This repo uses [Hermit](https://cashapp.github.io/hermit/) for toolchain
@@ -68,6 +71,9 @@ cp .env.example .env
 
 # 4. Start infrastructure + run migrations
 just setup
+
+# 5. Install Git hooks (optional, recommended)
+lefthook install
 ```
 
 `just setup` starts Docker services (MySQL on `:3306`, Redis on `:6379`,
@@ -134,7 +140,7 @@ Before opening a PR, run the full CI gate locally:
 
 ```bash
 just ci
-# Runs: fmt-check + clippy + unit tests
+# Runs: check + unit tests + desktop build + Tauri check
 ```
 
 This is the same check that runs in CI. PRs that fail `just ci` will not be

Cargo.toml

@@ -14,6 +14,7 @@ members = [
     "crates/sprout-admin",
     "crates/sprout-workflow",
 ]
+exclude = ["desktop/src-tauri"]
 resolver = "2"
 
 [workspace.package]

README.md

@@ -99,16 +99,38 @@ append-only and audited.
 
 ## Quick Start
 
-**1. Start infrastructure**
+**1. Activate the pinned toolchain**
+
+```bash
+. ./bin/activate-hermit
+```
+
+Hermit pins Rust, Node.js, pnpm, `just`, and related tooling from `bin/`.
+If you prefer not to use Hermit, install the prerequisites manually first.
+
+**2. Start infrastructure**
 
 ```bash
 cp .env.example .env
-docker compose up -d
+just setup
 ```
 
+`just setup` starts Docker services and applies pending database migrations.
+
 Services: MySQL `:3306`, Redis `:6379`, Typesense `:8108`, Adminer `:8082`
 
-**2. Start the relay**
+**3. Install desktop dependencies**
+
+```bash
+just desktop-install
+```
+
+This is required before running `just check`, `just ci`, Git hooks, or any
+`just desktop-*` command.
+
+The desktop workflow documented here is macOS-first for now.
+
+**4. Start the relay**
 
 ```bash
 just relay
@@ -117,25 +139,36 @@ just relay
 
 Relay listens on `ws://localhost:3000` by default.
 
-**3. Mint an API token**
+**5. Mint an API token**
 
 ```bash
 cargo run -p sprout-admin -- mint-token \
   --name "my-agent" \
   --scopes "messages:read,messages:write,channels:read"
 ```
 
-Outputs a bearer token. Set it as `SPROUT_API_TOKEN` for the MCP server.
+Save the `nsec...` private key and API token from the output. They are shown only once.
 
-**4. Connect an agent via MCP**
+**6. Launch an agent with the MCP extension**
 
 ```bash
 SPROUT_RELAY_URL=ws://localhost:3000 \
 SPROUT_API_TOKEN=<token> \
-cargo run -p sprout-mcp
+SPROUT_PRIVATE_KEY=nsec1... \
+goose run --no-profile \
+  --with-extension "cargo run -p sprout-mcp --bin sprout-mcp-server" \
+  --instructions "List available Sprout channels."
 ```
 
-The MCP server speaks stdio JSON-RPC. Wire it into any MCP-compatible agent host.
+`sprout-mcp-server` is a stdio MCP extension, so start it through a host such as Goose rather than
+as a standalone user-facing process. See [TESTING.md](TESTING.md) for the full multi-agent flow.
+
+**7. Run the desktop app (optional)**
+
+```bash
+just desktop-app
+# or: just desktop-dev
+```
 
 ## Configuration
 
@@ -194,24 +227,36 @@ Set `SPROUT_PRIVATE_KEY` (nsec format) to use a persistent identity.
 
 ## Development
 
-**Prerequisites:** Rust 1.88+, Docker, [`just`](https://github.com/casey/just)
+**Prerequisites:** Rust 1.88+, Docker, Node.js 24+, pnpm 10+, [`just`](https://github.com/casey/just)
 
 This repo uses [Hermit](https://cashapp.github.io/hermit/) for toolchain pinning. Activate with:
 
 ```bash
 . ./bin/activate-hermit
 ```
 
+For a fresh clone, install desktop dependencies before running desktop-aware
+checks or hooks:
+
+```bash
+just desktop-install
+lefthook install
+```
+
 **Common tasks**
 
 ```bash
 just setup          # Start Docker services + run migrations
 just relay          # Run the relay (dev mode)
-just build          # Build entire workspace
-just check          # fmt-check + clippy
+just build          # Build the Rust workspace
+just desktop-install # Install desktop dependencies
+just desktop-dev    # Run the desktop web UI only
+just desktop-app    # Run the Tauri desktop app
+just desktop-ci     # Desktop check + build + Tauri Rust check
+just check          # Rust fmt/clippy + desktop check
 just test-unit      # Unit tests (no infra required)
 just test           # All tests (starts services if needed)
-just ci             # fmt-check + clippy + unit tests (CI gate)
+just ci             # check + unit tests + desktop build + Tauri check
 just migrate        # Run pending migrations
 just down           # Stop Docker services (keep data)
 just reset          # ⚠️  Wipe all data and recreate environment
@@ -222,9 +267,11 @@ just reset          # ⚠️  Wipe all data and recreate environment
 ```bash
 cargo run -p sprout-relay
 cargo run -p sprout-admin -- --help
-cargo run -p sprout-mcp
+cargo run -p sprout-mcp --bin sprout-mcp-server
 ```
 
+`sprout-mcp-server` is normally launched by Goose or another MCP host.
+
 **Database migrations** live in `migrations/`. The relay applies them automatically on startup.
 To run manually: `just migrate` (uses `sqlx` CLI if available, falls back to `docker exec`).
 

bin/.rust@1.88.pkg bin/.cargo-deny-0.19.0.pkgbin/.rust@1.88.pkg renamed to bin/.cargo-deny-0.19.0.pkg

@@ -0,0 +1 @@
+hermit

bin/.lefthook-2.1.3.pkg

@@ -0,0 +1 @@
+hermit

bin/.node-24.14.0.pkg

@@ -0,0 +1 @@
+hermit

bin/.pnpm-10.31.0.pkg

@@ -0,0 +1 @@
+hermit