diff --git a/README.md b/README.md index e001191ef..09e7bc04d 100644 --- a/README.md +++ b/README.md @@ -63,7 +63,7 @@ append-only and audited. └──────────┬──────────────────────┬───────────────────────────────────────┘ │ │ ┌──────▼──────┐ ┌──────▼──────┐ - │ MySQL │ │ Redis │ + │ Postgres │ │ Redis │ │ (events, │ │ (pub/sub, │ │ channels, │ │ presence) │ │ tokens) │ └─────────────┘ @@ -87,7 +87,7 @@ append-only and audited. **Services** | Crate | Role | |-------|------| -| `sprout-db` | MySQL access layer — events, channels, API tokens (sqlx) | +| `sprout-db` | Postgres access layer — events, channels, API tokens (sqlx) | | `sprout-auth` | NIP-42 challenge/response + Okta OIDC JWT validation + token scopes | | `sprout-pubsub` | Redis pub/sub bridge — fan-out events across relay instances | | `sprout-search` | Typesense indexing and query — full-text search over event content | @@ -114,6 +114,10 @@ append-only and audited. ## Quick Start +Three steps to get the full stack running locally. + +**Prerequisites:** Docker, and either [Hermit](https://cashapp.github.io/hermit/) (recommended) or Rust 1.88+, Node.js 24+, pnpm 10+, and [`just`](https://github.com/casey/just) installed manually. + **1. Activate the pinned toolchain** ```bash @@ -121,40 +125,41 @@ append-only and audited. ``` 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** +**2. Configure and set up the dev environment** ```bash cp .env.example .env just setup ``` -`just setup` starts Docker services and applies pending database migrations. +`just setup` does the heavy lifting: +- Starts Docker services (Postgres, Redis, Typesense, Adminer, Keycloak, MinIO, Prometheus) +- Waits for all services to be healthy +- Runs database migrations +- Installs desktop dependencies (`pnpm install`) -Services: MySQL `:3306`, Redis `:6379`, Typesense `:8108`, Adminer `:8082` - -**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** +**3. Start the relay and desktop app** ```bash +# Terminal 1 — relay just relay -# or: cargo run -p sprout-relay + +# Terminal 2 — desktop app +just dev ``` -Relay listens on `ws://localhost:3000` by default. +The relay listens on `ws://localhost:3000`. The desktop app opens automatically. -**5. Mint an API token** +That's it — you're running Sprout locally. + +--- + +## Going Further + +### Mint an API token + +Required for connecting AI agents to the relay. ```bash cargo run -p sprout-admin -- mint-token \ @@ -162,11 +167,9 @@ cargo run -p sprout-admin -- mint-token \ --scopes "messages:read,messages:write,channels:read" ``` -Save the `nsec...` private key and API token from the output. They are shown only once. +Save the `nsec...` private key and API token from the output — they are shown only once. -> **Note:** Requires infrastructure from Step 2 to be running. - -**6. Launch an agent with the MCP extension** +### Launch an agent (MCP) ```bash SPROUT_RELAY_URL=ws://localhost:3000 \ @@ -179,35 +182,31 @@ goose run --no-profile \ `sprout-mcp-server` is a stdio MCP server — Goose manages its lifecycle. Do not run it directly in a terminal. See [TESTING.md](TESTING.md) for the full multi-agent flow. -**6b. Start the NIP-28 proxy (optional)** +### Start the NIP-28 proxy (optional) ```bash just proxy -# or: cargo run -p sprout-proxy ``` The proxy lets third-party Nostr clients (Coracle, nak, Amethyst) connect to Sprout using standard NIP-28 channel events. See [NOSTR.md](NOSTR.md) for setup, guest registration, and client configuration. -**7. Run the desktop app (optional)** +### Run the desktop web UI without Tauri (optional) ```bash -just desktop-app -# or: just desktop-dev +just desktop-dev ``` -The desktop app includes a home feed, Cmd+K search, settings page, profile management, presence -indicators, unread badges, diff message rendering, custom window chrome (macOS overlay titlebar), -and a full channel management UI. +This starts only the web frontend at `http://localhost:1420` — useful for UI development without rebuilding the Tauri shell. Use `just dev` (from Quick Start) for the full desktop app. ## Configuration -Copy `.env.example` to `.env`. All defaults work with `docker compose up` out of the box. +Copy `.env.example` to `.env` and adjust as needed. All defaults work out of the box for local development. | Variable | Default | Description | |----------|---------|-------------| -| `DATABASE_URL` | `mysql://sprout:sprout_dev@localhost:3306/sprout` | MySQL connection string | +| `DATABASE_URL` | `postgres://sprout:sprout_dev@localhost:5432/sprout` | Postgres connection string | | `REDIS_URL` | `redis://localhost:6379` | Redis connection string | | `TYPESENSE_URL` | `http://localhost:8108` | Typesense base URL | | `TYPESENSE_API_KEY` | `sprout_dev_key` | Typesense API key | @@ -234,26 +233,19 @@ automatically via the MCP protocol — see [AGENTS.md](AGENTS.md) for integratio ## Development -**Prerequisites:** Rust 1.88+, Docker, Node.js 24+, pnpm 10+, [`just`](https://github.com/casey/just) +See [Quick Start](#quick-start) for prerequisites. This repo uses Hermit for toolchain pinning — activate with `. ./bin/activate-hermit`. -This repo uses [Hermit](https://cashapp.github.io/hermit/) for toolchain pinning. Activate with: +For a fresh clone, copy `.env.example` to `.env`, then `just setup` handles the rest (Docker, migrations, desktop deps). +To install Git hooks: ```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 setup # Docker services, migrations, desktop deps (pnpm install) just relay # Run the relay (dev mode) just proxy # Run the NIP-28 proxy (dev mode) just build # Build the Rust workspace @@ -286,8 +278,8 @@ cargo run -p sprout-proxy Run `just test-unit` for unit tests (no infra required) or `just test` for the full suite. See [TESTING.md](TESTING.md) for the multi-agent E2E suite (Alice/Bob/Charlie via `sprout-acp`). -**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`). +**Database schema** lives in `schema/schema.sql`. The relay applies it automatically on startup. +To run manually: `just migrate`. ## License diff --git a/justfile b/justfile index 60669ffb9..107802a9e 100644 --- a/justfile +++ b/justfile @@ -11,7 +11,7 @@ default: # ─── Dev Environment ───────────────────────────────────────────────────────── -# Start all dev services (Docker Compose) and run migrations +# Start Docker services, run migrations, install desktop deps setup: ./scripts/dev-setup.sh diff --git a/scripts/dev-setup.sh b/scripts/dev-setup.sh index 2df3a6678..f7991cfea 100755 --- a/scripts/dev-setup.sh +++ b/scripts/dev-setup.sh @@ -4,8 +4,8 @@ # ============================================================================= # Usage: ./scripts/dev-setup.sh # -# Starts all Docker services, waits for healthy, runs migrations, prints -# connection info and next steps. +# Starts Docker services, waits for healthy, runs migrations, installs desktop +# deps, and prints next steps. # ============================================================================= set -euo pipefail @@ -20,10 +20,10 @@ YELLOW='\033[1;33m' BLUE='\033[0;34m' NC='\033[0m' # No Color -log() { echo -e "${BLUE}[dev-setup]${NC} $*"; } -success(){ echo -e "${GREEN}[dev-setup]${NC} $*"; } -warn() { echo -e "${YELLOW}[dev-setup]${NC} $*"; } -error() { echo -e "${RED}[dev-setup]${NC} $*" >&2; } +log() { echo -e "${BLUE}[dev-setup]${NC} $*"; } +success() { echo -e "${GREEN}[dev-setup]${NC} $*"; } +warn() { echo -e "${YELLOW}[dev-setup]${NC} $*"; } +error() { echo -e "${RED}[dev-setup]${NC} $*" >&2; } # ---- Preflight checks ------------------------------------------------------- @@ -157,6 +157,23 @@ else fi fi +# ---- Install desktop dependencies ------------------------------------------- + +DESKTOP_DIR="${REPO_ROOT}/desktop" + +if [[ -d "${DESKTOP_DIR}" ]]; then + if command -v pnpm &>/dev/null; then + log "Installing desktop dependencies (pnpm install)..." + (cd "${DESKTOP_DIR}" && pnpm install) + success "Desktop dependencies installed" + else + warn "pnpm not found — skipping desktop dependency install." + warn "Run '. ./bin/activate-hermit' to get pnpm, then 'just desktop-install'." + fi +else + warn "Desktop directory not found at ${DESKTOP_DIR} — skipping." +fi + # ---- Print connection info -------------------------------------------------- echo "" @@ -171,10 +188,8 @@ echo -e " ${BLUE}Adminer${NC} http://localhost:8082 (DB browser)" echo -e " ${BLUE}Keycloak${NC} http://localhost:8180 (admin / admin — local OAuth testing)" echo "" echo -e " ${YELLOW}Next steps:${NC}" -echo -e " cp .env.example .env # configure your environment" -echo -e " bash scripts/setup-keycloak.sh # configure Keycloak for OAuth testing (optional)" -echo -e " cargo run -p sprout-relay # start the relay server" -echo -e " ./scripts/run-tests.sh # run all tests" +echo -e " just relay # start the relay (terminal 1)" +echo -e " just dev # start the desktop app (terminal 2)" echo "" echo -e " ${YELLOW}Useful commands:${NC}" echo -e " docker compose ps # check service status"