mana_core/lib.rs
1//! # mana-core
2//!
3//! Core library for the mana work coordination system.
4//!
5//! `mana-core` provides the full data model, I/O layer, and orchestration logic
6//! for managing units (atomic work items) in a `.mana/` project directory.
7//! It is the single source of truth consumed by the mana CLI, GUI tooling,
8//! MCP servers, and any other integration point.
9//!
10//! ## Crate layout
11//!
12//! | Module | Purpose |
13//! |--------|---------|
14//! | [`api`] | High-level public API — the recommended entry point |
15//! | `unit` | Core `Unit` data model and serialization |
16//! | [`config`] | Project and global configuration |
17//! | [`index`] | Fast unit cache (`index.yaml`) |
18//! | [`graph`] | Dependency graph utilities |
19//! | [`ops`] | Low-level operations (create, update, close, claim, …) |
20//! | [`error`] | Typed error and result types |
21//! | [`discovery`] | `.mana/` directory and unit file discovery |
22//!
23//! ## Quick start
24//!
25//! ```rust,no_run
26//! use mana_core::api::{find_mana_dir, load_index, get_unit, list_units};
27//! use mana_core::ops::list::ListParams;
28//! use std::path::Path;
29//!
30//! // 1. Locate the .mana/ directory (walks up from the current path)
31//! let mana_dir = find_mana_dir(Path::new(".")).expect("not inside a mana project");
32//!
33//! // 2. Load the cached index (rebuilds from unit files if stale)
34//! let index = load_index(&mana_dir).expect("failed to load index");
35//! println!("{} units in project", index.units.len());
36//!
37//! // 3. Read a specific unit by ID
38//! let unit = get_unit(&mana_dir, "1").expect("unit not found");
39//! println!("{}: {} ({:?})", unit.id, unit.title, unit.status);
40//!
41//! // 4. List all open units
42//! let open = list_units(&mana_dir, &ListParams::default()).expect("list failed");
43//! for entry in open {
44//! println!(" [{}] {}", entry.id, entry.title);
45//! }
46//! ```
47//!
48//! ## Design principles
49//!
50//! - **`&Path` as entry point** — every function takes `mana_dir: &Path`.
51//! No global state, no singletons.
52//! - **No stdout/stderr side effects** — all output is returned as structured data.
53//! - **Serializable** — all public types derive `Serialize`/`Deserialize` for
54//! JSON-RPC, MCP, and Tauri IPC.
55//! - **Thread-safe** — no interior mutability or shared mutable globals.
56
57pub mod agent_presets;
58pub mod api;
59pub mod blocking;
60pub mod config;
61pub mod ctx_assembler;
62pub mod discovery;
63pub mod error;
64pub mod failure;
65pub mod graph;
66pub mod history;
67pub mod hooks;
68pub mod index;
69pub mod locks;
70pub mod ops;
71pub mod prompt;
72pub mod relevance;
73pub mod unit;
74pub mod util;
75pub mod verify_lint;
76pub mod worktree;