openlatch-client 0.6.1

//! Terminal UI for guided commands: a clack-style rail of stages, a
//! two-option select and a result card, over one process-scoped sink.
//!
//! ```text
//! ┌  Setting up this machine
//! │
//! ◇  Checked this machine · found Cline
//! │
//! ◆  Usage data
//! │  Share anonymous usage data to help improve OpenLatch?
//! │  › ● Yes, share    ○ No thanks        ← → then Enter
//! │
//! └  Done.
//! ```
//!
//! ## One sink, installed by a guard
//!
//! A command opens the rail with [`install`] and holds the returned
//! [`RailGuard`] for as long as the rail should own stderr. While it is held,
//! [`OutputConfig`]'s helpers route through it — `print_step`, `print_substep`
//! and `print_info` become [`detail`] (logged, shown only with `--verbose`),
//! `print_note` becomes [`note`], and `print_error` closes the running stage as
//! failed — so the dozens of helpers that already print through
//! `OutputConfig` join the rail without a signature change. Dropping the guard
//! restores today's output. Same process-scoped pattern as the
//! `report::verdict` latch.
//!
//! With no rail installed every function here is a no-op, and every
//! `OutputConfig` helper prints exactly what it printed before this module
//! existed.
//!
//! ## Errors print once
//!
//! [`OutputConfig::print_error`] records what it printed ([`mark_error_reported`]);
//! `main` prints a returned error only when it was not already reported
//! ([`error_reported`]). A command that shows its own error — inside the rail,
//! or ahead of hints that must follow it — no longer has it printed a second
//! time on the way out.

pub mod card;
pub mod log;
pub mod paint;
pub mod rail;
pub mod select;
pub mod term;

use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::Mutex;

pub use card::{result_line, result_line_token, Card, Row, Section, Update, Verdict};
pub use paint::Tone;
pub use rail::{Out, Rail};
pub use select::{Select, SelectOutcome};
pub use term::{Caps, Mode};

use crate::cli::output::OutputConfig;
use crate::error::OlError;

static RAIL: Mutex<Option<Rail>> = Mutex::new(None);
/// Fast path for the `OutputConfig` helpers: set exactly while `RAIL` is `Some`.
static ACTIVE: AtomicBool = AtomicBool::new(false);

fn slot() -> std::sync::MutexGuard<'static, Option<Rail>> {
    RAIL.lock()
        .unwrap_or_else(std::sync::PoisonError::into_inner)
}

/// Keeps the rail installed; dropping it uninstalls the rail (stopping any
/// spinner) and restores plain `OutputConfig` output.
#[must_use = "the rail is uninstalled as soon as the guard is dropped"]
pub struct RailGuard {
    _private: (),
}

impl Drop for RailGuard {
    fn drop(&mut self) {
        let rail = {
            let mut slot = slot();
            ACTIVE.store(false, Ordering::SeqCst);
            slot.take()
        };
        drop(rail);
    }
}

/// Open a rail of `total` stages for `command` on the real stderr, with its
/// transcript at `<openlatch dir>/logs/<command>-YYYY-MM-DD.log`.
///
/// `None` — and nothing changes — under `--json` or `--quiet`, or when a rail
/// is already installed.
pub fn install(output: &OutputConfig, command: &str, total: usize) -> Option<RailGuard> {
    let caps = Caps::detect(output)?;
    let log = log::Transcript::open(command);
    install_rail(Rail::new(
        caps,
        Out::Term(console::Term::stderr()),
        log,
        total,
    ))
}

/// Install a prepared rail (e.g. [`Rail::buffer`] in a test). `None` when a
/// rail is already installed.
pub fn install_rail(rail: Rail) -> Option<RailGuard> {
    let mut slot = slot();
    if slot.is_some() {
        return None;
    }
    *slot = Some(rail);
    ACTIVE.store(true, Ordering::SeqCst);
    Some(RailGuard { _private: () })
}

/// Whether a rail is installed.
pub fn is_active() -> bool {
    ACTIVE.load(Ordering::SeqCst)
}

/// Run `f` on the installed rail; `None` when there is none.
fn with<R>(f: impl FnOnce(&mut Rail) -> R) -> Option<R> {
    if !is_active() {
        return None;
    }
    slot().as_mut().map(f)
}

