From 2eaff5b79fed364d5eba5eb38e4b7bf76326884d Mon Sep 17 00:00:00 2001 From: DanConwayDev Date: Wed, 3 Dec 2025 11:19:40 +0000 Subject: remove docs archive --- docs/archive/2025-11-03-quick-reference.md | 449 ----------------------------- 1 file changed, 449 deletions(-) delete mode 100644 docs/archive/2025-11-03-quick-reference.md (limited to 'docs/archive/2025-11-03-quick-reference.md') diff --git a/docs/archive/2025-11-03-quick-reference.md b/docs/archive/2025-11-03-quick-reference.md deleted file mode 100644 index b9b9943..0000000 --- a/docs/archive/2025-11-03-quick-reference.md +++ /dev/null @@ -1,449 +0,0 @@ -# โšก 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! ๐Ÿ“Œ* -- cgit v1.2.3