Skip to content

API Reference

Jump to bottom
Prince Lad edited this page Jan 20, 2026 · 1 revision

API Reference

This document describes the public API types and functions in Forge.

Core Data Structures

Module

Represents a development task or module.

pub struct Module {
    pub id: String,
    pub name: String,
    pub description: String,
    pub owner_id: Option<String>,
    pub status: ModuleStatus,
    pub progress: u8,
}

pub enum ModuleStatus {
    Pending,
    Current,
    Completed,
}

Methods:

  • new(name: String) -> Self — Create a new module
  • load_from_file(path: &str) -> Result<Vec<Module>> — Load modules from .forge file
  • save_to_file(&self, path: &str) -> Result<()> — Save modules to file

Example:

let mut module = Module::new("Implement auth".to_string());
module.progress = 50;
module.status = ModuleStatus::Current;

Developer

Represents a team member.

pub struct Developer {
    pub id: String,
    pub name: String,
    pub email: String,
}

Methods:

  • new(name: String, email: String) -> Self — Create a new developer
  • load_from_file(path: &str) -> Result<Vec<Developer>> — Load developers from file
  • save_to_file(&self, path: &str) -> Result<()> — Save developers to file

Example:

let dev = Developer::new("Alice".to_string(), "alice@example.com".to_string());

Project

Represents a project with associated modules and developers.

pub struct Project {
    pub id: String,
    pub name: String,
    pub path: String,
    pub modules: Vec<Module>,
    pub developers: Vec<Developer>,
}

Git Operations

GitRepository

Wrapper around git2::Repository for common Git operations.

pub struct GitRepository {
    repo: git2::Repository,
}

Methods:

open(path: &Path) -> Result<Self>

Open a Git repository at the specified path.

let repo = GitRepository::open(Path::new("."))?;

get_status() -> Result<Vec<FileStatus>>

Get current file status.

let status = repo.get_status()?;
// Returns files: modified, staged, added, deleted

get_diff(path: &str) -> Result<String>

Get diff for a specific file.

let diff = repo.get_diff("src/main.rs")?;

get_history(limit: usize) -> Result<Vec<Commit>>

Get commit history (last N commits).

let commits = repo.get_history(50)?;

list_branches() -> Result<Vec<String>>

List all local branches.

let branches = repo.list_branches()?;

create_branch(name: &str) -> Result<()>

Create a new branch.

repo.create_branch("feature/my-feature")?;

switch_branch(name: &str) -> Result<()>

Switch to an existing branch.

repo.switch_branch("main")?;

delete_branch(name: &str) -> Result<()>

Delete a branch.

repo.delete_branch("feature/old-feature")?;

get_current_branch() -> Result<String>

Get the name of the current branch.

let branch = repo.get_current_branch()?;

commit(message: &str, staged_files: &[String]) -> Result<String>

Create a commit with staged files.

repo.commit("Add authentication", &["src/auth.rs", "src/main.rs"])?;

Screen Trait

All UI screens implement the Screen trait:

pub trait Screen {
    fn handle_key(&mut self, key: KeyEvent) -> Result<()>;
    fn render(&self, f: &mut Frame);
    fn on_enter(&mut self) -> Result<()>;
    fn on_exit(&mut self) -> Result<()>;
}

Methods:

handle_key(key: KeyEvent) -> Result<()>

Process keyboard input for this screen.

render(f: &mut Frame)

Render this screen to the terminal frame.

on_enter()

Called when screen becomes active. Use for initialization.

on_exit()

Called when screen is deactivated. Use for cleanup.

Example:

struct MyScreen {
    state: String,
}

impl Screen for MyScreen {
    fn handle_key(&mut self, key: KeyEvent) -> Result<()> {
        match key.code {
            KeyCode::Char('q') => {
                // handle quit
            }
            _ => {}
        }
        Ok(())
    }

    fn render(&self, f: &mut Frame) {
        // render to frame
    }

    fn on_enter(&mut self) -> Result<()> {
        // initialize
        Ok(())
    }

    fn on_exit(&mut self) -> Result<()> {
        // cleanup
        Ok(())
    }
}

RenderContext

Manages UI state and rendering context.

pub struct RenderContext {
    pub current_screen: Screen,
    pub focus: Focus,
    pub theme: Theme,
    pub is_search_active: bool,
    pub search_query: String,
}

Methods:

  • new() -> Self — Create a new render context
  • switch_screen(&mut self, screen: Box<dyn Screen>) — Switch to a new screen
  • set_focus(&mut self, focus: Focus) — Set which pane has focus
  • set_theme(&mut self, theme: Theme) — Change the theme

Error Handling

All fallible operations return color_eyre::Result<T>:

use color_eyre::Result;

fn risky_operation() -> Result<String> {
    let value = get_something()
        .context("Failed to get something")?;
    Ok(value)
}

Usage Example

Complete example using core APIs:

use forge::{GitRepository, Module, Developer};
use std::path::Path;

fn main() -> color_eyre::Result<()> {
    // Open repository
    let repo = GitRepository::open(Path::new("."))?;

    // Get current branch
    let branch = repo.get_current_branch()?;
    println!("On branch: {}", branch);

    // Get file status
    let status = repo.get_status()?;
    println!("Modified files: {}", status.len());

    // Get diff for a file
    if let Some(file) = status.first() {
        let diff = repo.get_diff(&file.path)?;
        println!("Diff:\n{}", diff);
    }

    // Load existing modules
    let modules = Module::load_from_file(".forge")?;
    println!("Modules: {}", modules.len());

    Ok(())
}

Deprecations

None currently. The API is still evolving and may change between versions.

See Also

Clone this wiki locally