ralph_workflow/git_helpers/

wrapper.rs

//! Git wrapper for blocking commits during agent phase.
//!
//! This module provides safety mechanisms to prevent accidental commits while
//! an AI agent is actively modifying files. It works through two mechanisms:
//!
//! - **Marker file**: Creates `.no_agent_commit` in the repo root during agent
//!   execution. Both the git wrapper and hooks check for this file.
//! - **PATH wrapper**: Installs a temporary `git` wrapper script that intercepts
//!   `commit`, `push`, and `tag` commands when the marker file exists.
//!
//! The wrapper is automatically cleaned up when the agent phase ends, even on
//! unexpected exits (Ctrl+C, panics) via [`cleanup_agent_phase_silent`].

use super::hooks::{install_hooks, uninstall_hooks_silent};
use super::repo::get_repo_root;
use crate::logger::Logger;
use crate::workspace::Workspace;
use std::env;
use std::fs::{self, File};
use std::io::{self, Write};
use std::path::{Path, PathBuf};
use tempfile::TempDir;
use which::which;

const WRAPPER_DIR_TRACK_FILE: &str = ".agent/git-wrapper-dir.txt";

/// Marker file path for blocking commits during agent phase.
const MARKER_FILE: &str = ".no_agent_commit";

/// Git helper state.
pub struct GitHelpers {
    real_git: Option<PathBuf>,
    wrapper_dir: Option<TempDir>,
}

impl GitHelpers {
    pub(crate) const fn new() -> Self {
        Self {
            real_git: None,
            wrapper_dir: None,
        }
    }

    /// Find the real git binary path.
    fn init_real_git(&mut self) {
        if self.real_git.is_none() {
            self.real_git = which("git").ok();
        }
    }
}

impl Default for GitHelpers {
    fn default() -> Self {
        Self::new()
    }
}

/// Escape a path for safe use in a POSIX shell single-quoted string.
///
/// Single quotes in POSIX shells cannot contain literal single quotes.
/// The standard workaround is to end the quote, add an escaped quote, and restart the quote.
/// This function rejects paths with newlines since they can't be safely handled.
fn escape_shell_single_quoted(path: &str) -> io::Result<String> {
    // Reject newlines - they cannot be safely handled in shell scripts
    if path.contains('\n') || path.contains('\r') {
        return Err(io::Error::new(
            io::ErrorKind::InvalidInput,
            "git path contains newline characters, cannot create safe shell wrapper",
        ));
    }
    // Replace ' with '\' (end literal string, escaped quote, restart literal string)
    Ok(path.replace('\'', "'\\''"))
}