/// `┌  <title>` — opens the rail.
pub fn intro(title: &str) {
    with(|r| r.intro(title));
}

/// Open the next stage: `running` while it works, `done` on its result line.
pub fn stage(running: &str, done: &str) {
    with(|r| r.stage(running, done));
}

/// Update what the running stage's spinner says.
pub fn progress(text: &str) {
    with(|r| r.progress(text));
}

/// Close the running stage: `◇  <done> · <result>`.
pub fn done(result: &str) {
    with(|r| r.done(result));
}

/// Close the running stage with only the result in `tone` (see
/// [`Rail::done_toned`]).
pub fn done_toned(result: &str, tone: Tone) {
    with(|r| r.done_toned(result, tone));
}

/// Show how far the running stage has got (see [`Rail::meter`]).
pub fn meter(frac: Option<f64>, tail: &str) {
    with(|r| r.meter(frac, tail));
}

/// Write the running stage's `[n/N] <running>…` heading now, in plain mode,
/// for a long stage that would otherwise leave a log looking stuck (see
/// [`Rail::announce`]).
pub fn announce() {
    with(|r| r.announce());
}

/// Close the running stage as needing the user: `!  <done> · <result>`.
pub fn attention(result: &str) {
    with(|r| r.attention(result));
}

/// An always-visible line under the gutter.
pub fn note(text: &str) {
    with(|r| r.note(text));
}

/// [`stage`], naming what the stage is for the line a failure leaves
/// (`Start OpenLatch failed`).
pub fn stage_named(name: &str, running: &str, done: &str) {
    with(|r| r.stage_named(name, running, done));
}

/// A dim line under the running stage that goes when it closes (see
/// [`Rail::hint`]).
pub fn hint(text: &str) {
    with(|r| r.hint(text));
}

/// A [`hint`] ending in a URL that is never wrapped: `Didn't open? https://…`.
pub fn link(lead: &str, url: &str) {
    with(|r| r.link(lead, url));
}

/// Close the running stage as where the run stops, without an error (see
/// [`Rail::halt`]).
pub fn halt(result: &str) {
    with(|r| r.halt(result));
}

/// Close the running stage as failed without an error of its own (see
/// [`Rail::failed`]).
pub fn failed(result: &str) {
    with(|r| r.failed(result));
}

/// Change the running stage's closing label (see [`Rail::relabel`]).
pub fn relabel(done: &str) {
    with(|r| r.relabel(done));
}

/// The gutter a line under the running stage starts with (`│  `), for output
/// the rail does not draw itself — a third-party prompt. `None` with no rail.
pub fn gutter() -> Option<String> {
    with(|r| r.gutter())
}

/// A line that is logged, and shown only with `--verbose`.
pub fn detail(text: &str) {
    with(|r| r.detail(text));
}

/// Close the running stage as failed with the error block under it, and mark
/// the error reported. `false` when no rail is installed.
pub fn fail(error: &OlError) -> bool {
    let shown = with(|r| r.fail(error)).is_some();
    if shown {
        mark_error_reported(error);
    }
    shown
}

/// `└  <text>` — closes the rail.
pub fn outro(text: &str) {
    with(|r| r.outro(text));
}

/// Draw the result card.
pub fn card(card: &Card) {
    with(|r| r.card(card));
}

/// Draw the result card with amber warning lines heading its footer.
pub fn card_with_warnings(card: &Card, warnings: &[String]) {
    with(|r| r.card_with_warnings(card, warnings));
}

/// Write the `result=` line (plain mode only; always logged).
pub fn result(verdict: Verdict, exit_code: i32, fields: &[(&str, &str)]) {
    with(|r| r.result_line(verdict, exit_code, fields));
}

/// [`result`] with a command's own token (`updated`, `up_to_date`, …).
pub fn result_token(token: &str, exit_code: i32, fields: &[(&str, &str)]) {
    with(|r| r.result_line_token(token, exit_code, fields));
}

/// Ask a two-option question. `None` when no rail is installed.
pub fn select(question: &Select<'_>) -> Option<SelectOutcome> {
    with(|r| r.select(question))
}

