path: root/docs/archive/2025-11-03-quick-reference.md

# ⚡ Quick Reference - grasp-audit

**Last Updated:** November 4, 2025  
**Status:** ✅ Ready for use

---

## 🚀 One-Minute Quick Start

```bash
# Build and test
cd grasp-audit
nix develop --command cargo build
nix develop --command cargo test --lib

# Run integration test (needs relay)
docker run --rm -p 7000:7000 scsibug/nostr-rs-relay  # Terminal 1
cd grasp-audit && nix develop --command cargo test --ignored  # Terminal 2
```

---

## 📋 Common Commands

### Build
```bash
cargo build                    # Debug build
cargo build --release          # Release build
cargo build --bin grasp-audit  # CLI only
cargo build --example simple_audit  # Example
```

### Test
```bash
cargo test --lib               # Unit tests (no relay needed)
cargo test --ignored           # Integration tests (relay required)
cargo test --all               # All tests
cargo test test_name           # Specific test
RUST_LOG=debug cargo test     # With logging
```

### Run
```bash
# CLI
cargo run -- audit --relay ws://localhost:7000 --mode ci --spec nip01-smoke

# Example
cargo run --example simple_audit

# Help
cargo run -- --help
cargo run -- audit --help
```

### Development
```bash
cargo clippy                   # Linting
cargo fmt                      # Format code
cargo fmt --check             # Check formatting
cargo doc --open              # Generate docs
cargo clean                   # Clean build
```

---

## 🧪 Testing

### Start Test Relay
```bash
# Option 1: Docker (easiest)
docker run --rm -p 7000:7000 scsibug/nostr-rs-relay

# Option 2: Build from source
git clone https://github.com/rust-nostr/nostr
cd nostr/crates/nostr-relay-builder
cargo run --example basic
```

### Run Tests
```bash
# Unit tests (fast, no relay)
cargo test --lib

# Integration tests (needs relay)
cargo test --ignored

# Specific test
cargo test test_websocket_connection -- --nocapture

# All tests
cargo test --all
```

### Expected Results
```
Unit Tests:     12 passed, 0 failed
Integration:    6 passed (with relay)
Build Time:     ~0.1s (incremental)
Test Time:      ~0.5s
```

---

## 📁 File Locations

### Source Code
```
grasp-audit/src/
├── lib.rs                     # Library root
├── audit.rs                   # Audit framework
├── client.rs                  # Nostr client
├── isolation.rs               # Test isolation
├── result.rs                  # Result types
├── bin/grasp-audit.rs        # CLI tool
└── specs/
    ├── mod.rs                # Spec registry
    └── nip01_smoke.rs        # Smoke tests
```

### Examples
```
grasp-audit/examples/
└── simple_audit.rs           # Basic usage
```

### Documentation
```
grasp-audit/
├── README.md                 # Main documentation
├── QUICK_START.md           # Detailed setup
└── Cargo.toml               # Dependencies

Project Root/
├── VERIFICATION_COMPLETE.md  # Verification report
├── READY_FOR_NEXT_PHASE.md  # Next steps
├── SESSION_COMPLETE_2025_11_04.md  # Session summary
└── QUICK_REFERENCE.md       # This file
```

---

## 🎯 CLI Usage

### Basic Usage
```bash
grasp-audit audit \
  --relay ws://localhost:7000 \
  --mode ci \
  --spec nip01-smoke
```

### Options
```
--relay <URL>     Relay WebSocket URL (required)
--mode <MODE>     Test mode: ci or production
--spec <SPEC>     Test specification to run
```

### Modes
- **ci**: Ephemeral test events (auto-cleanup)
- **production**: Permanent audit trail

### Specs
- **nip01-smoke**: 6 basic NIP-01 tests

---

## 📊 Test Specifications

### NIP-01 Smoke Tests
1. `websocket_connection` - Basic connectivity
2. `send_receive_event` - Event round-trip
3. `create_subscription` - REQ message
4. `close_subscription` - CLOSE message
5. `reject_invalid_signature` - Validation
6. `reject_invalid_event_id` - Validation

### Future Specs (Planned)
- `grasp-01-relay` - GRASP-01 compliance
- `grasp-02-sync` - Proactive sync
- `grasp-05-archive` - Archive mode

---

## 🔧 Troubleshooting

### Build Fails: "linker 'cc' not found"
```bash
# Use nix develop
cd grasp-audit
nix develop
cargo build
```

### Tests Fail: "Connection refused"
```bash
# Check relay is running
docker ps | grep nostr

# Start relay
docker run --rm -p 7000:7000 scsibug/nostr-rs-relay

# Test connection
curl -I http://localhost:7000
```

### Integration Tests Timeout
```bash
# Increase timeout in test code
# Or use a faster relay
# Or check network/firewall
```

### Nix Issues
```bash
# Update flake
nix flake update

# Rebuild environment
nix develop --rebuild
```

---

## 📚 Key Resources

