Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

20.7 KB
Raw Blame
use anyhow::Context;
use std::ffi::{OsStr, OsString};
use std::fs;
use std::path::{Path, PathBuf};
#[cfg(windows)]
use std::process::Command;
use std::process::Stdio;
use worktrunk::git::{HookType, Repository};
use worktrunk::path::{format_path_for_display, sanitize_for_filename};

use worktrunk::config::HookSource;

// ==================== Hook Log Specification ====================

/// Internal worktrunk operations that produce log files.
///
/// These are operations performed by worktrunk itself (not user-defined hooks).
#[derive(Debug, Clone, Copy, PartialEq, Eq, strum::EnumString, strum::Display, strum::EnumIter)]
#[strum(serialize_all = "kebab-case")]
pub enum InternalOp {
    /// Background worktree removal (`wt remove` in background mode)
    Remove,
    /// Delayed cleanup of the removed current worktree's empty PWD placeholder.
    RemovePlaceholder,
    /// Background cleanup of stale entries in `.git/wt/trash/`
    TrashSweep,
}

/// Specification for a hook log file.
///
/// This is the single source of truth for hook log file paths.
/// Used by log creation in `spawn_detached` to place background hook output.
///
/// All hook output is centralized under the main worktree's `.git/wt/logs/`
/// directory (`Repository::wt_logs_dir()`); per-branch logs live in subtrees,
/// and rerunning the same operation on the same branch overwrites its previous
/// log. The complementary categorization rule — top-level *files* are shared
/// logs, top-level *directories* are per-branch trees — is the "Log layout
/// invariant" documented in `commands::config::state`.
///
/// # Log file layout
///
/// Hook commands produce logs at: `{branch}/{source}/{hook-type}/{name}.log`
/// (`source` is `user` or `project`)
/// - Example: `feature/user/post-start/server.log`
///
/// Per-branch internal operations produce logs at: `{branch}/internal/{op}.log`
/// - Example: `feature/internal/remove.log`
///
/// Repo-wide (branch-agnostic) internal operations produce top-level logs at
/// `internal-{op}.log`, alongside the other shared logs (`commands.jsonl`,
/// `trace.log`).
/// - Example: `internal-trash-sweep.log`
///
/// Branch and hook names are sanitized for filesystem safety via
/// `sanitize_for_filename`. Already-safe names pass through unchanged; names
/// containing invalid characters have them replaced and a short
/// collision-avoidance hash appended.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum HookLog {
    /// Hook command log: `{branch}/{source}/{hook-type}/{name}.log`
    Hook {
        source: HookSource,
        hook_type: HookType,
        name: String,
    },
    /// Per-branch internal operation log: `{branch}/internal/{op}.log`
    Internal(InternalOp),
    /// Repo-wide internal operation log: `internal-{op}.log` (no branch segment).
    Shared(InternalOp),
}

impl HookLog {
    /// Create a hook command log specification.
    pub fn hook(source: HookSource, hook_type: HookType, name: impl Into<String>) -> Self {
        Self::Hook {
            source,
            hook_type,
            name: name.into(),
        }
    }

    /// Generate the full log path for a branch in the given log directory.
    ///
    /// Builds the nested path under `{log_dir}/{sanitized-branch}/...` for
    /// per-branch variants. The `Shared` variant ignores `branch` and writes
    /// directly under `{log_dir}` as `internal-{op}.log`.
    /// Parent directories must be created by the caller (see `create_detach_log`).
    pub fn path(&self, log_dir: &Path, branch: &str) -> PathBuf {
        match self {
            HookLog::Hook {
                source,
                hook_type,
                name,
            } => log_dir
                .join(sanitize_for_filename(branch))
                .join(source.to_string())
                .join(hook_type.to_string())
                .join(format!("{}.log", sanitize_for_filename(name))),
            HookLog::Internal(op) => log_dir
                .join(sanitize_for_filename(branch))
                .join("internal")
                .join(format!("{op}.log")),
            HookLog::Shared(op) => log_dir.join(format!("internal-{op}.log")),
        }
    }
}

