heroforge/
lib.rs

1//! # heroforge
2//!
3//! A pure Rust client library for reading and writing Heroforge SCM repositories.
4//!
5//! ## Overview
6//!
7//! `heroforge` provides a complete API for interacting with Heroforge repositories without
8//! requiring the Heroforge CLI. It supports both reading from existing repositories and
9//! creating new ones from scratch.
10//!
11//! ## Quick Start (Builder API)
12//!
13//! ```no_run
14//! use heroforge::Repository;
15//!
16//! fn main() -> heroforge::Result<()> {
17//!     // Create a new repository
18//!     let repo = Repository::init("project.forge")?;
19//!
20//!     // Create initial commit using builder
21//!     let init = repo.commit()
22//!         .message("Initial commit")
23//!         .author("admin")
24//!         .initial()
25//!         .execute()?;
26//!
27//!     // Add files using builder
28//!     let v1 = repo.commit()
29//!         .message("Add project files")
30//!         .author("developer")
31//!         .parent(&init)
32//!         .file("README.md", b"# My Project\n")
33//!         .file("src/main.rs", b"fn main() {}\n")
34//!         .execute()?;
35//!
36//!     // Tag the release
37//!     repo.tags()
38//!         .create("v1.0.0")
39//!         .at_commit(&v1)
40//!         .author("developer")
41//!         .execute()?;
42//!
43//!     // Read files using builder
44//!     let readme = repo.files().on_trunk().read_string("README.md")?;
45//!     let rust_files = repo.files().at_tag("v1.0.0").find("**/*.rs")?;
46//!
47//!     // Sync to remote
48//!     repo.sync()
49//!         .to("quic://backup.example.com:4443/project")
50//!         .push()?;
51//!
52//!     Ok(())
53//! }
54//! ```
55//!
56//! ## Features
57//!
58//! ### File Operations
59//! ```no_run
60//! # use heroforge::Repository;
61//! # let repo = Repository::open("project.forge")?;
62//! // List files on trunk
63//! let files = repo.files().on_trunk().list()?;
64//!
65//! // Read file from a branch
66//! let content = repo.files().on_branch("feature").read("config.json")?;
67//!
68//! // Find files at a tag
69//! let rust = repo.files().at_tag("v1.0").find("**/*.rs")?;
70//! # Ok::<(), heroforge::FossilError>(())
71//! ```
72//!
73//! ### Commit Operations
74//! ```no_run
75//! # use heroforge::Repository;
76//! # let repo = Repository::open_rw("project.forge")?;
77//! let hash = repo.commit()
78//!     .message("Add feature")
79//!     .author("developer")
80//!     .parent("abc123")
81//!     .file("src/feature.rs", b"// new feature")
82//!     .execute()?;
83//! # Ok::<(), heroforge::FossilError>(())
84//! ```
85//!
86//! ### Branch/Tag Operations
87//! ```no_run
88//! # use heroforge::Repository;
89//! # let repo = Repository::open_rw("project.forge")?;
90//! // Create branch
91//! repo.branches()
92//!     .create("feature-x")
93//!     .from_branch("trunk")
94//!     .author("developer")
95//!     .execute()?;
96//!
97//! // Create tag
98//! repo.tags()
99//!     .create("v1.0.0")
100//!     .at_branch("trunk")
101//!     .author("developer")
102//!     .execute()?;
103//! # Ok::<(), heroforge::FossilError>(())
104//! ```
105//!
106//! ### Filesystem Operations (Copy, Move, Delete, Find, Symlinks)
107//! ```no_run
108//! # use heroforge::Repository;
109//! # let repo = Repository::open_rw("project.forge")?;
110//! // Copy, move, delete files and directories
111//! repo.fs().modify()
112//!     .message("Reorganize project structure")
113//!     .author("developer")
114//!     .copy_file("README.md", "docs/README.md")
115//!     .copy_dir("src", "backup/src")
116//!     .move_file("old.txt", "archive/old.txt")
117//!     .move_dir("scripts", "tools")
118//!     .delete_file("temp.log")
119//!     .delete_dir("cache")
120//!     .execute()?;
121//!
122//! // Find files with patterns and ignore rules
123//! let rust_files = repo.fs().find()
124//!     .pattern("**/*.rs")
125//!     .ignore("target/**")
126//!     .ignore_hidden(true)
127//!     .paths()?;
128//!
129//! // Change permissions
130//! repo.fs().modify()
131//!     .message("Make scripts executable")
132//!     .author("developer")
133//!     .make_executable("scripts/deploy.sh")
134//!     .chmod_dir("bin", 0o755)
135//!     .execute()?;
136//!
137//! // Create symlinks
138//! repo.fs().modify()
139//!     .message("Add symlinks")
140//!     .author("developer")
141//!     .symlink("lib/latest", "lib/v2.0")
142//!     .execute()?;
143//!
144//! // Utility operations (no commit needed)
145//! let exists = repo.fs().exists("README.md")?;
146//! let is_dir = repo.fs().is_dir("src")?;
147//! let size = repo.fs().du("src")?;
148//! let count = repo.fs().count("**/*.rs")?;
149//! # Ok::<(), heroforge::FossilError>(())
150//! ```
151//!
152//! ### Sync Operations (QUIC)
153//! ```no_run
154//! # use heroforge::Repository;
155//! # let repo = Repository::open("project.forge")?;
156//! // Push over QUIC
157//! repo.sync()
158//!     .to("quic://server:4443/repo")
159//!     .push()?;
160//!
161//! // Pull from remote
162//! repo.sync()
163//!     .from("quic://server:4443/repo")
164//!     .auth("user", "password")
165//!     .pull()?;
166//! # Ok::<(), heroforge::FossilError>(())
167//! ```
168
169pub mod artifact;
170pub mod error;
171pub mod hash;
172pub mod repo;
173pub mod server;
174pub mod sync;
175
176pub use error::{FossilError, Result};
177pub use repo::{CheckIn, FileInfo, Repository};
178pub use server::Server;
179pub use sync::{SyncBuilder, SyncProtocol, SyncResult};
180
181// Re-export builders for convenience
182pub use repo::{
183    BranchBuilder, BranchesBuilder, CommitBuilder, FileEntry, FileQuery, FileType, FilesBuilder,
184    FindBuilder, FindResult, FsBuilder, FsOperation, FsOpsBuilder, FsPreview, HistoryBuilder,
185    Permissions, TagBuilder, TagsBuilder, UserBuilder, UsersBuilder,
186};
heroforge/lib.rs

heroforge/
lib.rs
