Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
//! TTY spinners for long-running work.
//!
//! Two spinner types share one set of render primitives (spinner frames, cursor
//! control, TTY gating, clear-on-drop): [`Progress`] shows file/byte counters
//! for file-walk operations; [`Watchdog`] shows an elapsed-time "still waiting"
//! line for a slow blocking subprocess (e.g. the `commit.generation` LLM) so a
//! long or hung command isn't silent.
//!
//! ## `Progress`
//!
//! Shows a single-line stderr spinner (`⠋ Copying 1,234 files · 312 MiB`,
//! `⠋ Removing 7,272 files · 64.5 MiB`) that updates in place while the work
//! runs. Workers bump atomic counters via [`Progress::record`]; a background
//! thread renders at ~10Hz using crossterm cursor control.
//!
//! `Progress` is the single owner of operation counts: every state (spinner
//! enabled, disabled, and the no-`cli` stub) accumulates files/bytes, and
//! [`Progress::totals`] reads the running totals from `&self` mid-operation.
//! Callers report from `totals()` rather than keeping their own counters.
//! Counts accumulate for the lifetime of the reporter, so each counted
//! operation (or batch reported as one) gets its own `Progress`.
//!
//! Every [`Progress::record`] also classifies the file by [`DataCopy`], so a
//! copy can report how much of it shared the source's extents rather than
//! costing disk. [`Progress::copy_split`] reads that pair back.
//!
//! `start` is named deliberately (not `new`) because it spawns a ticker thread
//! as a side effect — `Default`-style semantics would be misleading. The verb
//! (`"Copying"`, `"Removing"`) is fixed for the lifetime of the spinner.
//!
//! The progress line is cleared on [`Progress::finish`] or on drop, so the
//! caller can print a summary message immediately afterward without overlap.
//!
//! The spinner machinery (crossterm, the ticker thread, the render loop) is
//! gated on the `cli` feature. Without `cli`, [`Progress`] keeps the counters
//! but never renders. Pure formatting helpers ([`format_bytes`],
//! [`format_stats_paren`], [`format_reflink_paren`]) are always available since
//! callers in both modes want them.
use color_print::cformat;
pub use imp::Progress;
pub use imp::Watchdog;
/// How a recorded file's data reached its destination, which is what decides
/// whether the file cost disk.
///
/// [`Progress`] counts [`Self::Reflinked`] and [`Self::Written`] separately so
/// `wt step copy-ignored` can report the split; [`Self::Neither`] contributes
/// to the file and byte totals only. Only a filesystem clone distinguishes the
/// first two, so everything that moves no file extents — a symlink, whose
/// content is a path, and a removal, which frees them — records `Neither`.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum DataCopy {
/// The filesystem cloned the source's extents. The destination shares them
/// until one side writes, so the copy costs no data blocks.
Reflinked,
/// The bytes were written out, costing the file's full size on disk.
Written,
/// Neither — the record moved no file extents.
Neither,
}
#[cfg(feature = "cli")]
mod imp {
use std::io::{IsTerminal, Write};
use std::sync::Arc;
use std::sync::atomic::{AtomicBool, AtomicU64, AtomicUsize, Ordering};
use std::thread::{self, JoinHandle};
use std::time::{Duration, Instant};
use color_print::cformat;
use crossterm::{
QueueableCommand,
cursor::{MoveToColumn, MoveUp},
terminal::{Clear, ClearType},
};
use super::{format_bytes, format_count};
use crate::styling::HINT_SYMBOL;
const SPINNER_FRAMES: &[char] = &['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
const TICK_INTERVAL: Duration = Duration::from_millis(100);
/// Delay before the first frame renders, so sub-second operations stay silent.
const STARTUP_DELAY: Duration = Duration::from_millis(300);
/// `Watchdog` waits longer before nagging — a configured LLM routinely takes
/// a few seconds, and the caller has already printed a "Generating…"
/// line, so the watchdog only surfaces once a command is genuinely slow.
const WATCHDOG_STARTUP_DELAY: Duration = Duration::from_secs(4);
/// Second tier: once a command has run this long, the bare status line
/// isn't enough to debug it, so the exact invocation is revealed in a gutter
/// beneath the status — cleared with the rest of the block when the command
/// finishes.
const WATCHDOG_ESCALATE_DELAY: Duration = Duration::from_secs(10);
/// Whether either spinner renders at all — the shared half of both `start`
/// gates, checked alongside the TTY (and, for [`Watchdog`], verbosity).
///
/// A terminal *erases* an in-place redraw, so a frame never survives into
/// what the user is left with. A PTY test capturing the raw byte stream
/// keeps every frame instead, and whether any were drawn at all depends on
/// whether load pushed the operation past a startup delay above — with the
/// elapsed seconds baked into the bytes. So the test PTY environments set
/// `WORKTRUNK_TEST_SPINNERS=0` and capture only the output that persists.
/// Counters are unaffected: this gates the render, not the accounting.
fn spinners_enabled() -> bool {
!matches!(std::env::var("WORKTRUNK_TEST_SPINNERS").as_deref(), Ok("0"))
}
/// Shared state between the spinner and its ticker thread. `rendered` flips
/// true once the ticker has actually drawn a line, so `Drop` clears the line
/// only when there's something to clear — a sub-startup-delay operation that
/// never rendered leaves the terminal untouched (mirrors [`WatchdogShared`]).
struct Shared {
files: AtomicUsize,
bytes: AtomicU64,
reflinked: AtomicUsize,
written: AtomicUsize,
done: AtomicBool,
rendered: AtomicBool,
}
impl Shared {
fn new() -> Self {
Self {
files: AtomicUsize::new(0),
bytes: AtomicU64::new(0),
reflinked: AtomicUsize::new(0),
written: AtomicUsize::new(0),
done: AtomicBool::new(false),
rendered: AtomicBool::new(false),
}
}
}
/// Live spinner displaying file and byte counters for a single operation.
///
/// Counters accumulate in every state; only the rendering is conditional.
/// See [module docs](super) for the output format and lifecycle.
pub struct Progress {
shared: Arc<Shared>,
/// Render thread; present only when the spinner is enabled (stderr TTY).
ticker: Option<JoinHandle<()>>,
}
impl Progress {
/// Start a progress reporter, enabling the spinner iff stderr is a TTY
/// and `spinners_enabled`.
///
/// `verb` is the present-participle label shown to the user (e.g.
/// `"Copying"`, `"Removing"`). Spawns a background ticker thread when a
/// TTY is detected. When stderr is not a TTY, returns a disabled
/// reporter that still counts but renders nothing.
pub fn start(verb: &'static str) -> Self {
Self::start_with(verb, std::io::stderr().is_terminal() && spinners_enabled())
}
/// Dispatch helper that picks the enabled or disabled branch from an
/// explicit `is_tty` flag. Extracted so tests can exercise both branches
/// without depending on the ambient stderr fd — sandboxes (Nix builds,
/// some CI runners) hand the test process a PTY-backed stderr, which
/// would flip the gate in `start` and break a test that hard-coded the
/// disabled outcome. See #2615.
fn start_with(verb: &'static str, is_tty: bool) -> Self {
if is_tty {
Self::enabled(verb)
} else {
Self::disabled()
}
}
/// A reporter that renders nothing but still counts — for non-TTY
/// contexts, benchmarks, tests, and internal moves.
pub fn disabled() -> Self {
Self {
shared: Arc::new(Shared::new()),
ticker: None,
}
}
/// Constructor for the enabled state, separated so the TTY-gated branch in
/// [`Self::start`] and the test-only "force enabled" path share one
/// implementation. Spawns the ticker thread; safe to call from any
/// context that genuinely wants live output.
fn enabled(verb: &'static str) -> Self {
Self::enabled_with_delays(verb, STARTUP_DELAY)
}
/// Spawn the ticker with an explicit startup delay. The public path passes
/// the module constant; tests pass a millisecond delay so the render loop
/// is reachable without waiting out the full startup window.
fn enabled_with_delays(verb: &'static str, startup_delay: Duration) -> Self {
let shared = Arc::new(Shared::new());
let ticker = {
let shared = Arc::clone(&shared);
thread::spawn(move || ticker_loop(&shared, verb, startup_delay))
};
Self {
shared,
ticker: Some(ticker),
}
}
/// Record that a file (or symlink) was processed, classified by whether
/// its data cost disk. Safe to call from any thread.
pub fn record(&self, bytes: u64, data: super::DataCopy) {
self.shared.files.fetch_add(1, Ordering::Relaxed);
self.shared.bytes.fetch_add(bytes, Ordering::Relaxed);
let counter = match data {
super::DataCopy::Reflinked => &self.shared.reflinked,
super::DataCopy::Written => &self.shared.written,
super::DataCopy::Neither => return,
};
counter.fetch_add(1, Ordering::Relaxed);
}
/// Running `(files, bytes)` totals recorded so far.
///
/// Relaxed loads — exact only once the recording threads have finished
/// (e.g. after the rayon pool call returns).
pub fn totals(&self) -> (usize, u64) {
(
self.shared.files.load(Ordering::Relaxed),
self.shared.bytes.load(Ordering::Relaxed),
)
}
/// Running `(reflinked, written)` file counts. Their sum is at most
/// `totals().0` — the gap is the files that moved no extents.
pub fn copy_split(&self) -> (usize, usize) {
(
self.shared.reflinked.load(Ordering::Relaxed),
self.shared.written.load(Ordering::Relaxed),
)
}
/// Stop the spinner and clear the progress line.
pub fn finish(self) {
// Drop runs the same shutdown logic — no need to duplicate it here.
drop(self);
}
}
impl Drop for Progress {
fn drop(&mut self) {
if let Some(ticker) = self.ticker.take() {
self.shared.done.store(true, Ordering::Relaxed);
ticker.thread().unpark();
let _ = ticker.join();
// Clear the line only if the ticker actually drew one. A
// sub-startup-delay operation never rendered, so there's nothing
// to clear and the terminal is left untouched (mirrors Watchdog).
if self.shared.rendered.load(Ordering::Relaxed) {
let _ = clear_line(&mut std::io::stderr().lock());
}
}
}
}
fn ticker_loop(shared: &Shared, verb: &str, startup_delay: Duration) {
let start = Instant::now();
// Below the startup delay nothing renders — the line never gets drawn.
// park_timeout returns immediately on `unpark` from drop, so short
// operations don't block shutdown either.
while start.elapsed() < startup_delay {
if shared.done.load(Ordering::Relaxed) {
return;
}
thread::park_timeout(startup_delay.saturating_sub(start.elapsed()));
}
while !shared.done.load(Ordering::Relaxed) {
// Mark rendered only when the draw succeeds, so Drop clears exactly
// when a line is actually on screen — a failed write leaves nothing
// to clear.
if render_tick(&mut std::io::stderr().lock(), shared, verb, start.elapsed()).is_ok() {
shared.rendered.store(true, Ordering::Relaxed);
}
thread::park_timeout(TICK_INTERVAL);
}
}
/// Render one spinner frame: pick the frame for `elapsed`, read the live
/// counters, and write the formatted status line to `w`. Factored out of
/// [`ticker_loop`] so the render step is unit-testable directly — without
/// spawning the ticker thread or waiting out the startup delay.
fn render_tick<W: Write>(
w: &mut W,
shared: &Shared,
verb: &str,
elapsed: Duration,
) -> std::io::Result<()> {
let frame_idx =
(elapsed.as_millis() / TICK_INTERVAL.as_millis()) as usize % SPINNER_FRAMES.len();
let files = shared.files.load(Ordering::Relaxed);
let bytes = shared.bytes.load(Ordering::Relaxed);
let line = format_line(verb, files, bytes, SPINNER_FRAMES[frame_idx]);
render_line(w, &line)
}
fn format_line(verb: &str, files: usize, bytes: u64, spinner: char) -> String {
if files == 0 {
cformat!("<cyan>{spinner}</> {verb}...")
} else {
let word = if files == 1 { "file" } else { "files" };
cformat!(
"<cyan>{spinner}</> {verb} {} {} · {}",
format_count(files),
word,
format_bytes(bytes),
)
}
}
fn render_line<W: Write>(w: &mut W, line: &str) -> std::io::Result<()> {
w.queue(MoveToColumn(0))?;
w.queue(Clear(ClearType::CurrentLine))?;
write!(w, "{line}")?;
w.flush()
}
fn clear_line<W: Write>(w: &mut W) -> std::io::Result<()> {
w.queue(MoveToColumn(0))?;
w.queue(Clear(ClearType::CurrentLine))?;
w.flush()
}
/// Shared state between the watchdog and its ticker thread. `rendered_rows`
/// is the terminal-row count of the block currently on screen — 0 means
/// nothing was drawn (a fast command that finished inside
/// [`WATCHDOG_STARTUP_DELAY`], the common case), so `Drop` leaves the
/// terminal untouched; >0 tells `Drop` how many rows to clear. `escalated`
/// records whether the command gutter has been revealed, for tests.
struct WatchdogShared {
done: AtomicBool,
rendered_rows: AtomicUsize,
escalated: AtomicBool,
}
impl WatchdogShared {
fn new() -> Self {
Self {
done: AtomicBool::new(false),
rendered_rows: AtomicUsize::new(0),
escalated: AtomicBool::new(false),
}
}
}
/// Live "still waiting" status for a single slow blocking subprocess.
///
/// Unlike [`Progress`] (which counts work units), `Watchdog` just tracks
/// elapsed time. After a startup delay it renders a dim one-line status —
/// `↳ Waiting for the commit generation command (4s)` — redrawn in place
/// each second; the ticking counter is the "still alive" signal. After a
/// longer delay it escalates, revealing the exact command in a gutter
/// beneath the status:
///
/// ```text
/// ↳ Waiting for the commit generation command (12s)
/// sh -c 'claude -p --model=haiku'
/// ```
///
/// The whole block is cleared on drop — nothing persists — so the caller can
/// print its result immediately afterward. The dim, in-place look mirrors
/// `wt list`'s stall footer.
///
/// It only reads a clock and writes to stderr; it never touches the child's
/// stdin/stdout or its `wait`, so it's safe to wrap a capture-mode
/// [`Cmd::run`](crate::shell_exec::Cmd) whose output is captured rather than
/// streamed (e.g. the LLM commit command). Don't pair it with a streaming
/// command — the child's own output would interleave with the status block.
pub struct Watchdog {
shared: Arc<WatchdogShared>,
/// Render thread; present only when enabled (stderr TTY, non-verbose).
ticker: Option<JoinHandle<()>>,
}
impl Watchdog {
/// Start a watchdog for a slow subprocess.
///
/// `waiting_for` names the running operation (e.g. `"the commit
/// generation command"`). `command`, if given, is the exact
/// invocation — revealed in a gutter beneath the status line once the
/// command runs past the escalation delay, so a slow or stuck command
/// is debuggable.
///
/// Enabled only when stderr is a TTY, verbosity is 0, and
/// `spinners_enabled` — under `-v`/`-vv` the structured diagnostics
/// take over, and a non-TTY (piped) context renders nothing.
pub fn start(waiting_for: &str, command: Option<&str>) -> Self {
let enabled = std::io::stderr().is_terminal()
&& crate::styling::verbosity() == 0
&& spinners_enabled();
Self::start_with(waiting_for, command, enabled)
}
/// Dispatch helper picking enabled/disabled from an explicit flag, so
/// tests exercise both branches without depending on the ambient stderr
/// fd (see [`Progress::start_with`] for why).
fn start_with(waiting_for: &str, command: Option<&str>, enabled: bool) -> Self {
if enabled {
Self::enabled(waiting_for, command)
} else {
Self::disabled()
}
}
fn disabled() -> Self {
Self {
shared: Arc::new(WatchdogShared::new()),
ticker: None,
}
}
fn enabled(waiting_for: &str, command: Option<&str>) -> Self {
Self::enabled_with_delays(
waiting_for,
command,
WATCHDOG_STARTUP_DELAY,
WATCHDOG_ESCALATE_DELAY,
)
}
/// Spawn the ticker with explicit delays. The public path passes the
/// module constants; tests pass millisecond delays so the escalation
/// tier is exercisable without a 10-second wait.
fn enabled_with_delays(
waiting_for: &str,
command: Option<&str>,
startup_delay: Duration,
escalate_delay: Duration,
) -> Self {
let shared = Arc::new(WatchdogShared::new());
let ticker = {
let shared = Arc::clone(&shared);
let waiting_for = waiting_for.to_owned();
let command = command.map(str::to_owned);
thread::spawn(move || {
watchdog_loop(
&shared,
&waiting_for,
command.as_deref(),
startup_delay,
escalate_delay,
)
})
};
Self {
shared,
ticker: Some(ticker),
}
}
/// Stop the watchdog and clear its block. Equivalent to dropping.
pub fn finish(self) {
drop(self);
}
}
impl Drop for Watchdog {
fn drop(&mut self) {
if let Some(ticker) = self.ticker.take() {
self.shared.done.store(true, Ordering::Relaxed);
ticker.thread().unpark();
let _ = ticker.join();
// Clear the block the ticker left on screen. 0 rows means nothing
// was drawn (a fast command that never tripped the startup delay),
// so the terminal is left untouched.
let rows = self.shared.rendered_rows.load(Ordering::Relaxed);
if rows > 0 {
let _ = clear_block(&mut std::io::stderr().lock(), rows);
}
}
}
}
fn watchdog_loop(
shared: &WatchdogShared,
waiting_for: &str,
command: Option<&str>,
startup_delay: Duration,
escalate_delay: Duration,
) {
let start = Instant::now();
// park_timeout returns immediately on `unpark` from drop, so a command
// that finishes before the delay neither renders nor blocks shutdown.
while start.elapsed() < startup_delay {
if shared.done.load(Ordering::Relaxed) {
return;
}
thread::park_timeout(startup_delay.saturating_sub(start.elapsed()));
}
let mut prev_rows = 0usize;
let mut last_block: Vec<String> = Vec::new();
while !shared.done.load(Ordering::Relaxed) {
let elapsed = start.elapsed();
// Second tier: once the command has run long enough, reveal it in a
// gutter beneath the status line.
let escalated = command.is_some() && elapsed >= escalate_delay;
if escalated {
shared.escalated.store(true, Ordering::Relaxed);
}
let block = watchdog_block(
waiting_for,
elapsed.as_secs(),
if escalated { command } else { None },
crate::styling::terminal_width(),
);
// Redraw only when the content changes — the status counter ticks
// once a second, the gutter appears once — so the block doesn't
// flicker between the (sub-second) wake-ups.
if block != last_block {
let mut err = std::io::stderr().lock();
prev_rows = render_block(&mut err, &block, prev_rows);
shared.rendered_rows.store(prev_rows, Ordering::Relaxed);
last_block = block;
}
thread::park_timeout(TICK_INTERVAL);
}
}
/// Build the watchdog block: a dim status line, plus — once `command` is
/// given (escalated) — that command in a bash-highlighted gutter beneath it
/// (matching how worktrunk shows commands elsewhere, e.g. the LLM-failure
/// error).
///
/// Every returned string must occupy exactly one terminal row, or the
/// in-place cursor math in [`render_block`]/[`clear_block`] desyncs from what
/// the terminal actually wrapped and corrupts the lines above. So both lines
/// are width-bounded rather than left to soft-wrap: the status is
/// ANSI-aware-truncated to `width`, and the command gutter is *chopped* (not
/// wrapped) so an over-wide invocation stays one row. `width` is the terminal
/// width (`None` → unknown, leave the status unbounded); the loop passes the
/// live width each tick so a resize is picked up.
fn watchdog_block(
waiting_for: &str,
secs: u64,
command: Option<&str>,
width: Option<usize>,
) -> Vec<String> {
let status = cformat!("{HINT_SYMBOL} <dim>Waiting for {waiting_for} ({secs}s)</>");
let status = match width {
Some(w) => crate::styling::truncate_visible(&status, w),
None => status,
};
let mut lines = vec![status];
if let Some(cmd) = command {
lines.extend(
crate::styling::format_bash_with_gutter_chopped(cmd)
.lines()
.map(str::to_owned),
);
}
lines
}
/// Redraw the in-place block: clear the previous `prev_rows` rows, then write
/// the new lines (joined, no trailing newline). Returns the new row count.
/// Relies on each line being ≤ terminal width (one row), so `prev_rows`
/// equals the visual rows occupied.
fn render_block<W: Write>(w: &mut W, lines: &[String], prev_rows: usize) -> usize {
let _ = w.queue(MoveToColumn(0));
if prev_rows > 1 {
let _ = w.queue(MoveUp(prev_rows as u16 - 1));
}
let _ = w.queue(Clear(ClearType::FromCursorDown));
let _ = write!(w, "{}", lines.join("\n"));
let _ = w.flush();
lines.len()
}
/// Clear a `rows`-row block: move to its first row and clear downward.
fn clear_block<W: Write>(w: &mut W, rows: usize) -> std::io::Result<()> {
w.queue(MoveToColumn(0))?;
if rows > 1 {
w.queue(MoveUp(rows as u16 - 1))?;
}
w.queue(Clear(ClearType::FromCursorDown))?;
w.flush()
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_format_line_empty() {
let line = format_line("Copying", 0, 0, '⠋');
assert!(line.contains("Copying..."));
assert!(line.contains('⠋'));
}
#[test]
fn test_format_line_singular() {
let line = format_line("Copying", 1, 42, '⠙');
assert!(line.contains("1 file "));
assert!(line.contains("42 B"));
}
#[test]
fn test_format_line_plural() {
let line = format_line("Removing", 2_500, 5 * 1024 * 1024, '⠹');
assert!(line.contains("Removing"));
assert!(line.contains("2,500 files"));
assert!(line.contains("5.0 MiB"));
}
#[test]
fn test_render_line_writes_text_with_prefix_control_bytes() {
let mut buf = Vec::new();
render_line(&mut buf, "hello").unwrap();
assert!(buf.ends_with(b"hello"));
assert!(buf.len() > b"hello".len());
}
#[test]
fn test_clear_line_writes_control_bytes() {
let mut buf = Vec::new();
clear_line(&mut buf).unwrap();
assert!(!buf.is_empty());
}
#[test]
fn test_start_with_non_tty_is_disabled() {
assert!(Progress::start_with("Copying", false).ticker.is_none());
}
#[test]
fn test_start_with_tty_is_enabled() {
let p = Progress::start_with("Copying", true);
assert!(p.ticker.is_some());
p.finish();
}
#[test]
fn test_enabled_lifecycle_counters_propagate() {
let p = Progress::enabled("Copying");
p.record(1024, super::super::DataCopy::Reflinked);
p.record(2048, super::super::DataCopy::Written);
assert_eq!(p.totals(), (2, 3072));
p.finish();
}
#[test]
fn test_render_tick_writes_counter_line() {
// The ticker's per-frame render step, exercised directly — no thread,
// no startup-delay wait. Asserts the rendered line carries the verb
// and the live counters, the wiring ticker_loop runs each tick.
let shared = Shared::new();
shared.files.fetch_add(2, Ordering::Relaxed);
shared.bytes.fetch_add(5 * 1024 * 1024, Ordering::Relaxed);
let mut buf = Vec::new();
render_tick(&mut buf, &shared, "Removing", Duration::ZERO).unwrap();
let out = String::from_utf8(buf).unwrap();
assert!(out.contains("Removing"));
assert!(out.contains("2 files"));
assert!(out.contains("5.0 MiB"));
}
#[test]
fn test_progress_renders_after_startup_delay() {
// Tiny startup delay so the ticker reaches its render loop fast. Poll
// for the render rather than sleeping a fixed window the thread could
// be starved past under load: `rendered` is the background work we're
// verifying, so wait on it directly.
let p = Progress::enabled_with_delays("Removing", Duration::from_millis(10));
p.record(100, super::super::DataCopy::Neither);
let timeout = Duration::from_secs(5);
let start = Instant::now();
while start.elapsed() < timeout {
if p.shared.rendered.load(Ordering::Relaxed) {
break;
}
std::thread::sleep(Duration::from_millis(10));
}
assert!(p.shared.rendered.load(Ordering::Relaxed));
p.finish();
}
#[test]
fn test_fast_progress_leaves_no_trace() {
// A reporter dropped before its startup delay elapses never renders,
// so Drop has nothing to clear. The startup delay sits far in the
// future so the assertion can't race the ticker into rendering under
// load; finish() wakes the parked thread immediately regardless.
let p = Progress::enabled_with_delays("Copying", Duration::from_secs(3600));
assert!(!p.shared.rendered.load(Ordering::Relaxed));
p.finish();
}
#[test]
fn test_watchdog_block_status_only() {
// Before escalation (no command) the block is a single dim status
// row. A wide width leaves the status untruncated.
let block = watchdog_block("the commit generation command", 4, None, Some(200));
assert_eq!(block.len(), 1);
assert!(block[0].contains("Waiting for the commit generation command"));
assert!(block[0].contains("(4s)"));
assert!(block[0].contains('↳'));
assert!(!block[0].contains('…'));
}
#[test]
fn test_watchdog_block_escalated_adds_command_gutter() {
// Escalated, the command is revealed in a gutter row beneath the
// status. Assert on a bare word ("claude") rather than the whole
// command, since bash highlighting interleaves ANSI codes between
// tokens (a word itself is never split mid-token).
let block = watchdog_block(
"the commit generation command",
12,
Some("claude --model=haiku"),
Some(200),
);
assert!(block.len() >= 2);
assert!(block[0].contains("Waiting for the commit generation command"));
assert!(block.join("\n").contains("claude"));
}
#[test]
fn test_watchdog_block_status_truncated_to_width() {
// A width narrower than the status text truncates it to one row
// (visible width within budget, ellipsis appended) — without this the
// soft-wrapped second row desyncs the in-place cursor math.
use ansi_str::AnsiStr;
use unicode_width::UnicodeWidthStr;
let block = watchdog_block("the commit generation command", 1234, None, Some(20));
assert_eq!(block.len(), 1);
let visible = block[0].ansi_strip();
assert!(UnicodeWidthStr::width(visible.as_ref()) <= 20);
assert!(block[0].contains('…'));
}
#[test]
fn test_watchdog_start_with_non_tty_is_disabled() {
assert!(
Watchdog::start_with("the commit generation command", None, false)
.ticker
.is_none()
);
}
#[test]
fn test_watchdog_start_with_tty_is_enabled() {
let w = Watchdog::start_with("the commit generation command", None, true);
assert!(w.ticker.is_some());
w.finish();
}
#[test]
fn test_watchdog_renders_after_startup_delay() {
// Tiny startup delay, escalation far off: the status renders but the
// command gutter never appears. The first render happens on the
// background ticker thread, so poll for it rather than sleeping a
// fixed window the thread could be starved past under load. The
// far-off escalation delay keeps the gutter absent for the whole
// poll, so the `!escalated` assertion holds regardless of timing.
let w = Watchdog::enabled_with_delays(
"the commit generation command",
Some("sh -c 'claude -p'"),
Duration::from_millis(10),
Duration::from_secs(3600),
);
let timeout = Duration::from_secs(5);
let start = Instant::now();
while start.elapsed() < timeout {
if w.shared.rendered_rows.load(Ordering::Relaxed) > 0 {
break;
}
std::thread::sleep(Duration::from_millis(10));
}
assert!(w.shared.rendered_rows.load(Ordering::Relaxed) > 0);
assert!(!w.shared.escalated.load(Ordering::Relaxed));
w.finish();
}
#[test]
fn test_watchdog_fast_command_leaves_no_trace() {
// A command that finishes before the startup delay must never draw a
// block — so Drop has nothing to clear and leaves no escape in
// output. The startup delay sits far in the future so the assertion
// can't race the ticker into rendering under load; finish() wakes the
// parked thread immediately regardless.
let w = Watchdog::enabled_with_delays(
"the commit generation command",
None,
Duration::from_secs(3600),
WATCHDOG_ESCALATE_DELAY,
);
assert_eq!(w.shared.rendered_rows.load(Ordering::Relaxed), 0);
w.finish();
}
#[test]
fn test_watchdog_escalates_and_grows_the_block() {
// Short startup + escalation delays so the second tier fires fast; the
// revealed gutter makes the block more than one row. The escalation
// and render both happen on the background ticker thread, so poll for
// its work rather than sleeping a fixed window: a loaded runner can
// starve the ticker past any fixed deadline, but the condition itself
// is what we're verifying. Generous timeout, fast poll — fast when
// healthy, reliable under load.
let w = Watchdog::enabled_with_delays(
"the commit generation command",
Some("sh -c 'claude -p'"),
Duration::from_millis(10),
Duration::from_millis(30),
);
let timeout = Duration::from_secs(5);
let start = Instant::now();
while start.elapsed() < timeout {
if w.shared.escalated.load(Ordering::Relaxed)
&& w.shared.rendered_rows.load(Ordering::Relaxed) >= 2
{
break;
}
std::thread::sleep(Duration::from_millis(10));
}
assert!(w.shared.escalated.load(Ordering::Relaxed));
assert!(w.shared.rendered_rows.load(Ordering::Relaxed) >= 2);
w.finish();
}
#[test]
fn test_watchdog_no_escalation_without_command() {
// No command → the gutter never appears, however long it runs, so the
// block stays a single status row. Poll for that first render rather
// than sleeping a fixed window the ticker could be starved past under
// load; escalation is gated on `command.is_some()`, so `!escalated`
// holds at any instant no matter how long the loop runs.
let w = Watchdog::enabled_with_delays(
"the commit generation command",
None,
Duration::from_millis(10),
Duration::from_millis(30),
);
let timeout = Duration::from_secs(5);
let start = Instant::now();
while start.elapsed() < timeout {
if w.shared.rendered_rows.load(Ordering::Relaxed) >= 1 {
break;
}
std::thread::sleep(Duration::from_millis(10));
}
assert_eq!(w.shared.rendered_rows.load(Ordering::Relaxed), 1);
assert!(!w.shared.escalated.load(Ordering::Relaxed));
w.finish();
}
}
}
#[cfg(not(feature = "cli"))]
mod imp {
use std::sync::atomic::{AtomicU64, AtomicUsize, Ordering};
/// Spinner-less stub when the `cli` feature is off. The spinner depends on
/// `crossterm`, which is only pulled in by `cli`; library consumers that
/// disable default features get this thread-free, render-free type. The
/// counters still accumulate so [`Progress::totals`] reports the same
/// numbers in both builds.
pub struct Progress {
files: AtomicUsize,
bytes: AtomicU64,
reflinked: AtomicUsize,
written: AtomicUsize,
}
impl Progress {
pub fn start(_verb: &'static str) -> Self {
Self::disabled()
}
pub fn disabled() -> Self {
Self {
files: AtomicUsize::new(0),
bytes: AtomicU64::new(0),
reflinked: AtomicUsize::new(0),
written: AtomicUsize::new(0),
}
}
pub fn record(&self, bytes: u64, data: super::DataCopy) {
self.files.fetch_add(1, Ordering::Relaxed);
self.bytes.fetch_add(bytes, Ordering::Relaxed);
let counter = match data {
super::DataCopy::Reflinked => &self.reflinked,
super::DataCopy::Written => &self.written,
super::DataCopy::Neither => return,
};
counter.fetch_add(1, Ordering::Relaxed);
}
pub fn totals(&self) -> (usize, u64) {
(
self.files.load(Ordering::Relaxed),
self.bytes.load(Ordering::Relaxed),
)
}
pub fn copy_split(&self) -> (usize, usize) {
(
self.reflinked.load(Ordering::Relaxed),
self.written.load(Ordering::Relaxed),
)
}
pub fn finish(self) {}
}
/// Spinner-less stub when the `cli` feature is off — mirrors [`Progress`]'s
/// stub. The watchdog has no counters to keep, so it carries no state.
pub struct Watchdog;
impl Watchdog {
pub fn start(_waiting_for: &str, _command: Option<&str>) -> Self {
Self
}
pub fn finish(self) {}
}
}
fn format_count(n: usize) -> String {
let s = n.to_string();
let bytes = s.as_bytes();
let mut out = String::with_capacity(s.len() + s.len() / 3);
for (i, b) in bytes.iter().enumerate() {
if i > 0 && (bytes.len() - i).is_multiple_of(3) {
out.push(',');
}
out.push(*b as char);
}
out
}
/// Format a byte count using IEC binary prefixes (KiB, MiB, GiB, TiB).
///
/// The divisor is 1024; SI-prefix "MB" would imply 10^6 and doesn't match what
/// we compute. Used by both the spinner line and the post-operation summary.
pub fn format_bytes(n: u64) -> String {
const UNITS: &[&str] = &["B", "KiB", "MiB", "GiB", "TiB"];
let mut size = n as f64;
let mut unit = 0;
while size >= 1024.0 && unit < UNITS.len() - 1 {
size /= 1024.0;
unit += 1;
}
if unit == 0 {
format!("{n} {}", UNITS[unit])
} else {
format!("{size:.1} {}", UNITS[unit])
}
}
/// Format `(N files · X MiB)` as a gray stats parenthetical, matching the
/// spinner's units.
///
/// Returns an empty string when `files == 0` so callers can unconditionally
/// concatenate it to a success message without producing `(0 files · 0 B)`
/// when nothing was processed.
pub fn format_stats_paren(files: usize, bytes: u64) -> String {
if files == 0 {
return String::new();
}
let word = if files == 1 { "file" } else { "files" };
// Split the closing paren into a separate cformat so the optimizer doesn't
// collapse the two color-print spans (matches the squash-progress pattern
// in commands/step/squash.rs).
let close = cformat!("<bright-black>)</>");
cformat!(
" <bright-black>({} {word} · {}</>{close}",
format_count(files),
format_bytes(bytes),
)
}
/// Format the reflink split as a gray parenthetical, for a copy summary that
/// has already reported its file and byte counts.
///
/// Takes the two halves of [`Progress::copy_split`]. Only the reflinked wording
/// carries a gloss, since that is the term a reader won't know; the contrast
/// then tells them what a full copy cost, without repeating the byte count the
/// summary just gave.
///
/// A mixed result is real, since a tree can span two filesystems, so it reports
/// the count rather than collapsing to whichever side is larger.
///
/// Returns an empty string when neither half has anything in it, so a caller
/// can concatenate it unconditionally. That covers an empty run and one that
/// only created symlinks, neither of which has a split to report.
pub fn format_reflink_paren(reflinked: usize, written: usize) -> String {
match (reflinked, written) {
(0, 0) => String::new(),
(_, 0) => cformat!(" <bright-black>(reflinked, no extra disk)</>"),
(0, _) => cformat!(" <bright-black>(full copy)</>"),
_ => cformat!(
" <bright-black>({} of {} reflinked)</>",
format_count(reflinked),
format_count(reflinked + written),
),
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_format_count() {
assert_eq!(format_count(0), "0");
assert_eq!(format_count(42), "42");
assert_eq!(format_count(999), "999");
assert_eq!(format_count(1_000), "1,000");
assert_eq!(format_count(12_345), "12,345");
assert_eq!(format_count(1_234_567), "1,234,567");
}
#[test]
fn test_format_bytes() {
assert_eq!(format_bytes(0), "0 B");
assert_eq!(format_bytes(512), "512 B");
assert_eq!(format_bytes(1024), "1.0 KiB");
assert_eq!(format_bytes(1_536), "1.5 KiB");
assert_eq!(format_bytes(1_048_576), "1.0 MiB");
assert_eq!(format_bytes(1_610_612_736), "1.5 GiB");
}
#[test]
fn test_format_stats_paren_empty_is_blank() {
assert_eq!(format_stats_paren(0, 0), "");
}
#[test]
fn test_format_stats_paren_singular() {
let s = format_stats_paren(1, 42);
assert!(s.contains("1 file"));
assert!(s.contains("42 B"));
}
#[test]
fn test_format_stats_paren_plural() {
let s = format_stats_paren(2_500, 5 * 1024 * 1024);
assert!(s.contains("2,500 files"));
assert!(s.contains("5.0 MiB"));
}
// Which half is zero picks the wording, and the mixed case is the one no
// integration test can stage — it needs two filesystems under one tree.
#[test]
fn test_format_reflink_paren_wording() {
assert_eq!(format_reflink_paren(0, 0), "");
assert!(format_reflink_paren(3, 0).contains("(reflinked, no extra disk)"));
assert!(format_reflink_paren(0, 3).contains("(full copy)"));
assert!(format_reflink_paren(2, 1).contains("(2 of 3 reflinked)"));
assert!(format_reflink_paren(1_500, 500).contains("(1,500 of 2,000 reflinked)"));
}
// Not cfg-gated: covers the disabled-state counting contract in both the
// `cli` implementation and the no-`cli` stub.
#[test]
fn test_disabled_still_counts() {
let p = Progress::disabled();
p.record(1_000_000, DataCopy::Reflinked);
p.record(2_000_000, DataCopy::Written);
assert_eq!(p.totals(), (2, 3_000_000));
p.finish();
}
// The split counts only what moved extents, so `Neither` lands in the
// file/byte totals and in neither half — the property that keeps a tree of
// symlinks from reading as a partial reflink failure.
#[test]
fn test_copy_split_excludes_extentless_records() {
let p = Progress::disabled();
p.record(10, DataCopy::Reflinked);
p.record(20, DataCopy::Reflinked);
p.record(30, DataCopy::Written);
p.record(40, DataCopy::Neither);
assert_eq!(p.totals(), (4, 100));
assert_eq!(p.copy_split(), (2, 1));
p.finish();
}
}