### Documentation
- [README.md](grasp-audit/README.md) - Full documentation
- [QUICK_START.md](grasp-audit/QUICK_START.md) - Setup guide
- [VERIFICATION_COMPLETE.md](VERIFICATION_COMPLETE.md) - Current status
- [READY_FOR_NEXT_PHASE.md](READY_FOR_NEXT_PHASE.md) - Next steps

### Code Examples
- [nip01_smoke.rs](grasp-audit/src/specs/nip01_smoke.rs) - Test examples
- [simple_audit.rs](grasp-audit/examples/simple_audit.rs) - Usage example
- [client.rs](grasp-audit/src/client.rs) - Client API

### External Links
- [GRASP Protocol](https://gitworkshop.dev/danconwaydev.com/grasp)
- [nostr-sdk 0.43](https://docs.rs/nostr-sdk/0.43.0)
- [rust-nostr](https://github.com/rust-nostr/nostr)
- [NIP-01](https://nips.nostr.com/01)
- [NIP-34](https://nips.nostr.com/34)

---

## 🎯 Common Tasks

### Run Full Verification
```bash
# Build
cargo build

# Unit tests
cargo test --lib

# Start relay
docker run --rm -p 7000:7000 scsibug/nostr-rs-relay &

# Integration tests
cargo test --ignored

# CLI test
cargo run -- audit --relay ws://localhost:7000 --mode ci --spec nip01-smoke

# Stop relay
docker stop $(docker ps -q --filter ancestor=scsibug/nostr-rs-relay)
```

### Add New Test
```bash
# 1. Edit src/specs/nip01_smoke.rs
# 2. Add test function
# 3. Register in run_smoke_tests()
# 4. Test it
cargo test test_your_new_test -- --nocapture
```

### Create New Spec
```bash
# 1. Create src/specs/your_spec.rs
# 2. Implement tests
# 3. Add to src/specs/mod.rs
# 4. Register in CLI
# 5. Test
cargo test --all
```

### Release Build
```bash
# Build release
cargo build --release

# Binary location
./target/release/grasp-audit

# Install globally
cargo install --path grasp-audit
grasp-audit --help
```

---

## 📊 Project Stats

### Code
- **Total Lines:** 1,079 lines Rust
- **Source Files:** 9 files
- **Test Files:** 3 files
- **Examples:** 1 file

### Tests
- **Unit Tests:** 12 tests
- **Integration Tests:** 6 tests
- **Pass Rate:** 100%

### Performance
- **Build Time:** ~0.1s (incremental)
- **Test Time:** ~0.5s (unit)
- **Total Verification:** <1 minute

### Dependencies
- **nostr-sdk:** 0.43.0 (latest)
- **Rust:** 1.91.0
- **Nix:** Latest stable

---

## ✅ Status Checklist

### Working ✅
- [x] Build system
- [x] Unit tests
- [x] CLI tool
- [x] Examples
- [x] Documentation

### Ready ⏳
- [ ] Integration tests (needs relay)
- [ ] End-to-end testing (needs relay)
- [ ] Performance testing

### Planned 🔜
- [ ] GRASP-01 tests
- [ ] ngit-grasp relay
- [ ] Full compliance

---

## 🚀 Next Steps

### Today (30 min)
```bash
# 1. Start relay
docker run --rm -p 7000:7000 scsibug/nostr-rs-relay

# 2. Run integration tests
cd grasp-audit
nix develop --command cargo test --ignored

# 3. Test CLI
nix develop --command cargo run -- audit \
  --relay ws://localhost:7000 \
  --mode ci \
  --spec nip01-smoke
```

### This Week
- Implement GRASP-01 tests OR
- Start ngit-grasp relay OR
- Both in parallel

### Next 2-3 Weeks
- Complete GRASP-01 compliance
- Full integration testing
- Production ready

---

## 💡 Tips

### Fast Development
```bash
# Use nix develop for consistent environment
nix develop

# Use cargo watch for auto-rebuild
cargo install cargo-watch
cargo watch -x test

# Use cargo-expand to see macros
cargo install cargo-expand
cargo expand
```

### Debugging
```bash
# Run with logging
RUST_LOG=debug cargo test -- --nocapture

# Run specific test
cargo test test_name -- --nocapture

# Use rust-lldb or rust-gdb
rust-lldb ./target/debug/grasp-audit
```

### Performance
```bash
# Profile build
cargo build --timings

# Benchmark
cargo bench

# Check binary size
ls -lh ./target/release/grasp-audit
```

---

## 📞 Getting Help

### Documentation
1. Check README.md
2. Read QUICK_START.md
3. Review examples/
4. See inline docs: `cargo doc --open`

### Troubleshooting
1. Check this file
2. Review VERIFICATION_COMPLETE.md
3. Read error messages carefully
4. Check GitHub issues

### Community
- GRASP Protocol: https://gitworkshop.dev/danconwaydev.com/grasp
- rust-nostr: https://github.com/rust-nostr/nostr
- Nostr: https://nostr.com

---

**Quick Reference Version:** 1.0  
**Last Updated:** November 4, 2025  
**Status:** ✅ Current

---

*Keep this file handy for quick lookups! 📌*