rusty-beads 0.1.0

# Rusty Beads

[![Crates.io](https://img.shields.io/crates/v/rusty-beads.svg)](https://crates.io/crates/rusty-beads)
[![Documentation](https://docs.rs/rusty-beads/badge.svg)](https://docs.rs/rusty-beads)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A Git-backed graph issue tracker for AI coding agents, written in Rust.

Rusty Beads is a Rust implementation of [steveyegge/beads](https://github.com/steveyegge/beads), providing 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 (30+ fields)
- **Dependency Graphs** - Model complex task relationships with automatic cycle detection
- **Context Store** - Git-aware caching for file summaries, symbols, and project context
- **Semantic Compaction** - 3-level compaction to reduce context size while preserving essential info
- **SQLite Storage** - Fast, reliable local storage with WAL mode for concurrent access
- **JSONL Export** - Git-friendly format for version control and collaboration
- **Background Daemon** - JSON-RPC server over Unix sockets for concurrent access
- **Hash-based IDs** - Collision-free identifiers in `bd-xxxx` format

## Installation

### As a CLI Tool

```bash
cargo install rusty-beads
```

### As a Library

Add to your `Cargo.toml`:

```toml
[dependencies]
rusty-beads = "0.1"
```

## Quick Start

### CLI Usage

```bash
# Initialize a new beads repository
bd init

# Create issues
bd create -t "Implement user authentication"
bd create -t "Add login endpoint" --parent bd-a1b2

# View ready (unblocked) work
bd ready

# Add dependencies
bd dep add bd-c3d4 bd-a1b2  # bd-c3d4 is blocked by bd-a1b2

# List issues
bd list
bd list --status open --assignee alice

# Update and close issues
bd update bd-a1b2 --status in_progress
bd close bd-a1b2 --reason "Completed"

# Use the context store
bd context set "file:src/main.rs" '{"summary": "Application entry point"}'
bd context get "file:src/main.rs"
bd context list --namespace file
```

### Library Usage

```rust
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
use rusty_beads::{ContextStore, ContextEntry, FileContext};
use serde_json::json;
use anyhow::Result;

fn main() -> Result<()> {
    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 data with TTL
    let entry = ContextEntry::new("custom:cache-key", json!({"data": "value"}))
        .with_ttl(3600); // Expires in 1 hour
    store.set(entry)?;

    // Retrieve with automatic invalidation checking
    if let Some(ctx) = store.get_file_context("src/main.rs")? {
        println!("Summary: {:?}", ctx.summary);
    }

    Ok(())
}
```

## Architecture

```
rusty-beads/
├── src/
│   ├── lib.rs           # Public API and documentation
│   ├── main.rs          # CLI entry point
│   ├── types/           # Core data types (Issue, Status, Dependency, etc.)
│   ├── storage/         # SQLite backend + JSONL import/export
│   ├── 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 utilities
│   └── cli/             # Command-line interface
```

## CLI Commands

| Command | Description |
|---------|-------------|
| `bd init` | Initialize a new .beads directory |
| `bd create` | Create a new issue |
| `bd show <id>` | Show issue details |
| `bd list` | List issues with filters |
| `bd ready` | Show unblocked issues ready for work |
| `bd update <id>` | Update an issue |
| `bd close <id>` | Close an issue |
| `bd delete <id>` | Soft-delete (tombstone) an issue |
| `bd dep add/remove/list` | Manage dependencies |
| `bd label add/remove/list` | Manage labels |
| `bd stats` | Show repository statistics |
| `bd compact` | Run semantic compaction |
| `bd daemon start/stop/status` | Manage background daemon |
| `bd config` | Manage configuration |
| `bd context get/set/list/clear` | Manage context store |

## Context Store Namespaces

The context store organizes data into namespaces:

| Namespace | Prefix | Description |
|-----------|--------|-------------|
| File | `file:` | File-level context (summaries, AST, symbols) |
| Symbol | `symbol:` | Symbol definitions (functions, classes, types) |
| Project | `project:` | Project-level context (architecture, patterns) |
| Session | `session:` | Session context (recent decisions, working files) |
| Agent | `agent:` | Agent-specific context (preferences, learned patterns) |
| Custom | `custom:` | User-defined context |

## Git-Aware Invalidation

The context store automatically invalidates cached entries when:

- File modification time (mtime) changes
- File has uncommitted git changes
- Git HEAD commit changes
- TTL expires

## Issue Types

Rusty Beads supports various issue types for different use cases:

- `bug`, `feature`, `task`, `epic`, `chore` - Standard issue types
- `molecule`, `gate`, `agent`, `role`, `rig` - AI agent-specific types
- `convoy`, `event`, `merge_request`, `slot` - Advanced workflow types

## Dependency Types

Model complex relationships between issues:

- `blocks` - Issue A blocks issue B
- `parent_child` - Hierarchical relationship
- `relates_to` - General relationship
- `duplicates` - Duplicate issues
- `supersedes` - Replacement relationship
- And 14 more specialized types

## Storage

- **SQLite** with WAL mode for concurrent access
- **JSONL export** for git-friendly version control
- **Dirty tracking** for incremental exports
- **Content hashing** for change detection

## Development

```bash
# Build
cargo build

# Run tests
cargo test

# Generate documentation
cargo doc --open

# Run with debug logging
RUST_LOG=debug cargo run -- list
```

## Inspired By

This project is a Rust implementation inspired by [steveyegge/beads](https://github.com/steveyegge/beads), the original Go implementation.

## License

MIT License - see [LICENSE](LICENSE) for details.