# ⚡ 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 Relay WebSocket URL (required) --mode Test mode: ci or production --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! 📌*