docs(testing): rewrite TESTING.md for current API and CLI-first workflow#597
Merged
Conversation
Reflect the post-#475 ("Sprout speaks Nostr. Nothing else.") API: - Drop `POST /api/events` and `/api/channels/.../threads/...` (both 404 today); list the actual bridge endpoints: `/events`, `/query`, `/count`. - Replace the `nak | curl` + `screen` dance with a CLI-first smoke test using `sprout-cli` (NIP-98 by default), `sprout-admin generate-key`, and the channel UUID extraction needed because `sprout channels create` does not echo the UUID it generates. - Move ACP to an optional section and note that sprout-mcp is being deprecated. - Update env defaults to match `sprout-relay` / `sprout-acp` / `sprout-cli` source (`SPROUT_HEALTH_PORT=8080`, `SPROUT_METRICS_PORT=9102`, `SPROUT_REQUIRE_AUTH_TOKEN=false` in dev, `SPROUT_ACP_IDLE_TIMEOUT` as the canonical timeout, etc.). - Trim troubleshooting to current symptoms. Smoke test verified end-to-end against a fresh `just relay`. Signed-off-by: Tyler Longwell <tlongwell@squareup.com>
- Step 3: add port-collision callout (Sprout Desktop on :3000/:8080) and flag that overriding relay ports requires $SPROUT_RELAY_URL on the CLI. - Step 3: warn cold readers to `unset SPROUT_AUTH_TAG` if their shell has it set from another relay's config. - ACP recipe: add `channels add-member $AGENT_PUBKEY` BEFORE starting sprout-acp. Without this the agent boots to 'discovered 0 channel(s)' / 'no channel subscriptions resolved — agent will sit idle' and never picks up mentions. Verified end-to-end with goose against a local relay. - ACP recipe: capture sender SK first so the reader can switch back to it to send the @mention. Note that the agent log is quiet during turns; use `sprout messages get` to confirm the reply. - Troubleshooting: new row for the 'discovered 0 channels / sit idle' case. Signed-off-by: Tyler Longwell <tlongwell@squareup.com>
Findings from Max's second-pair-of-eyes pass on commit 0a0b3a6: 1. `just relay` is a DEBUG build (verified: `cargo run -p sprout-relay` with no --release). Doc said 'build release binaries' then 'just relay or cargo run --release', which contradicts itself. Switch the primary recommendation to running the `sprout-relay` release binary directly (already on PATH from step 2). Mention `just relay-release` as the matching recipe for anyone who wants a just target. 2. Port-override callout used to tell readers to switch ports, but the verify snippet right after still hardcoded :3000/:8080. A cold reader pasting the verify commands would hit Sprout Desktop's relay instead. Move the verify curls into the callout block on the overridden ports, and explicitly say later snippets assume defaults. 3. ACP recipe used to re-export `SPROUT_RELAY_URL=ws://localhost:3000 # or :3030 if you overrode...` which was paste-and-pray. Reworded to call out that sprout-acp wants `ws://` (not `http://`), and that the reader should match whatever step 3 used. 4. Added a 'using a different ACP agent?' note pointing out the recipe assumes `goose` is installed and configured (`goose --version`) and showing the env vars to swap for codex / claude code / sprout-agent. 5. `os error 48` is macOS-specific; Linux is `os error 98`. Make the troubleshooting row OS-agnostic. Signed-off-by: Tyler Longwell <tlongwell@squareup.com>
Findings from Mari's pass on commit 16454af (third pair of eyes after my own walkthrough and Max's review): 1. Port-override callout used to lump relay-terminal vars (SPROUT_BIND_ADDR, SPROUT_HEALTH_PORT, SPROUT_METRICS_PORT, RELAY_URL) together with the working-terminal var (SPROUT_RELAY_URL). Step 3 explicitly tells the reader 'separate terminal', but the callout didn't reflect that split, forcing readers to consciously re-export SPROUT_RELAY_URL in the CLI shell or accidentally talk to the wrong relay. Restructured as 'in the relay terminal' / 'in your working terminal' blocks so the division is obvious. Also called out :9102 since metrics is the third collision surface (Mari's collision was actually on metrics first). 2. ACP manual recipe now sets SPROUT_ACP_MCP_COMMAND explicitly to the built release binary. The default value 'sprout-mcp-server' relies on step 2's PATH export, which doesn't survive a new shell. The `just goose` recipe already does this — manual recipe should match. Signed-off-by: Tyler Longwell <tlongwell@squareup.com>
- §1: callout for Sprout Desktop's shared Docker stack (sprout-postgres / -redis / -typesense reuse Desktop's containers and DB; just reset wipes Desktop's data along with yours). - §1: stronger stale-env scrub block — unset SPROUT_AUTH_TAG / SPROUT_RELAY_URL / SPROUT_PRIVATE_KEY. A stale SPROUT_AUTH_TAG fails the local dev relay with auth_error (it is not tolerated, contrary to the old phrasing). - §3: ignore just setup's 'Next steps' banner (it still prints 'just relay' / debug; doc prefers 'sprout-relay' / release). - §3: explicit teardown note so the next reviewer doesn't collide on the override ports. - §4: smoke snippet now also exercises 'sprout messages thread' so all five core message commands are covered in one block. - §5: optional RUST_LOG=sprout_acp=debug,sprout_mcp=debug hint for cold readers who want visible turn boundaries. - Troubleshooting: widened the 'Address already in use' row (read the panic, lsof all three ports, handle the alt-port collision case) and added a new row for the stale SPROUT_AUTH_TAG failure. Signed-off-by: Tyler Longwell <tlongwell@squareup.com>
tlongwell-block
force-pushed
the
docs/testing-md-refresh
branch
from
00084f3 to
cd97c5b
Compare
tlongwell-block
added a commit
that referenced
this pull request
May 15, 2026
* origin/main: (33 commits) dev-mcp: add view_image tool (#602) fix(relay,desktop): only advertise NIP-43 when enforced; probe pairing by supported_nips (#601) fix(desktop): derive unread state from NIP-RS + relay catch-up only (#599) docs(testing): rewrite TESTING.md for current API and CLI-first workflow (#597) fix(agent): fix OpenAI-compat request body serialization and max_tokens (#595) feat(desktop): per-persona and per-agent env var overrides (#594) fix(desktop): stop pinning agents to deprecated SPROUT_ACP_TURN_TIMEOUT (#592) fix(desktop): populate member_count in get_channels so channel browser shows real counts (#548) fix(desktop): autofocus message composer on channel/thread open (#572) refactor(cli): restructure flat commands into 12 subcommand groups (#585) feat(sdk): add builder functions for workflows, DMs, and presence (#589) feat(desktop): add message more-actions dropdown menu (#590) fix(mobile): preserve channel list across background/resume reconnection (#588) Redesign Home as an inbox (#582) fix(desktop): drive unread badges from live subscription, not refetched lastMessageAt (#581) fix(desktop): refine header scaling and shadow (#573) fix(desktop): keep day dividers below header (#574) Move agent activity below composer (#579) docs(nips): NIP-AE — Agent Engrams (#575) refactor: extract shared @mention resolver into sprout-sdk (#580) ... Signed-off-by: Tyler Longwell <tlongwell@squareup.com>
tlongwell-block
added a commit
that referenced
this pull request
May 15, 2026
Signed-off-by: Tyler Longwell <tlongwell@squareup.com> * origin/main: dev-mcp: add view_image tool (#602) fix(relay,desktop): only advertise NIP-43 when enforced; probe pairing by supported_nips (#601) fix(desktop): derive unread state from NIP-RS + relay catch-up only (#599) docs(testing): rewrite TESTING.md for current API and CLI-first workflow (#597) fix(agent): fix OpenAI-compat request body serialization and max_tokens (#595) feat(desktop): per-persona and per-agent env var overrides (#594)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Refresh of the root
TESTING.mdso it matches reality after the Nostr-first relay migration (#475 and follow-ups). OnlyTESTING.mdis changed (146 insertions / 131 deletions, net ~30 lines shorter).What changed
POST /api/eventsandGET /api/channels/{ch}/threads/{eid}are 404 today. Bridge endpoints are now root-level:POST /events,POST /query,POST /count.nak | curl | screenwith a CLI-first smoke test. New flow:hermit→just setup→cargo build --release -p sprout-relay -p sprout-cli -p sprout-admin→just relay→ verify/health+:8080/_readiness→sprout-admin generate-key→sprout channels create→sprout messages send/get.sprout channels createUUID gap. The command doesn't echo the channel UUID it generates; the runbook usessprout channels list --member | jqon thed-tag as the workaround. Worth fixing in the CLI in a separate PR.sprout-mcpis being deprecated, so it's no longer on the critical path.SPROUT_HEALTH_PORT=8080,SPROUT_METRICS_PORT=9102,SPROUT_REQUIRE_AUTH_TOKEN=false(dev),SPROUT_ACP_IDLE_TIMEOUTas the canonical timeout (SPROUT_ACP_TURN_TIMEOUTis deprecated alias), etc.Verified
cargo build --release -p sprout-relay -p sprout-cli -p sprout-adminclean.just relay→/health200,:8080/_readiness200.h-tag = channel UUID, signed by the agent identity.Known follow-ups (out of scope here)
crates/sprout-cli/TESTING.mdstill uses stalejq -r '.id'onchannels createoutput.crates/sprout-acp/README.mdhas stale-p sprout-mcp-serverbuild hint,GET /api/channels?member=true, and "no member-management API" notes.channels create(crates/sprout-cli/src/commands/channels.rs:99).