laantungir/ngit-grasp

Fork 0

mirror of https://relay.ngit.dev/npub15qydau2hjma6ngxkl2cyar74wzyjshvl65za5k5rl69264ar2exs5cyejr/ngit-grasp.git synced 2026-10-05 15:08:24 +00:00

Files

T

History

DanConwayDev f286f62779 docs: clean up .txt files and add file format guidelines

- Archive 5 .txt files to docs/archive/
  - AUDIT_FIX_SUMMARY.txt
  - PROJECT_STATUS_VISUAL.txt
  - SESSION_SUMMARY.txt
  - TEST_VISUAL_SUMMARY.txt
  - CLEANUP_VISUAL_SUMMARY.txt

- Update AGENTS.md with file format guidelines:
  - When to use .txt (ASCII art only)
  - When to use .md (all documentation)
  - .txt lifecycle: create → use → archive immediately
  - Added to cleanup triggers and checklists

Root directory now completely clean:
- 4 .md files (README, AGENTS, CURRENT_STATUS, CLEANUP_COMPLETE)
- 0 .txt files (all archived)

Archive contains:
- 33 .md files (historical documentation)
- 5 .txt files (visual summaries)

2025-11-04 09:43:53 +00:00

README.md

ngit-grasp Documentation

Overview

This directory contains comprehensive documentation for the ngit-grasp project.

Documents

For Review

../REVIEW_SUMMARY.md - Start here! Executive summary of the architecture investigation and recommendations

Architecture & Design

ARCHITECTURE.md - Detailed technical architecture, component design, data flows, and implementation details
DECISION_SUMMARY.md - Why we chose inline authorization over Git hooks
COMPARISON.md - Side-by-side comparison with the reference implementation (ngit-relay)

Technical References

GIT_PROTOCOL.md - Git Smart HTTP protocol reference, pkt-line format, and parsing examples
TEST_STRATEGY.md - Comprehensive testing strategy including reusable GRASP compliance testing tool

Project Files

../README.md - Project overview, quick start, and feature list
../.env.example - Configuration template
../LICENSE - MIT License

Reading Guide

If you want to understand the architecture decision:

Read REVIEW_SUMMARY.md - Executive summary
Read DECISION_SUMMARY.md - Detailed rationale
Skim COMPARISON.md - See how we differ from reference

If you want to implement:

Read ARCHITECTURE.md - Component design and code structure
Read TEST_STRATEGY.md - Testing approach and compliance tool
Read GIT_PROTOCOL.md - Git protocol details
Review code examples in ARCHITECTURE.md

If you want to deploy:

Read README.md - Quick start
Review .env.example - Configuration
See deployment section in ARCHITECTURE.md

If you're comparing with ngit-relay:

Read COMPARISON.md - Detailed comparison
See architecture diagrams in both COMPARISON.md and ARCHITECTURE.md

Key Concepts

Inline Authorization

The core architectural decision: we validate Git pushes inside the HTTP handler before spawning Git, rather than using Git's pre-receive hooks.

Benefits:

Better error messages (HTTP responses vs. hook stderr)
Simpler deployment (no hook management)
Easier testing (pure Rust)
Better performance (skip Git for invalid pushes)

GRASP Protocol

Git Relays Authorized via Signed-Nostr Proofs - a protocol for hosting Git repositories with Nostr-based authorization.

Key Points:

Repository announcements (NIP-34 kind 30317)
State announcements (NIP-34 kind 30318)
Multi-maintainer support via recursive maintainer sets
Push validation against signed state events

Technology Stack

actix-web: HTTP server
git-http-backend: Git protocol handling (Rust crate)
nostr-relay-builder: Nostr relay infrastructure (rust-nostr)
tokio: Async runtime

Status

ALPHA - Architecture design complete, implementation not yet started.

Contributing

See ../README.md for contribution guidelines.

Questions?

Open an issue or discussion on the repository.