Files

587 lines
17 KiB
Markdown

# sprout-cli Live Testing Guide
Manual testing runbook for verifying every CLI command against a local relay.
An agent or developer follows this step by step, running each command and
checking the output.
---
## 1. Prerequisites
Docker services running and healthy:
```bash
docker compose ps
# sprout-postgres healthy
# sprout-redis healthy
# sprout-typesense healthy
```
If not running: `./scripts/dev-setup.sh` from the repo root.
Tools: `jq`, `curl`, Rust toolchain.
---
## 2. Build the CLI
```bash
cargo build -p sprout-cli
```
Use `cargo run -p sprout-cli --` or the built binary at `target/debug/sprout`.
---
## 3. Start the Relay
In a separate terminal:
```bash
cd REPOS/sprout-nostr
set -a && source .env && set +a
cargo run -p sprout-relay
```
Verify:
```bash
curl -s http://localhost:3000/_liveness
# "ok" or 200 status
```
The `.env` should have `SPROUT_REQUIRE_AUTH_TOKEN=false` for local dev.
---
## 4. Mint Test Credentials
### Option A: sprout-admin (full scopes including admin)
This mints a token with all CLI-relevant scopes (including `admin:channels`)
via direct DB access. Use this for testing admin operations (archive,
delete-channel, add/remove-channel-member).
```bash
DATABASE_URL=postgres://sprout:sprout_dev@localhost:5432/sprout \
cargo run -p sprout-admin -- mint-token \
--name "cli-test" \
--scopes "messages:read,messages:write,channels:read,channels:write,users:read,users:write,files:read,files:write,admin:channels"
```
This generates a keypair and prints:
- **Private key (nsec)** — save for `SPROUT_PRIVATE_KEY` testing
- **API Token** — save as `SPROUT_API_TOKEN`
- **Pubkey** — save for `SPROUT_PUBKEY` testing
Export:
```bash
export SPROUT_RELAY_URL="http://localhost:3000"
export SPROUT_API_TOKEN="sprout_tok_..."
export SPROUT_PRIVATE_KEY="nsec1..." # from the mint output
```
### Option B: sprout auth (NIP-98, self-mintable scopes only)
Tests the CLI's own auth flow. Cannot mint `admin:channels`.
```bash
export SPROUT_PRIVATE_KEY="nsec1..."
export SPROUT_RELAY_URL="http://localhost:3000"
cargo run -p sprout-cli -- auth
# Prints a token string to stdout
```
### Scope reference
| Scope | Self-mintable | Needed for |
|-------|:---:|------------|
| `messages:read` | ✅ | get-messages, get-thread, search, get-feed |
| `messages:write` | ✅ | send-message, edit-message, delete-message, reactions, vote |
| `channels:read` | ✅ | list-channels, get-channel, list-members |
| `channels:write` | ✅ | create-channel, update-channel, join, leave, topic, purpose |
| `users:read` | ✅ | get-users, get-presence |
| `users:write` | ✅ | set-profile, set-presence, set-channel-add-policy |
| `files:read` | ✅ | — |
| `files:write` | ✅ | — |
| `admin:channels` | ❌ | archive, unarchive, delete-channel, add/remove-channel-member |
**Use Option A for full testing.** Option B covers most commands but skips
admin operations.
---
## 5. Unit Tests
```bash
cargo test -p sprout-cli
# Expected: 38 passed, 0 failed
cargo clippy -p sprout-cli -- -D warnings
# Expected: zero warnings
```
---
## 6. Live Testing — Command by Command
Run each command, verify exit code 0 and check output. Most commands
return JSON (pipe through `jq .` to validate). Exceptions: `auth` prints
a raw token string, and `delete-token`/`delete-all-tokens` may return
empty (204). Commands are ordered so earlier ones create resources that
later ones need.
### 6.1 Auth & Tokens
```bash
# list-tokens — list existing tokens
sprout list-tokens | jq .
# auth — mint a new token (requires SPROUT_PRIVATE_KEY)
SPROUT_PRIVATE_KEY="nsec1..." sprout auth
# Should print: sprout_tok_...
# delete-token — delete a specific token by UUID
# ⚠️ Do NOT delete the token you're currently using (SPROUT_API_TOKEN).
# Mint a throwaway token first, then delete it:
THROWAWAY=$(sprout auth) # mint a new token
THROWAWAY_LIST=$(SPROUT_API_TOKEN="$THROWAWAY" sprout list-tokens)
# Filter by name to avoid deleting the wrong token
THROWAWAY_ID=$(echo "$THROWAWAY_LIST" | jq -r '[.[] // .tokens[] | select(.name == "sprout-cli")][0].id // empty')
sprout delete-token --id "$THROWAWAY_ID"
# May return 204 (empty) or JSON — both are success
# delete-all-tokens — DESTRUCTIVE, deletes all tokens for this pubkey
# sprout delete-all-tokens
# ⚠️ Only run this if you're about to re-mint
```
### 6.2 Channels
```bash
# create-channel (stream)
sprout create-channel --name "test-stream" --type stream --visibility open \
--description "CLI test channel" | jq .
# Save the channel ID:
CHANNEL_ID=$(sprout create-channel --name "test-cli" --type stream --visibility open | jq -r '.id')
# create-channel (forum) — needed for vote-on-post later
FORUM_ID=$(sprout create-channel --name "test-forum" --type forum --visibility open | jq -r '.id')
# list-channels
sprout list-channels | jq .
sprout list-channels --visibility open | jq .
sprout list-channels --member | jq .
# get-channel
sprout get-channel --channel "$CHANNEL_ID" | jq .
# update-channel
sprout update-channel --channel "$CHANNEL_ID" --name "test-cli-updated" \
--description "Updated" | jq .
# set-channel-topic
sprout set-channel-topic --channel "$CHANNEL_ID" --topic "Test topic" | jq .
# set-channel-purpose
sprout set-channel-purpose --channel "$CHANNEL_ID" --purpose "Testing" | jq .
# join-channel (may already be a member from create)
sprout join-channel --channel "$CHANNEL_ID" | jq .
# leave-channel
sprout leave-channel --channel "$CHANNEL_ID" | jq .
# Re-join so we can send messages
sprout join-channel --channel "$CHANNEL_ID" | jq .
# archive-channel (requires admin:channels scope)
sprout archive-channel --channel "$CHANNEL_ID" | jq .
# unarchive-channel
sprout unarchive-channel --channel "$CHANNEL_ID" | jq .
```
### 6.3 Canvas
```bash
# set-canvas
sprout set-canvas --channel "$CHANNEL_ID" --content "# Test Canvas" | jq .
# set-canvas from stdin
echo "# Canvas from stdin" | sprout set-canvas --channel "$CHANNEL_ID" --content - | jq .
# get-canvas
sprout get-canvas --channel "$CHANNEL_ID" | jq .
```
### 6.4 Messages
```bash
# send-message
MSG=$(sprout send-message --channel "$CHANNEL_ID" --content "Hello from CLI test" | jq .)
echo "$MSG"
EVENT_ID=$(echo "$MSG" | jq -r '.id // .event_id')
# send-message with reply + broadcast
REPLY=$(sprout send-message --channel "$CHANNEL_ID" --content "Reply" \
--reply-to "$EVENT_ID" --broadcast | jq .)
echo "$REPLY"
REPLY_ID=$(echo "$REPLY" | jq -r '.id // .event_id')
# send-message with mentions
sprout send-message --channel "$CHANNEL_ID" --content "Hey @someone" \
--mention "0000000000000000000000000000000000000000000000000000000000000001" | jq .
# get-messages
sprout get-messages --channel "$CHANNEL_ID" | jq .
sprout get-messages --channel "$CHANNEL_ID" --limit 5 | jq .
# get-thread
sprout get-thread --channel "$CHANNEL_ID" --event "$EVENT_ID" | jq .
# search
sprout search --query "Hello" | jq .
sprout search --query "CLI test" --limit 5 | jq .
# edit-message
sprout edit-message --event "$EVENT_ID" --content "Edited by CLI test" | jq .
# delete-message
sprout delete-message --event "$REPLY_ID" | jq .
```
### 6.5 Diff Messages
```bash
# send-diff-message from stdin
echo '--- a/foo.rs
+++ b/foo.rs
@@ -1,3 +1,3 @@
-fn old() {}
+fn new() {}' | sprout send-diff-message \
--channel "$CHANNEL_ID" \
--diff - \
--repo "https://github.com/example/repo" \
--commit "abcdef1234567890abcdef1234567890abcdef12" | jq .
# send-diff-message with metadata
echo "diff content" | sprout send-diff-message \
--channel "$CHANNEL_ID" \
--diff - \
--repo "https://github.com/example/repo" \
--commit "abcdef1234567890abcdef1234567890abcdef12" \
--file "src/main.rs" \
--lang "rust" \
--description "Refactored main" | jq .
# send-diff-message with branch + PR metadata
echo "diff content" | sprout send-diff-message \
--channel "$CHANNEL_ID" \
--diff - \
--repo "https://github.com/example/repo" \
--commit "abcdef1234567890abcdef1234567890abcdef12" \
--parent-commit "1234567890abcdef1234567890abcdef12345678" \
--source-branch "feature/cli" \
--target-branch "main" \
--pr 42 | jq .
```
### 6.6 Reactions
```bash
# Send a message to react to
REACT_MSG=$(sprout send-message --channel "$CHANNEL_ID" --content "React to this")
REACT_ID=$(echo "$REACT_MSG" | jq -r '.id // .event_id')
# add-reaction
sprout add-reaction --event "$REACT_ID" --emoji "👍" | jq .
# get-reactions
sprout get-reactions --event "$REACT_ID" | jq .
# remove-reaction
sprout remove-reaction --event "$REACT_ID" --emoji "👍" | jq .
```
### 6.7 DMs
```bash
# list-dms
sprout list-dms | jq .
# open-dm (needs a real pubkey — use your own or a test one)
# Get your own pubkey first:
MY_PUBKEY=$(sprout get-users | jq -r '.pubkey // .[0].pubkey // empty')
echo "My pubkey: $MY_PUBKEY"
# open-dm with a synthetic pubkey (relay will create the user)
DM_RESULT=$(sprout open-dm --pubkey "0000000000000000000000000000000000000000000000000000000000000001")
echo "$DM_RESULT" | jq .
DM_ID=$(echo "$DM_RESULT" | jq -r '.channel_id // .id // empty')
# add-dm-member (requires messages:write scope — NOT admin:channels)
sprout add-dm-member --channel "$DM_ID" \
--pubkey "0000000000000000000000000000000000000000000000000000000000000002" | jq .
```
### 6.8 Users & Presence
```bash
# get-users — own profile (0 pubkeys)
sprout get-users | jq .
# get-users — single pubkey
sprout get-users --pubkey "$MY_PUBKEY" | jq .
# get-users — batch (2+ pubkeys)
sprout get-users --pubkey "$MY_PUBKEY" --pubkey "$MY_PUBKEY" | jq .
# set-profile
sprout set-profile --name "CLI Test Agent" --about "Testing sprout-cli" | jq .
# get-presence
sprout get-presence --pubkeys "$MY_PUBKEY" | jq .
# set-presence
sprout set-presence --status online | jq .
sprout set-presence --status away | jq .
sprout set-presence --status offline | jq .
# set-channel-add-policy
sprout set-channel-add-policy --policy anyone | jq .
sprout set-channel-add-policy --policy owner_only | jq .
sprout set-channel-add-policy --policy nobody | jq .
# Reset to default
sprout set-channel-add-policy --policy anyone | jq .
```
### 6.9 Channel Members (add/remove require admin:channels)
```bash
# add-channel-member
sprout add-channel-member --channel "$CHANNEL_ID" \
--pubkey "0000000000000000000000000000000000000000000000000000000000000001" \
--role member | jq .
# list-channel-members
sprout list-channel-members --channel "$CHANNEL_ID" | jq .
# remove-channel-member
sprout remove-channel-member --channel "$CHANNEL_ID" \
--pubkey "0000000000000000000000000000000000000000000000000000000000000001" | jq .
```
### 6.10 Workflows
```bash
# create-workflow
# NOTE: trigger uses `on:` tag (serde internally tagged enum).
# Valid triggers: message_posted, reaction_added, diff_posted, schedule, webhook
# Steps use `action:` tag: send_message, send_dm, set_channel_topic, add_reaction, etc.
WF=$(sprout create-workflow --channel "$CHANNEL_ID" \
--yaml 'name: test-wf
trigger:
on: webhook
steps:
- id: step1
action: send_message
text: "Hello from workflow"' | jq .)
echo "$WF"
WF_ID=$(echo "$WF" | jq -r '.id')
# list-workflows
sprout list-workflows --channel "$CHANNEL_ID" | jq .
# get-workflow
sprout get-workflow --workflow "$WF_ID" | jq .
# update-workflow
sprout update-workflow --workflow "$WF_ID" \
--yaml 'name: test-wf-updated
trigger:
on: webhook
steps:
- id: step1
action: send_message
text: "Updated"' | jq .
# trigger-workflow
sprout trigger-workflow --workflow "$WF_ID" | jq .
# get-workflow-runs
sprout get-workflow-runs --workflow "$WF_ID" | jq .
# approve-step — requires a workflow run waiting for approval
# This is hard to test ad-hoc without a workflow that has an approval gate.
# Test the validation instead:
sprout approve-step --token "00000000-0000-0000-0000-000000000000" --approved true 2>&1 || true
# Should fail with relay error (token not found), not a validation error
# delete-workflow
sprout delete-workflow --workflow "$WF_ID" | jq .
```
### 6.11 Feed
```bash
sprout get-feed | jq .
sprout get-feed --limit 5 | jq .
```
### 6.12 Forum & Voting
```bash
# Send a forum post (kind 45001) to the forum channel
FORUM_POST=$(sprout send-message --channel "$FORUM_ID" \
--content "Forum post for vote testing" --kind 45001 | jq .)
echo "$FORUM_POST"
FORUM_EVENT_ID=$(echo "$FORUM_POST" | jq -r '.id // .event_id')
# vote-on-post (up)
sprout vote-on-post --event "$FORUM_EVENT_ID" --direction up | jq .
# vote-on-post (down)
sprout vote-on-post --event "$FORUM_EVENT_ID" --direction down | jq .
```
---
## 7. Error Path Testing
Verify the CLI produces correct JSON on stderr and correct exit codes.
```bash
# Exit 1: Invalid UUID
sprout get-channel --channel "not-a-uuid" 2>&1; echo "exit: $?"
# stderr: {"error":"user_error","message":"invalid UUID: not-a-uuid"}
# exit: 1
# Exit 1: Invalid hex64
sprout delete-message --event "not-hex" 2>&1; echo "exit: $?"
# stderr: {"error":"user_error","message":"must be a 64-character hex string: not-hex"}
# exit: 1
# Exit 1: Invalid --approved value
sprout approve-step --token "00000000-0000-0000-0000-000000000000" \
--approved maybe 2>&1; echo "exit: $?"
# stderr: {"error":"user_error","message":"--approved must be 'true' or 'false' (got: maybe)"}
# exit: 1
# Exit 1: Invalid --type value
sprout create-channel --name x --type invalid --visibility open 2>&1; echo "exit: $?"
# stderr: {"error":"user_error","message":"--type must be 'stream' or 'forum' (got: invalid)"}
# exit: 1
# Exit 1: Invalid --direction value
sprout vote-on-post --event "$(printf '0%.0s' {1..64})" \
--direction sideways 2>&1; echo "exit: $?"
# exit: 1
# Exit 1: Empty body guard
sprout set-profile 2>&1; echo "exit: $?"
# exit: 1 (at least one field required)
# Exit 3: No auth configured
env -u SPROUT_API_TOKEN -u SPROUT_PRIVATE_KEY -u SPROUT_PUBKEY \
cargo run -p sprout-cli -- list-channels 2>&1; echo "exit: $?"
# stderr: {"error":"auth_error","message":"auth error: Set SPROUT_API_TOKEN, SPROUT_PRIVATE_KEY, or SPROUT_PUBKEY"}
# exit: 3
# Exit 2: Non-existent channel (valid UUID)
sprout get-channel --channel "00000000-0000-0000-0000-000000000000" 2>&1; echo "exit: $?"
# stderr: {"error":"relay_error","message":"..."}
# exit: 2
```
---
## 8. Auth Mode Testing
Test all three authentication tiers.
```bash
# Mode 1: Bearer token (SPROUT_API_TOKEN)
SPROUT_API_TOKEN="sprout_tok_..." sprout list-channels | jq .
# Should succeed
# Mode 2: Private key auto-mint (SPROUT_PRIVATE_KEY)
SPROUT_PRIVATE_KEY="nsec1..." sprout list-channels | jq .
# Should succeed (mints a 1-day token at startup)
# Mode 3: Dev mode (SPROUT_PUBKEY) — only works with SPROUT_REQUIRE_AUTH_TOKEN=false
SPROUT_PUBKEY="<your-64-char-hex-pubkey>" sprout list-channels | jq .
# Should succeed
# No auth → exit 3
env -u SPROUT_API_TOKEN -u SPROUT_PRIVATE_KEY -u SPROUT_PUBKEY \
cargo run -p sprout-cli -- list-channels 2>&1; echo "exit: $?"
# exit: 3
```
---
## 9. Cleanup
```bash
# Delete test channels
sprout delete-channel --channel "$CHANNEL_ID" | jq .
sprout delete-channel --channel "$FORUM_ID" | jq .
```
---
## 10. Checklist
| # | Command | Tested | Notes |
|---|---------|:------:|-------|
| 1 | `send-message` | ☐ | Basic, reply, broadcast, mentions |
| 2 | `send-diff-message` | ☐ | Stdin, metadata, branch/PR |
| 3 | `edit-message` | ☐ | |
| 4 | `delete-message` | ☐ | |
| 5 | `get-messages` | ☐ | With limit |
| 6 | `get-thread` | ☐ | |
| 7 | `search` | ☐ | With limit |
| 8 | `list-channels` | ☐ | With visibility, member |
| 9 | `get-channel` | ☐ | |
| 10 | `create-channel` | ☐ | Stream and forum |
| 11 | `update-channel` | ☐ | |
| 12 | `set-channel-topic` | ☐ | |
| 13 | `set-channel-purpose` | ☐ | |
| 14 | `join-channel` | ☐ | |
| 15 | `leave-channel` | ☐ | |
| 16 | `archive-channel` | ☐ | Needs admin:channels |
| 17 | `unarchive-channel` | ☐ | Needs admin:channels |
| 18 | `delete-channel` | ☐ | Needs admin:channels |
| 19 | `list-channel-members` | ☐ | |
| 20 | `add-channel-member` | ☐ | Needs admin:channels |
| 21 | `remove-channel-member` | ☐ | Needs admin:channels |
| 22 | `get-canvas` | ☐ | |
| 23 | `set-canvas` | ☐ | Direct and stdin |
| 24 | `add-reaction` | ☐ | |
| 25 | `remove-reaction` | ☐ | |
| 26 | `get-reactions` | ☐ | |
| 27 | `list-dms` | ☐ | |
| 28 | `open-dm` | ☐ | |
| 29 | `add-dm-member` | ☐ | Needs messages:write |
| 30 | `get-users` | ☐ | Self, single, batch |
| 31 | `set-profile` | ☐ | |
| 32 | `get-presence` | ☐ | |
| 33 | `set-presence` | ☐ | online, away, offline |
| 34 | `set-channel-add-policy` | ☐ | anyone, owner_only, nobody |
| 35 | `list-workflows` | ☐ | |
| 36 | `create-workflow` | ☐ | |
| 37 | `update-workflow` | ☐ | |
| 38 | `delete-workflow` | ☐ | |
| 39 | `trigger-workflow` | ☐ | |
| 40 | `get-workflow-runs` | ☐ | |
| 41 | `get-workflow` | ☐ | |
| 42 | `approve-step` | ☐ | Validation only (needs approval gate) |
| 43 | `get-feed` | ☐ | |
| 44 | `vote-on-post` | ☐ | Up and down |
| 45 | `auth` | ☐ | Mint token via NIP-98 |
| 46 | `list-tokens` | ☐ | |
| 47 | `delete-token` | ☐ | |
| 48 | `delete-all-tokens` | ☐ | Optional (destructive) |