heroforge_core/

lib.rs

//! # heroforge
//!
//! A pure Rust client library for reading and writing Heroforge SCM repositories.
//!
//! ## Overview
//!
//! `heroforge` provides a complete API for interacting with Heroforge repositories without
//! requiring the Heroforge CLI. It supports both reading from existing repositories and
//! creating new ones from scratch.
//!
//! ## Quick Start (Builder API)
//!
//! ```no_run
//! use heroforge_core::Repository;
//!
//! fn main() -> heroforge_core::Result<()> {
//!     // Create a new repository
//!     let repo = Repository::init("project.forge")?;
//!
//!     // Create initial commit using builder
//!     let init = repo.commit_builder()
//!         .message("Initial commit")
//!         .author("admin")
//!         .initial()
//!         .execute()?;
//!
//!     // Add files using builder
//!     let v1 = repo.commit_builder()
//!         .message("Add project files")
//!         .author("developer")
//!         .parent(&init)
//!         .file("README.md", b"# My Project\n")
//!         .file("src/main.rs", b"fn main() {}\n")
//!         .execute()?;
//!
//!     // Tag the release
//!     repo.tags()
//!         .create("v1.0.0")
//!         .at_commit(&v1)
//!         .author("developer")
//!         .execute()?;
//!
//!     // Read files using builder
//!     let readme = repo.files().on_trunk().read_string("README.md")?;
//!     let rust_files = repo.files().at_tag("v1.0.0").find("**/*.rs")?;
//!
//!     // Sync to remote
//!     repo.sync()
//!         .to("quic://backup.example.com:4443/project")
//!         .push()?;
//!
//!     Ok(())
//! }
//! ```
//!
//! ## Features
//!
//! ### File Operations
//! ```no_run
//! # use heroforge_core::Repository;
//! # let repo = Repository::open("project.forge")?;
//! // List files on trunk
//! let files = repo.files().on_trunk().list()?;
//!
//! // Read file from a branch
//! let content = repo.files().on_branch("feature").read("config.json")?;
//!
//! // Find files at a tag
//! let rust = repo.files().at_tag("v1.0").find("**/*.rs")?;
//! # Ok::<(), heroforge_core::FossilError>(())
//! ```
//!
//! ### Commit Operations
//! ```no_run
//! # use heroforge_core::Repository;
//! # let repo = Repository::open_rw("project.forge")?;
//! let hash = repo.commit_builder()
//!     .message("Add feature")
//!     .author("developer")
//!     .parent("abc123")
//!     .file("src/feature.rs", b"// new feature")
//!     .execute()?;
//! # Ok::<(), heroforge_core::FossilError>(())
//! ```
//!
//! ### Branch/Tag Operations
//! ```no_run
//! # use heroforge_core::Repository;
//! # let repo = Repository::open_rw("project.forge")?;
//! // Create branch
//! repo.branches()
//!     .create("feature-x")
//!     .from_branch("trunk")
//!     .author("developer")
//!     .execute()?;
//!
//! // Create tag
//! repo.tags()
//!     .create("v1.0.0")
//!     .at_branch("trunk")
//!     .author("developer")
//!     .execute()?;
//! # Ok::<(), heroforge_core::FossilError>(())
//! ```
//!
//! ### Filesystem Operations (Copy, Move, Delete, Find, Symlinks)
//! ```no_run
//! # use heroforge_core::Repository;
//! use heroforge_core::fs::{Find, Modify};
//! # let repo = Repository::open_rw("project.forge")?;
//!
//! // Copy, move, delete files and directories
//! Modify::new(&repo)
//!     .message("Reorganize project structure")
//!     .author("developer")
//!     .copy_file("README.md", "docs/README.md")
//!     .copy_dir("src", "backup/src")
//!     .move_file("old.txt", "archive/old.txt")
//!     .move_dir("scripts", "tools")
//!     .delete_file("temp.log")
//!     .delete_dir("cache")
//!     .execute()?;
//!
//! // Find files with patterns and ignore rules
//! let rust_files = Find::new(&repo)
//!     .pattern("**/*.rs")
//!     .ignore("target/**")
//!     .ignore_hidden()
//!     .paths()?;
//!
//! // Change permissions
//! Modify::new(&repo)
//!     .message("Make scripts executable")
//!     .author("developer")
//!     .make_executable("scripts/deploy.sh")
//!     .chmod_dir("bin", 0o755)
//!     .execute()?;
//!
//! // Create symlinks
//! Modify::new(&repo)
//!     .message("Add symlinks")
//!     .author("developer")
//!     .symlink("lib/latest", "lib/v2.0")
//!     .execute()?;
//!
//! // Utility functions
//! use heroforge_core::fs::{exists, is_dir, du, count};
//! let file_exists = exists(&repo, "README.md")?;
//! let is_directory = is_dir(&repo, "src")?;
//! let size = du(&repo, "src/**/*")?;
//! let num_files = count(&repo, "**/*.rs")?;
//! # Ok::<(), heroforge_core::FossilError>(())
//! ```
//!
//! ### Sync Operations (QUIC)
//! ```no_run
//! # use heroforge_core::Repository;
//! # let repo = Repository::open("project.forge")?;
//! // Push over QUIC
//! repo.sync()
//!     .to("quic://server:4443/repo")
//!     .push()?;
//!
//! // Pull from remote
//! repo.sync()
//!     .from("quic://server:4443/repo")
//!     .auth("user", "password")
//!     .pull()?;
//! # Ok::<(), heroforge_core::FossilError>(())
//! ```

pub mod artifact;
pub mod error;
pub mod fs;
pub mod hash;
pub mod repo;
pub mod server;
pub mod sync;
#[cfg(feature = "git-import")]
pub mod tools;

// Rhai scripting API (requires rhai feature)
#[cfg(feature = "rhai")]
pub mod rhai_api;

pub use error::{FossilError, Result};
pub use repo::{CheckIn, FileInfo, Repository};
pub use server::Server;
pub use sync::{SyncBuilder, SyncProtocol, SyncResult};

// Filesystem storage backend
pub use fs::{
    DirectoryEntry, FileHandle, FileKind, FileMetadata, FilePermissions, FileSystem,
    FileSystemStatus, FindResults, FsError, FsOperation, FsResult, OperationSummary, SavePoint,
    Transaction, TransactionMode, TransactionState,
};

// New staging-based filesystem interface
pub use fs::{
    CommitConfig, CommitWorker, DEFAULT_COMMIT_INTERVAL, FsInterface, FsInterfaceStatus,
    MAX_FILE_SIZE, StagedFile, Staging, StagingState,
};

// Re-export builders for convenience
pub use repo::{
    BranchBuilder, BranchesBuilder, CommitBuilder, FileEntry, FileQuery, FileType, FilesBuilder,
    FindBuilder, FindResult, FsBuilder, FsOperation as RepoFsOperation, FsOpsBuilder, FsPreview,
    HistoryBuilder, Permissions, TagBuilder, TagsBuilder, UserBuilder, UsersBuilder,
};

// Git import tool (requires git-import feature)
#[cfg(feature = "git-import")]
pub use tools::{GitImportBuilder, GitImportResult};