/// Enable git wrapper that blocks commits during agent phase.
pub fn enable_git_wrapper(helpers: &mut GitHelpers) -> io::Result<()> {
    helpers.init_real_git();
    let Some(real_git) = helpers.real_git.as_ref() else {
        // Ralph's git operations use libgit2 and should work without the `git` CLI installed.
        // The wrapper is only a safety feature for intercepting `git commit/push/tag`.
        // If no `git` binary is available, there's nothing to wrap, so we no-op.
        return Ok(());
    };

    // Validate git path is valid UTF-8 for shell script generation.
    // On Unix systems, paths are typically valid UTF-8, but some filesystems
    // may contain invalid UTF-8 sequences. In such cases, we cannot safely
    // generate a shell wrapper and should return an error.
    let git_path_str = real_git.to_str().ok_or_else(|| {
        io::Error::new(
            io::ErrorKind::InvalidData,
            "git binary path contains invalid UTF-8 characters; cannot create wrapper script",
        )
    })?;

    // Validate that the git path is an absolute path.
    // This prevents potential issues with relative paths and ensures
    // we're using a known, trusted git binary location.
    if !real_git.is_absolute() {
        return Err(io::Error::new(
            io::ErrorKind::InvalidInput,
            format!(
                "git binary path is not absolute: '{git_path_str}'. \
                 Using absolute paths prevents potential security issues."
            ),
        ));
    }

    // Additional validation: ensure the git binary exists and is executable.
    // This prevents following symlinks to non-executable files or directories.
    if !real_git.exists() {
        return Err(io::Error::new(
            io::ErrorKind::NotFound,
            format!("git binary does not exist at path: '{git_path_str}'"),
        ));
    }

    // On Unix systems, verify it's a regular file (not a directory or special file).
    #[cfg(unix)]
    {
        match fs::metadata(real_git) {
            Ok(metadata) => {
                let file_type = metadata.file_type();
                if file_type.is_dir() {
                    return Err(io::Error::new(
                        io::ErrorKind::InvalidInput,
                        format!("git binary path is a directory, not a file: '{git_path_str}'"),
                    ));
                }
                if file_type.is_symlink() {
                    // Don't follow symlinks - require the actual path to be the binary.
                    // This prevents symlink-based attacks.
                    return Err(io::Error::new(
                        io::ErrorKind::InvalidInput,
                        format!("git binary path is a symlink; use the actual binary path: '{git_path_str}'"),
                    ));
                }
            }
            Err(_) => {
                return Err(io::Error::new(
                    io::ErrorKind::PermissionDenied,
                    format!("cannot access git binary metadata at path: '{git_path_str}'"),
                ));
            }
        }
    }

    let wrapper_dir = tempfile::tempdir()?;
    let wrapper_path = wrapper_dir.path().join("git");

    // Escape the git path for shell script to prevent command injection.
    // Use a helper function to properly handle edge cases and reject unsafe paths.
    let git_path_escaped = escape_shell_single_quoted(git_path_str)?;

    let wrapper_content = format!(
        r#"#!/usr/bin/env sh
set -eu
repo_root="$('{git_path_escaped}' rev-parse --show-toplevel 2>/dev/null || pwd)"
if [ -f "$repo_root/.no_agent_commit" ]; then
  subcmd="${{1-}}"
  case "$subcmd" in
    commit|push|tag)
      echo "Blocked: git $subcmd disabled during agent phase (.no_agent_commit present)." >&2
      exit 1
      ;;
  esac
fi
exec '{git_path_escaped}' "$@"
"#
    );

    let mut file = File::create(&wrapper_path)?;
    file.write_all(wrapper_content.as_bytes())?;

    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        let mut perms = fs::metadata(&wrapper_path)?.permissions();
        perms.set_mode(0o755);
        fs::set_permissions(&wrapper_path, perms)?;
    }

    // Prepend wrapper dir to PATH.
    let current_path = env::var("PATH").unwrap_or_default();
    env::set_var(
        "PATH",
        format!("{}:{}", wrapper_dir.path().display(), current_path),
    );

    fs::create_dir_all(".agent")?;
    fs::write(
        WRAPPER_DIR_TRACK_FILE,
        wrapper_dir.path().display().to_string(),
    )?;

    helpers.wrapper_dir = Some(wrapper_dir);
    Ok(())
}

/// Disable git wrapper.
///
/// # Thread Safety
///
/// This function modifies the process-wide `PATH` environment variable, which is
/// inherently not thread-safe. If multiple threads were concurrently modifying PATH,
/// there could be a TOCTOU (time-of-check-time-of-use) race condition. However,
/// in Ralph's usage, this function is only called from the main thread during
/// controlled shutdown sequences, so this is acceptable in practice.
pub fn disable_git_wrapper(helpers: &mut GitHelpers) {
    if let Some(wrapper_dir) = helpers.wrapper_dir.take() {
        let wrapper_dir_path = wrapper_dir.path().to_path_buf();
        let _ = fs::remove_dir_all(&wrapper_dir_path);
        // Remove from PATH.
        // Note: This read-modify-write sequence on PATH has a theoretical TOCTOU race,
        // but in practice it's safe because Ralph only calls this from the main thread
        // during controlled shutdown.
        if let Ok(path) = env::var("PATH") {
            let wrapper_str = wrapper_dir_path.to_string_lossy();
            let new_path: String = path
                .split(':')
                .filter(|p| !p.contains(wrapper_str.as_ref()))
                .collect::<Vec<_>>()
                .join(":");
            env::set_var("PATH", new_path);
        }
    }
    let _ = fs::remove_file(WRAPPER_DIR_TRACK_FILE);
}