/// Create the log directory and file for a detached process.
///
/// Returns `(log_path, log_file)`. Shared by `spawn_detached` and
/// `spawn_detached_exec`.
fn create_detach_log(
    repo: &Repository,
    branch: &str,
    hook_log: &HookLog,
) -> anyhow::Result<(PathBuf, fs::File)> {
    let log_dir = repo.wt_logs_dir();
    let relative_path = hook_log.path(Path::new(""), branch);
    let log_path = log_dir.join(&relative_path);
    let log_file =
        worktrunk::utils::open_log_file(&log_dir, &relative_path, false).with_context(|| {
            format!(
                "Failed to create log file {}",
                format_path_for_display(&log_path)
            )
        })?;

    Ok((log_path, log_file))
}

/// Spawn a detached background process with output redirected to a log file.
///
/// The process will be fully detached from the parent:
/// - On Unix: uses `process_group(0)` to create a new process group (survives PTY closure)
/// - On Windows: uses `CREATE_NEW_PROCESS_GROUP` to detach from console
///
/// Internal ops (`HookLog::Internal` and `HookLog::Shared`) are run at lowered
/// priority via [`worktrunk::priority::command`] so their I/O and CPU don't
/// compete with user-visible work; user hooks run at normal priority.
///
/// Logs are centralized in the main worktree's `.git/wt/logs/` directory.
pub fn spawn_detached(
    repo: &Repository,
    worktree_path: &Path,
    args: &[OsString],
    branch: &str,
    hook_log: &HookLog,
) -> anyhow::Result<PathBuf> {
    let shell = worktrunk::shell_exec::ShellConfig::get()?;
    let args: Vec<_> = shell
        .args
        .iter()
        .map(OsString::from)
        .chain(args.iter().cloned())
        .collect();
    spawn_detached_exec(
        repo,
        worktree_path,
        &shell.executable,
        &args,
        branch,
        hook_log,
        &[],
    )
}

/// Spawn a detached background process by executing a binary directly.
///
/// Unlike [`spawn_detached`] (which wraps a shell command in `sh -c`), this
/// spawns the executable without an intermediate shell. Complete input is
/// prepared by [`worktrunk::shell_exec::buffered_stdin`] before spawn.
///
/// Used for structured child processes like `wt hook run-pipeline` where the parent
/// passes data via stdin rather than through shell arguments.
///
/// When `hook_log` is [`HookLog::Hook`], the spawn is treated as a background
/// hook pipeline: the child (and every process it later spawns) receives
/// [`worktrunk::priority::FOREGROUND_ENV_VAR`] =
/// [`worktrunk::priority::BACKGROUND_HOOK_VALUE`] so nested `wt` invocations
/// can tell they're running inside a background hook.
pub fn spawn_detached_exec(
    repo: &Repository,
    worktree_path: &Path,
    program: &Path,
    args: &[impl AsRef<OsStr>],
    branch: &str,
    hook_log: &HookLog,
    stdin_bytes: &[u8],
) -> anyhow::Result<std::path::PathBuf> {
    let (log_path, log_file) = create_detach_log(repo, branch, hook_log)?;

    tracing::debug!(
        program = %program.display(),
        "$ {} {} (detached, logging to {})",
        program.display(),
        args.iter().map(|arg| arg.as_ref().to_string_lossy()).collect::<Vec<_>>().join(" "),
        log_path.file_name().unwrap_or_default().to_string_lossy()
    );

    let is_background_hook = matches!(hook_log, HookLog::Hook { .. });

    #[cfg(unix)]
    {
        let low_priority = matches!(hook_log, HookLog::Internal(_) | HookLog::Shared(_));
        spawn_detached_exec_unix(
            worktree_path,
            program,
            args,
            log_file,
            stdin_bytes,
            low_priority,
            is_background_hook,
        )?;
    }

    #[cfg(windows)]
    {
        spawn_detached_exec_windows(
            worktree_path,
            program,
            args,
            log_file,
            stdin_bytes,
            is_background_hook,
        )?;
    }

    Ok(log_path)
}

/// Apply [`worktrunk::priority::FOREGROUND_ENV_VAR`] to a
/// [`std::process::Command`] when spawning a background hook pipeline.
fn set_background_hook_env(cmd: &mut std::process::Command, is_background_hook: bool) {
    if is_background_hook {
        cmd.env(
            worktrunk::priority::FOREGROUND_ENV_VAR,
            worktrunk::priority::BACKGROUND_HOOK_VALUE,
        );
    }
}

