bn/api/
mod.rs

1//! # Beans Library API
2//!
3//! Programmatic access to beans operations. Use this module when embedding beans
4//! in another application (e.g., a GUI, MCP server, or custom tooling).
5//!
6//! The API is organized into layers:
7//!
8//! - **Types** — Core data structures (`Bean`, `Index`, `Status`, etc.)
9//! - **Discovery** — Find `.beans/` directories and bean files
10//! - **Query** — Read-only operations (list, get, tree, status, graph)
11//! - **Mutations** — Write operations (create, update, close, delete)
12//! - **Orchestration** — Agent dispatch, monitoring, and control
13//!
14//! ## Quick Start
15//!
16//! ```rust,no_run
17//! use bn::api::*;
18//!
19//! // Find the .beans/ directory
20//! let beans_dir = find_beans_dir(std::path::Path::new(".")).unwrap();
21//!
22//! // Load the index (cached, rebuilds if stale)
23//! let index = Index::load_or_rebuild(&beans_dir).unwrap();
24//!
25//! // Get a specific bean
26//! let bean = get_bean(&beans_dir, "1").unwrap();
27//! println!("{}: {}", bean.id, bean.title);
28//! ```
29//!
30//! ## Design Principles
31//!
32//! - **No I/O side effects** — Library functions never print to stdout/stderr.
33//!   All output is returned as structured data.
34//! - **Structured params and results** — Each operation takes a `Params` struct
35//!   and returns a `Result` type. No raw CLI argument passing.
36//! - **Serializable** — All types derive `Serialize`/`Deserialize` for easy
37//!   IPC (Tauri, JSON-RPC, MCP).
38//! - **Composable** — Functions take `&Path` (beans_dir) and return owned data.
39//!   No global state, no singletons.
40
41use std::path::Path;
42
43use anyhow::Result;
44
45// ---------------------------------------------------------------------------
46// Re-exported core types
47// ---------------------------------------------------------------------------
48
49// Bean and related types
50pub use crate::bean::{
51    AttemptOutcome, AttemptRecord, Bean, OnCloseAction, OnFailAction, RunRecord, RunResult, Status,
52};
53
54// Index types
55pub use crate::index::{Index, IndexEntry};
56
57// Configuration
58pub use crate::config::Config;
59
60// Discovery functions
61pub use crate::discovery::{
62    archive_path_for_bean, find_archived_bean, find_bean_file, find_beans_dir,
63};
64
65// Graph functions
66pub use crate::graph::{
67    build_dependency_tree, build_full_graph, count_subtree_attempts, detect_cycle, find_all_cycles,
68};
69
70// Utility
71pub use crate::bean::validate_priority;
72
73// ---------------------------------------------------------------------------
74// Query functions
75// ---------------------------------------------------------------------------
76
77/// Load a bean by ID.
78///
79/// Finds the bean file in the `.beans/` directory and deserializes it.
80/// Works for both active and legacy bean formats.
81///
82/// # Errors
83/// - Bean ID is invalid
84/// - No bean file found for the given ID
85/// - File cannot be parsed
86pub fn get_bean(beans_dir: &Path, id: &str) -> Result<Bean> {
87    let path = find_bean_file(beans_dir, id)?;
88    Bean::from_file(&path)
89}
90
91/// Load a bean from the archive by ID.
92///
93/// # Errors
94/// - Bean ID not found in archive
95/// - File cannot be parsed
96pub fn get_archived_bean(beans_dir: &Path, id: &str) -> Result<Bean> {
97    let path = find_archived_bean(beans_dir, id)?;
98    Bean::from_file(&path)
99}
100
101/// Load the index, rebuilding from bean files if stale.
102///
103/// This is the main entry point for reading bean metadata.
104/// The index is a YAML cache that's faster than reading every bean file.
105pub fn load_index(beans_dir: &Path) -> Result<Index> {
106    Index::load_or_rebuild(beans_dir)
107}
108
109// ---------------------------------------------------------------------------
110// Submodules (added as they are implemented)
111// ---------------------------------------------------------------------------
112
113// pub mod query;         // Phase 1: 88.2.2
114// pub mod mutations;     // Phase 1: 88.2.5, 88.2.6, 88.2.7
115// pub mod orchestration; // Phase 1: 88.2.4
bn/api/mod.rs

bn/api/
mod.rs
