Skip to content

PLAN.md

Latest commit

 

History

History
415 lines (344 loc) · 14.8 KB

PLAN.md

File metadata and controls

415 lines (344 loc) · 14.8 KB

Gitant Product Master Plan

Goal: make Gitant a production-grade, agent-native git platform — honest about what ships today (single-node) while building toward decentralized P2P.

Architecture target (informed by Radicle, gitlawb, UCAN spec, Forgejo ops)

┌─────────────┐     MCP (stdio)      ┌──────────────┐
│ AI Agents   │◄────────────────────►│  gitant-mcp  │
└─────────────┘                      └──────┬───────┘
                                               │ REST + UCAN
┌─────────────┐     git / gitant CLI   ┌──────────────┐
│  Developers │◄────────────────────►│  gitant-cli  │
└─────────────┘                      └──────┬───────┘
       │                                    │ REST + UCAN
       │     /api/daemon proxy              │
       ▼                                    ▼
┌─────────────┐                      ┌──────────────┐
│  Developers │◄────────────────────►│  gitant-web  │
└─────────────┘                      └──────┬───────┘
                                               │
                                        ┌──────▼───────┐
                                        │ gitant-daemon│
                                        │  HTTP + Git  │
                                        └──────┬───────┘
                                               │
                     Phase 2+ ─────────────────┼──────────────► libp2p DHT + GossipSub
                                               │                IPFS/block replication
                                        ┌──────▼───────┐
                                        │ Local stores │
                                        │ repos + CRDT │
                                        └──────────────┘

Current state (honest)