#[cfg(unix)]
fn spawn_detached_exec_unix(
    worktree_path: &Path,
    program: &Path,
    args: &[impl AsRef<OsStr>],
    log_file: fs::File,
    stdin_bytes: &[u8],
    low_priority: bool,
    is_background_hook: bool,
) -> anyhow::Result<()> {
    use std::os::unix::process::CommandExt;

    // See [`worktrunk::priority`] for the priority-lowering rationale.
    let mut cmd = worktrunk::priority::command(program, low_priority);
    cmd.args(args)
        .current_dir(worktree_path)
        .stdin(
            worktrunk::shell_exec::buffered_stdin(stdin_bytes)
                .context("Failed to prepare detached input")?,
        )
        .stdout(Stdio::from(
            log_file
                .try_clone()
                .context("Failed to clone log file handle")?,
        ))
        .stderr(Stdio::from(log_file))
        .process_group(0);
    worktrunk::shell_exec::scrub_directive_env_vars(&mut cmd);
    worktrunk::shell_exec::scrub_git_discovery_env_vars(&mut cmd);
    set_background_hook_env(&mut cmd, is_background_hook);
    worktrunk::shell_exec::spawn(&mut cmd).context("Failed to spawn detached process")?;

    Ok(())
}

#[cfg(windows)]
fn spawn_detached_exec_windows(
    worktree_path: &Path,
    program: &Path,
    args: &[impl AsRef<OsStr>],
    log_file: fs::File,
    stdin_bytes: &[u8],
    is_background_hook: bool,
) -> anyhow::Result<()> {
    use std::os::windows::process::CommandExt;

    const CREATE_NEW_PROCESS_GROUP: u32 = 0x00000200;
    const CREATE_NO_WINDOW: u32 = 0x08000000;

    let mut cmd = Command::new(program);
    cmd.args(args)
        .current_dir(worktree_path)
        .stdin(
            worktrunk::shell_exec::buffered_stdin(stdin_bytes)
                .context("Failed to prepare detached input")?,
        )
        .stdout(Stdio::from(
            log_file
                .try_clone()
                .context("Failed to clone log file handle")?,
        ))
        .stderr(Stdio::from(log_file))
        .creation_flags(CREATE_NEW_PROCESS_GROUP | CREATE_NO_WINDOW);
    worktrunk::shell_exec::scrub_directive_env_vars(&mut cmd);
    worktrunk::shell_exec::scrub_git_discovery_env_vars(&mut cmd);
    set_background_hook_env(&mut cmd, is_background_hook);
    worktrunk::shell_exec::spawn(&mut cmd).context("Failed to spawn detached process")?;

    Ok(())
}

/// Repo-wide internal cleanup op, run fire-and-forget after `wt remove`'s
/// primary user-visible output.
///
/// This is worktrunk's opportunistic janitor: it reclaims resources orphaned
/// by interrupted or out-of-band operations. It runs on the `wt remove`
/// cadence (not a timer, not a user command, not a read-only command), and
/// after primary output so it can never delay a user-visible message. Every
/// step is best-effort and additive — failures log at debug level and the
/// `wt remove` operation proceeds regardless.
///
/// It DOES delay process exit — the shell wrapper waits on it. Enumeration is
/// two spawns, one `pgrep` plus one `lsof` over the whole daemon PID set, flat
/// in the machine-wide daemon count. Any live daemon then costs a
/// `git worktree list`, and a classified orphan a `SIGTERM`→`SIGKILL` wait
/// bounded by `REAP_KILL_DEADLINE` — both flat in the daemon count too (see
/// the `internal-sweep` / `enumerate-fsmonitor-daemons` trace spans and
/// benches/AGENTS.md § Recording `wt remove` / `wt step prune` staging).
///
/// Steps:
///
/// 1. [`sweep_trash`] — restart deletion of `.git/wt/trash/` entries left
///    by an interrupted background removal.
/// 2. [`worktrunk::git::fsmonitor::reap_orphan_fsmonitor_daemons`] — terminate
///    `git fsmonitor--daemon` processes whose worktree no longer exists.
///    Defense-in-depth for daemons orphaned by paths that bypass `wt remove`
///    (plain `git worktree remove`, manual `rm -rf`, a crashed `wt`); the
///    `wt remove` source itself stops the daemon synchronously.
pub fn run_internal_sweep(repo: &Repository) {
    let _span = worktrunk::trace::Span::new("internal-sweep");
    sweep_trash(repo);
    worktrunk::git::fsmonitor::reap_orphan_fsmonitor_daemons(repo);
}

