vibed/nbd/CLAUDE.md

CLAUDE.md — nbd

nbd is a CLI tool for managing work tickets, primarily targeted at agent workflows. It is an independent Rust crate within the vibed mono-repo.

Project Structure

nbd/
├── CLAUDE.md
├── PLAN.md               # implementation plan and post-MVP roadmap
├── Cargo.toml
├── Cargo.lock
├── src/
│   ├── main.rs           # CLI entry point; clap subcommand dispatch
│   ├── ticket.rs         # Ticket struct, Status and TicketType enums
│   ├── store.rs          # file I/O, directory traversal, CRUD
│   ├── display.rs        # tabular and JSON output formatting
│   └── tests.rs          # unit tests
├── tests/
│   └── integration.rs    # integration tests using tempdir
├── docs/
│   ├── PLANNING.md       # development phases and work logs
│   └── ARCHITECTURE.md   # component overview and interactions
└── README.md

Tech Stack

• Language: Rust (edition 2021)
• Async runtime: async-std
• CLI parsing: clap (derive feature)
• Serialization: serde + serde_json
• Test utilities: tempfile (dev-dependency)

Data Model

Tickets are stored as .json files in .nbd/tickets/{id}.json, where id is a 6-character hex string (e.g. a3f9c2). The .nbd/ root is found by traversing up from cwd, like git finds .git/.

Ticket {
    id: String                  // 6-char hex
    title: String
    body: String
    priority: u8                // 0..=10, default 5
    status: Status              // Todo | InProgress | Done, default Todo
    dependencies: Vec<String>   // Vec of ticket IDs, default []
    ticket_type: TicketType     // Project | Feature | Task | Bug, default Task
}

CLI Interface

nbd create --title "..." [--body "..."] [--priority 5] [--status todo]
           [--type task] [--deps id1,id2] [--json]

nbd read <id> [--json]

nbd list [--json]

nbd update <id> [--title "..."] [--body "..."] [--priority N]
               [--status ...] [--type ...] [--deps ...] [--json]

--json is available on all commands for machine-readable output.

Module Responsibilities

Module	Responsibility
main.rs	clap CLI definition and subcommand dispatch only
ticket.rs	Ticket struct, enums, ID generation, validation
store.rs	directory traversal, file read/write, CRUD operations
display.rs	tabular formatting and JSON output
tests.rs	unit tests for all modules

Validation

Run in order from this directory before committing:

cargo fmt
cargo check
cargo clippy
cargo test

Testing

• Unit tests: src/tests.rs — test each module in isolation; use tempfile for any file I/O
• Integration tests: tests/integration.rs — test full command flows (create → read → list → update) against a real temp directory; test directory traversal by running from a subdirectory

Target 80%+ code coverage.

Git Conventions

Follows Conventional Commits. Use nbd as the scope:

feat(nbd): add list command
fix(nbd): handle missing .nbd directory gracefully
test(nbd): add roundtrip serialization test

Code Style

• All public functions, structs, enums, and modules must have rustdoc comments.
• Include doc-examples where applicable — these double as doctests.
• Default rustfmt conventions; no custom rustfmt.toml.

Release Builds

[profile.release]
opt-level = "z"
lto = true
strip = true
codegen-units = 1

License

Dual-licensed under Apache-2.0 and MIT, consistent with the rest of the vibed mono-repo.