Layer Status
Single-node Git host Operational — push/pull/clone, smart HTTP, packfile
Collaboration (issues/PRs/tasks) Operational — CRDT metadata on disk
DID + UCAN + HTTP Signatures Implemented — enforcement gaps being closed
Web dashboard Operational locally — most daemon APIs wired
MCP (64 tools) Dev-ready — GitHub clone + release tarballs
P2P / multi-node sync Partial — block exchange + CRDT gossip; bootstrap seeds via env
Multi-user auth NEW — SQLite backend, RBAC, session-based auth
Inline code review NEW — PR review comments with threads
CI/CD runner NEW — Workflow engine for .gitant/workflows/*.yml
Package registry NEW — npm/Docker package management
Wiki system NEW — Markdown wiki per repository
Notifications NEW — In-app notifications with unread counts
Git LFS NEW — Large file storage support
WebSocket NEW — Real-time updates for issues, PRs, pushes
Security NEW — CSRF, input validation, security headers
Monitoring NEW — Prometheus metrics, health checks
Caching NEW — In-memory cache with TTL
Import/Export NEW — Repository migration support

Phase A — Operational trust ✅ complete

gitant-daemon

  • Fix backup/restore (identity.key, repos/, data/ subtree)
  • Private repo access control (read middleware + list filter)
  • PR merge: git fast-forward + approval parse fix + identity context fix
  • Live agent count in /api/v1/status
  • RequireCapability: allow HTTP-signature operators; UCAN agents scoped
  • Fix "identity" context key → middleware.GetIdentity across handlers
  • docker-compose.stack.yml for daemon + web stack

gitant-web

  • UCAN token settings on /agents
  • Auto-save token after delegation
  • Agent registry list UI
  • Client error reporting via Next API route (no CORS)
  • Docker Compose (daemon + web) + web Dockerfile
  • output: "standalone" for production builds

gitant-mcp

  • Issue/PR IDs as strings (match daemon)
  • push_code includes objects[]
  • get_daemon_status tool
  • Node bin entry, ESM, shebang
  • README updated (64 tools, env vars)

gitant-cli

  • Standalone developer CLI repo (GrayCodeAI/gitant-cli)
  • v0.1.0 release + install script

Phase B — Production single-node ✅ complete

Daemon

  • Real merge commits when branches diverged (not just FF)
  • Smart HTTP ref deletion in receive-pack
  • Wire AgentRegistry.Record() on authenticated requests
  • Server integration tests with auth middleware
  • Enforce UCAN per-route: repo:{id} read/write capabilities
  • Fix fork: inherit visibility rules, block private fork without auth
  • Issue/PR list filters (status, labels query params)

Web

  • Repo stars UI (starRepo, getStarCount)
  • Label management pages
  • Release detail route
  • Settings: daemon URL display, connection test
  • Metrics dashboard (/metrics Prometheus → simple charts)
  • E2E tests (Playwright CI job)

MCP

  • push_packfile tool (CLI parity)
  • Pagination params on list tools
  • List filters aligned with daemon (status, labels)
  • MCP tool handler integration tests
  • GitHub release workflow (.github/workflows/release.yml — tarball on tag)

Ops

  • docker-compose.prod.yml with Caddy/nginx TLS
  • Documented backup schedule (docs/BACKUP.md)
  • Health checks in compose for both services
  • Install scripts (gitant-cli/scripts/install.sh, gitant-daemon/scripts/install.sh)

Phase C — Decentralization (major — matches Phase 1 roadmap claims)

Reference: gitlawb (libp2p DHT + GossipSub per repo), Radicle (git-native issues), UCAN delegation chains.

C1 — Network bootstrap ✅

  • Start libp2p host from gitant serve (--p2p)
  • mDNS for LAN; DHT for WAN peer discovery
  • Config: --p2p, --bootstrap-peers, listen addrs
  • Status API: real peer count, connected multiaddrs

C2 — Data replication ✅

  • GossipSub topics per repo: gitant/repo/{id}/events
  • DHT provide repo head on push
  • Replicate git objects on push (/gitant/block/1.0.0 + DHT announce)
  • CRDT op broadcast: issue/PR Lamport ops merged across peers
  • Conflict resolution policy documented + tested (docs/CRDT_SYNC.md)

C3 — Federation ✅

  • Cross-instance discovery endpoint (GET /api/v1/federation/discover)
  • Bootstrap seed nodes via GITANT_SEED_PEERS, embedded JSON, --bootstrap-peers
  • Optional IPFS warm pinning adapter (--ipfs-pin, in-process CID store)

C4 — Agent economy (partial)

  • Trust scores from cross-peer attestation (gossip + POST /agents/{did}/attest)
  • TypeScript SDK (gitant-mcp/sdk, @gitant/sdk)
  • Agent marketplace (Phase 6)

Phase D — Production Ready for 10-Dev Team ✅ complete

D1 — Database Layer

  • SQLite database backend (internal/store/sqlite/)
  • Migration system with versioned migrations
  • Store interfaces for pluggable backends
  • User, Session, Issue, PR, Label, Task, Release, Protection, ReviewComment stores

D2 — Multi-User Authentication

  • User registration and login
  • Session-based authentication (JWT tokens)
  • RBAC with 5 roles: owner, admin, maintainer, developer, viewer
  • Password hashing with bcrypt
  • Auth middleware for session validation

D3 — Inline Code Review

  • Review comment store with SQLite backend
  • Create, list, resolve, delete comments
  • File path and line number tracking
  • Comment threading with parent_id

D4 — CI/CD Runner

  • Workflow engine (internal/runner/)
  • YAML workflow parser
  • Job scheduler and execution
  • Log streaming
  • API endpoints for runs

D5 — Package Registry

  • Package registry (internal/packages/)
  • Publish, get, list, search, delete packages
  • Version management
  • API endpoints

D6 — Wiki System

  • Wiki per repository (internal/wiki/)
  • Markdown page CRUD
  • Page search
  • API endpoints

D7 — Notifications

  • Notification manager (internal/notifications/)
  • Create, list, mark as read
  • Unread count
  • API endpoints

D8 — Git LFS

  • LFS store (internal/lfs/)
  • Upload, download, verify objects
  • Batch operations
  • API endpoints

D9 — Performance

  • In-memory cache with TTL (internal/cache/)
  • Automatic cleanup of expired items
  • Thread-safe operations

D10 — Security

  • Input validation (internal/security/validation.go)
  • CSRF protection
  • Security headers middleware
  • CORS middleware
  • Request size limiting
  • Content type validation

D11 — Monitoring

  • Prometheus metrics (internal/observability/metrics.go)
  • HTTP, DB, cache, auth, WebSocket metrics
  • Structured logging middleware
  • Request ID tracking
  • Error/panic recovery

D12 — High Availability

  • Health checker (internal/observability/health.go)
  • Liveness probe (/live)
  • Readiness probe (/ready)
  • Health check (/health)
  • Graceful shutdown with hooks

D13 — Real-time Updates

  • WebSocket hub (internal/websocket/)
  • Client management
  • Repo-scoped broadcasting
  • User-scoped notifications
  • Event types for issues, PRs, pushes

D14 — API Completeness

  • Import/export handlers
  • Batch operations
  • OpenAPI specification
  • Activity feed

D15 — Documentation

  • Deployment guide (docs/DEPLOYMENT.md)
  • Configuration reference
  • TLS/HTTPS setup
  • Backup/restore procedures
  • Troubleshooting guide

Phase E — Future (Post v1.0)

  • Agent marketplace
  • IDE extensions (VS Code, JetBrains)
  • Mobile app
  • GitHub/GitLab import
  • Discussions/Q&A
  • Projects (Kanban)
  • SAML/SSO
  • Audit log
  • PostgreSQL support
  • Redis caching
  • Kubernetes deployment
  • Multi-node clustering

Success metrics

Metric Target Status
go test ./... pass ✅
SQLite backend working ✅
Multi-user auth working ✅
Inline code review working ✅
CI/CD runner working ✅
Package registry working ✅
Wiki system working ✅
Notifications working ✅
Git LFS working ✅
WebSocket working ✅
Security hardening working ✅
Monitoring working ✅
Health checks working ✅
Import/Export working ✅
Batch operations working ✅
OpenAPI spec working ✅
Deployment docs complete ✅

Research references

  • UCAN: https://ucan.xyz — capability delegation for agents
  • HTTP Signatures: RFC 9421 — request signing (already in daemon)
  • Radicle: peer-to-peer forge, git-native issues/patches
  • gitlawb: libp2p + IPFS + UCAN architecture reference
  • Forgejo/Gitea: Docker compose, Postgres, Caddy TLS patterns for self-hosting
  • freenet-git: phased decentralization (single-writer → multi-writer ACL)

Repo map

Repo Purpose Port
gitant-cli Developer CLI (gitant, git-remote-gitant) —
gitant-daemon Server (gitant serve), API, git transport 7777
gitant-web Next.js UI 3303 (dev) / 3000 (prod)
gitant-mcp MCP server for agents stdio

Local dev: clone all four repos into one folder (e.g. gitant-core/) — no wrapper repo required.

Distribution: GitHub only (clone, releases, install scripts). Public package registry deferred until post-launch.

New API Endpoints (40+)

Authentication

POST   /api/v1/auth/register     - Register new user
POST   /api/v1/auth/login        - Login
POST   /api/v1/auth/logout       - Logout
GET    /api/v1/auth/profile      - Get current user profile

Users

GET    /api/v1/users             - List all users
GET    /api/v1/users/:id         - Get user by ID

Review Comments

GET    /api/v1/repos/:id/prs/:prId/review    - List review comments
POST   /api/v1/repos/:id/prs/:prId/review    - Create review comment
POST   /api/v1/review-comments/:id/resolve   - Resolve comment
DELETE /api/v1/review-comments/:id            - Delete comment

Actions (CI/CD)

GET    /api/v1/actions/runs      - List workflow runs
GET    /api/v1/actions/runs/:id  - Get workflow run

Packages

GET    /api/v1/packages          - List packages
GET    /api/v1/packages/:name    - Get package
GET    /api/v1/packages/:name/:version - Get package version
POST   /api/v1/packages          - Publish package
DELETE /api/v1/packages/:name    - Delete package

Wiki

GET    /api/v1/repos/:id/wiki/pages          - List wiki pages
GET    /api/v1/repos/:id/wiki/pages/:slug    - Get wiki page
POST   /api/v1/repos/:id/wiki/pages          - Create wiki page
PUT    /api/v1/repos/:id/wiki/pages/:slug    - Update wiki page
DELETE /api/v1/repos/:id/wiki/pages/:slug    - Delete wiki page
GET    /api/v1/repos/:id/wiki/search?q=      - Search wiki

Notifications

GET    /api/v1/notifications              - List notifications
PUT    /api/v1/notifications/:id/read     - Mark as read
PUT    /api/v1/notifications/read-all     - Mark all as read
GET    /api/v1/notifications/unread-count - Get unread count

LFS

POST   /api/v1/repos/:id/lfs/objects/batch   - Batch request
GET    /api/v1/repos/:id/lfs/objects/:oid     - Download object
PUT    /api/v1/repos/:id/lfs/objects/:oid     - Upload object
POST   /api/v1/repos/:id/lfs/objects/:oid/verify - Verify object

Import/Export

POST   /api/v1/import              - Import repository
POST   /api/v1/export              - Export repository
POST   /api/v1/import/github       - Import from GitHub
POST   /api/v1/import/gitlab       - Import from GitLab

Batch

POST   /api/v1/batch               - Execute batch operations

System

GET    /health                     - Health check
GET    /ready                      - Readiness probe
GET    /live                       - Liveness probe
GET    /metrics                    - Prometheus metrics
GET    /api/v1/openapi.json        - OpenAPI specification
GET    /ws                         - WebSocket connection

Last updated: 2026-05-26 — All phases complete. Ready for 10-dev team.