/// Fire-and-forget restart of trash deletion.
///
/// Worktree removal renames the worktree into
/// `.git/wt/trash/<name>-<timestamp>/` and starts a detached
/// [`worktrunk::git::drain_trash`] to delete it. If that process is
/// interrupted (SIGKILL, reboot, disk full), its entries stay behind. `wt
/// remove` calls this function after its primary user-visible output — so the
/// sweep never delays the progress or success message — and starts another
/// drain when the trash holds anything and no drain is running.
///
/// Best effort: spawn failures are logged at debug level and otherwise
/// ignored. The sweep is purely additive — the primary `wt remove` operation
/// proceeds regardless of outcome.
pub fn sweep_trash(repo: &Repository) {
    let trash_dir = repo.wt_trash_dir();
    if worktrunk::git::staged_trash_entries(&trash_dir).is_empty()
        || worktrunk::git::trash_drain_running(&trash_dir)
    {
        return;
    }

    // The sweep is repo-wide (not branch-scoped), so it logs to a top-level
    // shared file alongside `commands.jsonl` and `trace.log`. The branch
    // argument is ignored for the `Shared` variant.
    let spawned = std::env::current_exe()
        .context("Failed to locate Worktrunk executable")
        .and_then(|executable| {
            spawn_detached(
                repo,
                &repo.wt_dir(),
                &build_drain_trash_command(executable, repo),
                "",
                &HookLog::Shared(InternalOp::TrashSweep),
            )
        });
    if let Err(e) = spawned {
        tracing::debug!(error = %format!("{e:#}"), "Failed to spawn stale trash sweep");
    }
}