/// Start agent phase (creates marker file, installs hooks, enables wrapper).
pub fn start_agent_phase(helpers: &mut GitHelpers) -> io::Result<()> {
    File::create(".no_agent_commit")?;
    install_hooks()?;
    enable_git_wrapper(helpers)?;
    Ok(())
}

/// End agent phase (removes marker file).
pub fn end_agent_phase() {
    let repo_root = match crate::git_helpers::get_repo_root() {
        Ok(root) => root,
        Err(_) => return,
    };
    let marker_path = repo_root.join(".no_agent_commit");
    let _ = fs::remove_file(marker_path);
}

fn cleanup_git_wrapper_dir_silent() {
    let repo_root = match crate::git_helpers::get_repo_root() {
        Ok(root) => root,
        Err(_) => return,
    };
    let track_file = repo_root.join(WRAPPER_DIR_TRACK_FILE);
    let wrapper_dir = match fs::read_to_string(&track_file) {
        Ok(path) => PathBuf::from(path.trim()),
        Err(_) => return,
    };

    if !wrapper_dir.as_os_str().is_empty() {
        let _ = fs::remove_dir_all(&wrapper_dir);
    }
    let _ = fs::remove_file(track_file);
}

/// Best-effort cleanup for unexpected exits (Ctrl+C, early-return, panics).
pub fn cleanup_agent_phase_silent() {
    end_agent_phase();
    cleanup_git_wrapper_dir_silent();
    uninstall_hooks_silent();
    cleanup_generated_files_silent();
}

/// Cleanup generated files silently without workspace.
///
/// This is a minimal implementation for cleanup in signal handlers where
/// workspace context is not available. Uses std::fs directly which is
/// acceptable for this emergency cleanup scenario.
fn cleanup_generated_files_silent() {
    let repo_root = match crate::git_helpers::get_repo_root() {
        Ok(root) => root,
        Err(_) => return,
    };
    for file in crate::files::io::agent_files::GENERATED_FILES {
        let absolute_path = repo_root.join(file);
        let _ = std::fs::remove_file(absolute_path);
    }
}

/// Clean up orphaned .`no_agent_commit` marker.
pub fn cleanup_orphaned_marker(logger: &Logger) -> io::Result<()> {
    let repo_root = get_repo_root()?;
    let marker_path = repo_root.join(".no_agent_commit");

    if marker_path.exists() {
        fs::remove_file(&marker_path)?;
        logger.success("Removed orphaned .no_agent_commit marker");
    } else {
        logger.info("No orphaned marker found");
    }

    Ok(())
}

// ============================================================================
// Workspace-aware variants
// ============================================================================

/// Create the agent phase marker file using workspace abstraction.
///
/// This is a workspace-aware version of the marker file creation that uses
/// the Workspace trait for file I/O, making it testable with `MemoryWorkspace`.
///
/// # Arguments
///
/// * `workspace` - The workspace to write to
///
/// # Returns
///
/// Returns `Ok(())` on success, or an error if the file cannot be created.
pub fn create_marker_with_workspace(workspace: &dyn Workspace) -> io::Result<()> {
    workspace.write(Path::new(MARKER_FILE), "")
}

/// Remove the agent phase marker file using workspace abstraction.
///
/// This is a workspace-aware version of the marker file removal that uses
/// the Workspace trait for file I/O, making it testable with `MemoryWorkspace`.
///
/// # Arguments
///
/// * `workspace` - The workspace to operate on
///
/// # Returns
///
/// Returns `Ok(())` on success (including if file doesn't exist).
pub fn remove_marker_with_workspace(workspace: &dyn Workspace) -> io::Result<()> {
    workspace.remove_if_exists(Path::new(MARKER_FILE))
}