/// Run `f` with the spinner out of the way, for output the rail does not own.
/// Runs `f` directly when no rail is installed.
pub fn suspend<R>(f: impl FnOnce() -> R) -> R {
    if !is_active() {
        return f();
    }
    let slot = slot();
    match slot.as_ref() {
        Some(rail) => rail.suspend(f),
        None => f(),
    }
}

/// The installed rail's capabilities.
pub fn caps() -> Option<Caps> {
    with(|r| *r.caps())
}

/// Where the installed rail's transcript is written.
pub fn log_path() -> Option<std::path::PathBuf> {
    with(|r| r.log_path().map(std::path::Path::to_path_buf)).flatten()
}

/// Move a transcript this run created out of the state directory, into the OS
/// temp directory, removing the directories opening it created (see
/// [`log::Transcript::take_back`]). For a failure that must leave the host as
/// it was found; the card then points at the moved file.
pub fn take_back_log() {
    with(|r| r.take_back_log(&std::env::temp_dir()));
}

/// Tests that install the process-wide rail run one at a time.
#[cfg(test)]
pub(crate) static INSTALL_LOCK: Mutex<()> = Mutex::new(());

static REPORTED: Mutex<Option<(&'static str, String)>> = Mutex::new(None);

/// Record that `error` has been shown to the operator.
pub fn mark_error_reported(error: &OlError) {
    *REPORTED
        .lock()
        .unwrap_or_else(std::sync::PoisonError::into_inner) =
        Some((error.code, error.message.clone()));
}

/// Whether this exact error (code and message) was already shown. `main` asks
/// before printing the error a command returned.
pub fn error_reported(error: &OlError) -> bool {
    REPORTED
        .lock()
        .unwrap_or_else(std::sync::PoisonError::into_inner)
        .as_ref()
        .is_some_and(|(code, message)| *code == error.code && *message == error.message)
}

/// Draw backtick-marked spans (`` `openlatch doctor` ``) in the accent colour,
/// URLs underlined too, dropping the backticks. With colour off the backticks
/// are simply removed.
pub fn style(text: &str, color_on: bool) -> String {
    style_over(text, color_on, |t, _| t.to_string())
}

/// [`style`], drawing the text between the marked spans with `base` (the card
/// footer's dim words around its commands).
pub fn style_over(text: &str, color_on: bool, base: fn(&str, bool) -> String) -> String {
    let mut out = String::with_capacity(text.len());
    for (i, part) in text.split('`').enumerate() {
        if i % 2 == 1 && !part.is_empty() {
            if part.starts_with("http://") || part.starts_with("https://") {
                out.push_str(&paint::link(part, color_on));
            } else {
                out.push_str(&paint::accent(part, color_on));
            }
        } else {
            out.push_str(&base(part, color_on));
        }
    }
    out
}

/// Swap the Unicode punctuation callers write (`·`, `…`, `—`, `→`) and the
/// meter's bar (`━`, `─`) for the ASCII set when the rail draws ASCII, so a
/// legacy console or a log file never shows a stray non-ASCII byte.
pub fn fit_glyphs(text: &str, caps: &Caps) -> String {
    if caps.unicode {
        return text.to_string();
    }
    text.replace('·', "-")
        .replace('…', "...")
        .replace('—', "-")
        .replace('›', ">")
        .replace('→', "->")
        .replace('━', "#")
        .replace('─', "-")
}

/// Visible width of marked-up text (backticks are markup, not columns).
fn visible_width(text: &str) -> usize {
    console::measure_text_width(&text.replace('`', ""))
}

/// Word-wrap marked-up `text` to `width` visible columns. A word longer than
/// the width is split; a backtick span broken across lines is closed and
/// reopened so each line styles on its own.
pub fn wrap(text: &str, width: usize) -> Vec<String> {
    let width = width.max(1);
    let mut lines = Vec::new();
    let mut line = String::new();
    for word in text.split_whitespace() {
        for piece in split_long(word, width) {
            let need = if line.is_empty() {
                visible_width(&piece)
            } else {
                visible_width(&line) + 1 + visible_width(&piece)
            };
            if need > width && !line.is_empty() {
                lines.push(std::mem::take(&mut line));
            }
            if !line.is_empty() {
                line.push(' ');
            }
            line.push_str(&piece);
        }
    }
    if !line.is_empty() || lines.is_empty() {
        lines.push(line);
    }
    // Rebalance backtick spans that a line break cut in two.
    let mut open = false;
    for line in &mut lines {
        if open {
            line.insert(0, '`');
        }
        if line.matches('`').count() % 2 == 1 {
            line.push('`');
            open = true;
        } else {
            open = false;
        }
    }
    lines
}

/// Split a word wider than `width` into chunks of at most `width` columns.
fn split_long(word: &str, width: usize) -> Vec<String> {
    if visible_width(word) <= width {
        return vec![word.to_string()];
    }
    let mut out = Vec::new();
    let mut chunk = String::new();
    for ch in word.chars() {
        if ch != '`' && visible_width(&chunk) >= width {
            out.push(std::mem::take(&mut chunk));
        }
        chunk.push(ch);
    }
    if !chunk.is_empty() {
        out.push(chunk);
    }
    out
}

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

    #[test]
    fn test_style_marks_commands() {
        assert_eq!(
            style("run `openlatch init` now", false),
            "run openlatch init now"
        );
        assert_eq!(
            style("run `openlatch init`", true),
            "run \x1b[36mopenlatch init\x1b[0m"
        );
        assert_eq!(
            style("see `https://app.openlatch.ai`", true),
            "see \x1b[4;36mhttps://app.openlatch.ai\x1b[0m"
        );
        assert_eq!(
            style_over("Check `openlatch status`", true, paint::dim),
            "\x1b[90mCheck \x1b[0m\x1b[36mopenlatch status\x1b[0m"
        );
        assert_eq!(style("no marks", true), "no marks");
    }

    #[test]
    fn test_fit_glyphs() {
        let ascii = Caps::new(Mode::Append, false, false, 80);
        assert_eq!(
            fit_glyphs("━━━─── 50% · 0.5.7 → 0.5.8…", &ascii),
            "###--- 50% - 0.5.7 -> 0.5.8..."
        );
        let unicode = Caps::new(Mode::Live, false, false, 80);
        assert_eq!(fit_glyphs("━━━───", &unicode), "━━━───");
    }

    #[test]
    fn test_wrap() {
        assert_eq!(wrap("", 10), vec![""]);
        assert_eq!(wrap("one two three", 7), vec!["one two", "three"]);
        assert_eq!(wrap("abcdefghij", 4), vec!["abcd", "efgh", "ij"]);
        // Backticks do not count, and a span cut by a break is rebalanced.
        assert_eq!(
            wrap("run `openlatch system telemetry enable` later", 20),
            vec!["run `openlatch system`", "`telemetry enable`", "later"]
        );
        for line in wrap(&"lorem ipsum ".repeat(30), 50) {
            assert!(visible_width(&line) <= 50, "{line}");
        }
    }

    #[test]
    fn test_error_fingerprint() {
        let e = OlError::new("OL-9901", "fingerprint test");
        assert!(!error_reported(&e));
        mark_error_reported(&e);
        assert!(error_reported(&e));
        assert!(!error_reported(&OlError::new("OL-9901", "another message")));
        assert!(!error_reported(&OlError::new(
            "OL-9902",
            "fingerprint test"
        )));
    }

    #[test]
    fn test_guard_installs_and_uninstalls() {
        let _l = INSTALL_LOCK
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        let (rail, screen) = Rail::buffer(Caps::new(Mode::Plain, false, false, 80), 2);
        {
            let _guard = install_rail(rail).expect("installs");
            assert!(is_active());
            let (second, _) = Rail::buffer(Caps::new(Mode::Plain, false, false, 80), 1);
            assert!(install_rail(second).is_none(), "one rail at a time");
            intro("Setting up");
            stage("Checking", "Checked");
            done("ok");
            assert!(fail(&OlError::new("OL-9903", "boom")));
            assert!(error_reported(&OlError::new("OL-9903", "boom")));
        }
        assert!(!is_active());
        assert!(caps().is_none());
        // Uninstalled: the free functions are no-ops again.
        note("not drawn");
        assert!(!fail(&OlError::new("OL-9904", "not drawn")));
        let lines = screen.lock().unwrap().clone();
        assert_eq!(
            lines,
            vec!["Setting up", "[1/2] Checked - ok", "x boom (OL-9903)"]
        );
    }
}