/// Shell argv that runs `wt -C <git-common-dir> _drain-trash`: a fixed script,
/// its `$0`, then native arguments. Paths are never interpolated into shell
/// source. The drain derives the trash directory from the repository it
/// discovers, so it can't be pointed at a directory outside a trash. `-C`
/// names that repository because the spawn's cwd may be the placeholder of a
/// worktree the removal just deleted.
pub fn build_drain_trash_command(executable: PathBuf, repo: &Repository) -> Vec<OsString> {
    vec![
        OsString::from(r#"exec "$@""#),
        OsString::from("wt"),
        executable.into_os_string(),
        OsString::from("-C"),
        repo.git_common_dir().as_os_str().to_os_string(),
        OsString::from("_drain-trash"),
    ]
}

/// Remove the empty shell-PWD placeholder after the wrapper consumes its cd directive.
/// `rmdir` preserves any files written into the original path.
pub fn build_remove_placeholder_command(path: &Path) -> Vec<OsString> {
    vec![
        r#"sleep 1 && rmdir -- "$1" 2>/dev/null"#.into(),
        "wt".into(),
        path.as_os_str().into(),
    ]
}

/// Fallback when staging fails. Only flags and sequencing enter the script;
/// the checkout remains a separate process argument.
pub fn build_remove_command(
    path: &Path,
    force_worktree: bool,
    changed_directory: bool,
    tail: Option<&[OsString]>,
) -> Vec<OsString> {
    let delay = if changed_directory { "sleep 1 && " } else { "" };
    let force = if force_worktree { " --force" } else { "" };
    let mut script = format!(r#"{delay}git worktree remove{force} -- "$1""#);
    if tail.is_some() {
        script.push_str(r#" && shift && "$@""#);
    }
    let mut args = vec![script.into(), "wt".into(), path.as_os_str().into()];
    if let Some(tail) = tail {
        args.extend_from_slice(tail);
    }
    args
}

#[cfg(test)]
mod tests {
    use insta::assert_snapshot;
    use path_slash::PathExt as _;

    use super::*;

    #[test]
    fn test_sanitize_for_filename() {
        // Path separators, Windows-illegal characters, multiple special chars,
        // already-safe names, and reserved prefix names
        assert_snapshot!(
            [
                ("path separator /", sanitize_for_filename("feature/branch")),
                (r"path separator \", sanitize_for_filename(r"feature\branch")),
                ("colon", sanitize_for_filename("bug:123")),
                ("angle brackets", sanitize_for_filename("fix<angle>")),
                ("pipe", sanitize_for_filename("fix|pipe")),
                ("question mark", sanitize_for_filename("fix?question")),
                ("wildcard", sanitize_for_filename("fix*wildcard")),
                ("quotes", sanitize_for_filename(r#"fix"quotes""#)),
                ("multiple special", sanitize_for_filename(r#"a/b\c<d>e:f"g|h?i*j"#)),
                ("already safe", sanitize_for_filename("normal-branch")),
                ("underscore", sanitize_for_filename("branch_with_underscore")),
                ("reserved prefix CONSOLE", sanitize_for_filename("CONSOLE")),
                ("reserved prefix COM10", sanitize_for_filename("COM10")),
            ]
            .into_iter()
            .map(|(label, val)| format!("{label}: {val}"))
            .collect::<Vec<_>>()
            .join("\n"),
            @r"
        path separator /: feature-branch-30k
        path separator \: feature-branch-k37
        colon: bug-123-4xh
        angle brackets: fix-angle-q9m
        pipe: fix-pipe-68k
        question mark: fix-question-ab6
        wildcard: fix-wildcard-38y
        quotes: fix-quotes-2xu
        multiple special: a-b-c-d-e-f-g-h-i-j-obi
        already safe: normal-branch
        underscore: branch_with_underscore
        reserved prefix CONSOLE: CONSOLE
        reserved prefix COM10: COM10
        "
        );

        // Windows reserved device names are handled (produce valid filenames)
        // The sanitize-filename crate replaces these rather than prefixing
        // Note: crate matches COM0-9/LPT0-9, stricter than Windows (which only reserves 1-9)
        for name in [
            "CON", "con", "PRN", "AUX", "NUL", "COM0", "COM1", "com9", "LPT0", "LPT1", "lpt9",
        ] {
            let result = sanitize_for_filename(name);
            assert!(!result.is_empty() && result.len() > 3, "{name} -> {result}");
        }

        // Collision avoidance: different inputs produce different outputs
        let a = sanitize_for_filename("feature/x");
        let b = sanitize_for_filename("feature-x");
        assert_ne!(a, b, "should not collide: {a} vs {b}");
    }

    #[test]
    fn drain_command_passes_paths_as_their_own_arguments() {
        let test = worktrunk::testing::TestRepo::with_initial_commit();
        let repo = Repository::at(test.root_path()).unwrap();
        let executable = PathBuf::from("/opt/with space-'$(echo PWNED)\n/wt");
        let args = build_drain_trash_command(executable.clone(), &repo);
        assert_eq!(args[0], r#"exec "$@""#);
        assert_eq!(args[2], executable.as_os_str());
        assert_eq!(args[3], "-C");
        assert_eq!(args[4], repo.git_common_dir().as_os_str());
        assert_eq!(args[5], "_drain-trash");
    }

    #[test]
    fn test_hook_log_path() {
        use worktrunk::git::HookType;

        let log_dir = Path::new("/repo/.git/wt/logs");

        // Hook path: {log_dir}/{sanitized-branch}/{source}/{hook-type}/{sanitized-name}.log
        let log = HookLog::hook(HookSource::User, HookType::PostCreate, "server");
        assert_snapshot!(
            log.path(log_dir, "main").to_slash_lossy(),
            @"/repo/.git/wt/logs/main/user/post-start/server.log"
        );

        // Slash in branch name gets sanitized (feature/auth → feature-auth-{hash})
        assert_snapshot!(
            log.path(log_dir, "feature/auth").to_slash_lossy(),
            @"/repo/.git/wt/logs/feature-auth-j34/user/post-start/server.log"
        );

        // Project source
        let log = HookLog::hook(HookSource::Project, HookType::PreCreate, "build");
        assert_snapshot!(
            log.path(log_dir, "main").to_slash_lossy(),
            @"/repo/.git/wt/logs/main/project/pre-start/build.log"
        );

        // Per-branch internal operation path: {log_dir}/{sanitized-branch}/internal/{op}.log
        assert_snapshot!(
            HookLog::Internal(InternalOp::Remove)
                .path(log_dir, "main")
                .to_slash_lossy(),
            @"/repo/.git/wt/logs/main/internal/remove.log"
        );

        // Repo-wide (branch-agnostic) internal operation path:
        // {log_dir}/internal-{op}.log — the branch argument is ignored.
        assert_snapshot!(
            HookLog::Shared(InternalOp::TrashSweep)
                .path(log_dir, "anything")
                .to_slash_lossy(),
            @"/repo/.git/wt/logs/internal-trash-sweep.log"
        );
    }
}