/// Check if the agent phase marker file exists using workspace abstraction.
///
/// This is a workspace-aware version that uses the Workspace trait for file I/O,
/// making it testable with `MemoryWorkspace`.
///
/// # Arguments
///
/// * `workspace` - The workspace to check
///
/// # Returns
///
/// Returns `true` if the marker file exists, `false` otherwise.
pub fn marker_exists_with_workspace(workspace: &dyn Workspace) -> bool {
    workspace.exists(Path::new(MARKER_FILE))
}

/// Clean up orphaned marker file using workspace abstraction.
///
/// This is a workspace-aware version of `cleanup_orphaned_marker` that uses
/// the Workspace trait for file I/O, making it testable with `MemoryWorkspace`.
///
/// # Arguments
///
/// * `workspace` - The workspace to operate on
/// * `logger` - Logger for output messages
///
/// # Returns
///
/// Returns `Ok(())` on success.
pub fn cleanup_orphaned_marker_with_workspace(
    workspace: &dyn Workspace,
    logger: &Logger,
) -> io::Result<()> {
    let marker_path = Path::new(MARKER_FILE);

    if workspace.exists(marker_path) {
        workspace.remove(marker_path)?;
        logger.success("Removed orphaned .no_agent_commit marker");
    } else {
        logger.info("No orphaned marker found");
    }

    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::workspace::MemoryWorkspace;

    #[test]
    fn test_create_marker_with_workspace() {
        let workspace = MemoryWorkspace::new_test();

        // Marker should not exist initially
        assert!(!marker_exists_with_workspace(&workspace));

        // Create marker
        create_marker_with_workspace(&workspace).unwrap();

        // Marker should now exist
        assert!(marker_exists_with_workspace(&workspace));
    }

    #[test]
    fn test_remove_marker_with_workspace() {
        let workspace = MemoryWorkspace::new_test();

        // Create marker first
        create_marker_with_workspace(&workspace).unwrap();
        assert!(marker_exists_with_workspace(&workspace));

        // Remove marker
        remove_marker_with_workspace(&workspace).unwrap();

        // Marker should no longer exist
        assert!(!marker_exists_with_workspace(&workspace));
    }

    #[test]
    fn test_remove_marker_with_workspace_nonexistent() {
        let workspace = MemoryWorkspace::new_test();

        // Removing non-existent marker should succeed silently
        remove_marker_with_workspace(&workspace).unwrap();
        assert!(!marker_exists_with_workspace(&workspace));
    }

    #[test]
    fn test_cleanup_orphaned_marker_with_workspace_exists() {
        let workspace = MemoryWorkspace::new_test();
        let logger = Logger::new(crate::logger::Colors { enabled: false });

        // Create an orphaned marker
        create_marker_with_workspace(&workspace).unwrap();
        assert!(marker_exists_with_workspace(&workspace));

        // Clean up should remove it
        cleanup_orphaned_marker_with_workspace(&workspace, &logger).unwrap();
        assert!(!marker_exists_with_workspace(&workspace));
    }

    #[test]
    fn test_cleanup_orphaned_marker_with_workspace_not_exists() {
        let workspace = MemoryWorkspace::new_test();
        let logger = Logger::new(crate::logger::Colors { enabled: false });

        // No marker exists
        assert!(!marker_exists_with_workspace(&workspace));

        // Clean up should succeed without error
        cleanup_orphaned_marker_with_workspace(&workspace, &logger).unwrap();
        assert!(!marker_exists_with_workspace(&workspace));
    }

    #[test]
    fn test_marker_file_constant() {
        // Verify the constant matches expected value
        assert_eq!(MARKER_FILE, ".no_agent_commit");
    }
}