rusty_beads/

lib.rs

//! # Rusty Beads
//!
//! A Git-backed graph issue tracker for AI coding agents.
//!
//! Rusty Beads provides a powerful issue tracking system designed specifically for AI coding
//! agents, with features like dependency graphs, semantic compaction, and a context store
//! for caching file summaries, symbol indexes, and project metadata.
//!
//! ## Features
//!
//! - **Issue Management**: Create, update, and track issues with rich metadata
//! - **Dependency Graphs**: Model complex relationships with cycle detection
//! - **Context Store**: Git-aware caching for file summaries, symbols, and project context
//! - **Semantic Compaction**: Reduce context size while preserving essential information
//! - **SQLite Storage**: Fast, reliable local storage with WAL mode
//! - **JSONL Export**: Git-friendly format for version control
//! - **Background Daemon**: RPC server for concurrent access
//!
//! ## Quick Start
//!
//! ### As a Library
//!
//! Add to your `Cargo.toml`:
//!
//! ```toml
//! [dependencies]
//! rusty-beads = "0.1"
//! ```
//!
//! ### Basic Usage
//!
//! ```rust,no_run
//! use rusty_beads::{SqliteStorage, Storage, Issue, generate_id};
//! use anyhow::Result;
//!
//! fn main() -> Result<()> {
//!     // Open or create a database
//!     let storage = SqliteStorage::open(".beads/beads.db")?;
//!
//!     // Create an issue
//!     let id = generate_id("bd");
//!     let issue = Issue::new(&id, "Implement new feature", "developer");
//!     storage.create_issue(&issue)?;
//!
//!     // Get ready work (unblocked issues)
//!     let ready = storage.get_ready_work()?;
//!     for issue in ready {
//!         println!("{}: {}", issue.id, issue.title);
//!     }
//!
//!     Ok(())
//! }
//! ```
//!
//! ### Context Store
//!
//! The context store helps AI agents cache and retrieve contextual information
//! with automatic git-aware invalidation:
//!
//! ```rust,no_run
//! use rusty_beads::{ContextStore, ContextEntry, FileContext, Namespace};
//! use serde_json::json;
//! use anyhow::Result;
//!
//! fn main() -> Result<()> {
//!     // Open context store
//!     let store = ContextStore::open(".beads/context.db")?;
//!
//!     // Store file context
//!     let file_ctx = FileContext {
//!         path: "src/main.rs".to_string(),
//!         summary: Some("Application entry point".to_string()),
//!         language: Some("rust".to_string()),
//!         ..Default::default()
//!     };
//!     store.set_file_context("src/main.rs", &file_ctx)?;
//!
//!     // Store arbitrary key-value data
//!     let entry = ContextEntry::new(
//!         "custom:my-key",
//!         json!({"data": "value"})
//!     ).with_ttl(3600); // Expires in 1 hour
//!     store.set(entry)?;
//!
//!     // Retrieve context
//!     if let Some(ctx) = store.get_file_context("src/main.rs")? {
//!         println!("Summary: {:?}", ctx.summary);
//!     }
//!
//!     Ok(())
//! }
//! ```
//!
//! ### Dependencies
//!
//! Model complex task relationships:
//!
//! ```rust,no_run
//! use rusty_beads::{SqliteStorage, Storage, Dependency, DependencyType};
//! use anyhow::Result;
//!
//! fn main() -> Result<()> {
//!     let storage = SqliteStorage::open(".beads/beads.db")?;
//!
//!     // Create a blocking dependency (bd-0002 is blocked by bd-0001)
//!     let dep = Dependency::blocks("bd-0002", "bd-0001");
//!
//!     // Check for cycles before adding
//!     if !storage.would_create_cycle("bd-0002", "bd-0001", DependencyType::Blocks)? {
//!         storage.add_dependency(&dep)?;
//!     }
//!
//!     Ok(())
//! }
//! ```
//!
//! ## Modules
//!
//! - [`types`] - Core data types (Issue, Status, Dependency, etc.)
//! - [`storage`] - Storage backends (SQLite, JSONL export/import)
//! - [`context`] - Context store for AI agents
//! - [`idgen`] - Hash-based ID generation
//! - [`compact`] - Semantic compaction
//! - [`daemon`] - Background RPC server
//! - [`git`] - Git integration utilities
//! - [`cli`] - Command-line interface
//!
//! ## CLI Tool
//!
//! Install the `bd` command-line tool:
//!
//! ```bash
//! cargo install rusty-beads
//! ```
//!
//! Basic commands:
//!
//! ```bash
//! # Initialize a new repository
//! bd init
//!
//! # Create an issue
//! bd create -t "Fix bug in parser"
//!
//! # List ready (unblocked) issues
//! bd ready
//!
//! # Add a dependency
//! bd dep add bd-0002 bd-0001
//!
//! # Use context store
//! bd context set "file:main.rs" '{"summary": "Entry point"}'
//! bd context get "file:main.rs"
//! ```
//!
//! ## Architecture
//!
//! ```text
//! rusty-beads/
//! ├── types/       # Core data types
//! ├── storage/     # SQLite + JSONL backends
//! ├── context/     # Context store with git-aware invalidation
//! ├── idgen/       # Hash-based ID generation (bd-xxxx)
//! ├── compact/     # Semantic compaction (3 levels)
//! ├── daemon/      # Background RPC server
//! ├── git/         # Git integration
//! └── cli/         # Command-line interface
//! ```

pub mod types;
pub mod storage;
pub mod idgen;
pub mod git;
pub mod daemon;
pub mod compact;
pub mod cli;
pub mod context;

// Re-export CLI types for binary
pub use cli::{Cli, run};

// Re-export commonly used types
pub use types::{
    Issue, Status, IssueType, Dependency, DependencyType,
    Comment, Event, EventType, Label, IssueFilter,
    AgentState, MolType, BlockedIssue, Statistics,
};

pub use storage::{Storage, SqliteStorage};
pub use idgen::generate_id;
pub use context::{ContextStore, ContextEntry, Namespace, FileContext, ProjectContext, SessionContext};

/// Library version.
pub const VERSION: &str = env!("CARGO_PKG_VERSION");

/// Default ID prefix for issues.
pub const DEFAULT_PREFIX: &str = "bd";