mirror of
https://relay.ngit.dev/npub15qydau2hjma6ngxkl2cyar74wzyjshvl65za5k5rl69264ar2exs5cyejr/ngit-grasp.git
synced 2026-10-05 15:08:24 +00:00
DanConwayDev
22557f15d6
- Archive 30 completed session documents to docs/archive/ - Extract learnings to docs/learnings/ (nix-flakes, nostr-sdk, grasp-audit) - Create CURRENT_STATUS.md as single source of truth - Create AGENTS.md with documentation guidelines - Create docs/archive/README.md for archive organization - Clean root directory: 32 files → 4 files Root directory now contains only: - README.md (project overview) - AGENTS.md (documentation guidelines) - CURRENT_STATUS.md (current state) - CLEANUP_SUMMARY.md (cleanup report) All historical documents preserved in docs/archive/ with proper dating. All reusable knowledge extracted to docs/learnings/. Benefits: - Easy to find current information - Clear document lifecycle - No more documentation sprawl - Learnings are accessible and reusable - Better onboarding for new developers/agents File counts: - Root: 4 (was 32) - Permanent docs: 7 - Learnings: 3 (new) - Archive: 32 (new) - Total: 49 well-organized docs
465 lines
10 KiB
Markdown
465 lines
10 KiB
Markdown
# ngit-grasp - Current Status
|
|
|
|
**Date:** November 4, 2025
|
|
**Phase:** Audit Tool Complete - Ready for NIP-01 Implementation
|
|
**Status:** 🟢 All Systems Green
|
|
|
|
---
|
|
|
|
## Quick Summary
|
|
|
|
✅ **grasp-audit tool complete** - NIP-01 smoke tests passing
|
|
✅ **Tag migration complete** - Using standard NIP-01 "t" tags
|
|
✅ **nostr-sdk upgraded** - Version 0.43.x (latest stable)
|
|
✅ **Nix flakes migrated** - Modern reproducible builds
|
|
✅ **Documentation cleaned** - Clear structure established
|
|
|
|
**Next:** Build NIP-01 relay implementation, test with grasp-audit
|
|
|
|
---
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
ngit-grasp/
|
|
├── README.md # Project overview
|
|
├── AGENTS.md # AI agent guidelines
|
|
├── CURRENT_STATUS.md # This file
|
|
│
|
|
├── docs/ # Permanent documentation
|
|
│ ├── ARCHITECTURE.md # System design
|
|
│ ├── TEST_STRATEGY.md # Testing approach
|
|
│ ├── GETTING_STARTED.md # Setup guide
|
|
│ ├── GIT_PROTOCOL.md # Git protocol reference
|
|
│ ├── COMPARISON.md # vs ngit-relay
|
|
│ ├── DECISION_SUMMARY.md # Key decisions
|
|
│ │
|
|
│ ├── learnings/ # Reusable knowledge
|
|
│ │ ├── nix-flakes.md # Nix flake patterns
|
|
│ │ ├── nostr-sdk.md # nostr-sdk 0.43 notes
|
|
│ │ └── grasp-audit.md # Audit tool patterns
|
|
│ │
|
|
│ └── archive/ # Historical documents
|
|
│ ├── 2025-11-04-tag-migration.md
|
|
│ ├── 2025-11-04-flake-migration.md
|
|
│ ├── 2025-11-04-nostr-sdk-upgrade.md
|
|
│ └── ...
|
|
│
|
|
└── grasp-audit/ # Audit tool (separate crate)
|
|
├── README.md # Audit tool docs
|
|
├── QUICK_START.md # Getting started
|
|
├── flake.nix # Nix dev environment
|
|
├── Cargo.toml # Rust dependencies
|
|
└── src/
|
|
├── specs/ # Test specifications
|
|
│ └── nip01_smoke.rs # NIP-01 basic tests ✅
|
|
├── audit.rs # Audit config & event builder
|
|
├── client.rs # Audit client wrapper
|
|
└── ...
|
|
```
|
|
|
|
---
|
|
|
|
## What Works
|
|
|
|
### grasp-audit Tool ✅
|
|
|
|
**Status:** Fully functional, all tests passing
|
|
|
|
```bash
|
|
cd grasp-audit
|
|
nix develop
|
|
cargo test --lib # 12/12 unit tests ✅
|
|
cargo test -- --ignored # 1/1 integration test ✅
|
|
cargo run -- audit --relay ws://localhost:7000 --spec nip01-smoke
|
|
# Results: 6/6 passed (100.0%) ✅
|
|
```
|
|
|
|
**Features:**
|
|
- ✅ NIP-01 smoke tests (websocket, events, subscriptions)
|
|
- ✅ CI and production modes
|
|
- ✅ Test isolation via unique run IDs
|
|
- ✅ Standard "t" tag usage
|
|
- ✅ Audit event cleanup strategy
|
|
- ✅ CLI interface
|
|
|
|
**Test Coverage:**
|
|
- websocket_connection
|
|
- send_receive_event
|
|
- create_subscription
|
|
- close_subscription
|
|
- reject_invalid_signature
|
|
- reject_invalid_event_id
|
|
|
|
---
|
|
|
|
### Development Environment ✅
|
|
|
|
**Nix Flakes:**
|
|
- ✅ `grasp-audit/flake.nix` - Reproducible builds
|
|
- ✅ Rust toolchain via rust-overlay
|
|
- ✅ All dependencies managed
|
|
- ✅ Cross-platform support
|
|
|
|
**Usage:**
|
|
```bash
|
|
cd grasp-audit
|
|
nix develop # Enter dev shell
|
|
nix develop -c cargo build # One-off command
|
|
nix build # Build package
|
|
```
|
|
|
|
---
|
|
|
|
### Documentation ✅
|
|
|
|
**Permanent Docs:**
|
|
- ✅ `docs/ARCHITECTURE.md` - Detailed system design
|
|
- ✅ `docs/TEST_STRATEGY.md` - Testing approach
|
|
- ✅ `docs/GETTING_STARTED.md` - Setup guide
|
|
- ✅ `docs/README.md` - Documentation index
|
|
|
|
**Learnings:**
|
|
- ✅ `docs/learnings/nix-flakes.md` - Nix patterns and gotchas
|
|
- ✅ `docs/learnings/nostr-sdk.md` - nostr-sdk 0.43 migration
|
|
- ✅ `docs/learnings/grasp-audit.md` - Audit tool patterns
|
|
|
|
**Guidelines:**
|
|
- ✅ `AGENTS.md` - AI agent documentation practices
|
|
|
|
---
|
|
|
|
## What's Next
|
|
|
|
### Immediate: NIP-01 Relay Implementation
|
|
|
|
**Goal:** Build basic Nostr relay that passes grasp-audit tests
|
|
|
|
**Approach:**
|
|
1. Create `src/` directory structure
|
|
2. Implement basic NIP-01 relay using nostr-relay-builder
|
|
3. Run grasp-audit tests against it
|
|
4. Iterate until all tests pass
|
|
|
|
**Files to Create:**
|
|
```
|
|
src/
|
|
├── main.rs # Entry point
|
|
├── config.rs # Configuration
|
|
├── nostr/
|
|
│ ├── mod.rs
|
|
│ ├── relay.rs # NIP-01 relay setup
|
|
│ └── events.rs # Event handling
|
|
└── storage/
|
|
├── mod.rs
|
|
└── repository.rs # Event storage
|
|
```
|
|
|
|
**Success Criteria:**
|
|
```bash
|
|
# Start ngit-grasp relay
|
|
cargo run
|
|
|
|
# In another terminal
|
|
cd grasp-audit
|
|
cargo run -- audit --relay ws://localhost:8080 --spec nip01-smoke
|
|
# Results: 6/6 passed (100.0%) ✅
|
|
```
|
|
|
|
---
|
|
|
|
### Phase 2: GRASP-01 Compliance
|
|
|
|
**After NIP-01 works:**
|
|
|
|
1. **Extend grasp-audit**
|
|
- Create `src/specs/grasp_01_relay.rs`
|
|
- Test repository announcements (NIP-34)
|
|
- Test state events
|
|
- Test maintainer validation
|
|
|
|
2. **Implement in ngit-grasp**
|
|
- NIP-34 event validation
|
|
- Repository state management
|
|
- Maintainer authorization
|
|
|
|
3. **Iterate**
|
|
- Run GRASP-01 audit tests
|
|
- Fix failures
|
|
- Repeat until passing
|
|
|
|
---
|
|
|
|
### Phase 3: Git Integration
|
|
|
|
**After GRASP-01 compliance:**
|
|
|
|
1. **Git HTTP Backend**
|
|
- Implement git-smart-http handlers
|
|
- Integrate with authorization
|
|
|
|
2. **Push Validation**
|
|
- Query Nostr state events
|
|
- Validate push permissions
|
|
- Inline authorization (no hooks)
|
|
|
|
3. **Full GRASP-01**
|
|
- Complete service requirements
|
|
- End-to-end testing
|
|
|
|
---
|
|
|
|
## Development Workflow
|
|
|
|
### Daily Development
|
|
|
|
```bash
|
|
# For ngit-grasp (when we create it)
|
|
cd ngit-grasp
|
|
nix develop
|
|
cargo build
|
|
cargo test
|
|
cargo run
|
|
|
|
# For grasp-audit
|
|
cd grasp-audit
|
|
nix develop
|
|
cargo build
|
|
cargo test --lib
|
|
cargo test -- --ignored # Requires relay
|
|
cargo run -- audit --relay ws://localhost:8080
|
|
```
|
|
|
|
---
|
|
|
|
### Running Tests
|
|
|
|
**Unit Tests (Fast):**
|
|
```bash
|
|
# grasp-audit
|
|
cd grasp-audit
|
|
cargo test --lib
|
|
|
|
# ngit-grasp (when created)
|
|
cargo test --lib
|
|
```
|
|
|
|
**Integration Tests (Requires Relay):**
|
|
```bash
|
|
# Start test relay
|
|
docker run --rm -p 7000:7000 scsibug/nostr-rs-relay
|
|
|
|
# Run integration tests
|
|
cd grasp-audit
|
|
cargo test -- --ignored
|
|
```
|
|
|
|
**Audit Tests:**
|
|
```bash
|
|
# Start your relay
|
|
cd ngit-grasp
|
|
cargo run
|
|
|
|
# Run audit in another terminal
|
|
cd grasp-audit
|
|
cargo run -- audit --relay ws://localhost:8080
|
|
```
|
|
|
|
---
|
|
|
|
## Key Technologies
|
|
|
|
### Current Stack
|
|
|
|
- **Rust**: Core language
|
|
- **nostr-sdk 0.43**: Nostr event handling
|
|
- **Nix Flakes**: Reproducible dev environment
|
|
- **Cargo**: Build system
|
|
- **Docker**: Test relay (nostr-rs-relay)
|
|
|
|
### Planned Stack (ngit-grasp)
|
|
|
|
- **actix-web**: HTTP server
|
|
- **nostr-relay-builder**: Relay infrastructure
|
|
- **git-http-backend**: Git protocol handling
|
|
- **tokio**: Async runtime
|
|
|
|
---
|
|
|
|
## Important Gotchas
|
|
|
|
### 1. Use Nix Flakes, Not nix-shell
|
|
|
|
```bash
|
|
# ✅ Correct
|
|
nix develop
|
|
|
|
# ❌ Wrong
|
|
nix-shell
|
|
```
|
|
|
|
**Why:** We use `flake.nix`, not `shell.nix`
|
|
|
|
---
|
|
|
|
### 2. grasp-audit is Separate
|
|
|
|
```bash
|
|
# ✅ Correct
|
|
cd grasp-audit
|
|
nix develop
|
|
cargo build
|
|
|
|
# ❌ Wrong
|
|
cd ngit-grasp
|
|
cargo build # Won't find grasp-audit
|
|
```
|
|
|
|
**Why:** Separate crate with own flake and Cargo.toml
|
|
|
|
---
|
|
|
|
### 3. Integration Tests Need Relay
|
|
|
|
```bash
|
|
# ✅ Correct
|
|
docker run --rm -p 7000:7000 scsibug/nostr-rs-relay
|
|
cargo test -- --ignored
|
|
|
|
# ❌ Wrong
|
|
cargo test -- --ignored # Will fail without relay
|
|
```
|
|
|
|
---
|
|
|
|
### 4. nostr-sdk 0.43 API Changes
|
|
|
|
**Event Building:**
|
|
```rust
|
|
// ✅ Correct (0.43)
|
|
EventBuilder::new(kind, content)
|
|
.tags(tags)
|
|
.sign_with_keys(&keys)?
|
|
|
|
// ❌ Wrong (0.35)
|
|
EventBuilder::new(kind, content, tags)
|
|
.to_event(&keys)?
|
|
```
|
|
|
|
**See:** `docs/learnings/nostr-sdk.md` for full migration guide
|
|
|
|
---
|
|
|
|
## Documentation Practices
|
|
|
|
### When to Create Documents
|
|
|
|
**Working Docs (Root):**
|
|
- Session summaries
|
|
- Status reports
|
|
- Next steps
|
|
- Temporary notes
|
|
|
|
**Permanent Docs (docs/):**
|
|
- Architecture
|
|
- Design decisions
|
|
- API documentation
|
|
- User guides
|
|
|
|
**Learnings (docs/learnings/):**
|
|
- Gotchas and patterns
|
|
- Migration notes
|
|
- Best practices
|
|
- Reusable knowledge
|
|
|
|
**Archive (docs/archive/):**
|
|
- Completed session docs
|
|
- Historical records
|
|
- Superseded documents
|
|
|
|
**See:** `AGENTS.md` for full guidelines
|
|
|
|
---
|
|
|
|
## Recent Milestones
|
|
|
|
- ✅ **Nov 4, 2025** - Tag migration to standard "t" tags
|
|
- ✅ **Nov 4, 2025** - Flake migration (shell.nix → flake.nix)
|
|
- ✅ **Nov 4, 2025** - nostr-sdk upgrade (0.35 → 0.43)
|
|
- ✅ **Nov 4, 2025** - Documentation cleanup
|
|
- ✅ **Nov 3, 2025** - Architecture investigation complete
|
|
- ✅ **Nov 3, 2025** - grasp-audit tool implemented
|
|
- ✅ **Nov 3, 2025** - NIP-01 smoke tests passing
|
|
|
|
---
|
|
|
|
## Success Metrics
|
|
|
|
### Current Status
|
|
|
|
| Metric | Status | Details |
|
|
|--------|--------|---------|
|
|
| grasp-audit builds | ✅ | Clean build, no warnings |
|
|
| Unit tests | ✅ | 12/12 passing |
|
|
| Integration tests | ✅ | 1/1 passing |
|
|
| CLI works | ✅ | All commands functional |
|
|
| Smoke tests | ✅ | 6/6 passing |
|
|
| Documentation | ✅ | Complete and organized |
|
|
| Nix flakes | ✅ | Reproducible builds |
|
|
|
|
### Next Milestone: NIP-01 Relay
|
|
|
|
| Metric | Status | Target |
|
|
|--------|--------|--------|
|
|
| ngit-grasp builds | 🔜 | Clean build |
|
|
| NIP-01 relay running | 🔜 | Accepts connections |
|
|
| Smoke tests pass | 🔜 | 6/6 against ngit-grasp |
|
|
| Basic event storage | 🔜 | Events persist |
|
|
| Subscriptions work | 🔜 | Real-time updates |
|
|
|
|
---
|
|
|
|
## Resources
|
|
|
|
### Documentation
|
|
- [Project README](README.md)
|
|
- [Architecture](docs/ARCHITECTURE.md)
|
|
- [Test Strategy](docs/TEST_STRATEGY.md)
|
|
- [Getting Started](docs/GETTING_STARTED.md)
|
|
- [Agent Guidelines](AGENTS.md)
|
|
|
|
### Learnings
|
|
- [Nix Flakes](docs/learnings/nix-flakes.md)
|
|
- [nostr-sdk](docs/learnings/nostr-sdk.md)
|
|
- [grasp-audit](docs/learnings/grasp-audit.md)
|
|
|
|
### External
|
|
- [GRASP Protocol](https://gitworkshop.dev/danconwaydev.com/grasp)
|
|
- [NIP-01](https://github.com/nostr-protocol/nips/blob/master/01.md)
|
|
- [NIP-34](https://github.com/nostr-protocol/nips/blob/master/34.md)
|
|
- [nostr-sdk docs](https://docs.rs/nostr-sdk/0.43.0)
|
|
|
|
---
|
|
|
|
## Contact & Contribution
|
|
|
|
**Status:** Alpha - Active Development
|
|
**License:** MIT
|
|
**Repository:** ngit-grasp (local development)
|
|
|
|
**Contributing:**
|
|
1. Read `AGENTS.md` for documentation practices
|
|
2. Review `docs/ARCHITECTURE.md` for design
|
|
3. Check `CURRENT_STATUS.md` (this file) for current state
|
|
4. Follow Rust conventions (`cargo fmt`, `cargo clippy`)
|
|
5. Add tests for new functionality
|
|
|
|
---
|
|
|
|
**Last Updated:** November 4, 2025
|
|
**Next Review:** When NIP-01 relay is implemented
|
|
|
|
---
|
|
|
|
*Status: 🟢 Ready to build NIP-01 relay implementation*
|