zeph_worktree/lib.rs
1// SPDX-FileCopyrightText: 2026 Andrei G <bug-ops>
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! Per-subagent git worktree lifecycle management for Zeph.
5//!
6//! This crate implements the `zeph-worktree` subsystem described in
7//! `specs/063-worktree-subsystem/spec.md`. It provides:
8//!
9//! - [`WorktreeManager`] — creates, removes, lists, and reconciles git worktrees
10//! - [`WorktreeHandle`] — a live record of one managed worktree
11//! - [`WorktreeError`] — all errors this crate can produce
12//! - [`GitRunner`][git_runner::GitRunner] / [`DefaultGitRunner`][git_runner::DefaultGitRunner]
13//! — the git invocation abstraction and its production implementation
14//! - [`manager::probe_capabilities`] — bootstrap git availability probe
15//!
16//! ## Dependency direction
17//!
18//! ```text
19//! zeph-subagent → zeph-worktree → (zeph-config, tokio, thiserror, tracing)
20//! ```
21//!
22//! This crate MUST NOT depend on `zeph-core`, `zeph-subagent`, or
23//! `zeph-channels`.
24//!
25//! ## Example
26//!
27//! ```no_run
28//! use std::path::PathBuf;
29//! use zeph_config::WorktreeConfig;
30//! use zeph_worktree::{DefaultWorktreeManager, git_runner::DefaultGitRunner, manager::probe_capabilities};
31//!
32//! # async fn example() -> Result<(), zeph_worktree::WorktreeError> {
33//! let repo = PathBuf::from("/path/to/repo");
34//! let runner = DefaultGitRunner::new();
35//! probe_capabilities(&runner, &repo).await?;
36//!
37//! let mgr = DefaultWorktreeManager::new(repo, WorktreeConfig::default(), DefaultGitRunner::new())?;
38//! let handle = mgr.create("agent-42").await?;
39//! println!("Worktree at {:?}", handle.path);
40//! mgr.remove(&handle, false).await?;
41//! # Ok(())
42//! # }
43//! ```
44
45pub mod error;
46pub mod git_runner;
47pub mod handle;
48pub mod manager;
49pub mod sanitize;
50
51pub use error::WorktreeError;
52pub use git_runner::{DefaultGitRunner, GitRunner};
53pub use handle::WorktreeHandle;
54pub use manager::{WorktreeManager, probe_capabilities};
55
56/// A [`WorktreeManager`] using the production [`DefaultGitRunner`].
57///
58/// This is the type that `SubAgentManager` stores as
59/// `Option<Arc<DefaultWorktreeManager>>`.
60pub type DefaultWorktreeManager = WorktreeManager<DefaultGitRunner>;