From e66a43c8a98110edd732b6f65278601bc253733f Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sat, 22 Aug 2026 19:41:50 +0800 Subject: [PATCH 001/147] rust: the shared core, and ports as the first widget ported A worktree and a branch to try the thing in. A cargo workspace under rust/, with toys-core holding what common.py holds - the terminal, the keyboard, seg/pad/draw/title/pack_hints - and one binary per widget. toys-core is libc and nothing else. The widgets will need crates for JSON, HTTP and timezones when their turn comes, but the terminal is an ioctl and a termios struct, and both are already in libc. ports is first because it exercises the parts everything else needs: /proc parsing, a subprocess, a table that drops columns as the pane narrows, and a poll thread behind a mutex. Side by side against the Python at 92x24, both report 24 listening and 22 of 24 drawn lines are byte-identical. Two faults found by comparing rather than by reading. The IPv6 decoder had the bytes of each word the wrong way round, which turned ::1 into ::100:0 and split every dual-stack row in two - 27 listening against Python's 24. And the kind table was missing the python and node fallbacks the Python keeps last, so an interpreter showed as its own basename. The test vector for the first of those was itself wrong, and made a correct decoder look broken; it is now a real address out of this machine's /proc/net/tcp6, checked against what ss prints for that socket. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/.gitignore | 1 + rust/Cargo.lock | 24 + rust/Cargo.toml | 18 + rust/core/Cargo.toml | 10 + rust/core/src/lib.rs | 407 +++++++++++++ rust/widgets/Cargo.toml | 13 + rust/widgets/src/bin/ports.rs | 846 ++++++++++++++++++++++++++++ rust/widgets/src/bin/ports_help.txt | 21 + 8 files changed, 1340 insertions(+) create mode 100644 rust/.gitignore create mode 100644 rust/Cargo.lock create mode 100644 rust/Cargo.toml create mode 100644 rust/core/Cargo.toml create mode 100644 rust/core/src/lib.rs create mode 100644 rust/widgets/Cargo.toml create mode 100644 rust/widgets/src/bin/ports.rs create mode 100644 rust/widgets/src/bin/ports_help.txt diff --git a/rust/.gitignore b/rust/.gitignore new file mode 100644 index 0000000..2f7896d --- /dev/null +++ b/rust/.gitignore @@ -0,0 +1 @@ +target/ diff --git a/rust/Cargo.lock b/rust/Cargo.lock new file mode 100644 index 0000000..6c1f615 --- /dev/null +++ b/rust/Cargo.lock @@ -0,0 +1,24 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +version = 4 + +[[package]] +name = "libc" +version = "0.2.189" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2" + +[[package]] +name = "toys-core" +version = "0.1.0" +dependencies = [ + "libc", +] + +[[package]] +name = "toys-widgets" +version = "0.1.0" +dependencies = [ + "libc", + "toys-core", +] diff --git a/rust/Cargo.toml b/rust/Cargo.toml new file mode 100644 index 0000000..bb63354 --- /dev/null +++ b/rust/Cargo.toml @@ -0,0 +1,18 @@ +[workspace] +resolver = "2" +members = ["core", "widgets"] + +[workspace.package] +version = "0.1.0" +edition = "2021" +license = "AGPL-3.0-or-later" + +# Thirteen of these run at once, so size is worth more here than the last +# few percent of speed: optimise for it, strip symbols, and let LTO drop +# everything nothing reaches. +[profile.release] +opt-level = "z" +lto = true +codegen-units = 1 +panic = "abort" +strip = true diff --git a/rust/core/Cargo.toml b/rust/core/Cargo.toml new file mode 100644 index 0000000..9b537ae --- /dev/null +++ b/rust/core/Cargo.toml @@ -0,0 +1,10 @@ +[package] +name = "toys-core" +version.workspace = true +edition.workspace = true +license.workspace = true + +# The terminal is an ioctl and a termios struct away; both come from libc, +# and nothing else here needs a crate at all. +[dependencies] +libc = "0.2" diff --git a/rust/core/src/lib.rs b/rust/core/src/lib.rs new file mode 100644 index 0000000..2c7af3a --- /dev/null +++ b/rust/core/src/lib.rs @@ -0,0 +1,407 @@ +// terminal-toys - small dependency-free terminal widgets +// Copyright (C) 2026 William Li +// +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU Affero General Public License as published +// by the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU Affero General Public License for more details. +// +// You should have received a copy of the GNU Affero General Public License +// along with this program. If not, see . + +//! What every widget shares: the terminal, the keyboard, and the drawing. +//! +//! A port of `common.py`, kept deliberately close to it. The widgets are +//! being translated one at a time and the two versions have to sit side by +//! side and agree on screen, so where a choice existed this keeps the +//! Python behaviour rather than the more idiomatic Rust one. + +use std::io::{Read, Write}; +use std::os::fd::AsRawFd; + +pub const HIDE: &str = "\x1b[?25l"; +pub const SHOW: &str = "\x1b[?25h"; +pub const HOME: &str = "\x1b[H"; +pub const CLEAR: &str = "\x1b[2J"; +pub const EL: &str = "\x1b[K"; +pub const RST: &str = "\x1b[0m"; +pub const NOBG: &str = "\x1b[49m"; + +/// A foreground colour, as a truecolor escape. +pub fn rgb(r: u8, g: u8, b: u8) -> String { + format!("\x1b[38;2;{};{};{}m", r, g, b) +} + +/// A background colour. Needs an explicit reset afterwards, or it bleeds +/// along the rest of the row - the same trap as in the Python. +pub fn bg(r: u8, g: u8, b: u8) -> String { + format!("\x1b[48;2;{};{};{}m", r, g, b) +} + +/// Truncate or pad a plain string to exactly `n` cells. +pub fn pad(s: &str, n: usize) -> String { + let count = s.chars().count(); + if count > n { + s.chars().take(n).collect() + } else { + let mut out = String::from(s); + out.extend(std::iter::repeat(' ').take(n - count)); + out + } +} + +/// Join coloured segments, hard-clipped to `width` printable cells. +/// +/// The colour of each segment is a prefix that costs nothing on screen, so +/// only the text counts toward the width. Every widget's layout arithmetic +/// depends on that, which is why escapes have to live in the colour half of +/// the pair and never in the text. +pub fn seg(parts: &[(&str, String)], width: usize) -> String { + let mut out = String::new(); + let mut n = 0usize; + for (colour, text) in parts { + if n >= width { + break; + } + let room = width - n; + let count = text.chars().count(); + let cut: String = if count > room { + text.chars().take(room).collect() + } else { + text.clone() + }; + out.push_str(colour); + out.push_str(&cut); + n += cut.chars().count(); + } + out +} + +/// The rule across the top of every widget. +pub fn title(text: &str, w: usize, colour: &str) -> String { + let t = format!(" {} ", text.to_uppercase()); + let left = "╺━"; + let used = t.chars().count() + left.chars().count() + 1; + let fill = "━".repeat(w.saturating_sub(used)); + format!( + "{}{}{}{}{}{}{}{}╸{}", + colour, + left, + RST, + rgb(220, 255, 240), + t, + RST, + colour, + fill, + RST + ) +} + +/// The terminal's size, or a sane pair if it will not say. +pub fn size() -> (usize, usize) { + let mut ws: libc::winsize = unsafe { std::mem::zeroed() }; + let ok = unsafe { libc::ioctl(libc::STDOUT_FILENO, libc::TIOCGWINSZ, &mut ws) }; + if ok == 0 && ws.ws_col > 0 && ws.ws_row > 0 { + ( + std::cmp::max(8, ws.ws_col as usize), + std::cmp::max(4, ws.ws_row as usize), + ) + } else { + (80, 24) + } +} + +pub fn out(text: &str) { + let mut stdout = std::io::stdout(); + let _ = stdout.write_all(text.as_bytes()); +} + +pub fn flush() { + let _ = std::io::stdout().flush(); +} + +/// Paint `rows` from the top-left, one full frame. +/// +/// Every row is followed by a reset and an erase-to-end, so a short row +/// cannot leave the tail of the previous frame behind it. +pub fn draw(rows: &[String], _w: usize, h: usize) { + let mut buf = String::from(HOME); + for i in 0..h { + let empty = String::new(); + let line = rows.get(i).unwrap_or(&empty); + buf.push_str(line); + buf.push_str(RST); + buf.push_str(EL); + if i + 1 != h { + buf.push_str("\r\n"); + } + } + out(&buf); + flush(); +} + +/// Hide the cursor and clear, and put it all back on the way out. +pub fn setup() { + unsafe { + let handler = handle_signal as *const () as libc::sighandler_t; + libc::signal(libc::SIGINT, handler); + libc::signal(libc::SIGTERM, handler); + } + out(&format!("{}{}{}", HIDE, CLEAR, HOME)); + flush(); +} + +extern "C" fn handle_signal(_sig: libc::c_int) { + out(&format!("{}{}{}{}", SHOW, RST, CLEAR, HOME)); + flush(); + std::process::exit(0); +} + +/// Put the terminal back the way it was found. +pub fn restore_screen() { + out(&format!("{}{}{}{}", SHOW, RST, CLEAR, HOME)); + flush(); +} + +/// Fit hint groups onto as few lines as possible without splitting one. +/// +/// A hint that gets cut in half teaches a key that does not exist, so the +/// line wraps instead of truncating - the rule the whole repo follows. +pub fn pack_hints(hints: &[Vec<(&str, String)>], width: usize, sep: &str) -> Vec { + let mut lines: Vec = Vec::new(); + let mut current: Vec = Vec::new(); + let mut used = 0usize; + for hint in hints { + let plain: usize = hint.iter().map(|(_, t)| t.chars().count()).sum(); + let extra = if current.is_empty() { + plain + } else { + plain + sep.chars().count() + }; + if !current.is_empty() && used + extra > width { + lines.push(current.join(sep)); + current = Vec::new(); + used = 0; + } + let piece: String = hint + .iter() + .map(|(c, t)| format!("{}{}", c, t)) + .collect::>() + .join(""); + if current.is_empty() { + used = plain; + } else { + used += plain + sep.chars().count(); + } + current.push(piece); + } + if !current.is_empty() { + lines.push(current.join(sep)); + } + lines +} + +/// Non-blocking key input, decoding the sequences arrows arrive as. +/// +/// Returns names for special keys and the bare character otherwise, and +/// restores the terminal's settings when dropped - including when the +/// widget exits by panicking. +pub struct Keyboard { + fd: i32, + saved: Option, + buf: Vec, +} + +impl Keyboard { + pub fn new() -> Keyboard { + let fd = std::io::stdin().as_raw_fd(); + let mut saved: libc::termios = unsafe { std::mem::zeroed() }; + let is_tty = unsafe { libc::isatty(fd) } == 1; + let saved = if is_tty && unsafe { libc::tcgetattr(fd, &mut saved) } == 0 { + let mut raw = saved; + // cbreak, not full raw: characters arrive unbuffered and + // unechoed, while the terminal keeps translating signals. + raw.c_lflag &= !(libc::ICANON | libc::ECHO); + raw.c_cc[libc::VMIN] = 0; + raw.c_cc[libc::VTIME] = 0; + unsafe { libc::tcsetattr(fd, libc::TCSANOW, &raw) }; + Some(saved) + } else { + None + }; + Keyboard { + fd, + saved, + buf: Vec::new(), + } + } + + pub fn restore(&mut self) { + if let Some(saved) = self.saved.take() { + unsafe { libc::tcsetattr(self.fd, libc::TCSADRAIN, &saved) }; + } + } + + /// Every key waiting, decoded. Empty when nothing has been pressed. + pub fn poll(&mut self) -> Vec { + if self.saved.is_none() { + return Vec::new(); + } + let mut chunk = [0u8; 64]; + loop { + let flags = unsafe { libc::fcntl(self.fd, libc::F_GETFL) }; + unsafe { libc::fcntl(self.fd, libc::F_SETFL, flags | libc::O_NONBLOCK) }; + let n = std::io::stdin().read(&mut chunk); + unsafe { libc::fcntl(self.fd, libc::F_SETFL, flags) }; + match n { + Ok(0) | Err(_) => break, + Ok(n) => self.buf.extend_from_slice(&chunk[..n]), + } + } + let text = String::from_utf8_lossy(&self.buf).to_string(); + self.buf.clear(); + decode(&text) + } +} + +impl Drop for Keyboard { + fn drop(&mut self) { + self.restore(); + } +} + +/// Turn a run of input bytes into key names. +fn decode(text: &str) -> Vec { + const SEQUENCES: &[(&str, &str)] = &[ + ("\x1b[A", "up"), + ("\x1b[B", "down"), + ("\x1b[C", "right"), + ("\x1b[D", "left"), + ("\x1bOA", "up"), + ("\x1bOB", "down"), + ("\x1bOC", "right"), + ("\x1bOD", "left"), + ("\x1b[5~", "pgup"), + ("\x1b[6~", "pgdn"), + ("\x1b[H", "home"), + ("\x1b[F", "end"), + ]; + let mut keys = Vec::new(); + let chars: Vec = text.chars().collect(); + let mut i = 0usize; + while i < chars.len() { + if chars[i] == '\x1b' { + let rest: String = chars[i..].iter().collect(); + let found = SEQUENCES + .iter() + .find(|(seq, _)| rest.starts_with(seq)) + .map(|(seq, name)| (seq.chars().count(), *name)); + match found { + Some((len, name)) => { + keys.push(name.to_string()); + i += len; + } + None => { + keys.push("esc".to_string()); + i += 1; + } + } + continue; + } + let ch = chars[i]; + i += 1; + match ch { + '\r' | '\n' => keys.push("enter".to_string()), + '\t' => keys.push("tab".to_string()), + '\x7f' | '\x08' => keys.push("backspace".to_string()), + c => keys.push(c.to_string()), + } + } + keys +} + +/// Print the doc comment and leave, when asked for help. +pub fn maybe_help(doc: &str) { + let args: Vec = std::env::args().skip(1).collect(); + if args.iter().any(|a| a == "-h" || a == "--help") { + println!("{}", doc.trim()); + std::process::exit(0); + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn seg_counts_only_the_text() { + let red = rgb(255, 0, 0); + // Twelve printable cells asked for, twelve delivered, however many + // escape bytes rode along with them. + let line = seg(&[(red.as_str(), "hello world!!!".into())], 12); + let visible: String = line.replace(&red, ""); + assert_eq!(visible.chars().count(), 12); + } + + #[test] + fn pad_is_exact_in_both_directions() { + assert_eq!(pad("ab", 5).chars().count(), 5); + assert_eq!(pad("abcdefgh", 3), "abc"); + } + + #[test] + fn title_fills_the_width() { + let plain = strip(&title("clocks", 40, &rgb(0, 255, 170))); + assert_eq!(plain.chars().count(), 40); + assert!(plain.contains(" CLOCKS ")); + } + + #[test] + fn arrows_decode_to_names() { + assert_eq!(decode("\x1b[A"), vec!["up"]); + assert_eq!(decode("\x1b[B\x1b[B"), vec!["down", "down"]); + assert_eq!(decode("q"), vec!["q"]); + assert_eq!(decode("\x1b"), vec!["esc"]); + assert_eq!(decode("\r"), vec!["enter"]); + } + + #[test] + fn hints_wrap_rather_than_split() { + let dim = rgb(1, 1, 1); + let hints: Vec> = vec![ + vec![(dim.as_str(), "[a]lpha".into())], + vec![(dim.as_str(), "[b]ravo".into())], + vec![(dim.as_str(), "[c]harlie".into())], + ]; + let lines = pack_hints(&hints, 20, " "); + assert!(lines.len() > 1); + for line in &lines { + let plain = strip(line); + assert!(plain.chars().count() <= 20, "{:?} is too wide", plain); + // A hint is never cut in half. + assert!(!plain.ends_with("[c]har")); + } + } + + fn strip(s: &str) -> String { + let mut out = String::new(); + let mut chars = s.chars().peekable(); + while let Some(c) = chars.next() { + if c == '\x1b' { + while let Some(n) = chars.next() { + if n.is_ascii_alphabetic() { + break; + } + } + } else { + out.push(c); + } + } + out + } +} diff --git a/rust/widgets/Cargo.toml b/rust/widgets/Cargo.toml new file mode 100644 index 0000000..20d3533 --- /dev/null +++ b/rust/widgets/Cargo.toml @@ -0,0 +1,13 @@ +[package] +name = "toys-widgets" +version.workspace = true +edition.workspace = true +license.workspace = true + +[dependencies] +toys-core = { path = "../core" } +libc = "0.2" + +[[bin]] +name = "ports" +path = "src/bin/ports.rs" diff --git a/rust/widgets/src/bin/ports.rs b/rust/widgets/src/bin/ports.rs new file mode 100644 index 0000000..750b2ee --- /dev/null +++ b/rust/widgets/src/bin/ports.rs @@ -0,0 +1,846 @@ +// terminal-toys - small dependency-free terminal widgets +// Copyright (C) 2026 William Li +// +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU Affero General Public License as published +// by the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU Affero General Public License for more details. +// +// You should have received a copy of the GNU Affero General Public License +// along with this program. If not, see . + +//! What is listening on this machine, what started it, and who can reach it. +//! +//! A port of ports.py. Same sources - the kernel's socket table for the +//! ports, each process's own cmdline and cwd for the rest - and deliberately +//! the same behaviour on screen, so the two can be compared side by side +//! while the rest of the collection is translated. +//! +//! ports [-n SECONDS] +//! +//! Keys: up/down select, o hides the machine's own ports, r refreshes, +//! q quits. + +use std::collections::HashMap; +use std::sync::{Arc, Mutex}; +use std::time::{Duration, SystemTime, UNIX_EPOCH}; + +use toys_core as tc; + +const SYSTEM_PORTS: &[u16] = &[22, 53, 123, 323, 631, 5353]; + +/// Process titles worth recognising, first match winning, so the specific +/// ones come before `node` and `python`. +const KINDS: &[(&str, &str)] = &[ + ("next-server", "Next.js"), + ("node_modules/next/dist", "Next.js"), + ("node_modules/.bin/vite", "Vite"), + ("react-scripts", "React"), + ("webpack", "webpack"), + ("nuxt", "Nuxt"), + ("astro", "Astro"), + ("remix", "Remix"), + ("uvicorn", "uvicorn"), + ("gunicorn", "gunicorn"), + ("manage.py", "Django"), + ("rails", "Rails"), + ("postgres", "Postgres"), + ("redis-server", "Redis"), + ("mysqld", "MySQL"), + ("mongod", "MongoDB"), + ("docker-proxy", "Docker"), + ("ollama", "Ollama"), + ("code-server", "VS Code"), + ("herdr", "Herdr"), + ("tailscaled", "Tailscale"), + ("sshd", "SSH"), + ("systemd-resolve", "DNS"), + ("python", "Python"), + ("node", "Node"), +]; + +/// Ports whose owner is usually root, so /proc will not say what it is. +/// Naming them by convention is a guess, and is marked as one. +const BY_PORT: &[(u16, &str)] = &[ + (22, "SSH"), + (53, "DNS"), + (80, "HTTP"), + (123, "NTP"), + (443, "HTTPS"), + (631, "printing"), + (3306, "MySQL"), + (5432, "Postgres"), + (6379, "Redis"), + (5353, "mDNS"), + (27017, "MongoDB"), +]; + +// cmdline, cwd and families are carried for the detail screen, which is +// the next thing to be ported; the table itself does not read them. +#[allow(dead_code)] +#[derive(Clone, Default)] +struct Row { + port: u16, + bind: String, + families: u8, + pid: Option, + cmdline: String, + cwd: String, + kind: String, + guessed: bool, + user: String, + project: String, + gone: bool, + up: Option, + exposed: String, + orphan: bool, +} + +fn now() -> f64 { + SystemTime::now() + .duration_since(UNIX_EPOCH) + .map(|d| d.as_secs_f64()) + .unwrap_or(0.0) +} + +/// Who can reach a socket bound to this address. +fn bind_class(bind: &str) -> String { + if bind == "0.0.0.0" || bind == "::" { + return "all".into(); + } + if bind.starts_with("127.") || bind == "::1" { + return "local".into(); + } + if is_tailnet_v4(bind) || bind.starts_with("fd7a:115c:a1e0") { + return "tailnet".into(); + } + bind.to_string() +} + +/// Tailscale hands out 100.64.0.0/10, which is a different answer from +/// either "all" or "local". +fn is_tailnet_v4(bind: &str) -> bool { + let mut parts = bind.split('.'); + match (parts.next(), parts.next()) { + (Some("100"), Some(second)) => second + .parse::() + .map(|n| (64..=127).contains(&n)) + .unwrap_or(false), + _ => false, + } +} + +/// The bind address out of /proc's little-endian hex. +fn hex_addr(text: &str) -> String { + if text.len() == 8 { + let n = u32::from_str_radix(text, 16).unwrap_or(0); + return format!( + "{}.{}.{}.{}", + n & 0xff, + (n >> 8) & 0xff, + (n >> 16) & 0xff, + (n >> 24) & 0xff + ); + } + if text.len() == 32 { + // Written as four 32-bit words, each little-endian: the four bytes + // of a word appear in reverse of the order they take in the + // address. Reverse each word and the sixteen bytes are in order. + let mut groups = Vec::new(); + for word in 0..4 { + let raw = &text[word * 8..word * 8 + 8]; + let mut bytes = [0u8; 4]; + for (i, byte) in bytes.iter_mut().enumerate() { + *byte = u8::from_str_radix(&raw[i * 2..i * 2 + 2], 16).unwrap_or(0); + } + bytes.reverse(); + groups.push(format!("{:02x}{:02x}", bytes[0], bytes[1])); + groups.push(format!("{:02x}{:02x}", bytes[2], bytes[3])); + } + return compress_v6(&groups); + } + "?".into() +} + +/// The conventional shortest form of an IPv6 address. +fn compress_v6(groups: &[String]) -> String { + let trimmed: Vec = groups + .iter() + .map(|g| g.trim_start_matches('0').to_string()) + .map(|g| if g.is_empty() { "0".into() } else { g }) + .collect(); + let (mut best_at, mut best_len, mut at, mut len) = (usize::MAX, 0usize, usize::MAX, 0usize); + for (i, g) in trimmed.iter().enumerate() { + if g == "0" { + if len == 0 { + at = i; + } + len += 1; + if len > best_len { + best_len = len; + best_at = at; + } + } else { + len = 0; + } + } + if best_len < 2 { + return trimmed.join(":"); + } + let head = trimmed[..best_at].join(":"); + let tail = trimmed[best_at + best_len..].join(":"); + format!("{}::{}", head, tail) +} + +struct Socket { + port: u16, + bind: String, + inode: String, + uid: u32, +} + +/// Every listening TCP socket, from the kernel's own table. +fn listening() -> Vec { + let mut out = Vec::new(); + for path in ["/proc/net/tcp", "/proc/net/tcp6"] { + let text = match std::fs::read_to_string(path) { + Ok(t) => t, + Err(_) => continue, + }; + for line in text.lines().skip(1) { + let cols: Vec<&str> = line.split_whitespace().collect(); + if cols.len() < 10 || cols[3] != "0A" { + continue; + } + let (addr, port) = match cols[1].rsplit_once(':') { + Some(pair) => pair, + None => continue, + }; + let port = match u16::from_str_radix(port, 16) { + Ok(p) => p, + Err(_) => continue, + }; + out.push(Socket { + port, + bind: hex_addr(addr), + inode: cols[9].to_string(), + // The uid is in the table even where the process behind it + // is not reachable, which is the difference between + // "somebody else's" and "a mystery". + uid: cols[7].parse().unwrap_or(0), + }); + } + } + out +} + +/// inode -> pid, for every process this user can read. +/// +/// Root's sockets are not readable, so sshd and the like arrive unowned. +/// That is stated on screen rather than papered over. +fn socket_owners() -> HashMap { + let mut owners = HashMap::new(); + let entries = match std::fs::read_dir("/proc") { + Ok(e) => e, + Err(_) => return owners, + }; + for entry in entries.flatten() { + let name = entry.file_name(); + let name = name.to_string_lossy(); + let pid: i32 = match name.parse() { + Ok(p) => p, + Err(_) => continue, + }; + let fds = match std::fs::read_dir(format!("/proc/{}/fd", pid)) { + Ok(f) => f, + Err(_) => continue, + }; + for fd in fds.flatten() { + if let Ok(target) = std::fs::read_link(fd.path()) { + let target = target.to_string_lossy(); + if let Some(rest) = target.strip_prefix("socket:[") { + owners.insert(rest.trim_end_matches(']').to_string(), pid); + } + } + } + } + owners +} + +/// Whose socket it is, by name where the machine has one. +fn owner_name(uid: u32) -> String { + if uid == unsafe { libc::getuid() } { + return String::new(); + } + let entry = unsafe { libc::getpwuid(uid) }; + if entry.is_null() { + return format!("uid {}", uid); + } + let name = unsafe { std::ffi::CStr::from_ptr((*entry).pw_name) }; + name.to_string_lossy().to_string() +} + +fn process_info(pid: i32) -> (String, String, Option) { + let cmdline = std::fs::read(format!("/proc/{}/cmdline", pid)) + .map(|raw| { + String::from_utf8_lossy(&raw) + .replace('\0', " ") + .trim() + .to_string() + }) + .unwrap_or_default(); + let cwd = std::fs::read_link(format!("/proc/{}/cwd", pid)) + .map(|p| p.to_string_lossy().to_string()) + .unwrap_or_default(); + // The link resolves even when the directory is gone; the kernel just + // marks it, and that marker is worth keeping. + let deleted = std::fs::metadata(format!("/proc/{}/cwd", pid)).is_err() && !cwd.is_empty(); + let cwd = if deleted && !cwd.ends_with("(deleted)") { + format!("{} (deleted)", cwd) + } else { + cwd + }; + let started = std::fs::metadata(format!("/proc/{}", pid)) + .ok() + .and_then(|m| m.created().or_else(|_| m.modified()).ok()) + .and_then(|t| t.duration_since(UNIX_EPOCH).ok()) + .map(|d| d.as_secs_f64()); + (cmdline, cwd, started) +} + +/// What a directory calls itself, for the label a person would use. +fn project_name(cwd: &str) -> String { + if cwd.is_empty() { + return String::new(); + } + let real = cwd.trim_end_matches(" (deleted)"); + let named = std::fs::read_to_string(format!("{}/package.json", real)) + .ok() + .and_then(|text| json_string(&text, "name")); + let base = std::path::Path::new(real) + .file_name() + .map(|s| s.to_string_lossy().to_string()) + .unwrap_or_default(); + let name = named.unwrap_or(base); + if cwd.ends_with("(deleted)") { + format!("{} ✗", name) + } else { + name + } +} + +/// The first string value for a top-level key, without a JSON parser. +/// +/// Enough for `package.json`'s name and for tailscale's serve status: both +/// are shapes this only needs one field out of, and a parser for them would +/// be a dependency bought for two lookups. +fn json_string(text: &str, key: &str) -> Option { + let needle = format!("\"{}\"", key); + let at = text.find(&needle)? + needle.len(); + let rest = &text[at..]; + let colon = rest.find(':')? + 1; + let rest = &rest[colon..]; + let open = rest.find('"')? + 1; + let rest = &rest[open..]; + let close = rest.find('"')?; + Some(rest[..close].to_string()) +} + +/// What sort of server this is, from the process itself. +fn kind_of(cmdline: &str, port: u16) -> (String, bool) { + if !cmdline.is_empty() { + for (needle, name) in KINDS { + if cmdline.contains(needle) { + // Next.js rewrites its own title to next-server (v16.3.0), + // which hands over the framework and the version at once. + if let Some(version) = version_in(cmdline) { + return (format!("{} {}", name, version), false); + } + return (name.to_string(), false); + } + } + let first = cmdline.split_whitespace().next().unwrap_or(""); + let base = first.rsplit('/').next().unwrap_or(first); + if !base.is_empty() { + return (base.to_string(), false); + } + } + for (known, name) in BY_PORT { + if *known == port { + return (format!("{}?", name), true); + } + } + (String::new(), false) +} + +fn version_in(cmdline: &str) -> Option { + let at = cmdline.find("(v")?; + let rest = &cmdline[at + 2..]; + let close = rest.find(')')?; + let version = &rest[..close]; + if version.chars().next()?.is_ascii_digit() { + Some(version.to_string()) + } else { + None + } +} + +fn run(args: &[&str]) -> String { + match std::process::Command::new(args[0]).args(&args[1..]).output() { + Ok(out) if out.status.success() => String::from_utf8_lossy(&out.stdout).to_string(), + _ => String::new(), + } +} + +/// Ports Tailscale is serving, and whether the world can see them. +fn exposure() -> HashMap { + let mut served = HashMap::new(); + let text = run(&["tailscale", "serve", "status", "--json"]); + for port in proxied_ports(&text) { + served.insert(port, "tailnet".to_string()); + } + let funnel = run(&["tailscale", "funnel", "status"]); + if !funnel.contains("tailnet only") { + for port in proxied_ports(&funnel) { + served.insert(port, "public".to_string()); + } + } + served +} + +/// Every local port a proxy line points at, in either output shape. +fn proxied_ports(text: &str) -> Vec { + let mut found = Vec::new(); + for marker in ["127.0.0.1:", "localhost:", "[::1]:"] { + let mut rest = text; + while let Some(at) = rest.find(marker) { + rest = &rest[at + marker.len()..]; + let digits: String = rest.chars().take_while(|c| c.is_ascii_digit()).collect(); + if let Ok(port) = digits.parse::() { + found.push(port); + } + } + } + found +} + +/// One entry per listening service, plus anything served but not bound. +fn scan() -> Vec { + let owners = socket_owners(); + let served = exposure(); + let mut rows: Vec = Vec::new(); + let mut services: HashMap<(u16, Option, String), usize> = HashMap::new(); + let mut seen: Vec = Vec::new(); + let stamp = now(); + + for sock in listening() { + let pid = owners.get(&sock.inode).copied(); + // A server on both address families is two sockets in the kernel + // table but one thing to know about. Any of port, owner or + // reachability differing is a real second row. + let key = (sock.port, pid, bind_class(&sock.bind)); + if let Some(&at) = services.get(&key) { + rows[at].families += 1; + continue; + } + let (cmdline, cwd, started) = match pid { + Some(pid) => process_info(pid), + None => (String::new(), String::new(), None), + }; + let (kind, guessed) = kind_of(&cmdline, sock.port); + let row = Row { + port: sock.port, + bind: sock.bind.clone(), + families: 1, + pid, + cmdline, + cwd: cwd.clone(), + kind, + guessed, + user: owner_name(sock.uid), + project: project_name(&cwd), + gone: cwd.ends_with("(deleted)"), + up: started.map(|s| stamp - s), + exposed: served.get(&sock.port).cloned().unwrap_or_default(), + orphan: false, + }; + services.insert(key, rows.len()); + seen.push(sock.port); + rows.push(row); + } + + // A port Tailscale forwards to with nothing behind it is worth its own + // row: the URL exists, answers 502, and nothing in lsof explains why. + for (port, how) in &served { + if !seen.contains(port) { + rows.push(Row { + port: *port, + kind: "nothing listening".into(), + exposed: how.clone(), + orphan: true, + ..Default::default() + }); + } + } + rows.sort_by_key(|r| (SYSTEM_PORTS.contains(&r.port), r.port)); + rows +} + +fn span(seconds: Option) -> String { + let s = match seconds { + Some(s) if s >= 0.0 => s, + _ => return "--".into(), + }; + if s < 90.0 { + format!("{}s", s as i64) + } else if s < 5400.0 { + format!("{}m", (s / 60.0) as i64) + } else if s < 172_800.0 { + format!("{}h", (s / 3600.0) as i64) + } else { + format!("{}d", (s / 86400.0) as i64) + } +} + +/// Whether a row is part of the machine rather than something you started. +fn theirs(row: &Row) -> bool { + if row.orphan { + return false; + } + SYSTEM_PORTS.contains(&row.port) || !row.user.is_empty() +} + +struct Store { + rows: Mutex>, +} + +fn main() { + tc::maybe_help(include_str!("ports_help.txt")); + let mut refresh = 4.0f64; + let args: Vec = std::env::args().skip(1).collect(); + let mut i = 0; + while i < args.len() { + if (args[i] == "-n" || args[i] == "--refresh") && i + 1 < args.len() { + refresh = args[i + 1].parse::().unwrap_or(4.0).max(1.0); + i += 2; + } else { + i += 1; + } + } + + let ok = rgb_ok(); + let store = Arc::new(Store { + rows: Mutex::new(Vec::new()), + }); + let poller = Arc::clone(&store); + std::thread::spawn(move || loop { + // A thread that dies takes its explanation with it, so the scan is + // caught rather than left to unwind: an empty table would look + // exactly like a machine with nothing listening. + let found = std::panic::catch_unwind(scan).unwrap_or_default(); + if let Ok(mut guard) = poller.rows.lock() { + *guard = found; + } + std::thread::sleep(Duration::from_secs_f64(refresh)); + }); + + tc::setup(); + let mut keyboard = tc::Keyboard::new(); + let (mut selected, mut hide_system, mut scroll) = (0usize, true, 0usize); + + loop { + for key in keyboard.poll() { + match key.as_str() { + "q" | "Q" => { + keyboard.restore(); + tc::restore_screen(); + return; + } + "up" => selected = selected.saturating_sub(1), + "down" => selected += 1, + "o" | "O" => hide_system = !hide_system, + _ => {} + } + } + + let (w, h) = tc::size(); + let all: Vec = store.rows.lock().map(|g| g.clone()).unwrap_or_default(); + let shown: Vec<&Row> = all + .iter() + .filter(|r| !(hide_system && theirs(r))) + .collect(); + if !shown.is_empty() && selected >= shown.len() { + selected = shown.len() - 1; + } + let mine = all.iter().filter(|r| r.pid.is_some()).count(); + let off_box = all.iter().filter(|r| !r.exposed.is_empty()).count(); + + let mut rows = vec![tc::title("dev servers", w, &ok.port)]; + rows.push(tc::seg( + &[ + (ok.dim.as_str(), format!(" {} listening", all.len())), + (ok.dim.as_str(), format!(" · {} yours", mine)), + (ok.dim.as_str(), " · ".into()), + ( + if off_box > 0 { &ok.ok } else { &ok.dim }, + format!("{} reachable off-box", off_box), + ), + (ok.dim.as_str(), format!(" every {}s", refresh as i64)), + ], + w - 1, + )); + rows.push(String::new()); + + let wide = w >= 78; + // The project column takes whatever the fixed ones leave: it is the + // one that identifies the server, and the one whose contents are a + // directory name of any length. + let fixed = 1 + 6 + 8 + 18 + if wide { 6 + 8 } else { 0 }; + let name_w = std::cmp::max(8, (w - 1).saturating_sub(fixed)); + rows.push(tc::seg( + &[ + (ok.dim.as_str(), " PORT BIND WHAT ".into()), + (ok.dim.as_str(), tc::pad("PROJECT", name_w)), + ( + ok.dim.as_str(), + if wide { "UP EXPOSED".into() } else { String::new() }, + ), + ], + w - 1, + )); + + let visible = std::cmp::max(1, h.saturating_sub(rows.len() + 3)); + if selected < scroll { + scroll = selected; + } else if selected >= scroll + visible { + scroll = selected - visible + 1; + } + scroll = std::cmp::min(scroll, shown.len().saturating_sub(visible)); + + for (i, row) in shown.iter().enumerate().skip(scroll).take(visible) { + let here = i == selected; + let tint = if here { tc::bg(28, 44, 62) } else { String::new() }; + let (note, note_colour) = bind_note(row, &ok); + let who = if !row.project.is_empty() { + row.project.clone() + } else if !row.user.is_empty() { + row.user.clone() + } else if row.pid.is_some() { + "—".into() + } else { + String::new() + }; + let port_colour = format!("{}{}", tint, if here { &ok.accent } else { &ok.port }); + let note_c = format!("{}{}", tint, note_colour); + let kind_c = format!( + "{}{}", + tint, + if row.guessed || row.kind.is_empty() { + &ok.dim + } else { + &ok.txt + } + ); + let who_c = format!( + "{}{}", + tint, + if row.gone { + &ok.warn + } else if !row.user.is_empty() { + &ok.dim + } else { + &ok.txt + } + ); + let mut line = vec![ + ( + port_colour.as_str(), + format!("{}{:<6}", if here { "▸" } else { " " }, row.port), + ), + (note_c.as_str(), format!("{:<8}", note)), + (kind_c.as_str(), tc::pad(&row.kind, 18)), + (who_c.as_str(), tc::pad(&who, name_w)), + ]; + let up_c = format!("{}{}", tint, ok.dim); + let exp_c = format!( + "{}{}", + tint, + match row.exposed.as_str() { + "tailnet" => &ok.ok, + "public" => &ok.bad, + _ => &ok.grid, + } + ); + if wide { + line.push((up_c.as_str(), format!("{:<6}", span(row.up)))); + line.push(( + exp_c.as_str(), + if row.exposed.is_empty() { + "-".into() + } else { + row.exposed.clone() + }, + )); + } + if here { + line.push((tint.as_str(), " ".repeat(w))); + } + rows.push(tc::seg(&line, w - 1)); + } + + let hints: Vec> = vec![ + vec![(ok.accent.as_str(), "↑↓".into()), (ok.dim.as_str(), " select".into())], + vec![( + ok.dim.as_str(), + format!("[o]{} system", if hide_system { "show" } else { "hide" }), + )], + vec![(ok.dim.as_str(), "[r]efresh".into())], + vec![(ok.dim.as_str(), "[q]uit".into())], + ]; + let foot: Vec = tc::pack_hints(&hints, w - 2, " ") + .into_iter() + .map(|l| format!(" {}", l)) + .collect(); + while rows.len() < h.saturating_sub(foot.len() + 1) { + rows.push(String::new()); + } + rows.extend(foot); + tc::draw(&rows, w, h); + std::thread::sleep(Duration::from_millis(300)); + } +} + +struct Palette { + ok: String, + warn: String, + bad: String, + dim: String, + grid: String, + txt: String, + accent: String, + port: String, + open: String, + local: String, +} + +fn rgb_ok() -> Palette { + Palette { + ok: tc::rgb(90, 240, 160), + warn: tc::rgb(255, 200, 90), + bad: tc::rgb(255, 100, 110), + dim: tc::rgb(127, 147, 172), + grid: tc::rgb(60, 78, 98), + txt: tc::rgb(225, 235, 245), + accent: tc::rgb(150, 210, 255), + port: tc::rgb(160, 220, 255), + open: tc::rgb(255, 170, 120), + local: tc::rgb(120, 200, 160), + } +} + +/// What the bound address means for who can reach it. +/// +/// The address itself is too wide for the column - a tailnet IPv6 address +/// is 24 characters - and is rarely the answer to the question being asked. +fn bind_note(row: &Row, p: &Palette) -> (String, String) { + if row.orphan { + return ("--".into(), p.dim.clone()); + } + let reach = bind_class(&row.bind); + match reach.as_str() { + "all" => ("all".into(), p.open.clone()), + "local" => ("local".into(), p.local.clone()), + "tailnet" => ("tailnet".into(), p.accent.clone()), + other => (other.chars().take(7).collect(), p.txt.clone()), + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn ipv6_comes_out_of_little_endian_words() { + // ::1 as /proc/net/tcp6 writes it: four words, each reversed. + assert_eq!(hex_addr("00000000000000000000000001000000"), "::1"); + assert_eq!(hex_addr("00000000000000000000000000000000"), "::"); + // A tailnet address, taken from this machine's own /proc/net/tcp6 + // and checked against what ss prints for the same socket, rather + // than assembled by hand - the first attempt at that was wrong in + // a way that made a correct decoder look broken. + assert_eq!( + hex_addr("5C117AFD0000E0A100000000686338DE"), + "fd7a:115c:a1e0::de38:6368" + ); + } + + #[test] + fn ipv4_comes_out_of_little_endian_hex() { + // 0100007F is 127.0.0.1 the way /proc writes it. + assert_eq!(hex_addr("0100007F"), "127.0.0.1"); + assert_eq!(hex_addr("00000000"), "0.0.0.0"); + } + + #[test] + fn reachability_is_classified_not_printed() { + assert_eq!(bind_class("0.0.0.0"), "all"); + assert_eq!(bind_class("::"), "all"); + assert_eq!(bind_class("127.0.0.1"), "local"); + assert_eq!(bind_class("::1"), "local"); + assert_eq!(bind_class("100.89.99.102"), "tailnet"); + assert_eq!(bind_class("fd7a:115c:a1e0::1"), "tailnet"); + // A LAN address is its own answer, not one of the three. + assert_eq!(bind_class("192.168.1.9"), "192.168.1.9"); + assert_eq!(bind_class("10.240.0.46"), "10.240.0.46"); + } + + #[test] + fn tailnet_range_stops_where_it_should() { + assert!(is_tailnet_v4("100.64.0.1")); + assert!(is_tailnet_v4("100.127.255.254")); + assert!(!is_tailnet_v4("100.63.0.1")); + assert!(!is_tailnet_v4("100.128.0.1")); + } + + #[test] + fn a_version_in_the_title_is_kept() { + let (kind, guessed) = kind_of("next-server (v16.3.1)", 3000); + assert_eq!(kind, "Next.js 16.3.1"); + assert!(!guessed); + } + + #[test] + fn a_port_number_alone_is_marked_as_a_guess() { + let (kind, guessed) = kind_of("", 443); + assert_eq!(kind, "HTTPS?"); + assert!(guessed, "a guess from a port number must say so"); + } + + #[test] + fn proxy_lines_give_up_their_ports() { + let json = r#"{"Web":{"host:443":{"Handlers":{"/":{"Proxy":"http://127.0.0.1:4100"}}}}}"#; + assert_eq!(proxied_ports(json), vec![4100]); + } + + #[test] + fn a_package_name_beats_the_directory() { + assert_eq!( + json_string(r#"{"name": "piaf-web", "version": "1.0"}"#, "name"), + Some("piaf-web".into()) + ); + } + + #[test] + fn spans_read_as_a_person_would_say_them() { + assert_eq!(span(Some(45.0)), "45s"); + assert_eq!(span(Some(600.0)), "10m"); + assert_eq!(span(Some(7200.0)), "2h"); + assert_eq!(span(Some(200_000.0)), "2d"); + assert_eq!(span(None), "--"); + } +} diff --git a/rust/widgets/src/bin/ports_help.txt b/rust/widgets/src/bin/ports_help.txt new file mode 100644 index 0000000..e46ad27 --- /dev/null +++ b/rust/widgets/src/bin/ports_help.txt @@ -0,0 +1,21 @@ +What is listening on this machine, what started it, and who can reach it. + +On a box running several agents at once, "which port is that project on" and +"is this reachable from outside" are asked constantly and answered badly. +`lsof -i` gives a pid and a port and stops there. + +Each row is one listening service: the port, what it is bound to, what kind of +server it is, the project directory it was started from - the label that +actually identifies a dev server - how long it has been up, and whether +anything outside this machine can reach it. A server listening on both IPv4 +and IPv6 is one row, not two. + + ports [-n SECONDS] + +Read from /proc alone: the socket table for the ports, and each process's own +cmdline and cwd for the rest. Exposure comes from `tailscale serve status` +where Tailscale is installed. Another user's sockets cannot be tied to a +process without root, so those rows name the owner the socket table gives +and are hidden behind o along with the system ports. + +Keys: up/down select, o hides the machine's own ports, r refreshes, q quits. From 6656d055625e225d770577f5d929dcdbe74ebda9 Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sat, 22 Aug 2026 19:48:19 +0800 Subject: [PATCH 002/147] rust: netwatch ported, and the first honest measurement Second widget, and the one pane 008 runs. Same two sources as the Python - ss -tine for the per-socket counters and the inode beside them, /proc//fd for the process that owns it - and the same behaviour that took several rounds to get right there: sockets opened since the last sample count in full, a reused inode is taken at face value rather than subtracted, cgroups name the daemons /proc will not, and only traffic that actually leaves the machine is counted. The braille chart came over intact, tx above and rx below, each half on its own scale with its own unsigned label. With both running seventy seconds in the same size terminal, polling at the same interval: resident cpu seconds rust 3.1 MB 0.89 s python 16.8 MB 1.04 s Memory is 5.4x smaller and that is a real difference. The cpu is not: fourteen per cent, because the work is a subprocess and a walk of /proc, and neither of those cares what language asked for it. That is worth recording plainly, since speed was the thing a rewrite was supposed to buy and speed is not what it bought. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/widgets/Cargo.toml | 4 + rust/widgets/src/bin/netwatch.rs | 1117 ++++++++++++++++++++++++ rust/widgets/src/bin/netwatch_help.txt | 25 + 3 files changed, 1146 insertions(+) create mode 100644 rust/widgets/src/bin/netwatch.rs create mode 100644 rust/widgets/src/bin/netwatch_help.txt diff --git a/rust/widgets/Cargo.toml b/rust/widgets/Cargo.toml index 20d3533..e15396d 100644 --- a/rust/widgets/Cargo.toml +++ b/rust/widgets/Cargo.toml @@ -11,3 +11,7 @@ libc = "0.2" [[bin]] name = "ports" path = "src/bin/ports.rs" + +[[bin]] +name = "netwatch" +path = "src/bin/netwatch.rs" diff --git a/rust/widgets/src/bin/netwatch.rs b/rust/widgets/src/bin/netwatch.rs new file mode 100644 index 0000000..6759867 --- /dev/null +++ b/rust/widgets/src/bin/netwatch.rs @@ -0,0 +1,1117 @@ +// terminal-toys - small dependency-free terminal widgets +// Copyright (C) 2026 William Li +// +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU Affero General Public License as published +// by the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU Affero General Public License for more details. +// +// You should have received a copy of the GNU Affero General Public License +// along with this program. If not, see . + +//! Which processes are using the network, how much, and how fast. +//! +//! A port of netwatch.py, reading the same two things: `ss -tine` for the +//! per-socket byte counters and the inode beside them, and /proc//fd +//! for the process that owns the inode. + +use std::collections::HashMap; +use std::sync::{Arc, Mutex}; +use std::time::{Duration, SystemTime, UNIX_EPOCH}; + +use toys_core as tc; + +const SERIES: usize = 240; + +/// A braille cell is two dots wide and four tall, so one character holds +/// eight addressable points. The bit for each is fixed by the encoding. +const BRAILLE: [[u8; 2]; 4] = [[0x01, 0x08], [0x02, 0x10], [0x04, 0x20], [0x40, 0x80]]; + +/// Interfaces that are not the wire. A packet forwarded out of one of these +/// leaves through a real interface as well, and counting both counts it +/// twice. +const VIRTUAL: &[&str] = &[ + "lo", "tailscale0", "docker", "veth", "br-", "virbr", "wg", "tun", "tap", "cni", "flannel", + "kube", +]; + +/// Systemd names the slice, not the thing in it. +const SLICES: &[&str] = &["system.slice", "user.slice", "init.scope", "-.slice", "app.slice"]; + +fn now() -> f64 { + SystemTime::now() + .duration_since(UNIX_EPOCH) + .map(|d| d.as_secs_f64()) + .unwrap_or(0.0) +} + +/// Decimal units, as network equipment and ISPs quote them. +fn units(n: f64) -> String { + for (suffix, scale) in [("GB", 1e9), ("MB", 1e6), ("KB", 1e3)] { + if n >= scale { + return format!("{:.1} {}", n / scale, suffix); + } + } + format!("{} B", n as i64) +} + +fn rate(n: f64) -> String { + if n > 0.0 { + format!("{}/s", units(n)) + } else { + "-".into() + } +} + +fn elapsed(seconds: f64) -> String { + let s = seconds as i64; + if s < 60 { + format!("{}s", s) + } else if s < 3600 { + format!("{}m {:02}s", s / 60, s % 60) + } else { + format!("{}h {:02}m", s / 3600, (s % 3600) / 60) + } +} + +fn run(args: &[&str]) -> String { + match std::process::Command::new(args[0]).args(&args[1..]).output() { + Ok(out) if out.status.success() => String::from_utf8_lossy(&out.stdout).to_string(), + _ => String::new(), + } +} + +/// Every address this machine answers to. +/// +/// A connection to one of them is turned around inside the kernel and never +/// reaches a wire, so it is not traffic leaving the machine even though the +/// address is not loopback. +fn own_addresses() -> Vec { + let mut found = Vec::new(); + for line in run(&["ip", "-o", "addr"]).lines() { + let cols: Vec<&str> = line.split_whitespace().collect(); + if let Some(at) = cols.iter().position(|c| *c == "inet" || *c == "inet6") { + if let Some(addr) = cols.get(at + 1) { + found.push(addr.split('/').next().unwrap_or(addr).to_string()); + } + } + } + found +} + +/// Whether this traffic never leaves the machine. +fn local_peer(host: &str, own: &[String]) -> bool { + if host.starts_with("127.") || host == "::1" || host.is_empty() || host == "*" { + return true; + } + let bare = host.strip_prefix("::ffff:").unwrap_or(host); + own.iter().any(|a| a == bare) +} + +/// Whether a peer is out on the internet rather than nearby. +fn off_box(host: &str, own: &[String]) -> bool { + if local_peer(host, own) { + return false; + } + let h = host.strip_prefix("::ffff:").unwrap_or(host); + if h.starts_with("10.") || h.starts_with("192.168.") || h.starts_with("169.254.") { + return false; + } + if h.starts_with("172.") { + if let Some(second) = h.split('.').nth(1).and_then(|s| s.parse::().ok()) { + if (16..=31).contains(&second) { + return false; + } + } + } + if let Some(second) = h.strip_prefix("100.").and_then(|r| r.split('.').next()) { + if let Ok(n) = second.parse::() { + if (64..=127).contains(&n) { + return false; + } + } + } + !(h.starts_with("fd7a:115c:a1e0") + || h.starts_with("fe80:") + || h.starts_with("fc") + || h.starts_with("fd")) +} + +#[derive(Clone)] +struct Seen { + sent: u64, + recv: u64, + peer: String, + port: u16, + cgroup: String, +} + +/// Every TCP socket's byte counters, keyed by inode. +/// +/// -i for the counters, -e for the inode. Without the inode there is no +/// honest way to reach the process: `ss -p` needs root to name anybody +/// else's, while /proc//fd needs nothing to name our own. +fn sockets(external: bool, own: &[String]) -> (HashMap, String) { + let text = run(&["ss", "-tine"]); + if text.is_empty() { + return (HashMap::new(), "ss would not run".into()); + } + let mut found = HashMap::new(); + let (mut inode, mut peer, mut port, mut cgroup) = (None, String::new(), 0u16, String::new()); + for (i, line) in text.lines().enumerate() { + if i == 0 { + continue; + } + // A socket is two lines: the addresses and inode, then the counters + // on an indented continuation. Neither is usable without the other. + if !line.starts_with(' ') && !line.starts_with('\t') { + let cols: Vec<&str> = line.split_whitespace().collect(); + peer = cols + .get(4) + .and_then(|a| a.rsplit_once(':')) + .map(|(h, _)| h.trim_matches(|c| c == '[' || c == ']').to_string()) + .unwrap_or_default(); + port = cols + .get(4) + .and_then(|a| a.rsplit_once(':')) + .and_then(|(_, p)| p.parse().ok()) + .unwrap_or(0); + inode = field(line, "ino:").filter(|v| v != "0"); + cgroup = field(line, "cgroup:").unwrap_or_default(); + continue; + } + let id = match inode.take() { + Some(id) => id, + None => continue, + }; + if local_peer(&peer, own) || (external && !off_box(&peer, own)) { + continue; + } + found.insert( + id, + Seen { + sent: field(line, "bytes_sent:") + .and_then(|v| v.parse().ok()) + .unwrap_or(0), + recv: field(line, "bytes_received:") + .and_then(|v| v.parse().ok()) + .unwrap_or(0), + peer: peer.clone(), + port, + cgroup: cgroup.clone(), + }, + ); + } + (found, String::new()) +} + +/// The value after `key:` on a line, up to the next space. +fn field(line: &str, key: &str) -> Option { + let at = line.find(key)? + key.len(); + let rest = &line[at..]; + let end = rest.find(char::is_whitespace).unwrap_or(rest.len()); + let value = &rest[..end]; + if value.is_empty() { + None + } else { + Some(value.to_string()) + } +} + +/// Who owns a socket, from the cgroup the kernel already reports. +/// +/// Another user's /proc is closed, but `ss` prints the control group for +/// every socket regardless, and on a systemd machine that names the unit. +fn unit_name(cgroup: &str) -> String { + for part in cgroup.trim_matches('/').split('/').rev() { + if part.is_empty() || SLICES.contains(&part) { + continue; + } + let mut name = part; + for suffix in [".service", ".scope", ".slice"] { + if let Some(base) = name.strip_suffix(suffix) { + name = base; + break; + } + } + // A login session is a person, not a program. + if name.starts_with("session-") || name.starts_with("user-") { + continue; + } + return name.to_string(); + } + String::new() +} + +/// inode -> (pid, name), for every process this user can read. +fn socket_owners() -> HashMap { + let mut owners = HashMap::new(); + let entries = match std::fs::read_dir("/proc") { + Ok(e) => e, + Err(_) => return owners, + }; + for entry in entries.flatten() { + let pid: i32 = match entry.file_name().to_string_lossy().parse() { + Ok(p) => p, + Err(_) => continue, + }; + let fds = match std::fs::read_dir(format!("/proc/{}/fd", pid)) { + Ok(f) => f, + Err(_) => continue, + }; + let mut name = String::new(); + for fd in fds.flatten() { + if let Ok(target) = std::fs::read_link(fd.path()) { + let target = target.to_string_lossy(); + if let Some(rest) = target.strip_prefix("socket:[") { + if name.is_empty() { + name = process_name(pid); + } + owners.insert(rest.trim_end_matches(']').to_string(), (pid, name.clone())); + } + } + } + } + owners +} + +/// What to call a process, preferring something a person would recognise. +/// +/// /proc//comm is the kernel's answer and usually right, but some +/// binaries are versioned - .../claude/versions/2.1.233 reports itself as +/// "2.1.233", which is true and useless. +fn process_name(pid: i32) -> String { + let comm = std::fs::read_to_string(format!("/proc/{}/comm", pid)) + .map(|s| s.trim().to_string()) + .unwrap_or_default(); + if comm.chars().any(|c| c.is_ascii_alphabetic()) { + return comm; + } + const GENERIC: &[&str] = &[ + "versions", "bin", "sbin", "libexec", "node_modules", "dist", "build", "lib", "share", + "local", "current", "releases", + ]; + let argv0 = std::fs::read(format!("/proc/{}/cmdline", pid)) + .map(|raw| { + String::from_utf8_lossy(&raw) + .split('\0') + .next() + .unwrap_or("") + .to_string() + }) + .unwrap_or_default(); + for part in argv0.split('/').rev() { + if part.chars().any(|c| c.is_ascii_alphabetic()) + && !GENERIC.contains(&part.to_lowercase().as_str()) + { + return part.to_string(); + } + } + if comm.is_empty() { + "?".into() + } else { + comm + } +} + +/// Bytes in and out of this machine's real interfaces. +/// +/// The kernel counts these whatever produced them, which is the point: a +/// packet this machine routes rather than terminates never touches a +/// socket. On an exit node that is most of the traffic. +fn wire_bytes() -> Option<(u64, u64, Vec)> { + let text = std::fs::read_to_string("/proc/net/dev").ok()?; + let (mut rx, mut tx, mut names) = (0u64, 0u64, Vec::new()); + for line in text.lines().skip(2) { + let (name, rest) = line.split_once(':')?; + let name = name.trim(); + if VIRTUAL.iter().any(|v| name.starts_with(v)) { + continue; + } + let fields: Vec<&str> = rest.split_whitespace().collect(); + if fields.len() < 9 { + continue; + } + rx += fields[0].parse::().unwrap_or(0); + tx += fields[8].parse::().unwrap_or(0); + names.push(name.to_string()); + } + Some((rx, tx, names)) +} + +/// Which interfaces are being counted, for the end of the line. +fn wire_label(names: &[String]) -> String { + match names.len() { + 0 => String::new(), + 1..=3 => names.join(", "), + n => format!("{} of them", n), + } +} + +#[derive(Clone, Default)] +struct Proc { + pid: i32, + name: String, + up: u64, + down: u64, + up_rate: f64, + down_rate: f64, + alive: bool, +} + +#[derive(Default)] +struct State { + totals: HashMap<(i32, String), Proc>, + last: HashMap, + series: Vec<(f64, f64, f64, f64)>, + stamp: f64, + started: f64, + wire: Option<(u64, u64)>, + wire_rate: (f64, f64), + wire_names: Vec, + err: String, +} + +fn sample(state: &mut State, external: bool) { + let stamp = now(); + let own = own_addresses(); + let counters = wire_bytes(); + let (found, err) = sockets(external, &own); + let owners = if found.is_empty() { + HashMap::new() + } else { + socket_owners() + }; + let gap = if state.stamp > 0.0 { + (stamp - state.stamp).max(1e-6) + } else { + 0.0 + }; + state.err = err; + + for row in state.totals.values_mut() { + row.up_rate = 0.0; + row.down_rate = 0.0; + row.alive = false; + } + + let first = state.stamp == 0.0; + for (inode, seen) in &found { + let was = state.last.get(inode).copied(); + // A socket opened since the last sample started at zero when it was + // created, so all of its counters are traffic that happened while + // we were watching. Only sockets already open at the first sample + // are zeroed - the difference is a connection that opens and closes + // inside one interval, whose bytes would otherwise never count. + let (d_sent, d_recv) = if first { + (0, 0) + } else { + match was { + None => (seen.sent, seen.recv), + // A reused inode reads lower than it did; subtracting would + // underflow, so the new socket's own figures are the delta. + Some((s, r)) if seen.sent < s || seen.recv < r => (seen.sent, seen.recv), + Some((s, r)) => (seen.sent - s, seen.recv - r), + } + }; + let (pid, name) = match owners.get(inode) { + Some((pid, name)) => (*pid, name.clone()), + None => { + let unit = unit_name(&seen.cgroup); + ( + 0, + if unit.is_empty() { + "(unattributed)".into() + } else { + unit + }, + ) + } + }; + let row = state + .totals + .entry((pid, name.clone())) + .or_insert_with(|| Proc { + pid, + name, + ..Default::default() + }); + row.alive = true; + row.up += d_sent; + row.down += d_recv; + if gap > 0.0 { + row.up_rate += d_sent as f64 / gap; + row.down_rate += d_recv as f64 / gap; + } + } + + // Both totals are recorded every sample, so the filter is a display + // choice: o flips instantly and the chart redraws over history it + // already had rather than starting again. + if gap > 0.0 { + let mine_down: f64 = state + .totals + .values() + .filter(|r| r.pid != 0) + .map(|r| r.down_rate) + .sum(); + let mine_up: f64 = state + .totals + .values() + .filter(|r| r.pid != 0) + .map(|r| r.up_rate) + .sum(); + let all_down: f64 = state.totals.values().map(|r| r.down_rate).sum(); + let all_up: f64 = state.totals.values().map(|r| r.up_rate).sum(); + state.series.push((mine_down, mine_up, all_down, all_up)); + if state.series.len() > SERIES { + let drop = state.series.len() - SERIES; + state.series.drain(..drop); + } + } + + if let Some((rx, tx, names)) = counters { + if let Some((was_rx, was_tx)) = state.wire { + if gap > 0.0 { + state.wire_rate = ( + rx.saturating_sub(was_rx) as f64 / gap, + tx.saturating_sub(was_tx) as f64 / gap, + ); + } + } + state.wire = Some((rx, tx)); + state.wire_names = names; + } + + state.last = found.iter().map(|(k, v)| (k.clone(), (v.sent, v.recv))).collect(); + state.stamp = stamp; +} + +/// Plot a series on a dot canvas eight times finer than the cells. +/// +/// Two dots per column and four per row, which is the difference between a +/// line that steps between character rows and one that reads as a curve. +fn braille_canvas(values: &[f64], peak: f64, cols: usize, rows: usize, inverted: bool) -> Vec> { + let (px_w, px_h) = (cols * 2, rows * 4); + let mut grid = vec![vec![0u8; cols]; rows]; + let vals: Vec = values.iter().rev().take(px_w).rev().copied().collect(); + if vals.is_empty() { + return grid; + } + let point = |i: usize| -> (i64, i64) { + let x = if vals.len() == 1 { + px_w as i64 - 1 + } else { + ((i as f64) * (px_w as f64 - 1.0) / (vals.len() as f64 - 1.0)).round() as i64 + }; + let scaled = if peak > 0.0 { + (vals[i] / peak).clamp(0.0, 1.0) + } else { + 0.0 + }; + let magnitude = (scaled * (px_h as f64 - 1.0)).round() as i64; + (x, if inverted { magnitude } else { px_h as i64 - 1 - magnitude }) + }; + let mut dot = |x: i64, y: i64, grid: &mut Vec>| { + if x >= 0 && (x as usize) < px_w && y >= 0 && (y as usize) < px_h { + grid[y as usize / 4][x as usize / 2] |= BRAILLE[y as usize % 4][x as usize % 2]; + } + }; + if vals.len() == 1 { + if vals[0] > 0.0 { + let (x, y) = point(0); + dot(x, y, &mut grid); + } + return grid; + } + for i in 1..vals.len() { + // An idle stretch draws nothing at all rather than a flat line + // pinned to the axis, which would read as activity at zero. + if vals[i - 1] == 0.0 && vals[i] == 0.0 { + continue; + } + let (mut x0, mut y0) = point(i - 1); + let (x1, y1) = point(i); + let (dx, dy) = ((x1 - x0).abs(), -(y1 - y0).abs()); + let sx = if x0 < x1 { 1 } else { -1 }; + let sy = if y0 < y1 { 1 } else { -1 }; + let mut err = dx + dy; + loop { + dot(x0, y0, &mut grid); + if x0 == x1 && y0 == y1 { + break; + } + let twice = 2 * err; + if twice >= dy { + err += dy; + x0 += sx; + } + if twice <= dx { + err += dx; + y0 += sy; + } + } + } + grid +} + +fn braille_row(masks: &[u8], colour: &str) -> Vec<(String, String)> { + masks + .iter() + .map(|m| { + ( + colour.to_string(), + if *m == 0 { + " ".to_string() + } else { + char::from_u32(0x2800 + *m as u32).unwrap_or(' ').to_string() + }, + ) + }) + .collect() +} + +fn main() { + tc::maybe_help(include_str!("netwatch_help.txt")); + let mut interval = 1.0f64; + let mut limit = 0usize; + let mut external = true; + let mut mine = true; + let mut sort_live = false; + let args: Vec = std::env::args().skip(1).collect(); + let mut i = 0; + while i < args.len() { + match args[i].as_str() { + "-i" | "--interval" if i + 1 < args.len() => { + interval = args[i + 1].parse::().unwrap_or(1.0).max(0.2); + i += 2; + } + "-n" | "--limit" if i + 1 < args.len() => { + limit = args[i + 1].parse().unwrap_or(0); + i += 2; + } + "--sort" if i + 1 < args.len() => { + sort_live = args[i + 1] == "live"; + i += 2; + } + "--all-external" => { + external = false; + i += 1; + } + "--all-users" => { + mine = false; + i += 1; + } + "-V" | "--version" => { + println!("netwatch 1.1"); + return; + } + _ => i += 1, + } + } + + let p = palette(); + let state = Arc::new(Mutex::new(State { + started: now(), + ..Default::default() + })); + let poller = Arc::clone(&state); + std::thread::spawn(move || loop { + { + let mut guard = match poller.lock() { + Ok(g) => g, + Err(_) => return, + }; + sample(&mut guard, external); + } + std::thread::sleep(Duration::from_secs_f64(interval)); + }); + + tc::setup(); + let mut keyboard = tc::Keyboard::new(); + let mut selected = 0usize; + + loop { + for key in keyboard.poll() { + match key.as_str() { + "q" | "Q" => { + keyboard.restore(); + tc::restore_screen(); + return; + } + "1" => sort_live = false, + "2" => sort_live = true, + "s" | "S" | "t" | "T" => sort_live = !sort_live, + "o" | "O" => { + mine = !mine; + selected = 0; + } + "up" | "k" | "K" => selected = selected.saturating_sub(1), + "down" | "j" | "J" => selected += 1, + "r" | "R" => { + if let Ok(mut guard) = state.lock() { + guard.totals.clear(); + guard.series.clear(); + guard.started = now(); + } + } + _ => {} + } + } + + let (w, h) = tc::size(); + let guard = match state.lock() { + Ok(g) => g, + Err(_) => return, + }; + let mut rows: Vec = guard + .totals + .values() + .filter(|r| !mine || r.pid != 0) + .cloned() + .collect(); + if sort_live { + rows.sort_by(|a, b| { + (b.up_rate + b.down_rate) + .partial_cmp(&(a.up_rate + a.down_rate)) + .unwrap_or(std::cmp::Ordering::Equal) + .then((b.up + b.down).cmp(&(a.up + a.down))) + }); + } else { + rows.sort_by(|a, b| { + (b.up + b.down).cmp(&(a.up + a.down)).then( + (b.up_rate + b.down_rate) + .partial_cmp(&(a.up_rate + a.down_rate)) + .unwrap_or(std::cmp::Ordering::Equal), + ) + }); + } + if !rows.is_empty() && selected >= rows.len() { + selected = rows.len() - 1; + } + let moving = rows.iter().filter(|r| r.up_rate + r.down_rate > 0.0).count(); + let down: f64 = rows.iter().map(|r| r.down_rate).sum(); + let up: f64 = rows.iter().map(|r| r.up_rate).sum(); + + let mut out = vec![tc::title("netwatch", w, &p.accent)]; + out.push(tc::seg( + &[ + ( + p.dim.as_str(), + format!( + " {} process{}", + rows.len(), + if rows.len() == 1 { "" } else { "es" } + ), + ), + (p.dim.as_str(), format!(" · {} moving", moving)), + (p.dim.as_str(), " · ".into()), + (p.accent.as_str(), elapsed(now() - guard.started)), + (p.dim.as_str(), " · sorted by ".into()), + ( + p.accent.as_str(), + if sort_live { "live".into() } else { "total".into() }, + ), + (p.dim.as_str(), format!(" every {}s", interval)), + ], + w - 1, + )); + out.push(tc::seg( + &[ + ( + p.dim.as_str(), + if mine { + " TCP only · ".into() + } else { + " TCP only · every user · ".into() + }, + ), + (p.down.as_str(), format!("↓ {}", rate(down))), + (p.dim.as_str(), " ".into()), + (p.up.as_str(), format!("↑ {}", rate(up))), + ( + p.dim.as_str(), + if external { + " · internet only".into() + } else { + " · everything off-box".into() + }, + ), + ], + w - 1, + )); + + // What the interfaces actually moved, against what the sockets can + // explain. On a router the two differ by most of the traffic. + let (wire_rx, wire_tx) = guard.wire_rate; + let wire = wire_rx + wire_tx; + if wire > 0.0 { + let share = ((down + up) / wire).min(1.0); + let mut said = vec![ + (p.lbl.as_str(), " interfaces".to_string()), + (p.dim.as_str(), " · ".into()), + (p.down.as_str(), format!("↓ {}", rate(wire_rx))), + (p.dim.as_str(), " ".into()), + (p.up.as_str(), format!("↑ {}", rate(wire_tx))), + (p.dim.as_str(), " · ".into()), + ( + if share >= 0.9 { &p.dim } else { &p.warn }, + format!("{:.0}% of it has a socket", share * 100.0), + ), + ]; + let which = wire_label(&guard.wire_names); + let used: usize = said.iter().map(|(_, t)| t.chars().count()).sum(); + if !which.is_empty() && used + which.chars().count() + 4 <= w - 1 { + said.push((p.grid.as_str(), format!(" · {}", which))); + } + out.push(tc::seg(&said, w - 1)); + } + if !guard.err.is_empty() { + out.push(tc::seg(&[(p.bad.as_str(), format!(" ! {}", guard.err))], w - 1)); + } + out.push(String::new()); + + // The chart takes a share of the pane and the list takes the rest, + // but the list is the point: below a certain height there is no + // chart at all rather than two rows of neither. + let spare = h.saturating_sub(out.len() + 4); + let graph_h = if spare >= 20 { + 9 + } else if spare >= 15 { + 7 + } else if spare >= 11 { + 5 + } else { + 0 + }; + let series: Vec<(f64, f64)> = guard + .series + .iter() + .map(|s| if mine { (s.0, s.1) } else { (s.2, s.3) }) + .collect(); + if graph_h > 0 && !series.is_empty() { + out.push(tc::seg( + &[ + (p.lbl.as_str(), " ── PROCESS WATCH ── ".into()), + (p.up.as_str(), "↑ tx above".into()), + (p.dim.as_str(), " · ".into()), + (p.down.as_str(), "↓ rx below".into()), + ( + p.dim.as_str(), + format!(" · {} of history", elapsed(series.len() as f64 * interval)), + ), + ], + w - 1, + )); + out.extend(chart(&series, w, graph_h, &p)); + out.push(String::new()); + } + + let room = h.saturating_sub(out.len() + 3).max(1); + let show = if limit > 0 { limit.min(room) } else { room }; + if rows.is_empty() { + out.push(tc::seg( + &[( + p.dim.as_str(), + " Nothing has moved yet. Totals start at zero, so this fills as traffic happens.".into(), + )], + w - 1, + )); + } else { + out.extend(table(&rows, w, show, selected, &p)); + } + + let hints: Vec> = vec![ + vec![(p.accent.as_str(), "↑↓".into()), (p.dim.as_str(), " select".into())], + vec![(p.accent.as_str(), "↵".into()), (p.dim.as_str(), " details".into())], + vec![( + if sort_live { &p.dim } else { &p.accent }, + "[1] total".into(), + )], + vec![( + if sort_live { &p.accent } else { &p.dim }, + "[2] live".into(), + )], + vec![( + p.dim.as_str(), + format!("[o]{} others", if mine { "show" } else { "hide" }), + )], + vec![(p.dim.as_str(), "[r]ezero".into())], + vec![(p.dim.as_str(), "[q]uit".into())], + ]; + drop(guard); + let foot: Vec = tc::pack_hints(&hints, w - 2, " ") + .into_iter() + .map(|l| format!(" {}", l)) + .collect(); + while out.len() < h.saturating_sub(foot.len()) { + out.push(String::new()); + } + out.extend(foot); + tc::draw(&out, w, h); + std::thread::sleep(Duration::from_millis(300).min(Duration::from_secs_f64(interval))); + } +} + +/// Sent above the line, received below it, newest on the right. +/// +/// That way round because of the arrows: ↑ means upload and ↓ means +/// download, so upload has to be the half that goes up. +fn chart(series: &[(f64, f64)], w: usize, h: usize, p: &Palette) -> Vec { + let canvas = h.saturating_sub(3).max(2); + let up_h = (canvas / 2).max(1); + let down_h = canvas.saturating_sub(up_h).max(1); + let plot = w.saturating_sub(18).max(12); + let window: Vec<(f64, f64)> = series.iter().rev().take(plot * 2).rev().copied().collect(); + let rx: Vec = window.iter().map(|s| s.0).collect(); + let tx: Vec = window.iter().map(|s| s.1).collect(); + let rx_peak = rx.iter().cloned().fold(0.0f64, f64::max).max(1.0); + let tx_peak = tx.iter().cloned().fold(0.0f64, f64::max).max(1.0); + // Each label carries its own direction and neither is signed: rx is not + // negative traffic, it is simply the half drawn downward. + let up_label = format!("↑ {}", rate(tx_peak)); + let down_label = format!("↓ {}", rate(rx_peak)); + let lab = up_label + .chars() + .count() + .max(down_label.chars().count()) + .clamp(9, 16); + let plot = w.saturating_sub(lab + 4).max(12); + + let mut out = Vec::new(); + out.push(tc::seg( + &[ + (p.up.as_str(), format!("{:>1$} ", up_label, lab)), + (p.grid.as_str(), format!("┌{}┐", "─".repeat(plot))), + ], + w - 1, + )); + for masks in braille_canvas(&tx, tx_peak, plot, up_h, false) { + let mut line = vec![ + (p.dim.clone(), " ".repeat(lab + 1)), + (p.grid.clone(), "│".into()), + ]; + line.extend(braille_row(&masks, &p.up)); + line.push((p.grid.clone(), "│".into())); + let refs: Vec<(&str, String)> = line.iter().map(|(c, t)| (c.as_str(), t.clone())).collect(); + out.push(tc::seg(&refs, w - 1)); + } + out.push(tc::seg( + &[ + (p.dim.as_str(), format!("{:>1$} ", "0", lab)), + (p.grid.as_str(), format!("├{}┤", "─".repeat(plot))), + ], + w - 1, + )); + for masks in braille_canvas(&rx, rx_peak, plot, down_h, true) { + let mut line = vec![ + (p.dim.clone(), " ".repeat(lab + 1)), + (p.grid.clone(), "│".into()), + ]; + line.extend(braille_row(&masks, &p.down)); + line.push((p.grid.clone(), "│".into())); + let refs: Vec<(&str, String)> = line.iter().map(|(c, t)| (c.as_str(), t.clone())).collect(); + out.push(tc::seg(&refs, w - 1)); + } + out.push(tc::seg( + &[ + (p.down.as_str(), format!("{:>1$} ", down_label, lab)), + (p.grid.as_str(), format!("└{}┘", "─".repeat(plot))), + ], + w - 1, + )); + out +} + +/// The process table, dropping columns rather than clipping them. +fn table(rows: &[Proc], w: usize, limit: usize, selected: usize, p: &Palette) -> Vec { + let avail = (w - 1).saturating_sub(2 + 8 + 11); + let wide = avail >= 10 + 11 + 22; + let mid = avail >= 10 + 11; + let name_w = avail + .saturating_sub(if wide { 33 } else if mid { 11 } else { 0 }) + .clamp(8, 26); + + let mut head = vec![ + (p.dim.as_str(), format!(" {}", tc::pad("PROCESS", name_w))), + (p.dim.as_str(), format!("{:<8}", "PID")), + (p.dim.as_str(), format!("{:>11}", "TOTAL")), + ]; + if mid { + head.push((p.dim.as_str(), format!("{:>11}", "NOW"))); + } + if wide { + head.push((p.dim.as_str(), format!("{:>11}", "DOWN"))); + head.push((p.dim.as_str(), format!("{:>11}", "UP"))); + } + let mut out = vec![tc::seg(&head, w - 1)]; + + for (i, row) in rows.iter().take(limit).enumerate() { + let live = row.up_rate + row.down_rate; + let total = (row.up + row.down) as f64; + let here = i == selected; + let tint = if here { tc::bg(28, 44, 62) } else { String::new() }; + let name_c = format!( + "{}{}", + tint, + if here { + &p.accent + } else if row.alive { + &p.txt + } else { + &p.dim + } + ); + let pid_c = format!("{}{}", tint, p.dim); + let total_c = format!("{}{}", tint, if total > 0.0 { &p.txt } else { &p.dim }); + let live_c = format!("{}{}", tint, if live > 0.0 { &p.ok } else { &p.dim }); + let down_c = format!("{}{}", tint, if row.down_rate > 0.0 { &p.down } else { &p.dim }); + let up_c = format!("{}{}", tint, if row.up_rate > 0.0 { &p.up } else { &p.dim }); + let name: String = row.name.chars().take(name_w.saturating_sub(2)).collect(); + let mut line = vec![ + ( + name_c.as_str(), + format!("{} {}", if here { "▸" } else { " " }, tc::pad(&name, name_w - 1)), + ), + ( + pid_c.as_str(), + format!("{:<8}", if row.pid > 0 { row.pid.to_string() } else { "-".into() }), + ), + (total_c.as_str(), format!("{:>11}", units(total))), + ]; + if mid { + line.push((live_c.as_str(), format!("{:>11}", rate(live)))); + } + if wide { + line.push((down_c.as_str(), format!("{:>11}", rate(row.down_rate)))); + line.push((up_c.as_str(), format!("{:>11}", rate(row.up_rate)))); + } + if here { + line.push((tint.as_str(), " ".repeat(w))); + } + out.push(tc::seg(&line, w - 1)); + } + out +} + +struct Palette { + ok: String, + warn: String, + bad: String, + dim: String, + grid: String, + txt: String, + lbl: String, + accent: String, + down: String, + up: String, +} + +fn palette() -> Palette { + Palette { + ok: tc::rgb(90, 240, 160), + warn: tc::rgb(255, 200, 90), + bad: tc::rgb(255, 100, 110), + dim: tc::rgb(127, 147, 172), + grid: tc::rgb(60, 78, 98), + txt: tc::rgb(225, 235, 245), + lbl: tc::rgb(130, 165, 200), + accent: tc::rgb(150, 210, 255), + down: tc::rgb(120, 200, 255), + up: tc::rgb(255, 170, 120), + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn units_are_decimal_as_isps_quote_them() { + assert_eq!(units(1000.0), "1.0 KB"); + assert_eq!(units(2_500_000.0), "2.5 MB"); + assert_eq!(units(3_000_000_000.0), "3.0 GB"); + assert_eq!(units(512.0), "512 B"); + } + + #[test] + fn traffic_that_never_leaves_is_recognised() { + let own = vec!["10.240.0.46".to_string(), "100.89.99.102".to_string()]; + assert!(local_peer("127.0.0.1", &own)); + assert!(local_peer("::1", &own)); + // The half that is easy to miss: our own non-loopback address. + assert!(local_peer("10.240.0.46", &own)); + assert!(local_peer("::ffff:10.240.0.46", &own)); + assert!(!local_peer("10.240.0.99", &own)); + } + + #[test] + fn only_globally_routable_peers_are_off_box() { + let own = vec!["10.240.0.46".to_string()]; + assert!(off_box("160.79.104.10", &own)); + assert!(!off_box("10.0.0.5", &own)); + assert!(!off_box("172.16.0.1", &own)); + assert!(!off_box("192.168.1.1", &own)); + assert!(!off_box("100.89.99.102", &own)); + assert!(!off_box("127.0.0.1", &own)); + // 172.32 is outside the private range and really is out there. + assert!(off_box("172.32.0.1", &own)); + } + + #[test] + fn a_cgroup_names_the_daemon() { + assert_eq!(unit_name("/system.slice/tailscaled.service"), "tailscaled"); + assert_eq!( + unit_name("/system.slice/google-guest-agent.service"), + "google-guest-agent" + ); + // A login session says who is logged in, not what opened the socket. + assert_eq!(unit_name("/user.slice/user-1002.slice/session-1.scope"), ""); + assert_eq!(unit_name("/"), ""); + } + + #[test] + fn ss_fields_are_read_off_the_line() { + let line = "\t ts sack cubic bytes_sent:1669 bytes_acked:1670 bytes_received:11469 segs_out:272"; + assert_eq!(field(line, "bytes_sent:"), Some("1669".into())); + assert_eq!(field(line, "bytes_received:"), Some("11469".into())); + assert_eq!(field(line, "nothing:"), None); + } + + #[test] + fn virtual_interfaces_are_not_the_wire() { + // Counting a tunnel as well as the card counts a forwarded packet + // twice, which is the whole reason for the exclusion list. + for name in ["lo", "tailscale0", "docker0", "veth1234"] { + assert!(VIRTUAL.iter().any(|v| name.starts_with(v)), "{}", name); + } + for name in ["ens4", "eth0", "wlan0"] { + assert!(!VIRTUAL.iter().any(|v| name.starts_with(v)), "{}", name); + } + } + + #[test] + fn an_idle_series_draws_nothing() { + let grid = braille_canvas(&[0.0, 0.0, 0.0, 0.0], 1.0, 10, 2, false); + assert!(grid.iter().all(|row| row.iter().all(|c| *c == 0))); + } + + #[test] + fn a_spike_puts_dots_on_the_canvas() { + let grid = braille_canvas(&[0.0, 5.0, 0.0], 5.0, 10, 2, false); + assert!(grid.iter().any(|row| row.iter().any(|c| *c != 0))); + } + + #[test] + fn the_interface_label_names_few_and_counts_many() { + assert_eq!(wire_label(&["ens4".into()]), "ens4"); + assert_eq!(wire_label(&["ens4".into(), "eth1".into()]), "ens4, eth1"); + let many: Vec = (0..5).map(|i| format!("eth{}", i)).collect(); + assert_eq!(wire_label(&many), "5 of them"); + } +} diff --git a/rust/widgets/src/bin/netwatch_help.txt b/rust/widgets/src/bin/netwatch_help.txt new file mode 100644 index 0000000..9c86a15 --- /dev/null +++ b/rust/widgets/src/bin/netwatch_help.txt @@ -0,0 +1,25 @@ +Which processes are using the network, how much, and how fast. + +`nettop` answers this on macOS and has no equivalent here. What Linux does +have is the kernel's own per-socket accounting: `ss -tine` reports bytes_sent +and bytes_received for every TCP socket along with its inode, and the inode +appears in /proc//fd, which is what ties bytes to a process. No packet +capture, no kernel module, no root. + + netwatch [-i SECONDS] [-n COUNT] [--sort total|live] + [--all-external] [--all-users] + +Only traffic that leaves the machine is counted. Loopback is excluded, and so +is any connection to one of this machine's own addresses - talking to your own +10.x or tailnet address never reaches a wire. + +Totals start at zero: the first sample is a baseline and only what happens +after it is counted. A process that exits keeps what it used. + +TCP only, which is the honest limit of this method: ss keeps no byte counters +for UDP, so QUIC, DNS and everything Tailscale carries over WireGuard are +invisible. The interfaces line says how much of the machine's traffic the +table can actually account for. + +Keys: up/down select, 1 sorts by total, 2 by current rate, o shows the +daemons you do not own, r rezeroes, q quits. From 3545af07366f037844f58b193277e58da332ad23 Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sat, 22 Aug 2026 21:01:10 +0800 Subject: [PATCH 003/147] rust: latency and matrix, and config loading in the core Two more, both needing nothing new from the crate list beyond what the core now carries. latency keeps one ping per target running and reads it line by line, so the numbers are still ping's rather than anything this timed itself. The statistics came over as they are: jitter is the median absolute deviation, not the standard deviation, because one 400ms spike in a thousand samples is worth knowing about and is not what the link feels like - it belongs in the worst column, and the test says so. matrix computes nothing, which makes it a fair test of the drawing path, since it repaints every cell of every frame. Its randomness is eight lines of xorshift rather than a crate, seeded from the clock so two panes started together do not fall in lockstep. The core gained config loading, which is where serde_json enters: every widget reads the same file, and hand-rolling a parser thirteen times over would be a bug farm bought for nothing. The path precedence is the Python's, so one config serves both while the collection is half translated. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/Cargo.lock | 96 +++++ rust/core/Cargo.toml | 7 +- rust/core/src/lib.rs | 90 +++++ rust/widgets/Cargo.toml | 8 + rust/widgets/src/bin/latency.rs | 559 ++++++++++++++++++++++++++ rust/widgets/src/bin/latency_help.txt | 20 + rust/widgets/src/bin/matrix.rs | 218 ++++++++++ rust/widgets/src/bin/matrix_help.txt | 9 + 8 files changed, 1005 insertions(+), 2 deletions(-) create mode 100644 rust/widgets/src/bin/latency.rs create mode 100644 rust/widgets/src/bin/latency_help.txt create mode 100644 rust/widgets/src/bin/matrix.rs create mode 100644 rust/widgets/src/bin/matrix_help.txt diff --git a/rust/Cargo.lock b/rust/Cargo.lock index 6c1f615..cc8e6d6 100644 --- a/rust/Cargo.lock +++ b/rust/Cargo.lock @@ -2,17 +2,101 @@ # It is not intended for manual editing. version = 4 +[[package]] +name = "itoa" +version = "1.0.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682" + [[package]] name = "libc" version = "0.2.189" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2" +[[package]] +name = "memchr" +version = "2.8.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98" + +[[package]] +name = "proc-macro2" +version = "1.0.107" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "quote" +version = "1.0.47" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001" +dependencies = [ + "proc-macro2", +] + +[[package]] +name = "serde" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba" +dependencies = [ + "serde_core", +] + +[[package]] +name = "serde_core" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48" +dependencies = [ + "serde_derive", +] + +[[package]] +name = "serde_derive" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "serde_json" +version = "1.0.151" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14" +dependencies = [ + "itoa", + "memchr", + "serde", + "serde_core", + "zmij", +] + +[[package]] +name = "syn" +version = "3.0.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "53e9bae58849f64dfa4f5d5ae372c8341f7305f82a3868709269343628b659a3" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + [[package]] name = "toys-core" version = "0.1.0" dependencies = [ "libc", + "serde_json", ] [[package]] @@ -22,3 +106,15 @@ dependencies = [ "libc", "toys-core", ] + +[[package]] +name = "unicode-ident" +version = "1.0.24" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75" + +[[package]] +name = "zmij" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b" diff --git a/rust/core/Cargo.toml b/rust/core/Cargo.toml index 9b537ae..de54983 100644 --- a/rust/core/Cargo.toml +++ b/rust/core/Cargo.toml @@ -4,7 +4,10 @@ version.workspace = true edition.workspace = true license.workspace = true -# The terminal is an ioctl and a termios struct away; both come from libc, -# and nothing else here needs a crate at all. [dependencies] +# The terminal is an ioctl and a termios struct away, both of which are in +# libc. serde_json is here for one reason: every widget reads the same +# config file, and hand-rolling a parser thirteen times over would be a bug +# farm for no gain. libc = "0.2" +serde_json = "1" diff --git a/rust/core/src/lib.rs b/rust/core/src/lib.rs index 2c7af3a..d6ddf57 100644 --- a/rust/core/src/lib.rs +++ b/rust/core/src/lib.rs @@ -206,6 +206,96 @@ pub fn pack_hints(hints: &[Vec<(&str, String)>], width: usize, sep: &str) -> Vec lines } +/// Where settings are looked for, in order of preference. +/// +/// The same three places the Python looks, so one config file serves both +/// while the collection is half translated. +pub fn config_paths() -> Vec { + let mut found = Vec::new(); + if let Ok(env) = std::env::var("TERMINAL_TOYS_CONFIG") { + if !env.is_empty() { + found.push(std::path::PathBuf::from(env)); + } + } + let xdg = std::env::var("XDG_CONFIG_HOME").ok().filter(|s| !s.is_empty()); + let home = std::env::var("HOME").unwrap_or_default(); + let base = xdg.unwrap_or(format!("{}/.config", home)); + found.push(std::path::PathBuf::from(base).join("terminal-toys/config.json")); + if let Ok(exe) = std::env::current_exe() { + if let Some(dir) = exe.parent() { + found.push(dir.join("config.json")); + } + } + found +} + +/// One section of the config file, or an empty object. +/// +/// The first readable file wins, and a malformed one falls back to the +/// defaults rather than stopping a running panel - a widget on a wall +/// should not vanish because a comma went missing in a file it shares. +pub fn load_config(section: &str) -> serde_json::Value { + for path in config_paths() { + let text = match std::fs::read_to_string(&path) { + Ok(t) => t, + Err(_) => continue, + }; + let parsed: serde_json::Value = match serde_json::from_str(&text) { + Ok(v) => v, + Err(_) => continue, + }; + if let Some(found) = parsed.get(section) { + return found.clone(); + } + return serde_json::json!({}); + } + serde_json::json!({}) +} + +/// A setting, or the default when it is absent or the wrong shape. +pub fn cfg_f64(cfg: &serde_json::Value, key: &str, fallback: f64) -> f64 { + cfg.get(key).and_then(|v| v.as_f64()).unwrap_or(fallback) +} + +pub fn cfg_usize(cfg: &serde_json::Value, key: &str, fallback: usize) -> usize { + cfg.get(key) + .and_then(|v| v.as_u64()) + .map(|n| n as usize) + .unwrap_or(fallback) +} + +pub fn cfg_str(cfg: &serde_json::Value, key: &str, fallback: &str) -> String { + cfg.get(key) + .and_then(|v| v.as_str()) + .unwrap_or(fallback) + .to_string() +} + +pub fn cfg_strings(cfg: &serde_json::Value, key: &str, fallback: &[&str]) -> Vec { + match cfg.get(key).and_then(|v| v.as_array()) { + Some(items) if !items.is_empty() => items + .iter() + .filter_map(|v| v.as_str().map(|s| s.to_string())) + .collect(), + _ => fallback.iter().map(|s| s.to_string()).collect(), + } +} + +/// Which of these required commands are not on PATH. +pub fn missing(programs: &[&str]) -> Vec { + let path = std::env::var("PATH").unwrap_or_default(); + programs + .iter() + .filter(|p| { + !path.split(':').any(|dir| { + let candidate = std::path::Path::new(dir).join(p); + candidate.is_file() + }) + }) + .map(|p| p.to_string()) + .collect() +} + /// Non-blocking key input, decoding the sequences arrows arrive as. /// /// Returns names for special keys and the bare character otherwise, and diff --git a/rust/widgets/Cargo.toml b/rust/widgets/Cargo.toml index e15396d..616622b 100644 --- a/rust/widgets/Cargo.toml +++ b/rust/widgets/Cargo.toml @@ -15,3 +15,11 @@ path = "src/bin/ports.rs" [[bin]] name = "netwatch" path = "src/bin/netwatch.rs" + +[[bin]] +name = "latency" +path = "src/bin/latency.rs" + +[[bin]] +name = "matrix" +path = "src/bin/matrix.rs" diff --git a/rust/widgets/src/bin/latency.rs b/rust/widgets/src/bin/latency.rs new file mode 100644 index 0000000..6e92eac --- /dev/null +++ b/rust/widgets/src/bin/latency.rs @@ -0,0 +1,559 @@ +// terminal-toys - small dependency-free terminal widgets +// Copyright (C) 2026 William Li +// +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU Affero General Public License as published +// by the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU Affero General Public License for more details. +// +// You should have received a copy of the GNU Affero General Public License +// along with this program. If not, see . + +//! Multi-target latency monitor. +//! +//! A port of latency.py. One ping per target, read line by line as it +//! arrives, so the numbers are what ping measured rather than anything this +//! timed itself. + +use std::io::{BufRead, BufReader}; +use std::sync::{Arc, Mutex}; +use std::time::{Duration, SystemTime, UNIX_EPOCH}; + +use toys_core as tc; + +fn now() -> f64 { + SystemTime::now() + .duration_since(UNIX_EPOCH) + .map(|d| d.as_secs_f64()) + .unwrap_or(0.0) +} + +#[derive(Clone, Default)] +struct Target { + host: String, + label: String, + ip: String, + samples: Vec<(f64, Option)>, // (when, rtt or a loss) + down_since: Option, +} + +impl Target { + /// Round trips that arrived, newest last. + fn rtts(&self) -> Vec { + self.samples.iter().filter_map(|(_, r)| *r).collect() + } + + fn median(&self) -> Option { + let mut got = self.rtts(); + if got.is_empty() { + return None; + } + got.sort_by(|a, b| a.partial_cmp(b).unwrap()); + Some(got[got.len() / 2]) + } + + /// The spread of the middle of the distribution, not the extremes. + /// + /// A single 400ms spike in a thousand samples is worth knowing about, + /// but it is not what the link feels like, and a standard deviation + /// would let it dominate the number. + fn jitter(&self) -> Option { + let got = self.rtts(); + if got.len() < 2 { + return None; + } + let median = self.median()?; + let mut deviations: Vec = got.iter().map(|r| (r - median).abs()).collect(); + deviations.sort_by(|a, b| a.partial_cmp(b).unwrap()); + Some(deviations[deviations.len() / 2]) + } + + fn worst(&self) -> Option { + self.rtts().into_iter().fold(None, |acc: Option, r| { + Some(acc.map_or(r, |a: f64| a.max(r))) + }) + } + + fn loss(&self) -> f64 { + if self.samples.is_empty() { + return 0.0; + } + let lost = self.samples.iter().filter(|(_, r)| r.is_none()).count(); + 100.0 * lost as f64 / self.samples.len() as f64 + } +} + +fn ms(value: Option) -> String { + match value { + None => "—".into(), + Some(v) if v >= 100.0 => format!("{:.0}ms", v), + Some(v) if v >= 10.0 => format!("{:.1}ms", v), + Some(v) => format!("{:.2}ms", v), + } +} + +/// The round trip out of one ping reply line. +/// +/// Both shapes ping writes are read - `time=12.3 ms` and `time=12.3ms` - +/// and anything else on the line is left alone rather than guessed at. +fn rtt_of(line: &str) -> Option { + let at = line.find("time=")? + 5; + let rest = &line[at..]; + let end = rest + .find(|c: char| !c.is_ascii_digit() && c != '.') + .unwrap_or(rest.len()); + rest[..end].parse().ok() +} + +fn is_loss(line: &str) -> bool { + line.contains("Unreachable") || line.contains("no answer") || line.contains("Time to live") +} + +/// The address ping resolved the host to, from its first line. +fn ip_of(line: &str) -> Option { + let open = line.find('(')?; + let close = line[open..].find(')')? + open; + let inside = &line[open + 1..close]; + if inside.chars().any(|c| c.is_ascii_digit()) { + Some(inside.to_string()) + } else { + None + } +} + +/// Keep one ping running per target, forever. +fn watch(host: String, index: usize, interval: f64, window: usize, shared: Arc>>) { + loop { + let child = std::process::Command::new("ping") + .args(["-n", "-O", "-i", &interval.to_string(), &host]) + .stdout(std::process::Stdio::piped()) + .stderr(std::process::Stdio::piped()) + .spawn(); + let mut child = match child { + Ok(c) => c, + Err(_) => { + std::thread::sleep(Duration::from_secs(2)); + continue; + } + }; + let stdout = match child.stdout.take() { + Some(s) => s, + None => continue, + }; + for line in BufReader::new(stdout).lines().map_while(Result::ok) { + let mut guard = match shared.lock() { + Ok(g) => g, + Err(_) => return, + }; + let target = &mut guard[index]; + if target.ip.is_empty() { + if let Some(ip) = ip_of(&line) { + target.ip = ip; + } + } + let stamp = now(); + if let Some(rtt) = rtt_of(&line) { + target.samples.push((stamp, Some(rtt))); + target.down_since = None; + } else if is_loss(&line) { + target.samples.push((stamp, None)); + if target.down_since.is_none() { + target.down_since = Some(stamp); + } + } + if target.samples.len() > window { + let drop = target.samples.len() - window; + target.samples.drain(..drop); + } + } + let _ = child.wait(); + // ping exited - the host may have gone, or the network. Retry + // rather than leaving a dead row that never updates again. + std::thread::sleep(Duration::from_secs(2)); + } +} + +/// Log-scale plot of every target's round trip. +/// +/// Log because the targets on one screen can differ by two orders of +/// magnitude, and a linear axis renders the near one as a flat line at the +/// bottom. +fn graph(targets: &[Target], w: usize, h: usize, p: &Palette) -> Vec { + let gw = w.saturating_sub(9).max(10); + let gh = h.max(4); + let series: Vec<(usize, Vec)> = targets + .iter() + .enumerate() + .map(|(i, t)| { + let all = t.rtts(); + let start = all.len().saturating_sub(gw); + (i, all[start..].to_vec()) + }) + .filter(|(_, v)| !v.is_empty()) + .collect(); + if series.is_empty() { + return vec![tc::seg(&[(p.dim.as_str(), " collecting…".into())], w - 1)]; + } + let lo = series + .iter() + .flat_map(|(_, v)| v.iter()) + .cloned() + .fold(f64::INFINITY, f64::min) + .max(0.05) + * 0.8; + let hi = series + .iter() + .flat_map(|(_, v)| v.iter()) + .cloned() + .fold(0.0f64, f64::max) + .max(lo * 1.6) + * 1.25; + let (llo, lhi) = (lo.log10(), hi.log10()); + + let mut grid = vec![vec![(p.grid.clone(), " ".to_string()); gw]; gh]; + for (idx, values) in &series { + let glyph = SERIES[idx % SERIES.len()]; + let colour = &p.hues[idx % p.hues.len()]; + let start = gw - values.len(); + let mut previous: Option = None; + for (x, value) in values.iter().enumerate() { + let frac = (value.max(1e-3).log10() - llo) / (lhi - llo); + let y = ((1.0 - frac) * (gh as f64 - 1.0)).round().clamp(0.0, gh as f64 - 1.0) as usize; + let col = start + x; + if let Some(prev) = previous { + if prev.abs_diff(y) > 1 { + // Join consecutive samples so a series reads as a trace + // rather than as marks a row apart. + for fill in prev.min(y) + 1..prev.max(y) { + if grid[fill][col].1 == " " { + grid[fill][col] = (colour.clone(), "│".into()); + } + } + } + } + grid[y][col] = (colour.clone(), glyph.to_string()); + previous = Some(y); + } + } + + let mut out = Vec::new(); + for (y, line) in grid.iter().enumerate() { + let frac = 1.0 - (y as f64 / (gh as f64 - 1.0).max(1.0)); + let value = 10f64.powf(llo + frac * (lhi - llo)); + // Label only the top, middle and bottom: a number on every row is a + // table pretending to be an axis. + let label = if y == 0 || y == gh / 2 || y == gh - 1 { + format!("{:>7}", ms(Some(value))) + } else { + " ".repeat(7) + }; + let mut parts: Vec<(&str, String)> = + vec![(p.dim.as_str(), label), (p.grid.as_str(), "│".into())]; + for (colour, ch) in line { + parts.push((colour.as_str(), ch.clone())); + } + out.push(tc::seg(&parts, w - 1)); + } + out +} + +const SERIES: &[char] = &['●', '▲', '■', '◆', '✚', '✦']; + +fn main() { + tc::maybe_help(include_str!("latency_help.txt")); + let cfg = tc::load_config("latency"); + let hosts = tc::cfg_strings(&cfg, "hosts", &["1.1.1.1", "8.8.8.8"]); + let mut interval = tc::cfg_f64(&cfg, "interval", 0.5); + let window = tc::cfg_usize(&cfg, "window", 600); + let strip: Vec = tc::cfg_strings(&cfg, "strip_suffixes", &[]); + + let args: Vec = std::env::args().skip(1).collect(); + let mut named: Vec = Vec::new(); + let mut i = 0; + while i < args.len() { + match args[i].as_str() { + "-i" | "--interval" if i + 1 < args.len() => { + interval = args[i + 1].parse::().unwrap_or(0.5).max(0.1); + i += 2; + } + other if !other.starts_with('-') => { + named.push(other.to_string()); + i += 1; + } + _ => i += 1, + } + } + let hosts = if named.is_empty() { hosts } else { named }; + + let absent = tc::missing(&["ping"]); + if !absent.is_empty() { + cannot_start(&absent); + return; + } + + let p = palette(); + let targets: Vec = hosts + .iter() + .map(|h| Target { + host: h.clone(), + label: label_for(h, &strip), + ..Default::default() + }) + .collect(); + let shared = Arc::new(Mutex::new(targets)); + for (index, host) in hosts.iter().enumerate() { + let shared = Arc::clone(&shared); + let host = host.clone(); + std::thread::spawn(move || watch(host, index, interval, window, shared)); + } + + tc::setup(); + let mut keyboard = tc::Keyboard::new(); + loop { + for key in keyboard.poll() { + if key == "q" || key == "Q" { + keyboard.restore(); + tc::restore_screen(); + return; + } + } + let (w, h) = tc::size(); + let snapshot: Vec = match shared.lock() { + Ok(g) => g.clone(), + Err(_) => return, + }; + + let mut rows = vec![tc::title("network latency monitor", w, &p.head)]; + let live = snapshot.iter().filter(|t| t.down_since.is_none()).count(); + rows.push(tc::seg( + &[ + (p.dim.as_str(), format!(" {} targets", snapshot.len())), + (p.dim.as_str(), " · ".into()), + ( + if live == snapshot.len() { &p.ok } else { &p.bad }, + format!("{} answering", live), + ), + (p.dim.as_str(), format!(" every {}s", interval)), + ], + w - 1, + )); + rows.push(String::new()); + + let name_w = snapshot + .iter() + .map(|t| t.label.chars().count()) + .max() + .unwrap_or(8) + .clamp(8, 24); + rows.push(tc::seg( + &[ + (p.dim.as_str(), format!(" {}", tc::pad("TARGET", name_w))), + (p.dim.as_str(), format!("{:>9}", "MEDIAN")), + (p.dim.as_str(), format!("{:>9}", "JITTER")), + (p.dim.as_str(), format!("{:>9}", "WORST")), + (p.dim.as_str(), format!("{:>8}", "LOSS")), + ], + w - 1, + )); + for (i, t) in snapshot.iter().enumerate() { + let glyph = SERIES[i % SERIES.len()]; + let hue = &p.hues[i % p.hues.len()]; + let loss = t.loss(); + rows.push(tc::seg( + &[ + (hue.as_str(), format!(" {}", glyph)), + (p.txt.as_str(), tc::pad(&t.label, name_w)), + (p.txt.as_str(), format!("{:>9}", ms(t.median()))), + (p.dim.as_str(), format!("{:>9}", ms(t.jitter()))), + (p.dim.as_str(), format!("{:>9}", ms(t.worst()))), + ( + if loss > 0.0 { &p.bad } else { &p.dim }, + format!("{:>7.1}%", loss), + ), + ], + w - 1, + )); + } + rows.push(String::new()); + + let room = h.saturating_sub(rows.len() + 3); + if room >= 5 { + rows.extend(graph(&snapshot, w, room, &p)); + } + + let hints: Vec> = vec![vec![(p.dim.as_str(), "[q]uit".into())]]; + let foot: Vec = tc::pack_hints(&hints, w - 2, " ") + .into_iter() + .map(|l| format!(" {}", l)) + .collect(); + while rows.len() < h.saturating_sub(foot.len()) { + rows.push(String::new()); + } + rows.extend(foot); + tc::draw(&rows, w, h); + std::thread::sleep(Duration::from_millis(300)); + } +} + +/// A host as a person would say it, with the noise stripped off the end. +fn label_for(host: &str, strip: &[String]) -> String { + let mut label = host.to_string(); + for suffix in strip { + if let Some(base) = label.strip_suffix(suffix.as_str()) { + label = base.to_string(); + break; + } + } + label +} + +/// Draw the reason and wait, rather than exiting. +fn cannot_start(needed: &[String]) { + let bad = tc::rgb(255, 100, 110); + let dim = tc::rgb(127, 147, 172); + let txt = tc::rgb(225, 235, 245); + tc::setup(); + let mut keyboard = tc::Keyboard::new(); + loop { + for key in keyboard.poll() { + if key == "q" || key == "Q" { + keyboard.restore(); + tc::restore_screen(); + return; + } + } + let (w, h) = tc::size(); + let mut rows = vec![tc::title("latency", w, &bad), String::new()]; + rows.push(tc::seg( + &[ + (bad.as_str(), " cannot start · ".into()), + (txt.as_str(), format!("needs {}", needed.join(", "))), + ], + w - 1, + )); + rows.push(String::new()); + for line in [ + "Every figure here comes from ping: this widget times replies,", + "it does not send packets itself. With no ping there is nothing", + "to time and nothing to draw.", + ] { + rows.push(tc::seg(&[(dim.as_str(), format!(" {}", line))], w - 1)); + } + rows.push(String::new()); + rows.push(tc::seg( + &[ + (dim.as_str(), " try: ".into()), + (txt.as_str(), "apt install iputils-ping".into()), + ], + w - 1, + )); + while rows.len() < h - 1 { + rows.push(String::new()); + } + rows.push(tc::seg(&[(dim.as_str(), " [q]uit".into())], w - 1)); + tc::draw(&rows, w, h); + std::thread::sleep(Duration::from_millis(200)); + } +} + +struct Palette { + ok: String, + bad: String, + dim: String, + grid: String, + txt: String, + head: String, + hues: Vec, +} + +fn palette() -> Palette { + Palette { + ok: tc::rgb(90, 240, 160), + bad: tc::rgb(255, 100, 110), + dim: tc::rgb(127, 147, 172), + grid: tc::rgb(60, 78, 98), + txt: tc::rgb(225, 235, 245), + head: tc::rgb(90, 220, 255), + hues: vec![ + tc::rgb(120, 200, 255), + tc::rgb(150, 230, 180), + tc::rgb(220, 170, 255), + tc::rgb(160, 190, 240), + tc::rgb(200, 220, 150), + tc::rgb(240, 180, 210), + ], + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn a_reply_gives_up_its_round_trip() { + let line = "64 bytes from 1.1.1.1: icmp_seq=1 ttl=57 time=12.3 ms"; + assert_eq!(rtt_of(line), Some(12.3)); + // The other shape ping writes, without the space. + assert_eq!(rtt_of("... time=0.45ms"), Some(0.45)); + assert_eq!(rtt_of("PING example (1.2.3.4) 56 bytes"), None); + } + + #[test] + fn losses_are_recognised_but_not_timed() { + assert!(is_loss("From 10.0.0.1 icmp_seq=2 Destination Net Unreachable")); + assert!(is_loss("no answer yet for icmp_seq=3")); + assert!(!is_loss("64 bytes from 1.1.1.1: time=1 ms")); + } + + #[test] + fn the_resolved_address_is_taken_from_the_header() { + assert_eq!( + ip_of("PING one.one.one.one (1.1.1.1) 56(84) bytes of data."), + Some("1.1.1.1".into()) + ); + assert_eq!(ip_of("64 bytes from host: time=1 ms"), None); + } + + #[test] + fn jitter_is_the_middle_of_the_spread_not_the_extremes() { + let mut t = Target::default(); + // Nine steady samples and one wild spike: the spike belongs in + // worst, and must not be allowed to define jitter. + for v in [10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 400.0] { + t.samples.push((0.0, Some(v))); + } + assert_eq!(t.median(), Some(10.0)); + assert_eq!(t.jitter(), Some(0.0)); + assert_eq!(t.worst(), Some(400.0)); + } + + #[test] + fn loss_counts_the_unanswered() { + let mut t = Target::default(); + t.samples.push((0.0, Some(10.0))); + t.samples.push((0.0, None)); + t.samples.push((0.0, Some(12.0))); + t.samples.push((0.0, None)); + assert_eq!(t.loss(), 50.0); + } + + #[test] + fn milliseconds_gain_precision_as_they_shrink() { + assert_eq!(ms(Some(123.4)), "123ms"); + assert_eq!(ms(Some(12.34)), "12.3ms"); + assert_eq!(ms(Some(1.234)), "1.23ms"); + assert_eq!(ms(None), "—"); + } + + #[test] + fn a_suffix_is_stripped_from_the_label() { + let strip = vec![".example.internal".to_string()]; + assert_eq!(label_for("box.example.internal", &strip), "box"); + assert_eq!(label_for("1.1.1.1", &strip), "1.1.1.1"); + } +} diff --git a/rust/widgets/src/bin/latency_help.txt b/rust/widgets/src/bin/latency_help.txt new file mode 100644 index 0000000..e533f09 --- /dev/null +++ b/rust/widgets/src/bin/latency_help.txt @@ -0,0 +1,20 @@ +Multi-target latency monitor. + +Continuously pings every target, and shows per-target statistics and a +log-scale graph of every target at once. + + latency [-i SECONDS] [HOST...] + +One ping per target, read line by line as it arrives, so the numbers are what +ping measured rather than anything this timed itself. + +Jitter is the median absolute deviation, not the standard deviation: a single +400ms spike in a thousand samples is worth knowing about, but it is not what +the link feels like, and a standard deviation would let it dominate. The spike +is in the worst column instead. + +The graph is log-scale, because targets on one screen can differ by two orders +of magnitude and a linear axis draws the near one as a flat line along the +bottom. + +Keys: q quits. diff --git a/rust/widgets/src/bin/matrix.rs b/rust/widgets/src/bin/matrix.rs new file mode 100644 index 0000000..0d3eb81 --- /dev/null +++ b/rust/widgets/src/bin/matrix.rs @@ -0,0 +1,218 @@ +// terminal-toys - small dependency-free terminal widgets +// Copyright (C) 2026 William Li +// +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU Affero General Public License as published +// by the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU Affero General Public License for more details. +// +// You should have received a copy of the GNU Affero General Public License +// along with this program. If not, see . + +//! Digital rain. +//! +//! The one widget in the collection that computes nothing at all. It just +//! looks good, and it knows it - and it is a fair test of the drawing path, +//! since it repaints every cell of every frame. + +use std::time::{Duration, SystemTime, UNIX_EPOCH}; + +use toys_core as tc; + +const GLYPHS: &str = "ｱｲｳｴｵｶｷｸｹｺｻｼｽｾｿﾀﾁﾂﾃﾄﾅﾆﾇﾈﾉﾊﾋﾌﾍﾎﾏﾐﾑﾒﾓﾔﾕﾖﾗﾘﾙﾚﾛﾜﾝ0123456789ABCDEF<>*+=$#%&@"; + +/// A tiny xorshift, because the rain does not need a crate to be random. +/// +/// Seeded from the clock, so two panes started together do not fall in +/// lockstep - which they would with a fixed seed, and which looks wrong +/// immediately. +struct Rng(u64); + +impl Rng { + fn new() -> Rng { + let seed = SystemTime::now() + .duration_since(UNIX_EPOCH) + .map(|d| d.as_nanos() as u64) + .unwrap_or(0x2545F4914F6CDD1D); + Rng(seed | 1) + } + + fn next(&mut self) -> u64 { + let mut x = self.0; + x ^= x << 13; + x ^= x >> 7; + x ^= x << 17; + self.0 = x; + x + } + + fn float(&mut self) -> f64 { + (self.next() >> 11) as f64 / (1u64 << 53) as f64 + } + + fn range(&mut self, lo: f64, hi: f64) -> f64 { + lo + self.float() * (hi - lo) + } + + fn below(&mut self, n: usize) -> usize { + if n == 0 { + 0 + } else { + (self.next() % n as u64) as usize + } + } +} + +struct Drop { + y: f64, + speed: f64, + length: usize, +} + +impl Drop { + fn new(h: usize, rng: &mut Rng) -> Drop { + Drop { + y: -rng.range(0.0, h as f64 * 1.5), + speed: rng.range(0.25, 1.15), + length: rng.below(std::cmp::max(6, h)) + std::cmp::max(4, h / 5), + } + } +} + +/// The trail's colour at a given distance from the head, 1 being closest. +fn shade(level: f64) -> String { + let g = (60.0 + 175.0 * level) as u8; + tc::rgb((10.0 + 20.0 * level) as u8, g, (30.0 + 50.0 * level) as u8) +} + +fn main() { + tc::maybe_help(include_str!("matrix_help.txt")); + let head = tc::rgb(210, 255, 225); + let near = tc::rgb(120, 255, 170); + let glyphs: Vec = GLYPHS.chars().collect(); + let mut rng = Rng::new(); + + tc::setup(); + let mut keyboard = tc::Keyboard::new(); + let (mut w, mut h) = tc::size(); + let mut drops: Vec = (0..w).map(|_| Drop::new(h, &mut rng)).collect(); + // Glyphs mutate in place, independently of the drops falling over them, + // which is what stops the rain reading as a repeating pattern. + let mut field: Vec> = (0..h) + .map(|_| (0..w).map(|_| glyphs[rng.below(glyphs.len())]).collect()) + .collect(); + + loop { + for key in keyboard.poll() { + if key == "q" || key == "Q" { + keyboard.restore(); + tc::restore_screen(); + return; + } + } + let (nw, nh) = tc::size(); + if (nw, nh) != (w, h) { + w = nw; + h = nh; + drops = (0..w).map(|_| Drop::new(h, &mut rng)).collect(); + field = (0..h) + .map(|_| (0..w).map(|_| glyphs[rng.below(glyphs.len())]).collect()) + .collect(); + } + + // A handful of cells change character every frame, wherever they + // happen to be. + for _ in 0..(w * h / 40).max(1) { + let y = rng.below(h); + let x = rng.below(w); + field[y][x] = glyphs[rng.below(glyphs.len())]; + } + + let mut rows: Vec = vec![String::new(); h]; + let mut cells: Vec> = + vec![vec![(String::new(), ' '); w]; h]; + for (x, drop) in drops.iter_mut().enumerate() { + drop.y += drop.speed; + if drop.y - drop.length as f64 > h as f64 { + *drop = Drop::new(h, &mut rng); + drop.y = -(drop.length as f64); + } + for back in 0..drop.length { + let y = drop.y as isize - back as isize; + if y < 0 || y >= h as isize { + continue; + } + let level = 1.0 - (back as f64 / drop.length as f64); + let colour = if back == 0 { + head.clone() + } else if back == 1 { + near.clone() + } else { + shade(level) + }; + cells[y as usize][x] = (colour, field[y as usize][x]); + } + } + for (y, line) in cells.iter().enumerate() { + let parts: Vec<(&str, String)> = line + .iter() + .map(|(colour, ch)| { + ( + colour.as_str(), + if colour.is_empty() { + " ".to_string() + } else { + ch.to_string() + }, + ) + }) + .collect(); + rows[y] = tc::seg(&parts, w); + } + tc::draw(&rows, w, h); + std::thread::sleep(Duration::from_millis(55)); + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn the_trail_fades_from_the_head() { + // Closer to the head is brighter; the far end is nearly dark. + let bright = shade(1.0); + let faint = shade(0.0); + assert_ne!(bright, faint); + assert!(bright.contains("235"), "head shade was {:?}", bright); + assert!(faint.contains("60"), "tail shade was {:?}", faint); + } + + #[test] + fn two_instances_do_not_fall_in_lockstep() { + let mut a = Rng::new(); + std::thread::sleep(std::time::Duration::from_millis(2)); + let mut b = Rng::new(); + let left: Vec = (0..4).map(|_| a.next()).collect(); + let right: Vec = (0..4).map(|_| b.next()).collect(); + assert_ne!(left, right, "a fixed seed would sync every pane"); + } + + #[test] + fn random_values_stay_inside_their_bounds() { + let mut rng = Rng::new(); + for _ in 0..500 { + let f = rng.float(); + assert!((0.0..1.0).contains(&f)); + let r = rng.range(0.25, 1.15); + assert!((0.25..=1.15).contains(&r)); + assert!(rng.below(10) < 10); + } + assert_eq!(rng.below(0), 0, "an empty range must not divide by zero"); + } +} diff --git a/rust/widgets/src/bin/matrix_help.txt b/rust/widgets/src/bin/matrix_help.txt new file mode 100644 index 0000000..015152c --- /dev/null +++ b/rust/widgets/src/bin/matrix_help.txt @@ -0,0 +1,9 @@ +Digital rain. + +Falling glyphs with truecolor fade trails: near-white head, bright green +shoulder, and a smooth decay over each drop length. Glyphs mutate in place +independently of the drops, and the field reflows on terminal resize. + + matrix + +Keys: q quits. From a50783f467b8b50203c8bda4d5b4be695a68998e Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sat, 22 Aug 2026 21:09:55 +0800 Subject: [PATCH 004/147] rust: link ported Fifth widget, and the fiddliest parsing so far. `ss` mixes two shapes on one line - key:value pairs and space-separated ones like `delivery_rate 45107960bps` - and both are read, with anything unrecognised left alone rather than guessed at. The traps the Python hit are carried over with it: ::ffff:10.0.0.1 is unwrapped before the loopback filter sees it, or ::ffff:127.0.0.1 walks straight past and puts a 22-microsecond local socket on a log chart, flattening every real session against the ceiling. And the chart still condenses by median rather than mean, so one stall cannot define a column. Two differences the side-by-side caught, neither visible from reading the code. The table header had drifted to columns of my own naming; it is the Python's now, word for word, because the two have to sit in a wall together and read as one widget. And ms() rounds on link.py's own scale, which drops to microseconds below one - a loopback socket reads 22us, and 0.02ms hides what that means. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/widgets/Cargo.toml | 4 + rust/widgets/src/bin/link.rs | 793 +++++++++++++++++++++++++++++ rust/widgets/src/bin/link_help.txt | 17 + 3 files changed, 814 insertions(+) create mode 100644 rust/widgets/src/bin/link.rs create mode 100644 rust/widgets/src/bin/link_help.txt diff --git a/rust/widgets/Cargo.toml b/rust/widgets/Cargo.toml index 616622b..07b0f05 100644 --- a/rust/widgets/Cargo.toml +++ b/rust/widgets/Cargo.toml @@ -23,3 +23,7 @@ path = "src/bin/latency.rs" [[bin]] name = "matrix" path = "src/bin/matrix.rs" + +[[bin]] +name = "link" +path = "src/bin/link.rs" diff --git a/rust/widgets/src/bin/link.rs b/rust/widgets/src/bin/link.rs new file mode 100644 index 0000000..4bcbcd4 --- /dev/null +++ b/rust/widgets/src/bin/link.rs @@ -0,0 +1,793 @@ +// terminal-toys - small dependency-free terminal widgets +// Copyright (C) 2026 William Li +// +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU Affero General Public License as published +// by the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU Affero General Public License for more details. +// +// You should have received a copy of the GNU Affero General Public License +// along with this program. If not, see . + +//! How good the connection is between here and whoever is connected to it. +//! +//! A port of link.py. Every other network widget in the collection measures +//! a path it chose; this one measures the path you are on, and it sends +//! nothing to do it - `ss -tin` reports what the kernel has already +//! measured for each established socket. + +use std::collections::HashMap; +use std::sync::{Arc, Mutex}; +use std::time::Duration; + +use toys_core as tc; + +const IDLE_AFTER: f64 = 300.0; +const SPARK: &[char] = &['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█']; +const SERIES: &[char] = &['●', '▲', '■', '◆', '✚', '✦']; + +#[derive(Clone, Default)] +struct Session { + peer: String, + ip: String, + port: u16, + rtt: Option, + jitter: Option, + floor: Option, + sent: f64, + recv: f64, + retrans_bytes: f64, + delivery: Option, + cwnd: Option, + mss: Option, + lastsnd: Option, + lastrcv: Option, + raw: HashMap, +} + +fn run(args: &[&str]) -> String { + match std::process::Command::new(args[0]).args(&args[1..]).output() { + Ok(out) if out.status.success() => String::from_utf8_lossy(&out.stdout).to_string(), + _ => String::new(), + } +} + +/// Ports this machine accepts connections on. +/// +/// Inbound is defined as "arrived at a port we listen on" rather than by a +/// list of numbers, so SSH, a terminal server and anything else that +/// accepts sessions are all found without being named. +fn listening_ports() -> Vec { + let mut ports = Vec::new(); + for line in run(&["ss", "-tlnH"]).lines() { + let cols: Vec<&str> = line.split_whitespace().collect(); + if let Some(local) = cols.get(3) { + if let Some((_, port)) = local.rsplit_once(':') { + if let Ok(p) = port.parse() { + ports.push(p); + } + } + } + } + ports +} + +/// The kernel's own numbers for one socket. +/// +/// `ss` mixes two shapes on that line: `key:value` pairs and +/// space-separated ones like `delivery_rate 45107960bps`. Both are read; +/// anything unknown is left alone rather than guessed at. +fn parse_metrics(text: &str) -> HashMap { + let mut out = HashMap::new(); + let words: Vec<&str> = text.split_whitespace().collect(); + for key in ["send", "pacing_rate", "delivery_rate"] { + if let Some(at) = words.iter().position(|w| *w == key) { + if let Some(value) = words.get(at + 1) { + if let Some(bps) = value.strip_suffix("bps") { + out.insert(key.to_string(), bps.to_string()); + } + } + } + } + for word in &words { + if let Some((key, value)) = word.split_once(':') { + out.insert(key.to_string(), value.to_string()); + } + } + out +} + +fn num(map: &HashMap, key: &str) -> Option { + map.get(key).and_then(|v| v.parse().ok()) +} + +/// One entry per established inbound connection, with its metrics. +fn sessions() -> Vec { + let ports = listening_ports(); + if ports.is_empty() { + return Vec::new(); + } + let text = run(&["ss", "-tinH", "state", "established"]); + let mut found = Vec::new(); + let mut head: Option> = None; + for line in text.lines() { + if !line.starts_with('\t') && !line.starts_with(' ') { + head = Some(line.split_whitespace().map(|s| s.to_string()).collect()); + continue; + } + let cols = match &head { + Some(c) if c.len() >= 4 => c.clone(), + _ => continue, + }; + let (local, peer) = (&cols[2], &cols[3]); + let lport: u16 = match local.rsplit_once(':').and_then(|(_, p)| p.parse().ok()) { + Some(p) => p, + None => { + head = None; + continue; + } + }; + let (peer_host, peer_port) = match peer.rsplit_once(':') { + Some((h, p)) => (h.trim_matches(|c| c == '[' || c == ']'), p), + None => { + head = None; + continue; + } + }; + // ::ffff:10.0.0.1 is an IPv4 address wearing an IPv6 hat - the same + // machine, the same session - so it is unwrapped before anything + // else looks at it. Left wrapped, ::ffff:127.0.0.1 walked straight + // past the loopback filter and put a 22-microsecond local socket on + // the chart, flattening every real session against the ceiling. + let peer_ip = peer_host.strip_prefix("::ffff:").unwrap_or(peer_host); + if !ports.contains(&lport) || peer_ip.starts_with("127.") || peer_ip.starts_with("::1") { + head = None; + continue; + } + let m = parse_metrics(line); + let rtt_pair = m.get("rtt").cloned().unwrap_or_default(); + let mut halves = rtt_pair.split('/'); + found.push(Session { + peer: format!("{}:{}", peer_ip, peer_port), + ip: peer_ip.to_string(), + port: lport, + rtt: halves.next().and_then(|v| v.parse().ok()), + jitter: halves.next().and_then(|v| v.parse().ok()), + floor: num(&m, "minrtt"), + sent: num(&m, "bytes_sent").unwrap_or(0.0), + recv: num(&m, "bytes_received").unwrap_or(0.0), + retrans_bytes: num(&m, "bytes_retrans").unwrap_or(0.0), + delivery: num(&m, "delivery_rate"), + cwnd: num(&m, "cwnd"), + mss: num(&m, "mss"), + lastsnd: num(&m, "lastsnd"), + lastrcv: num(&m, "lastrcv"), + raw: m, + }); + head = None; + } + found +} + +/// Who is logged in from where, to put a name against an address. +fn who() -> HashMap> { + let mut seen: HashMap> = HashMap::new(); + for line in run(&["who"]).lines() { + let cols: Vec<&str> = line.split_whitespace().collect(); + if cols.len() < 2 { + continue; + } + let user = cols[0]; + // The address is in parentheses at the end, where there is one. + if let Some(open) = line.rfind('(') { + if let Some(close) = line[open..].find(')') { + let host = &line[open + 1..open + close]; + if !host.is_empty() { + let names = seen.entry(host.to_string()).or_default(); + if !names.iter().any(|n| n == user) { + names.push(user.to_string()); + } + } + } + } + } + seen +} + +fn rate(n: Option) -> String { + let v = match n { + Some(v) if v > 0.0 => v, + _ => return "—".into(), + }; + for (suffix, scale) in [("Gbps", 1e9), ("Mbps", 1e6), ("Kbps", 1e3)] { + if v >= scale { + return format!("{:.1}{}", v / scale, suffix); + } + } + format!("{:.0}bps", v) +} + +/// Milliseconds on link.py's own scale, which drops to microseconds below +/// one: a loopback socket reads 22us, and 0.02ms hides what that means. +fn ms(value: Option) -> String { + match value { + None => "—".into(), + Some(v) if v >= 100.0 => format!("{}ms", v.round() as i64), + Some(v) if v >= 10.0 => format!("{:.0}ms", v), + Some(v) if v >= 1.0 => format!("{:.1}ms", v), + Some(v) => format!("{}µs", (v * 1000.0).round() as i64), + } +} + +/// A duration in milliseconds, as a person would say it. +fn span(milliseconds: Option) -> String { + let s = match milliseconds { + Some(v) => v / 1000.0, + None => return "—".into(), + }; + if s < 90.0 { + format!("{}s", s as i64) + } else if s < 5400.0 { + format!("{}m", (s / 60.0) as i64) + } else if s < 172_800.0 { + format!("{}h", (s / 3600.0) as i64) + } else { + format!("{}d", (s / 86400.0) as i64) + } +} + +fn sparkline(values: &[f64], width: usize) -> String { + if values.is_empty() { + return String::new(); + } + let window: Vec = values.iter().rev().take(width).rev().copied().collect(); + let hi = window.iter().cloned().fold(0.0f64, f64::max).max(1e-9); + window + .iter() + .map(|v| { + let level = ((v / hi) * (SPARK.len() - 1) as f64).round() as usize; + SPARK[level.min(SPARK.len() - 1)] + }) + .collect() +} + +/// Fit samples to the columns available, by median. +/// +/// A fifteen-minute window at a two-second poll is 450 readings and a pane +/// is eighty columns wide, so something has to give. The median of each +/// bucket is the typical round-trip over that slice. +fn condense(values: &[f64], columns: usize) -> Vec { + if values.len() <= columns || columns < 1 { + return values.to_vec(); + } + let mut out = Vec::with_capacity(columns); + for i in 0..columns { + let from = i * values.len() / columns; + let to = (i + 1) * values.len() / columns; + let mut chunk: Vec = values[from..to].to_vec(); + if chunk.is_empty() { + continue; + } + chunk.sort_by(|a, b| a.partial_cmp(b).unwrap()); + out.push(chunk[chunk.len() / 2]); + } + out +} + +fn window_label(seconds: f64) -> String { + if seconds < 60.0 { + format!("{}s", seconds as i64) + } else if seconds < 3600.0 { + format!("{}m", (seconds / 60.0).round() as i64) + } else { + format!("{}h", (seconds / 3600.0).round() as i64) + } +} + +struct State { + rows: Vec, + names: HashMap>, + history: HashMap>, + err: String, +} + +fn main() { + tc::maybe_help(include_str!("link_help.txt")); + let cfg = tc::load_config("link"); + let refresh = tc::cfg_f64(&cfg, "refresh", 2.0).max(0.5); + let windows: Vec = { + let got = cfg + .get("windows") + .and_then(|v| v.as_array()) + .map(|a| a.iter().filter_map(|v| v.as_f64()).collect::>()) + .unwrap_or_default(); + if got.is_empty() { + vec![60.0, 300.0, 900.0, 3600.0] + } else { + got + } + }; + // Retention has to cover the longest span on offer, or w would cycle to + // a window the samples could never fill. + let history_len = ((windows.iter().cloned().fold(0.0f64, f64::max) / refresh) as usize + 2) + .max(tc::cfg_usize(&cfg, "history", 120)); + + let absent = tc::missing(&["ss"]); + if !absent.is_empty() { + hold(&absent); + return; + } + + let p = palette(); + let state = Arc::new(Mutex::new(State { + rows: Vec::new(), + names: HashMap::new(), + history: HashMap::new(), + err: String::new(), + })); + let poller = Arc::clone(&state); + std::thread::spawn(move || loop { + let found = sessions(); + let names = who(); + { + let mut guard = match poller.lock() { + Ok(g) => g, + Err(_) => return, + }; + for row in &found { + if let Some(rtt) = row.rtt { + let series = guard.history.entry(row.peer.clone()).or_default(); + series.push(rtt); + if series.len() > history_len { + let drop = series.len() - history_len; + series.drain(..drop); + } + } + } + guard.rows = found; + guard.names = names; + } + std::thread::sleep(Duration::from_secs_f64(refresh)); + }); + + tc::setup(); + let mut keyboard = tc::Keyboard::new(); + let (mut selected, mut hide_idle, mut span_at) = (0usize, false, 0usize); + + loop { + for key in keyboard.poll() { + match key.as_str() { + "q" | "Q" => { + keyboard.restore(); + tc::restore_screen(); + return; + } + "up" | "k" | "K" => selected = selected.saturating_sub(1), + "down" | "j" | "J" => selected += 1, + "o" | "O" => hide_idle = !hide_idle, + "w" | "W" => span_at = (span_at + 1) % windows.len(), + _ => {} + } + } + + let (w, h) = tc::size(); + let guard = match state.lock() { + Ok(g) => g, + Err(_) => return, + }; + let shown: Vec = guard + .rows + .iter() + .filter(|r| !(hide_idle && r.lastrcv.unwrap_or(0.0) > IDLE_AFTER * 1000.0)) + .cloned() + .collect(); + if !shown.is_empty() && selected >= shown.len() { + selected = shown.len() - 1; + } + let window = windows[span_at]; + + let mut rows = vec![tc::title("connections", w, &p.link)]; + rows.push(tc::seg( + &[ + (p.dim.as_str(), format!(" {} inbound", guard.rows.len())), + ( + p.dim.as_str(), + " · measured by the kernel, nothing sent".into(), + ), + (p.dim.as_str(), format!(" every {}s", refresh)), + ], + w - 1, + )); + if !guard.err.is_empty() { + rows.push(tc::seg(&[(p.bad.as_str(), format!(" ! {}", guard.err))], w - 1)); + } + rows.push(String::new()); + + if guard.rows.is_empty() { + rows.push(tc::seg( + &[( + p.dim.as_str(), + " No inbound sessions on a listening port.".into(), + )], + w - 1, + )); + rows.push(tc::seg( + &[( + p.dim.as_str(), + " Nothing is connected to this machine, or ss cannot see it.".into(), + )], + w - 1, + )); + } else { + rows.extend(table(&shown, &guard, w, selected, &p)); + rows.push(String::new()); + let room = h.saturating_sub(rows.len() + 4); + if room >= 5 { + rows.extend(graph(&shown, &guard.history, w, room, window, refresh, &p)); + rows.push(tc::seg( + &[ + (p.dim.as_str(), " ".repeat(7)), + (p.grid.as_str(), format!("└{}", "─".repeat(w.saturating_sub(9).max(10)))), + ], + w - 1, + )); + let covered = plotted_span(&shown, &guard.history, window, refresh, w); + rows.push(tc::seg( + &[ + (p.dim.as_str(), format!(" {} ago", window_label(covered))), + (p.dim.as_str(), " ".repeat(w.saturating_sub(26).max(1))), + (p.dim.as_str(), "now".into()), + ], + w - 1, + )); + } + } + + let hints: Vec> = vec![ + vec![(p.accent.as_str(), "↑↓".into()), (p.dim.as_str(), " select".into())], + vec![ + (p.accent.as_str(), "[w]".into()), + (p.dim.as_str(), format!(" {}", window_label(window))), + ], + vec![( + p.dim.as_str(), + format!("[o]{} idle", if hide_idle { "show" } else { "hide" }), + )], + vec![(p.dim.as_str(), "[q]uit".into())], + ]; + drop(guard); + let foot: Vec = tc::pack_hints(&hints, w - 2, " ") + .into_iter() + .map(|l| format!(" {}", l)) + .collect(); + while rows.len() < h.saturating_sub(foot.len()) { + rows.push(String::new()); + } + rows.extend(foot); + tc::draw(&rows, w, h); + std::thread::sleep(Duration::from_millis(300)); + } +} + +fn plotted_span( + rows: &[Session], + history: &HashMap>, + window: f64, + refresh: f64, + w: usize, +) -> f64 { + let _ = w; + let longest = rows + .iter() + .filter_map(|r| history.get(&r.peer).map(|h| h.len())) + .max() + .unwrap_or(0); + let capped = longest.min((window / refresh).round() as usize); + capped as f64 * refresh +} + +fn table(rows: &[Session], state: &State, w: usize, selected: usize, p: &Palette) -> Vec { + // The Python's header, column for column: the two have to sit side by + // side in a wall and read as the same widget. + let wide = w >= 74; + let name_w = 20usize; + let mut out = vec![tc::seg( + &[ + (p.dim.as_str(), " PEER".into()), + (p.dim.as_str(), " ".repeat(14)), + (p.dim.as_str(), " NOW FLOOR JITTER LOSS".into()), + (p.dim.as_str(), if wide { " ACHIEVED".into() } else { String::new() }), + (p.dim.as_str(), if wide { " IDLE".into() } else { String::new() }), + ], + w - 1, + )]; + for (i, row) in rows.iter().enumerate() { + let here = i == selected; + let tint = if here { tc::bg(28, 44, 62) } else { String::new() }; + let hue = &p.hues[i % p.hues.len()]; + let glyph = SERIES[i % SERIES.len()]; + let who = state + .names + .get(&row.ip) + .map(|names| names.join(",")) + .unwrap_or_default(); + let label = if who.is_empty() { + row.ip.clone() + } else { + format!("{} {}", row.ip, who) + }; + let loss = if row.sent > 0.0 { + 100.0 * row.retrans_bytes / row.sent + } else { + 0.0 + }; + let name_c = format!("{}{}", tint, hue); + let txt_c = format!("{}{}", tint, p.txt); + let dim_c = format!("{}{}", tint, p.dim); + let loss_c = format!("{}{}", tint, if loss > 0.5 { &p.bad } else { &p.dim }); + let idle = [row.lastsnd, row.lastrcv] + .into_iter() + .flatten() + .fold(None, |acc: Option, v| Some(acc.map_or(v, |a| a.min(v)))); + let mut line = vec![ + (name_c.as_str(), format!(" {} ", glyph)), + (txt_c.as_str(), tc::pad(&label, name_w)), + (txt_c.as_str(), format!("{:>7}", ms(row.rtt))), + (dim_c.as_str(), format!("{:>8}", ms(row.floor))), + (dim_c.as_str(), format!("{:>8}", ms(row.jitter))), + (loss_c.as_str(), format!("{:>7.2}%", loss)), + ]; + if wide { + line.push((dim_c.as_str(), format!("{:>10}", rate(row.delivery)))); + line.push((dim_c.as_str(), format!("{:>7}", span(idle)))); + } + if here { + line.push((tint.as_str(), " ".repeat(w))); + } + out.push(tc::seg(&line, w - 1)); + } + out +} + +/// Log-scale multi-series plot of round-trip time. +fn graph( + rows: &[Session], + history: &HashMap>, + w: usize, + h: usize, + window: f64, + refresh: f64, + p: &Palette, +) -> Vec { + let gw = w.saturating_sub(9).max(10); + let gh = h.max(4); + let want = ((window / refresh).round() as usize).max(1); + let series: Vec<(usize, Vec)> = rows + .iter() + .enumerate() + .filter_map(|(i, row)| { + let all = history.get(&row.peer)?; + let start = all.len().saturating_sub(want); + let vals = condense(&all[start..], gw); + if vals.is_empty() { + None + } else { + Some((i, vals)) + } + }) + .collect(); + if series.is_empty() { + return vec![tc::seg(&[(p.dim.as_str(), " collecting…".into())], w - 1)]; + } + let lo = series + .iter() + .flat_map(|(_, v)| v.iter()) + .cloned() + .fold(f64::INFINITY, f64::min) + .max(0.05) + * 0.8; + let hi = (series + .iter() + .flat_map(|(_, v)| v.iter()) + .cloned() + .fold(0.0f64, f64::max) + * 1.25) + .max(lo * 1.6); + let (llo, lhi) = (lo.log10(), hi.log10()); + + let mut grid = vec![vec![(p.grid.clone(), ' '); gw]; gh]; + for (idx, values) in &series { + let glyph = SERIES[idx % SERIES.len()]; + let colour = &p.hues[idx % p.hues.len()]; + let start = gw - values.len(); + let mut previous: Option = None; + for (x, value) in values.iter().enumerate() { + let frac = (value.max(1e-3).log10() - llo) / (lhi - llo); + let y = ((1.0 - frac) * (gh as f64 - 1.0)).round().clamp(0.0, gh as f64 - 1.0) as usize; + let col = start + x; + if let Some(prev) = previous { + if prev.abs_diff(y) > 1 { + for fill in prev.min(y) + 1..prev.max(y) { + if grid[fill][col].1 == ' ' { + grid[fill][col] = (colour.clone(), '│'); + } + } + } + } + grid[y][col] = (colour.clone(), glyph); + previous = Some(y); + } + } + + let mut out = Vec::new(); + for (y, line) in grid.iter().enumerate() { + let frac = 1.0 - (y as f64 / (gh as f64 - 1.0).max(1.0)); + let value = 10f64.powf(llo + frac * (lhi - llo)); + let label = if y == 0 || y == gh / 2 || y == gh - 1 { + format!("{:>7}", ms(Some(value))) + } else { + " ".repeat(7) + }; + let mut parts: Vec<(&str, String)> = + vec![(p.dim.as_str(), label), (p.grid.as_str(), "│".into())]; + for (colour, ch) in line { + parts.push((colour.as_str(), ch.to_string())); + } + out.push(tc::seg(&parts, w - 1)); + } + out +} + +/// Draw the reason and wait, rather than exiting. +fn hold(needed: &[String]) { + let bad = tc::rgb(255, 100, 110); + let dim = tc::rgb(127, 147, 172); + let txt = tc::rgb(225, 235, 245); + tc::setup(); + let mut keyboard = tc::Keyboard::new(); + loop { + for key in keyboard.poll() { + if key == "q" || key == "Q" { + keyboard.restore(); + tc::restore_screen(); + return; + } + } + let (w, h) = tc::size(); + let mut rows = vec![tc::title("connections", w, &bad), String::new()]; + rows.push(tc::seg( + &[ + (bad.as_str(), " cannot start · ".into()), + (txt.as_str(), format!("needs {}", needed.join(", "))), + ], + w - 1, + )); + rows.push(String::new()); + for line in [ + "ss reads the kernel's own per-socket metrics, which is where", + "every figure here comes from: round-trip time, retransmits,", + "delivery rate. Nothing else on the machine reports them.", + ] { + rows.push(tc::seg(&[(dim.as_str(), format!(" {}", line))], w - 1)); + } + rows.push(String::new()); + rows.push(tc::seg( + &[ + (dim.as_str(), " try: ".into()), + (txt.as_str(), "apt install iproute2".into()), + ], + w - 1, + )); + while rows.len() < h - 1 { + rows.push(String::new()); + } + rows.push(tc::seg(&[(dim.as_str(), " [q]uit".into())], w - 1)); + tc::draw(&rows, w, h); + std::thread::sleep(Duration::from_millis(200)); + } +} + +struct Palette { + bad: String, + dim: String, + grid: String, + txt: String, + accent: String, + link: String, + hues: Vec, +} + +fn palette() -> Palette { + Palette { + bad: tc::rgb(255, 100, 110), + dim: tc::rgb(127, 147, 172), + grid: tc::rgb(60, 78, 98), + txt: tc::rgb(225, 235, 245), + accent: tc::rgb(150, 210, 255), + link: tc::rgb(140, 200, 255), + hues: vec![ + tc::rgb(120, 200, 255), + tc::rgb(150, 230, 180), + tc::rgb(220, 170, 255), + tc::rgb(160, 190, 240), + tc::rgb(200, 220, 150), + tc::rgb(240, 180, 210), + ], + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn both_shapes_on_the_ss_line_are_read() { + let line = "\t ts sack cubic rtt:3.604/1.027 minrtt:3.553 cwnd:10 \ + bytes_sent:1669 delivery_rate 6287464bps"; + let m = parse_metrics(line); + assert_eq!(m.get("rtt").map(String::as_str), Some("3.604/1.027")); + assert_eq!(m.get("minrtt").map(String::as_str), Some("3.553")); + // The space-separated shape, which a key:value scan alone misses. + assert_eq!(m.get("delivery_rate").map(String::as_str), Some("6287464")); + assert_eq!(num(&m, "cwnd"), Some(10.0)); + } + + #[test] + fn milliseconds_follow_the_python_scale() { + assert_eq!(ms(Some(123.4)), "123ms"); + assert_eq!(ms(Some(28.1)), "28ms"); + assert_eq!(ms(Some(2.74)), "2.7ms"); + // Below a millisecond it changes unit rather than losing the value. + assert_eq!(ms(Some(0.022)), "22µs"); + assert_eq!(ms(None), "—"); + } + + #[test] + fn rates_read_as_a_person_would_say_them() { + assert_eq!(rate(Some(6_287_464.0)), "6.3Mbps"); + assert_eq!(rate(Some(1_500.0)), "1.5Kbps"); + assert_eq!(rate(Some(45_000_000_000.0)), "45.0Gbps"); + assert_eq!(rate(None), "—"); + assert_eq!(rate(Some(0.0)), "—"); + } + + #[test] + fn spans_come_from_milliseconds() { + assert_eq!(span(Some(45_000.0)), "45s"); + assert_eq!(span(Some(600_000.0)), "10m"); + assert_eq!(span(None), "—"); + } + + #[test] + fn condensing_keeps_the_typical_not_the_extreme() { + // Ten samples into two columns: each column is its half's median, + // so a single spike cannot define a column on its own. + let values = vec![10.0, 10.0, 10.0, 10.0, 400.0, 10.0, 10.0, 10.0, 10.0, 10.0]; + let got = condense(&values, 2); + assert_eq!(got, vec![10.0, 10.0]); + // Fewer samples than columns is left alone. + assert_eq!(condense(&[1.0, 2.0], 8), vec![1.0, 2.0]); + } + + #[test] + fn a_sparkline_scales_to_its_own_peak() { + let line = sparkline(&[0.0, 5.0, 10.0], 3); + let chars: Vec = line.chars().collect(); + assert_eq!(chars.len(), 3); + assert_eq!(chars[0], '▁'); + assert_eq!(chars[2], '█'); + } + + #[test] + fn window_labels_are_short() { + assert_eq!(window_label(60.0), "1m"); + assert_eq!(window_label(900.0), "15m"); + assert_eq!(window_label(3600.0), "1h"); + assert_eq!(window_label(45.0), "45s"); + } +} diff --git a/rust/widgets/src/bin/link_help.txt b/rust/widgets/src/bin/link_help.txt new file mode 100644 index 0000000..caff87f --- /dev/null +++ b/rust/widgets/src/bin/link_help.txt @@ -0,0 +1,17 @@ +How good the connection is between here and whoever is connected to it. + +Every other network widget in this repo measures a path it chose - ping these +hosts, watch that tailnet. This one measures the path you are on: the TCP +socket carrying your session, as the kernel already sees it. + +Nothing is sent. `ss -tin` reports what the kernel has measured for each +established socket - round-trip time and its variance, the best round trip it +has ever seen, retransmitted bytes, the delivery rate it actually achieved. + + link [-n SECONDS] + +w cycles how much time the chart covers - a minute, five, fifteen, an hour. +Past a minute there are more samples than columns, so each column becomes the +median of its slice. + +Keys: up/down select, w changes the span, o toggles idle sessions, q quits. From 552ca1baff5d5014c506c4281cb15d83c32e56e7 Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sat, 22 Aug 2026 21:30:45 +0800 Subject: [PATCH 005/147] rust: clocks ported, with the pomodoro Sixth widget, and the first needing a real crate. Timezones come from chrono-tz, which embeds the IANA database: London is UTC+1 in August and UTC+0 in January, and a world clock that gets that wrong is worse than no world clock. It costs 1.8MB of binary - clocks is 2.3MB against the others' 300-500KB - and that is the right trade, because DST rules are exactly the kind of thing a hand-rolled parser gets subtly wrong. The pomodoro came with it, including the part that matters: hiding suspends it rather than merely concealing it. A timer that keeps counting out of sight is worse than no timer, because you come back to a focus block that expired half an hour ago. It also does not advance itself when a phase elapses - it rings and counts up - since a break that starts while you are mid-sentence is a break you ignore, and then the session count is a lie. Both are tested. Two more things the side-by-side caught, neither of them visible from reading the code. The pomodoro was hidden on the first frame, because I read "off until you press p" as invisible when it means paused. And "Start of Office Hour" is exactly twenty characters, so a twenty-wide label field ran it into the time beside it; there is now a test that fails if a label ever grows into its gap. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/Cargo.lock | 320 +++++++++++- rust/core/Cargo.toml | 4 + rust/widgets/Cargo.toml | 9 + rust/widgets/src/bin/clocks.rs | 714 +++++++++++++++++++++++++++ rust/widgets/src/bin/clocks_help.txt | 17 + 5 files changed, 1063 insertions(+), 1 deletion(-) create mode 100644 rust/widgets/src/bin/clocks.rs create mode 100644 rust/widgets/src/bin/clocks_help.txt diff --git a/rust/Cargo.lock b/rust/Cargo.lock index cc8e6d6..1c2b57d 100644 --- a/rust/Cargo.lock +++ b/rust/Cargo.lock @@ -2,24 +2,198 @@ # It is not intended for manual editing. version = 4 +[[package]] +name = "android_system_properties" +version = "0.1.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ae221649c9976a6f6c56ae1facf410f3ddb33cc661c4b7b61020a912d4237fbc" +dependencies = [ + "libc", +] + +[[package]] +name = "autocfg" +version = "1.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53" + +[[package]] +name = "bumpalo" +version = "3.20.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649" + +[[package]] +name = "cc" +version = "1.4.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0ad534f4357a5264cce5019c989cf66a4f0dc4e0d1b1d15f8aacec0ff7360273" +dependencies = [ + "find-msvc-tools", + "shlex", +] + +[[package]] +name = "cfg-if" +version = "1.0.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801" + +[[package]] +name = "chrono" +version = "0.4.45" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1aa79e62e7697b8e29b513a68abacf485adcd1fe8284a4316c5ae868e6633327" +dependencies = [ + "iana-time-zone", + "num-traits", + "windows-link", +] + +[[package]] +name = "chrono-tz" +version = "0.10.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a6139a8597ed92cf816dfb33f5dd6cf0bb93a6adc938f11039f371bc5bcd26c3" +dependencies = [ + "chrono", + "phf", +] + +[[package]] +name = "core-foundation-sys" +version = "0.8.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b" + +[[package]] +name = "find-msvc-tools" +version = "0.1.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d45db016d36b838f563236e9193d0ee6ce38f3f68b6c94e914b4929c96bbb890" + +[[package]] +name = "futures-core" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "92d699e522242e69e3003b94ecc1f960f3a5e015aa7c5d7486e65ad01dd94f5e" + +[[package]] +name = "futures-task" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cd417de3d1d015fc3bfd2b1ea46dfc7bab72ef86f1cc7cc9c78e728b34a6d1fd" + +[[package]] +name = "futures-util" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0d50a92467f8ba5dd6e3ee5d4bd04d73ab2e4e1c44474a0674821dfce14b79bc" +dependencies = [ + "futures-core", + "futures-task", + "pin-project-lite", + "slab", +] + +[[package]] +name = "iana-time-zone" +version = "0.1.65" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e31bc9ad994ba00e440a8aa5c9ef0ec67d5cb5e5cb0cc7f8b744a35b389cc470" +dependencies = [ + "android_system_properties", + "core-foundation-sys", + "iana-time-zone-haiku", + "js-sys", + "log", + "wasm-bindgen", + "windows-core", +] + +[[package]] +name = "iana-time-zone-haiku" +version = "0.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f31827a206f56af32e590ba56d5d2d085f558508192593743f16b2306495269f" +dependencies = [ + "cc", +] + [[package]] name = "itoa" version = "1.0.18" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682" +[[package]] +name = "js-sys" +version = "0.3.104" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0e0c1080212aad755ea003d18543e8768dd432c48819efd73a7bf1e39b7a5a3a" +dependencies = [ + "cfg-if", + "futures-util", + "wasm-bindgen", +] + [[package]] name = "libc" version = "0.2.189" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2" +[[package]] +name = "log" +version = "0.4.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f9f8bd3e56ce4dfc153cf470fffbfa98c7620958b312ca5c3a4b8d5181fd13c6" + [[package]] name = "memchr" version = "2.8.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98" +[[package]] +name = "num-traits" +version = "0.2.19" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841" +dependencies = [ + "autocfg", +] + +[[package]] +name = "once_cell" +version = "1.21.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50" + +[[package]] +name = "phf" +version = "0.12.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "913273894cec178f401a31ec4b656318d95473527be05c0752cc41cdc32be8b7" +dependencies = [ + "phf_shared", +] + +[[package]] +name = "phf_shared" +version = "0.12.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "06005508882fb681fd97892ecff4b7fd0fee13ef1aa569f8695dae7ab9099981" +dependencies = [ + "siphasher", +] + +[[package]] +name = "pin-project-lite" +version = "0.2.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd" + [[package]] name = "proc-macro2" version = "1.0.107" @@ -38,6 +212,12 @@ dependencies = [ "proc-macro2", ] +[[package]] +name = "rustversion" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f" + [[package]] name = "serde" version = "1.0.229" @@ -64,7 +244,7 @@ checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348" dependencies = [ "proc-macro2", "quote", - "syn", + "syn 3.0.3", ] [[package]] @@ -80,6 +260,35 @@ dependencies = [ "zmij", ] +[[package]] +name = "shlex" +version = "2.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba" + +[[package]] +name = "siphasher" +version = "1.0.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8ee5873ec9cce0195efcb7a4e9507a04cd49aec9c83d0389df45b1ef7ba2e649" + +[[package]] +name = "slab" +version = "0.4.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5" + +[[package]] +name = "syn" +version = "2.0.119" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + [[package]] name = "syn" version = "3.0.3" @@ -95,6 +304,8 @@ dependencies = [ name = "toys-core" version = "0.1.0" dependencies = [ + "chrono", + "chrono-tz", "libc", "serde_json", ] @@ -103,7 +314,10 @@ dependencies = [ name = "toys-widgets" version = "0.1.0" dependencies = [ + "chrono", + "chrono-tz", "libc", + "serde_json", "toys-core", ] @@ -113,6 +327,110 @@ version = "1.0.24" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75" +[[package]] +name = "wasm-bindgen" +version = "0.2.127" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1b70935747edd64d89de3efa29d73789b806c15798f8e7dca4d8ac356b50ce70" +dependencies = [ + "cfg-if", + "once_cell", + "rustversion", + "wasm-bindgen-macro", + "wasm-bindgen-shared", +] + +[[package]] +name = "wasm-bindgen-macro" +version = "0.2.127" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "77775f8f3f7217702089053b94958f8f54061a3f663417df76e19cbdcca29bc1" +dependencies = [ + "quote", + "wasm-bindgen-macro-support", +] + +[[package]] +name = "wasm-bindgen-macro-support" +version = "0.2.127" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e11d33f857dc2fb11b8bc75aee111aa9cbeb12cd9f25efd3d4c2a3dd4e235284" +dependencies = [ + "bumpalo", + "proc-macro2", + "quote", + "syn 2.0.119", + "wasm-bindgen-shared", +] + +[[package]] +name = "wasm-bindgen-shared" +version = "0.2.127" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7ef64dbcc55df09c7e5a46182d181c2cfa3e925f3da937ea764728b4bbb9dcbf" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "windows-core" +version = "0.62.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b8e83a14d34d0623b51dce9581199302a221863196a1dde71a7663a4c2be9deb" +dependencies = [ + "windows-implement", + "windows-interface", + "windows-link", + "windows-result", + "windows-strings", +] + +[[package]] +name = "windows-implement" +version = "0.60.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "windows-interface" +version = "0.59.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "windows-link" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5" + +[[package]] +name = "windows-result" +version = "0.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7781fa89eaf60850ac3d2da7af8e5242a5ea78d1a11c49bf2910bb5a73853eb5" +dependencies = [ + "windows-link", +] + +[[package]] +name = "windows-strings" +version = "0.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7837d08f69c77cf6b07689544538e017c1bfcf57e34b4c0ff58e6c2cd3b37091" +dependencies = [ + "windows-link", +] + [[package]] name = "zmij" version = "1.0.23" diff --git a/rust/core/Cargo.toml b/rust/core/Cargo.toml index de54983..ac97ef8 100644 --- a/rust/core/Cargo.toml +++ b/rust/core/Cargo.toml @@ -11,3 +11,7 @@ license.workspace = true # farm for no gain. libc = "0.2" serde_json = "1" +# Timezones: the IANA database, so a world clock is right across a DST +# boundary without this having to parse TZif itself. +chrono = { version = "0.4", default-features = false, features = ["clock", "std"] } +chrono-tz = "0.10" diff --git a/rust/widgets/Cargo.toml b/rust/widgets/Cargo.toml index 07b0f05..b384faf 100644 --- a/rust/widgets/Cargo.toml +++ b/rust/widgets/Cargo.toml @@ -7,6 +7,11 @@ license.workspace = true [dependencies] toys-core = { path = "../core" } libc = "0.2" +serde_json = "1" +# clocks needs these; nothing else does yet, and an unused dependency costs +# nothing at run time because LTO drops what no binary reaches. +chrono = { version = "0.4", default-features = false, features = ["clock", "std"] } +chrono-tz = "0.10" [[bin]] name = "ports" @@ -27,3 +32,7 @@ path = "src/bin/matrix.rs" [[bin]] name = "link" path = "src/bin/link.rs" + +[[bin]] +name = "clocks" +path = "src/bin/clocks.rs" diff --git a/rust/widgets/src/bin/clocks.rs b/rust/widgets/src/bin/clocks.rs new file mode 100644 index 0000000..0b785f8 --- /dev/null +++ b/rust/widgets/src/bin/clocks.rs @@ -0,0 +1,714 @@ +// terminal-toys - small dependency-free terminal widgets +// Copyright (C) 2026 William Li +// +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU Affero General Public License as published +// by the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU Affero General Public License for more details. +// +// You should have received a copy of the GNU Affero General Public License +// along with this program. If not, see . + +//! Clocks: this server's, everyone else's, and the ones counting down. +//! +//! A port of clocks.py: the big clock, the countdown bars, the pomodoro, +//! and a world clock. The one widget here that needs a timezone database, +//! which is why the core carries one. + +use std::time::Duration; + +use chrono::{Datelike, Local, NaiveTime, Offset, TimeZone, Timelike, Utc}; +use chrono_tz::Tz; +use toys_core as tc; + +/// Five rows per digit, as clocks.py draws them. +const BIG: &[(char, [&str; 5])] = &[ + ('0', ["███", "█ █", "█ █", "█ █", "███"]), + ('1', [" █", " █", " █", " █", " █"]), + ('2', ["███", " █", "███", "█ ", "███"]), + ('3', ["███", " █", "███", " █", "███"]), + ('4', ["█ █", "█ █", "███", " █", " █"]), + ('5', ["███", "█ ", "███", " █", "███"]), + ('6', ["███", "█ ", "███", "█ █", "███"]), + ('7', ["███", " █", " █", " █", " █"]), + ('8', ["███", "█ █", "███", "█ █", "███"]), + ('9', ["███", "█ █", "███", " █", "███"]), + (':', [" ", " █ ", " ", " █ ", " "]), +]; + +fn glyph(c: char) -> [&'static str; 5] { + BIG.iter() + .find(|(ch, _)| *ch == c) + .map(|(_, rows)| *rows) + .unwrap_or([" ", " ", " ", " ", " "]) +} + +/// A time as five rows of blocks. +fn render_big(text: &str) -> Vec { + let mut rows = vec![String::new(); 5]; + for c in text.chars() { + let art = glyph(c); + for (i, row) in rows.iter_mut().enumerate() { + row.push_str(art[i]); + row.push(' '); + } + } + rows +} + +fn hms(seconds: i64) -> String { + let s = seconds.max(0); + format!("{:02}:{:02}:{:02}", s / 3600, (s % 3600) / 60, s % 60) +} + +/// The offset from UTC, as a person writes it. +fn offset_str(when: &chrono::DateTime) -> String +where + T: TimeZone, + T::Offset: Offset, +{ + let seconds = when.offset().fix().local_minus_utc(); + let sign = if seconds < 0 { '-' } else { '+' }; + let total = seconds.abs(); + let (hours, minutes) = (total / 3600, (total % 3600) / 60); + if minutes == 0 { + format!("UTC{}{}", sign, hours) + } else { + format!("UTC{}{}:{:02}", sign, hours, minutes) + } +} + +/// A progress bar of the given width, filled to `frac`. +fn bar(frac: f64, width: usize) -> String { + let filled = ((frac.clamp(0.0, 1.0)) * width as f64).round() as usize; + let mut out = "█".repeat(filled); + out.push_str(&"░".repeat(width.saturating_sub(filled))); + out +} + +struct Countdown { + label: String, + left: i64, + frac: f64, +} + +/// The three fixed countdowns: the hour, the working day, and midnight. +fn countdowns(now: chrono::DateTime, work_start: u32, work_end: u32) -> Vec { + let mut out = Vec::new(); + + let into_hour = now.minute() as i64 * 60 + now.second() as i64; + out.push(Countdown { + label: "Next Hour".into(), + left: 3600 - into_hour, + frac: into_hour as f64 / 3600.0, + }); + + // Office hours run to work_end today; past it, to work_start tomorrow. + let today = now.date_naive(); + let start = today.and_time(NaiveTime::from_hms_opt(work_start, 0, 0).unwrap()); + let end = today.and_time(NaiveTime::from_hms_opt(work_end, 0, 0).unwrap()); + let naive = now.naive_local(); + let (label, target, from) = if naive < start { + ("Start of Office Hour", start, start - chrono::Duration::hours(12)) + } else if naive < end { + ("End of Office Hour", end, start) + } else { + let tomorrow = today + chrono::Duration::days(1); + ( + "Start of Office Hour", + tomorrow.and_time(NaiveTime::from_hms_opt(work_start, 0, 0).unwrap()), + end, + ) + }; + let span = (target - from).num_seconds().max(1); + let left = (target - naive).num_seconds(); + out.push(Countdown { + label: label.into(), + left, + frac: 1.0 - (left as f64 / span as f64), + }); + + let into_day = now.num_seconds_from_midnight() as i64; + out.push(Countdown { + label: "End of Day".into(), + left: 86400 - into_day, + frac: into_day as f64 / 86400.0, + }); + out +} + +/// The pomodoro, and the state it keeps between runs. +/// +/// Hidden means suspended, not merely invisible. A timer that keeps +/// counting while out of sight is worse than no timer: you come back to a +/// focus block that expired half an hour ago. Hiding freezes it where it +/// stands and showing resumes it only if it was running when it went away. +struct Pomodoro { + phase: Phase, + running: bool, + shown: bool, + /// When the current phase ends, while running. + deadline: f64, + /// What was left when it stopped, while not. + left: f64, + done: u32, + focus: f64, + short: f64, + long: f64, + before_long: u32, + bell: bool, + rang_at: i64, +} + +#[derive(Clone, Copy, PartialEq, Eq, Debug)] +enum Phase { + Focus, + Short, + Long, +} + +impl Phase { + fn label(self) -> &'static str { + match self { + Phase::Focus => "FOCUS", + Phase::Short => "SHORT BREAK", + Phase::Long => "LONG BREAK", + } + } +} + +impl Pomodoro { + fn new(cfg: &serde_json::Value) -> Pomodoro { + let focus = tc::cfg_f64(cfg, "pomodoro_focus_minutes", 25.0); + let mut it = Pomodoro { + phase: Phase::Focus, + running: false, + // On screen from the start, paused. Hidden and paused are + // different things, and the Python shows it from the first + // frame with "paused" against it. + shown: true, + deadline: 0.0, + left: focus * 60.0, + done: 0, + focus, + short: tc::cfg_f64(cfg, "pomodoro_short_break_minutes", 5.0), + long: tc::cfg_f64(cfg, "pomodoro_long_break_minutes", 15.0), + before_long: tc::cfg_usize(cfg, "pomodoro_sessions_before_long_break", 4) as u32, + bell: cfg + .get("pomodoro_bell") + .and_then(|v| v.as_bool()) + .unwrap_or(true), + rang_at: -1, + }; + it.left = it.duration(); + it + } + + fn duration(&self) -> f64 { + 60.0 * match self.phase { + Phase::Focus => self.focus, + Phase::Short => self.short, + Phase::Long => self.long, + } + } + + /// Seconds left, negative once the phase has been overrun. + fn signed(&self, now: f64) -> f64 { + if self.running && self.deadline > 0.0 { + self.deadline - now + } else { + self.left + } + } + + fn remaining(&self, now: f64) -> f64 { + self.signed(now).max(0.0) + } + + fn overtime(&self, now: f64) -> f64 { + (-self.signed(now)).max(0.0) + } + + /// Show or hide, suspending with it. + fn toggle(&mut self, now: f64) { + if self.shown { + self.left = self.signed(now); + self.shown = false; + } else { + self.shown = true; + if self.running { + self.deadline = now + self.left; + } + } + } + + fn start_stop(&mut self, now: f64) { + if self.running { + self.left = self.signed(now); + self.running = false; + } else { + self.running = true; + self.deadline = now + self.left; + } + } + + /// Move to whatever comes next, counting a finished focus block. + fn advance(&mut self, now: f64) { + if self.phase == Phase::Focus { + self.done += 1; + self.phase = if self.before_long > 0 && self.done % self.before_long == 0 { + Phase::Long + } else { + Phase::Short + }; + } else { + self.phase = Phase::Focus; + } + self.left = self.duration(); + self.deadline = now + self.left; + self.rang_at = -1; + } + + fn restart(&mut self, now: f64) { + self.left = self.duration(); + self.deadline = now + self.left; + self.rang_at = -1; + } + + /// One tick: ring on elapse, and once a minute while overrunning. + /// + /// It does not advance on its own. A break that starts itself while you + /// are mid-sentence is a break you ignore, and then the count is a lie. + fn tick(&mut self, now: f64) { + if !self.running || !self.shown { + return; + } + let over = self.overtime(now); + if over <= 0.0 { + return; + } + let minute = (over / 60.0) as i64; + if minute != self.rang_at { + self.rang_at = minute; + if self.bell { + tc::out("\x07"); + tc::flush(); + } + } + } +} + +struct City { + name: String, + zone: Tz, +} + +fn main() { + tc::maybe_help(include_str!("clocks_help.txt")); + let cfg = tc::load_config("clocks"); + let work_start = tc::cfg_usize(&cfg, "work_start_hour", 9) as u32; + let work_end = tc::cfg_usize(&cfg, "work_end_hour", 18) as u32; + let cities = load_cities(&cfg); + + let p = palette(); + let mut pomo = Pomodoro::new(&cfg); + tc::setup(); + let mut keyboard = tc::Keyboard::new(); + let mut scroll = 0usize; + + loop { + for key in keyboard.poll() { + match key.as_str() { + "q" | "Q" => { + keyboard.restore(); + tc::restore_screen(); + return; + } + "up" | "k" | "K" => scroll = scroll.saturating_sub(1), + "down" | "j" | "J" => scroll += 1, + "p" | "P" => pomo.toggle(seconds()), + " " => pomo.start_stop(seconds()), + "n" | "N" => pomo.advance(seconds()), + "r" | "R" => pomo.restart(seconds()), + _ => {} + } + } + + let (w, h) = tc::size(); + let now = Local::now(); + let mut rows = vec![tc::title("clocks", w, &p.head)]; + rows.push(tc::seg(&[(p.lbl.as_str(), " ── SERVER TIME ── ".into())], w - 1)); + + for line in render_big(&now.format("%H:%M:%S").to_string()) { + rows.push(tc::seg(&[(p.big.as_str(), format!(" {}", line))], w - 1)); + } + rows.push(String::new()); + rows.push(tc::seg( + &[ + (p.txt.as_str(), format!(" {}", now.format("%Y-%m-%d"))), + ( + p.dim.as_str(), + format!(" {} {}", now.format("%A").to_string().to_uppercase(), offset_str(&now)), + ), + ], + w - 1, + )); + rows.push(String::new()); + + rows.push(tc::seg(&[(p.lbl.as_str(), " ── COUNTDOWN ── ".into())], w - 1)); + let bar_w = w.saturating_sub(3).min(90); + + // The pomodoro leads the section, as it does in the Python. + let stamp = seconds(); + pomo.tick(stamp); + if pomo.shown { + let over = pomo.overtime(stamp); + let left = pomo.remaining(stamp); + let frac = 1.0 - (left / pomo.duration().max(1.0)); + rows.push(tc::seg( + &[ + (p.txt.as_str(), " Pomodoro · ".into()), + ( + if pomo.phase == Phase::Focus { &p.focus } else { &p.rest }, + format!("{:<12}", pomo.phase.label()), + ), + ( + if over > 0.0 { &p.focus } else { &p.accent }, + if over > 0.0 { + format!("+{}", hms(over as i64)) + } else { + hms(left as i64) + }, + ), + ( + p.dim.as_str(), + format!( + " {} {} done", + if pomo.running { "running" } else { "paused" }, + pomo.done + ), + ), + ], + w - 1, + )); + rows.push(tc::seg( + &[( + if pomo.phase == Phase::Focus { &p.focus } else { &p.rest }, + format!(" {}", bar(frac, bar_w)), + )], + w - 1, + )); + } + for item in countdowns(now, work_start, work_end) { + rows.push(tc::seg( + &[ + (p.txt.as_str(), format!(" {:<21}", item.label)), + (p.accent.as_str(), hms(item.left)), + ], + w - 1, + )); + rows.push(tc::seg( + &[(p.bar.as_str(), format!(" {}", bar(item.frac, bar_w)))], + w - 1, + )); + } + rows.push(String::new()); + + // The world clock takes whatever is left, and says which slice of + // the list it is showing rather than silently truncating. + let room = h.saturating_sub(rows.len() + 3); + if room >= 2 && !cities.is_empty() { + let shown = room.saturating_sub(1).min(cities.len()); + if scroll + shown > cities.len() { + scroll = cities.len().saturating_sub(shown); + } + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── WORLD CLOCK ── ".into()), + ( + p.dim.as_str(), + format!(" {}-{} of {} ↑↓", scroll + 1, scroll + shown, cities.len()), + ), + ], + w - 1, + )); + for city in cities.iter().skip(scroll).take(shown) { + let there = now.with_timezone(&city.zone); + // Sun or moon by the local hour, which is the fastest way + // to read "is it a reasonable time to message them". + let awake = (7..19).contains(&there.hour()); + let day_shift = there.date_naive().signed_duration_since(now.date_naive()).num_days(); + rows.push(tc::seg( + &[ + ( + if awake { &p.sun } else { &p.moon }, + format!(" {} ", if awake { "☀" } else { "☾" }), + ), + (p.txt.as_str(), tc::pad(&city.name, 16)), + (p.txt.as_str(), there.format("%H:%M").to_string()), + ( + p.dim.as_str(), + format!(" {} {}", there.format("%a"), offset_str(&there)), + ), + ( + p.dim.as_str(), + match day_shift { + 0 => String::new(), + d if d > 0 => format!(" +{}d", d), + d => format!(" {}d", d), + }, + ), + ], + w - 1, + )); + } + } + + let hints: Vec> = vec![ + vec![( + p.dim.as_str(), + format!("[p]{}", if pomo.shown { "off" } else { "omodoro" }), + )], + vec![(p.accent.as_str(), "↑↓".into()), (p.dim.as_str(), " cities".into())], + vec![(p.dim.as_str(), "[q]uit".into())], + ]; + let foot: Vec = tc::pack_hints(&hints, w - 2, " ") + .into_iter() + .map(|l| format!(" {}", l)) + .collect(); + while rows.len() < h.saturating_sub(foot.len()) { + rows.push(String::new()); + } + rows.extend(foot); + tc::draw(&rows, w, h); + std::thread::sleep(Duration::from_millis(200)); + } +} + +/// The configured cities, or the four the Python ships with. +/// +/// A zone the database does not know is dropped rather than defaulted to +/// UTC: a clock quietly showing the wrong city is worse than one absent. +fn load_cities(cfg: &serde_json::Value) -> Vec { + let mut out = Vec::new(); + if let Some(items) = cfg.get("cities").and_then(|v| v.as_array()) { + for pair in items { + let name = pair.get(0).and_then(|v| v.as_str()).unwrap_or(""); + let zone = pair.get(1).and_then(|v| v.as_str()).unwrap_or(""); + if let Ok(tz) = zone.parse::() { + out.push(City { + name: name.to_string(), + zone: tz, + }); + } + } + } + if out.is_empty() { + for (name, zone) in [ + ("San Francisco", "America/Los_Angeles"), + ("London", "Europe/London"), + ("Singapore", "Asia/Singapore"), + ("Tokyo", "Asia/Tokyo"), + ] { + if let Ok(tz) = zone.parse::() { + out.push(City { + name: name.into(), + zone: tz, + }); + } + } + } + out +} + +fn seconds() -> f64 { + std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .map(|d| d.as_secs_f64()) + .unwrap_or(0.0) +} + +struct Palette { + focus: String, + rest: String, + dim: String, + txt: String, + lbl: String, + accent: String, + head: String, + big: String, + bar: String, + sun: String, + moon: String, +} + +fn palette() -> Palette { + Palette { + focus: tc::rgb(255, 130, 120), + rest: tc::rgb(120, 220, 170), + dim: tc::rgb(127, 147, 172), + txt: tc::rgb(225, 235, 245), + lbl: tc::rgb(130, 165, 200), + accent: tc::rgb(150, 210, 255), + head: tc::rgb(0, 255, 170), + big: tc::rgb(220, 255, 240), + bar: tc::rgb(90, 200, 255), + sun: tc::rgb(255, 210, 120), + moon: tc::rgb(150, 170, 210), + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn digits_are_five_rows_of_blocks() { + let rows = render_big("12:34"); + assert_eq!(rows.len(), 5); + // Every row is the same width, or the clock leans. + let widths: Vec = rows.iter().map(|r| r.chars().count()).collect(); + assert!(widths.windows(2).all(|w| w[0] == w[1]), "{:?}", widths); + assert!(rows[0].contains('█')); + } + + #[test] + fn an_unknown_character_leaves_a_gap_rather_than_panicking() { + let rows = render_big("1?2"); + assert_eq!(rows.len(), 5); + } + + #[test] + fn the_offset_is_written_as_people_write_it() { + let utc = Utc.with_ymd_and_hms(2026, 8, 22, 12, 0, 0).unwrap(); + let india: Tz = "Asia/Kolkata".parse().unwrap(); + // Half-hour offsets have to keep their minutes. + assert_eq!(offset_str(&utc.with_timezone(&india)), "UTC+5:30"); + let tokyo: Tz = "Asia/Tokyo".parse().unwrap(); + assert_eq!(offset_str(&utc.with_timezone(&tokyo)), "UTC+9"); + let la: Tz = "America/Los_Angeles".parse().unwrap(); + assert_eq!(offset_str(&utc.with_timezone(&la)), "UTC-7"); + } + + #[test] + fn daylight_saving_actually_moves_the_clock() { + // The whole reason for carrying a timezone database: London is one + // hour off UTC in August and level with it in January. + let london: Tz = "Europe/London".parse().unwrap(); + let summer = Utc.with_ymd_and_hms(2026, 8, 22, 12, 0, 0).unwrap(); + let winter = Utc.with_ymd_and_hms(2026, 1, 22, 12, 0, 0).unwrap(); + assert_eq!(offset_str(&summer.with_timezone(&london)), "UTC+1"); + assert_eq!(offset_str(&winter.with_timezone(&london)), "UTC+0"); + } + + #[test] + fn the_longest_countdown_label_still_leaves_a_gap() { + // "Start of Office Hour" is exactly twenty characters, and a + // twenty-wide field ran it straight into the time beside it. + let now = Local.with_ymd_and_hms(2026, 8, 22, 7, 0, 0).unwrap(); + let longest = countdowns(now, 9, 18) + .into_iter() + .map(|c| c.label.chars().count()) + .max() + .unwrap(); + assert!(longest < 21, "a label of {} needs a wider field", longest); + } + + #[test] + fn a_focus_block_leads_to_a_break_and_back() { + let cfg = serde_json::json!({}); + let mut pomo = Pomodoro::new(&cfg); + let now = 1000.0; + assert_eq!(pomo.phase, Phase::Focus); + pomo.advance(now); + assert_eq!(pomo.phase, Phase::Short); + assert_eq!(pomo.done, 1); + pomo.advance(now); + assert_eq!(pomo.phase, Phase::Focus, "a break returns to focus"); + } + + #[test] + fn every_fourth_break_is_a_long_one() { + let mut pomo = Pomodoro::new(&serde_json::json!({})); + let now = 0.0; + for _ in 0..3 { + pomo.advance(now); // focus -> short + pomo.advance(now); // short -> focus + } + pomo.advance(now); // the fourth focus block + assert_eq!(pomo.done, 4); + assert_eq!(pomo.phase, Phase::Long); + } + + #[test] + fn hiding_freezes_it_rather_than_letting_it_run_away() { + let mut pomo = Pomodoro::new(&serde_json::json!({})); + pomo.shown = true; + pomo.start_stop(0.0); + assert!(pomo.running); + // Two minutes in, hide it, and leave it hidden for an hour. + pomo.toggle(120.0); + let frozen = pomo.left; + pomo.toggle(3720.0); + // What is left is what was left, not an hour less. + assert!((pomo.remaining(3720.0) - frozen).abs() < 0.001, + "left {} against frozen {}", pomo.remaining(3720.0), frozen); + assert!(pomo.running, "it was running when it went away"); + } + + #[test] + fn overrunning_counts_up_rather_than_stopping() { + let mut pomo = Pomodoro::new(&serde_json::json!({})); + pomo.shown = true; + pomo.start_stop(0.0); + let past = pomo.duration() + 90.0; + assert_eq!(pomo.remaining(past), 0.0); + assert!((pomo.overtime(past) - 90.0).abs() < 0.001); + // And it does not advance itself: a break that starts while you are + // mid-sentence is a break you ignore, and then the count is a lie. + assert_eq!(pomo.phase, Phase::Focus); + } + + #[test] + fn hms_counts_down_and_never_below_zero() { + assert_eq!(hms(3661), "01:01:01"); + assert_eq!(hms(59), "00:00:59"); + assert_eq!(hms(-5), "00:00:00"); + } + + #[test] + fn a_bar_is_exactly_its_width() { + for frac in [0.0, 0.25, 0.5, 1.0, 1.5, -0.2] { + assert_eq!(bar(frac, 20).chars().count(), 20, "frac {}", frac); + } + assert!(bar(0.0, 10).starts_with('░')); + assert!(bar(1.0, 10).starts_with('█')); + } + + #[test] + fn the_countdowns_stay_inside_their_spans() { + let now = Local.with_ymd_and_hms(2026, 8, 22, 14, 30, 0).unwrap(); + let items = countdowns(now, 9, 18); + assert_eq!(items.len(), 3); + for item in &items { + assert!(item.left > 0, "{} had {}s left", item.label, item.left); + assert!((0.0..=1.0).contains(&item.frac), "{} at {}", item.label, item.frac); + } + // Half past two leaves half an hour of this hour. + assert_eq!(items[0].left, 1800); + } + + #[test] + fn after_hours_counts_to_tomorrow_morning() { + let evening = Local.with_ymd_and_hms(2026, 8, 22, 21, 0, 0).unwrap(); + let items = countdowns(evening, 9, 18); + assert_eq!(items[1].label, "Start of Office Hour"); + // Twelve hours to nine the next morning. + assert_eq!(items[1].left, 12 * 3600); + } +} diff --git a/rust/widgets/src/bin/clocks_help.txt b/rust/widgets/src/bin/clocks_help.txt new file mode 100644 index 0000000..86c71d2 --- /dev/null +++ b/rust/widgets/src/bin/clocks_help.txt @@ -0,0 +1,17 @@ +Clocks: this server's, everyone else's, and the ones counting down. + +A big clock in the machine's own timezone, countdown bars for the next hour, +office hours and the end of day, and a world clock covering the hubs you care +about. + + clocks + +The world clock marks each city with a sun or a moon by its local hour, which +is the fastest way to read whether it is a reasonable time to message someone +there, and shows the day offset where the date differs from this machine's. + +Timezones come from the IANA database, so the offsets are right across a +daylight-saving boundary rather than fixed at whatever they were when the +config was written. + +Keys: up/down scroll the cities, q quits. From 8cad6acc6dc2c2f3f587007521a2ac3b2a89058e Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sat, 22 Aug 2026 23:00:35 +0800 Subject: [PATCH 006/147] rust: the pomodoro's flash and toast, which clocks was missing I ported the state machine and the bell, stopped when the widget looked right, and flagged the rest as missing instead of finishing it. There was no reason for that beyond momentum, so here is the rest. The flash is derived from one timestamp rather than driven by sleeps, which is the whole trick: the render loop keeps running, so the clock stays live and keys stay responsive while the panel blinks. A lit frame is the same frame with its colours stripped and one loud background painted across every row, and the ink is chosen by the luminance of that background - a configured flash colour cannot make the panel unreadable at the moment it is trying to get attention. The Herdr toast ported without trouble, so it is in rather than skipped: it is one guarded subprocess call, and outside Herdr it does nothing at all. That is how the Python has it too - purely additive, nobody who is not running Herdr is affected either way. Verified by driving a real pomodoro to elapse with a config that gives it a one-second focus block: one bell, ninety-six rows repainted across the two blink windows, and the frame's content still legible underneath. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/widgets/src/bin/clocks.rs | 180 +++++++++++++++++++++++++++++++-- 1 file changed, 169 insertions(+), 11 deletions(-) diff --git a/rust/widgets/src/bin/clocks.rs b/rust/widgets/src/bin/clocks.rs index 0b785f8..cd87924 100644 --- a/rust/widgets/src/bin/clocks.rs +++ b/rust/widgets/src/bin/clocks.rs @@ -142,6 +142,83 @@ fn countdowns(now: chrono::DateTime, work_start: u32, work_end: u32) -> V out } +/// Seconds each flash stays lit. +const FLASH_ON: f64 = 0.35; + +/// Is the panel lit right now? +/// +/// Flashes are derived from one timestamp rather than driven by sleeps, so +/// the render loop keeps running - the clock stays live and keys stay +/// responsive while it blinks. +fn flash_window(started: Option, count: u32, gap: f64, now: f64) -> bool { + let started = match started { + Some(s) => s, + None => return false, + }; + let since = now - started; + (0..count.max(1)).any(|n| { + let edge = n as f64 * gap; + since >= edge && since < edge + FLASH_ON + }) +} + +/// The same frame, repainted solid: colours stripped, one loud background. +fn flash_frame(rows: &[String], w: usize, h: usize, bg: &str, fg: &str) -> Vec { + (0..h) + .map(|i| { + let plain = rows.get(i).map(|r| strip_ansi(r)).unwrap_or_default(); + format!("{}{}{}", bg, fg, tc::pad(&plain, w)) + }) + .collect() +} + +fn strip_ansi(text: &str) -> String { + let mut out = String::new(); + let mut chars = text.chars().peekable(); + while let Some(c) = chars.next() { + if c == '\x1b' { + for n in chars.by_ref() { + if n == 'm' || n.is_ascii_alphabetic() { + break; + } + } + } else { + out.push(c); + } + } + out +} + +/// A readable foreground for whatever the flash colour is. +/// +/// A near-white flash needs dark text on it and a dark one needs light; +/// picking by luminance means a configured colour cannot make the panel +/// unreadable at the moment it is trying to get your attention. +fn flash_ink(rgb: (u8, u8, u8)) -> String { + let lum = (0.299 * rgb.0 as f64 + 0.587 * rgb.1 as f64 + 0.114 * rgb.2 as f64) / 255.0; + if lum > 0.5 { + tc::rgb(18, 20, 26) + } else { + tc::rgb(255, 240, 240) + } +} + +/// Herdr, when we happen to be inside it, can raise a real toast. +/// +/// Purely additive: nothing here requires Herdr, and outside it this is a +/// no-op. The widget usually runs on a server, so anything local to that +/// machine - notify-send, a sound file - would fire where nobody is. +fn herdr_toast(title: &str, body: &str) { + if std::env::var("HERDR_ENV").unwrap_or_default() != "1" { + return; + } + let _ = std::process::Command::new("herdr") + .args(["notification", "show", title, body, "--sound", "done"]) + .stdout(std::process::Stdio::null()) + .stderr(std::process::Stdio::null()) + .spawn(); +} + /// The pomodoro, and the state it keeps between runs. /// /// Hidden means suspended, not merely invisible. A timer that keeps @@ -284,22 +361,25 @@ impl Pomodoro { /// /// It does not advance on its own. A break that starts itself while you /// are mid-sentence is a break you ignore, and then the count is a lie. - fn tick(&mut self, now: f64) { + /// Returns true on the tick an alert fires, so the panel can flash. + fn tick(&mut self, now: f64) -> bool { if !self.running || !self.shown { - return; + return false; } let over = self.overtime(now); if over <= 0.0 { - return; + return false; } let minute = (over / 60.0) as i64; - if minute != self.rang_at { - self.rang_at = minute; - if self.bell { - tc::out("\x07"); - tc::flush(); - } + if minute == self.rang_at { + return false; } + self.rang_at = minute; + if self.bell { + tc::out("\x07"); + tc::flush(); + } + true } } @@ -317,6 +397,23 @@ fn main() { let p = palette(); let mut pomo = Pomodoro::new(&cfg); + let flash_rgb = cfg + .get("pomodoro_flash_rgb") + .and_then(|v| v.as_array()) + .map(|a| { + let n = |i: usize| a.get(i).and_then(|v| v.as_u64()).unwrap_or(250) as u8; + (n(0), n(1), n(2)) + }) + .unwrap_or((246, 248, 252)); + let flash_bg = tc::bg(flash_rgb.0, flash_rgb.1, flash_rgb.2); + let flash_fg = flash_ink(flash_rgb); + let flash_count = tc::cfg_usize(&cfg, "pomodoro_flash_count", 2) as u32; + let flash_gap = tc::cfg_f64(&cfg, "pomodoro_flash_gap", 1.0); + let flash_on = cfg + .get("pomodoro_flash") + .and_then(|v| v.as_bool()) + .unwrap_or(true); + let mut flash_started: Option = None; tc::setup(); let mut keyboard = tc::Keyboard::new(); let mut scroll = 0usize; @@ -365,7 +462,22 @@ fn main() { // The pomodoro leads the section, as it does in the Python. let stamp = seconds(); - pomo.tick(stamp); + if pomo.tick(stamp) { + flash_started = Some(stamp); + let over = pomo.overtime(stamp); + herdr_toast( + "Pomodoro", + &format!( + "{} elapsed{}", + pomo.phase.label(), + if over >= 60.0 { + format!(", {} over", hms(over as i64)) + } else { + String::new() + } + ), + ); + } if pomo.shown { let over = pomo.overtime(stamp); let left = pomo.remaining(stamp); @@ -485,7 +597,18 @@ fn main() { rows.push(String::new()); } rows.extend(foot); - tc::draw(&rows, w, h); + if flash_on && flash_window(flash_started, flash_count, flash_gap, seconds()) { + tc::draw(&flash_frame(&rows, w, h, &flash_bg, &flash_fg), w, h); + } else { + tc::draw(&rows, w, h); + } + // Forget a flash once its last blink has passed, so the check stops + // costing anything for the rest of the session. + if let Some(started) = flash_started { + if seconds() - started > flash_count as f64 * flash_gap + FLASH_ON { + flash_started = None; + } + } std::thread::sleep(Duration::from_millis(200)); } } @@ -619,6 +742,41 @@ mod tests { assert!(longest < 21, "a label of {} needs a wider field", longest); } + #[test] + fn the_flash_blinks_and_then_stops() { + let started = Some(100.0); + // Lit at the start of each window, dark between them. + assert!(flash_window(started, 2, 1.0, 100.0)); + assert!(flash_window(started, 2, 1.0, 100.3)); + assert!(!flash_window(started, 2, 1.0, 100.5)); + assert!(flash_window(started, 2, 1.0, 101.1)); + // And over for good once the last blink has passed. + assert!(!flash_window(started, 2, 1.0, 102.0)); + assert!(!flash_window(None, 2, 1.0, 100.0)); + } + + #[test] + fn a_flashed_frame_is_solid_and_exactly_the_width() { + let rows = vec![ + format!("{}hello{}", tc::rgb(1, 2, 3), tc::RST), + "plain".to_string(), + ]; + let lit = flash_frame(&rows, 20, 3, &tc::bg(250, 250, 250), &tc::rgb(0, 0, 0)); + assert_eq!(lit.len(), 3); + for line in &lit { + // The original colours are gone; only the flash pair remains. + assert!(!line.contains("38;2;1;2;3")); + assert_eq!(strip_ansi(line).chars().count(), 20); + } + } + + #[test] + fn the_flash_picks_ink_it_can_be_read_through() { + // Near-white wants dark text; a dark colour wants light. + assert_eq!(flash_ink((246, 248, 252)), tc::rgb(18, 20, 26)); + assert_eq!(flash_ink((20, 20, 30)), tc::rgb(255, 240, 240)); + } + #[test] fn a_focus_block_leads_to_a_break_and_back() { let cfg = serde_json::json!({}); From 60baf3885e2c2037a307769dbcd2947c8ad99d79 Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sat, 22 Aug 2026 23:03:16 +0800 Subject: [PATCH 007/147] netwatch: average rates over a few seconds, not one interval The rate column flickered - a figure, then a dash, then a figure - and each of those readings was correct. The delta over one sample interval really is zero when a bursty process happens to be between bursts, and nearly all traffic is bursty. Correct and unreadable at the same time. Rates are now averaged over four seconds: the same arithmetic over a longer span, which is just as true and can actually be read. The header says which window, so the number is not a mystery, and the divisor is the span the samples actually cover rather than the nominal window - for the first seconds after launch there is less history than that, and dividing by four would read low. Totals are untouched. Smoothing a rate is honest; smoothing a total would not be. Watched on the busiest row: 362, 396, 395, 34, 34, 176, 609, 610 KB/s across eight seconds, where before it alternated between a figure and a dash. This diverges from netwatch.py, which still flickers the same way. Worth backporting if the Python is staying. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/widgets/src/bin/netwatch.rs | 89 +++++++++++++++++++++++++++++--- 1 file changed, 82 insertions(+), 7 deletions(-) diff --git a/rust/widgets/src/bin/netwatch.rs b/rust/widgets/src/bin/netwatch.rs index 6759867..fc09665 100644 --- a/rust/widgets/src/bin/netwatch.rs +++ b/rust/widgets/src/bin/netwatch.rs @@ -353,6 +353,15 @@ fn wire_label(names: &[String]) -> String { } } +/// How long a rate is averaged over. +/// +/// One sample interval is the honest instantaneous rate and an unreadable +/// column: nearly all traffic is bursty, so a process that is steadily busy +/// flickers between a figure and a dash. Averaging over a few seconds is +/// just as true - it is a rate over a stated window - and can actually be +/// read. The header says which window, so the number is not a mystery. +const RATE_WINDOW: f64 = 4.0; + #[derive(Clone, Default)] struct Proc { pid: i32, @@ -362,6 +371,32 @@ struct Proc { up_rate: f64, down_rate: f64, alive: bool, + /// (when, up bytes, down bytes) for the last few samples. + recent: Vec<(f64, u64, u64)>, +} + +impl Proc { + /// Fold this sample in, and re-average over the window. + fn add(&mut self, when: f64, up: u64, down: u64) { + self.up += up; + self.down += down; + self.recent.push((when, up, down)); + self.recent.retain(|(t, _, _)| when - t <= RATE_WINDOW); + let oldest = self.recent.first().map(|(t, _, _)| *t).unwrap_or(when); + // The span the samples actually cover, not the nominal window: for + // the first few seconds after launch there is less history than + // that, and dividing by the full window would read low. + let span = (when - oldest).max(1e-6); + let (mut u, mut d) = (0u64, 0u64); + for (_, up, down) in &self.recent { + u += up; + d += down; + } + if self.recent.len() > 1 { + self.up_rate = u as f64 / span; + self.down_rate = d as f64 / span; + } + } } #[derive(Default)] @@ -395,9 +430,13 @@ fn sample(state: &mut State, external: bool) { state.err = err; for row in state.totals.values_mut() { - row.up_rate = 0.0; - row.down_rate = 0.0; row.alive = false; + // A row with nothing in the window really is idle, and says so. + row.recent.retain(|(t, _, _)| stamp - t <= RATE_WINDOW); + if row.recent.is_empty() { + row.up_rate = 0.0; + row.down_rate = 0.0; + } } let first = state.stamp == 0.0; @@ -442,11 +481,8 @@ fn sample(state: &mut State, external: bool) { ..Default::default() }); row.alive = true; - row.up += d_sent; - row.down += d_recv; if gap > 0.0 { - row.up_rate += d_sent as f64 / gap; - row.down_rate += d_recv as f64 / gap; + row.add(stamp, d_sent, d_recv); } } @@ -717,7 +753,10 @@ fn main() { p.accent.as_str(), if sort_live { "live".into() } else { "total".into() }, ), - (p.dim.as_str(), format!(" every {}s", interval)), + ( + p.dim.as_str(), + format!(" every {}s · rates over {}s", interval, RATE_WINDOW as i64), + ), ], w - 1, )); @@ -1031,6 +1070,42 @@ fn palette() -> Palette { mod tests { use super::*; + #[test] + fn a_bursty_process_keeps_a_readable_rate() { + let mut row = Proc::default(); + // A kilobyte at t=0 and nothing for the next three seconds. The + // instantaneous rate is zero for most of that; the windowed one + // stays up, which is the whole point. + row.add(0.0, 0, 1000); + row.add(1.0, 0, 0); + row.add(2.0, 0, 0); + row.add(3.0, 0, 0); + assert!(row.down_rate > 0.0, "the rate flickered to nothing"); + assert_eq!(row.down, 1000, "the total is unaffected by smoothing"); + } + + #[test] + fn a_rate_is_the_window_it_claims() { + let mut row = Proc::default(); + // Two kilobytes a second, steadily, for four seconds. + for i in 0..5 { + row.add(i as f64, 0, 2000); + } + // Averaged over the span the samples cover, which is 4s for 5 + // samples: 10000 bytes over 4 seconds. + assert!((row.down_rate - 2500.0).abs() < 1.0, "got {}", row.down_rate); + } + + #[test] + fn history_older_than_the_window_is_dropped() { + let mut row = Proc::default(); + row.add(0.0, 0, 5000); + row.add(100.0, 0, 1000); + // The ancient sample is gone, so it cannot prop the rate up. + assert_eq!(row.recent.len(), 1); + assert_eq!(row.down, 6000); + } + #[test] fn units_are_decimal_as_isps_quote_them() { assert_eq!(units(1000.0), "1.0 KB"); From a9e92b641a4ffdd6557ba68b045ce363c05f795e Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sat, 22 Aug 2026 23:13:34 +0800 Subject: [PATCH 008/147] rust: clocks reads the real config, and wears the right colours Two faults, both spotted on screen rather than in the code. The config was never being found. The Python's third search path is "beside the script", and a compiled binary has no script - its own directory is target/release, where nobody would keep a config. So it fell through to the built-in four cities while a real file with nineteen sat in the project directory, and it did that silently, which is the worst part. The working directory now stands in for "beside the script", since that is the project directory when a widget is started from a pane, and the executable's own directory is kept last for a binary shipped with a config beside it. There is a test for the search path that would have caught this. The big clock was one flat colour. It is two: the top three rows bright and the base darker, which is what gives the digits their weight. And clocks.py has its own palette - its DIM is a green-grey where the rest of the collection uses a blue-grey - so the whole thing now takes its values from that file rather than from the house set. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/core/src/lib.rs | 25 +++++++++++++++++-- rust/widgets/src/bin/clocks.rs | 45 +++++++++++++++++++++++++--------- 2 files changed, 56 insertions(+), 14 deletions(-) diff --git a/rust/core/src/lib.rs b/rust/core/src/lib.rs index d6ddf57..bac70a4 100644 --- a/rust/core/src/lib.rs +++ b/rust/core/src/lib.rs @@ -208,8 +208,12 @@ pub fn pack_hints(hints: &[Vec<(&str, String)>], width: usize, sep: &str) -> Vec /// Where settings are looked for, in order of preference. /// -/// The same three places the Python looks, so one config file serves both -/// while the collection is half translated. +/// The Python's third place is "beside the script", which a compiled +/// binary does not have: its own directory is target/release, where nobody +/// would put a config. The working directory stands in for it, since that +/// is the project directory when a widget is started from a pane, and the +/// executable's own directory is kept last for a binary shipped with one +/// beside it. pub fn config_paths() -> Vec { let mut found = Vec::new(); if let Ok(env) = std::env::var("TERMINAL_TOYS_CONFIG") { @@ -221,6 +225,9 @@ pub fn config_paths() -> Vec { let home = std::env::var("HOME").unwrap_or_default(); let base = xdg.unwrap_or(format!("{}/.config", home)); found.push(std::path::PathBuf::from(base).join("terminal-toys/config.json")); + if let Ok(cwd) = std::env::current_dir() { + found.push(cwd.join("config.json")); + } if let Ok(exe) = std::env::current_exe() { if let Some(dir) = exe.parent() { found.push(dir.join("config.json")); @@ -428,6 +435,20 @@ pub fn maybe_help(doc: &str) { mod tests { use super::*; + #[test] + fn the_config_search_includes_the_working_directory() { + // The bug this exists for: a compiled binary looked only beside + // itself, which is target/release, and silently used defaults + // while a real config sat in the project directory. + let paths = config_paths(); + let cwd = std::env::current_dir().unwrap().join("config.json"); + assert!(paths.contains(&cwd), "cwd missing from {:?}", paths); + assert!( + paths.iter().any(|p| p.to_string_lossy().contains(".config/terminal-toys")), + "the xdg location must stay, for an installed binary" + ); + } + #[test] fn seg_counts_only_the_text() { let red = rgb(255, 0, 0); diff --git a/rust/widgets/src/bin/clocks.rs b/rust/widgets/src/bin/clocks.rs index cd87924..575ffff 100644 --- a/rust/widgets/src/bin/clocks.rs +++ b/rust/widgets/src/bin/clocks.rs @@ -439,10 +439,16 @@ fn main() { let (w, h) = tc::size(); let now = Local::now(); let mut rows = vec![tc::title("clocks", w, &p.head)]; - rows.push(tc::seg(&[(p.lbl.as_str(), " ── SERVER TIME ── ".into())], w - 1)); + rows.push(tc::seg(&[(p.lbl.as_str(), " ── SERVER TIME ──".into())], w - 1)); - for line in render_big(&now.format("%H:%M:%S").to_string()) { - rows.push(tc::seg(&[(p.big.as_str(), format!(" {}", line))], w - 1)); + // Two colours down the digits, not one: the top three rows are + // bright and the base is darker, which is what gives them weight. + for (i, line) in render_big(&now.format("%H:%M:%S").to_string()) + .into_iter() + .enumerate() + { + let ink = if i < 3 { &p.big_top } else { &p.big_base }; + rows.push(tc::seg(&[(ink.as_str(), format!(" {}", line))], w - 1)); } rows.push(String::new()); rows.push(tc::seg( @@ -457,7 +463,7 @@ fn main() { )); rows.push(String::new()); - rows.push(tc::seg(&[(p.lbl.as_str(), " ── COUNTDOWN ── ".into())], w - 1)); + rows.push(tc::seg(&[(p.lbl.as_str(), " ── COUNTDOWN ──".into())], w - 1)); let bar_w = w.saturating_sub(3).min(90); // The pomodoro leads the section, as it does in the Python. @@ -664,23 +670,28 @@ struct Palette { lbl: String, accent: String, head: String, - big: String, + big_top: String, + big_base: String, bar: String, sun: String, moon: String, } fn palette() -> Palette { + // clocks.py's own palette, value for value. Its DIM is a green-grey + // rather than the blue-grey the other widgets use, and the difference + // is visible the moment the two sit side by side. Palette { focus: tc::rgb(255, 130, 120), - rest: tc::rgb(120, 220, 170), - dim: tc::rgb(127, 147, 172), - txt: tc::rgb(225, 235, 245), - lbl: tc::rgb(130, 165, 200), - accent: tc::rgb(150, 210, 255), + rest: tc::rgb(120, 235, 170), + dim: tc::rgb(70, 130, 110), + txt: tc::rgb(220, 255, 240), + lbl: tc::rgb(70, 130, 110), + accent: tc::rgb(90, 220, 255), head: tc::rgb(0, 255, 170), - big: tc::rgb(220, 255, 240), - bar: tc::rgb(90, 200, 255), + big_top: tc::rgb(120, 255, 200), + big_base: tc::rgb(40, 150, 120), + bar: tc::rgb(90, 220, 255), sun: tc::rgb(255, 210, 120), moon: tc::rgb(150, 170, 210), } @@ -690,6 +701,16 @@ fn palette() -> Palette { mod tests { use super::*; + #[test] + fn the_clock_is_two_colours_down_its_height() { + // The Python paints the top three rows bright and the base dark; + // one flat colour loses the weight of the digits entirely. + let p = palette(); + assert_ne!(p.big_top, p.big_base); + assert_eq!(p.big_top, tc::rgb(120, 255, 200)); + assert_eq!(p.big_base, tc::rgb(40, 150, 120)); + } + #[test] fn digits_are_five_rows_of_blocks() { let rows = render_big("12:34"); From 280c9b26fe7c703bea5313b163c908ca458d890f Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sat, 22 Aug 2026 23:24:19 +0800 Subject: [PATCH 009/147] rust: clocks gets its colours, its weekends, and a configurable week The countdown bars were all one colour. They are three different clocks and the Python gives each its own: cyan for the hour, amber for the office, purple for the day. A single hue made them read as three readings of one thing. The pomodoro line was missing two behaviours as well. Paused takes its own ink, because a stopped timer showing focus red reads as a running one. And once a phase is overrun the bar goes two-toned and rescales to duration plus overtime, so the red share grows the longer it is ignored - the point being that it gets harder to miss rather than sitting there. The world clock was reading light and dark where the Python reads four states: asleep, weekend, working, and the evening either side. The glyph says light or dark and the colour says whether anyone is plausibly at a desk, which is the actual question being asked. It is also sorted west to east now, so the row order is a map. And the office countdown did not know about weekends at all: on a Friday evening it counted to Saturday morning. It now walks to the next working day, and the working week itself is configurable - work_days takes names or numbers, Monday being zero, and defaults to Monday through Friday with the existing nine-to-six hours. That is a step past clocks.py, which hardcodes Mon-Fri. One of my own tests was asserting the bug: it used a Saturday evening and expected twelve hours to "tomorrow". It now uses a Thursday, and says why it changed. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/widgets/src/bin/clocks.rs | 319 ++++++++++++++++++++++++++++----- 1 file changed, 272 insertions(+), 47 deletions(-) diff --git a/rust/widgets/src/bin/clocks.rs b/rust/widgets/src/bin/clocks.rs index 575ffff..4074d61 100644 --- a/rust/widgets/src/bin/clocks.rs +++ b/rust/widgets/src/bin/clocks.rs @@ -95,10 +95,96 @@ struct Countdown { label: String, left: i64, frac: f64, + /// Its own colour: the three are different clocks, not three readings + /// of one, and a single hue makes them look like a stack of the same + /// thing. + ink: String, +} + +/// Which days are working days, and between which hours. +#[derive(Clone)] +struct Office { + /// Monday is 0. Defaults to Monday through Friday. + days: Vec, + start: u32, + end: u32, +} + +impl Office { + fn from_config(cfg: &serde_json::Value) -> Office { + let days = cfg + .get("work_days") + .and_then(|v| v.as_array()) + .map(|a| { + a.iter() + .filter_map(|v| day_number(v)) + .filter(|d| *d < 7) + .collect::>() + }) + .filter(|d: &Vec| !d.is_empty()) + .unwrap_or_else(|| vec![0, 1, 2, 3, 4]); + Office { + days, + start: tc::cfg_usize(cfg, "work_start_hour", 9) as u32, + end: tc::cfg_usize(cfg, "work_end_hour", 18) as u32, + } + } + + fn is_working_day(&self, when: &chrono::DateTime) -> bool { + self.days.contains(&when.weekday().num_days_from_monday()) + } + + fn is_open(&self, when: &chrono::DateTime) -> bool { + self.is_working_day(when) && (self.start..self.end).contains(&when.hour()) + } + + /// The next opening after `now`, skipping days that are not worked. + fn next_open(&self, now: &chrono::DateTime) -> chrono::DateTime { + let mut day = now.date_naive(); + for _ in 0..14 { + let candidate = day.and_time(NaiveTime::from_hms_opt(self.start, 0, 0).unwrap()); + let stamp = Local.from_local_datetime(&candidate).single(); + if let Some(stamp) = stamp { + if stamp > *now && self.is_working_day(&stamp) { + return stamp; + } + } + day += chrono::Duration::days(1); + } + *now + } + + /// The last closing before `now`, for measuring how far into the gap + /// we are - without it the bar has nothing to fill from. + fn prev_close(&self, now: &chrono::DateTime) -> chrono::DateTime { + let mut day = now.date_naive(); + for _ in 0..14 { + let candidate = day.and_time(NaiveTime::from_hms_opt(self.end, 0, 0).unwrap()); + if let Some(stamp) = Local.from_local_datetime(&candidate).single() { + if stamp <= *now && self.is_working_day(&stamp) { + return stamp; + } + } + day -= chrono::Duration::days(1); + } + *now + } +} + +/// A weekday from a config entry, as a number or a name. +fn day_number(value: &serde_json::Value) -> Option { + if let Some(n) = value.as_u64() { + return Some(n as u32); + } + let name = value.as_str()?.to_lowercase(); + ["mon", "tue", "wed", "thu", "fri", "sat", "sun"] + .iter() + .position(|d| name.starts_with(d)) + .map(|i| i as u32) } /// The three fixed countdowns: the hour, the working day, and midnight. -fn countdowns(now: chrono::DateTime, work_start: u32, work_end: u32) -> Vec { +fn countdowns(now: chrono::DateTime, office: &Office) -> Vec { let mut out = Vec::new(); let into_hour = now.minute() as i64 * 60 + now.second() as i64; @@ -106,31 +192,33 @@ fn countdowns(now: chrono::DateTime, work_start: u32, work_end: u32) -> V label: "Next Hour".into(), left: 3600 - into_hour, frac: into_hour as f64 / 3600.0, + ink: tc::rgb(90, 220, 255), }); - // Office hours run to work_end today; past it, to work_start tomorrow. + // Inside working hours this counts to the close; outside them, to the + // next opening - which on a Friday evening is Monday morning, not + // tomorrow. The bar fills from the last close, so the gap has a span. let today = now.date_naive(); - let start = today.and_time(NaiveTime::from_hms_opt(work_start, 0, 0).unwrap()); - let end = today.and_time(NaiveTime::from_hms_opt(work_end, 0, 0).unwrap()); - let naive = now.naive_local(); - let (label, target, from) = if naive < start { - ("Start of Office Hour", start, start - chrono::Duration::hours(12)) - } else if naive < end { + let (label, target, from) = if office.is_open(&now) { + let start = Local + .from_local_datetime(&today.and_time(NaiveTime::from_hms_opt(office.start, 0, 0).unwrap())) + .single() + .unwrap_or(now); + let end = Local + .from_local_datetime(&today.and_time(NaiveTime::from_hms_opt(office.end, 0, 0).unwrap())) + .single() + .unwrap_or(now); ("End of Office Hour", end, start) } else { - let tomorrow = today + chrono::Duration::days(1); - ( - "Start of Office Hour", - tomorrow.and_time(NaiveTime::from_hms_opt(work_start, 0, 0).unwrap()), - end, - ) + ("Start of Office Hour", office.next_open(&now), office.prev_close(&now)) }; let span = (target - from).num_seconds().max(1); - let left = (target - naive).num_seconds(); + let left = (target - now).num_seconds(); out.push(Countdown { label: label.into(), left, frac: 1.0 - (left as f64 / span as f64), + ink: tc::rgb(255, 200, 90), }); let into_day = now.num_seconds_from_midnight() as i64; @@ -138,6 +226,7 @@ fn countdowns(now: chrono::DateTime, work_start: u32, work_end: u32) -> V label: "End of Day".into(), left: 86400 - into_day, frac: into_day as f64 / 86400.0, + ink: tc::rgb(175, 130, 255), }); out } @@ -391,8 +480,7 @@ struct City { fn main() { tc::maybe_help(include_str!("clocks_help.txt")); let cfg = tc::load_config("clocks"); - let work_start = tc::cfg_usize(&cfg, "work_start_hour", 9) as u32; - let work_end = tc::cfg_usize(&cfg, "work_end_hour", 18) as u32; + let office = Office::from_config(&cfg); let cities = load_cities(&cfg); let p = palette(); @@ -488,15 +576,23 @@ fn main() { let over = pomo.overtime(stamp); let left = pomo.remaining(stamp); let frac = 1.0 - (left / pomo.duration().max(1.0)); + // Paused takes its own ink: a stopped timer showing focus red + // reads as one that is running. + let ink = if !pomo.running { + &p.paused + } else if pomo.phase == Phase::Focus { + &p.focus + } else { + &p.rest + }; rows.push(tc::seg( &[ - (p.txt.as_str(), " Pomodoro · ".into()), ( - if pomo.phase == Phase::Focus { &p.focus } else { &p.rest }, - format!("{:<12}", pomo.phase.label()), + ink.as_str(), + format!(" {}", tc::pad(&format!("Pomodoro · {}", pomo.phase.label()), 23)), ), ( - if over > 0.0 { &p.focus } else { &p.accent }, + if over > 0.0 { &p.over } else { &p.txt }, if over > 0.0 { format!("+{}", hms(over as i64)) } else { @@ -504,25 +600,38 @@ fn main() { }, ), ( - p.dim.as_str(), - format!( - " {} {} done", - if pomo.running { "running" } else { "paused" }, - pomo.done - ), + p.paused.as_str(), + if pomo.running { String::new() } else { " paused".into() }, ), + ( + if over > 0.0 { &p.over } else { &p.dim }, + if over > 0.0 { " OVER".into() } else { String::new() }, + ), + (p.dim.as_str(), format!(" {} done", pomo.done)), ], w - 1, )); - rows.push(tc::seg( - &[( - if pomo.phase == Phase::Focus { &p.focus } else { &p.rest }, - format!(" {}", bar(frac, bar_w)), - )], - w - 1, - )); + if over > 0.0 { + // The bar rescales to duration plus overtime, so the red + // share grows the longer the phase is ignored - the point + // being that it keeps getting harder to miss. + let total = pomo.duration() + over; + let base = ((bar_w as f64 * pomo.duration() / total).round() as usize).max(1); + rows.push(tc::seg( + &[ + (ink.as_str(), format!(" {}", "█".repeat(base))), + (p.over.as_str(), "█".repeat(bar_w.saturating_sub(base))), + ], + w - 1, + )); + } else { + rows.push(tc::seg( + &[(ink.as_str(), format!(" {}", bar(frac, bar_w)))], + w - 1, + )); + } } - for item in countdowns(now, work_start, work_end) { + for item in countdowns(now, &office) { rows.push(tc::seg( &[ (p.txt.as_str(), format!(" {:<21}", item.label)), @@ -531,7 +640,7 @@ fn main() { w - 1, )); rows.push(tc::seg( - &[(p.bar.as_str(), format!(" {}", bar(item.frac, bar_w)))], + &[(item.ink.as_str(), format!(" {}", bar(item.frac, bar_w)))], w - 1, )); } @@ -559,14 +668,11 @@ fn main() { let there = now.with_timezone(&city.zone); // Sun or moon by the local hour, which is the fastest way // to read "is it a reasonable time to message them". - let awake = (7..19).contains(&there.hour()); + let (ink, glyph) = phase_of(&there, &p); let day_shift = there.date_naive().signed_duration_since(now.date_naive()).num_days(); rows.push(tc::seg( &[ - ( - if awake { &p.sun } else { &p.moon }, - format!(" {} ", if awake { "☀" } else { "☾" }), - ), + (ink.as_str(), format!(" {} ", glyph)), (p.txt.as_str(), tc::pad(&city.name, 16)), (p.txt.as_str(), there.format("%H:%M").to_string()), ( @@ -619,6 +725,30 @@ fn main() { } } +/// Colour and glyph for what people there are plausibly doing. +/// +/// Four states rather than two: asleep, weekend, working, and the evening +/// either side of it. The glyph says light or dark and the colour says +/// whether anyone is likely to be at a desk, which is the actual question +/// being asked of a world clock. +fn phase_of(there: &chrono::DateTime, p: &Palette) -> (String, &'static str) { + let hour = there.hour() as f64 + there.minute() as f64 / 60.0; + let weekend = there.weekday().num_days_from_monday() >= 5; + if hour < 6.5 || hour >= 22.0 { + return (p.night.clone(), "☾"); + } + if weekend { + return (p.weekend.clone(), "☀"); + } + if (9.0..18.0).contains(&hour) { + return (p.work.clone(), "☀"); + } + if hour >= 18.0 { + return (p.eve.clone(), "☾"); + } + (p.eve.clone(), "☀") +} + /// The configured cities, or the four the Python ships with. /// /// A zone the database does not know is dropped rather than defaulted to @@ -637,6 +767,17 @@ fn load_cities(cfg: &serde_json::Value) -> Vec { } } } + if !out.is_empty() { + // West to east by current offset, so the row order is a map. + let now = Utc::now(); + out.sort_by_key(|c| { + ( + now.with_timezone(&c.zone).offset().fix().local_minus_utc(), + c.name.clone(), + ) + }); + return out; + } if out.is_empty() { for (name, zone) in [ ("San Francisco", "America/Los_Angeles"), @@ -665,6 +806,12 @@ fn seconds() -> f64 { struct Palette { focus: String, rest: String, + paused: String, + over: String, + work: String, + eve: String, + night: String, + weekend: String, dim: String, txt: String, lbl: String, @@ -684,6 +831,12 @@ fn palette() -> Palette { Palette { focus: tc::rgb(255, 130, 120), rest: tc::rgb(120, 235, 170), + paused: tc::rgb(160, 172, 190), + over: tc::rgb(255, 80, 90), + work: tc::rgb(130, 255, 180), + eve: tc::rgb(255, 200, 90), + night: tc::rgb(95, 130, 175), + weekend: tc::rgb(150, 150, 170), dim: tc::rgb(70, 130, 110), txt: tc::rgb(220, 255, 240), lbl: tc::rgb(70, 130, 110), @@ -701,6 +854,75 @@ fn palette() -> Palette { mod tests { use super::*; + #[test] + fn friday_evening_counts_to_monday_not_saturday() { + let office = Office::from_config(&serde_json::json!({})); + // Friday 21 August 2026 at 19:00 - after the close, and the next + // working day is three days off. + let friday = Local.with_ymd_and_hms(2026, 8, 21, 19, 0, 0).unwrap(); + assert!(!office.is_open(&friday)); + let opens = office.next_open(&friday); + assert_eq!(opens.weekday(), chrono::Weekday::Mon); + assert_eq!(opens.hour(), 9); + // Which is nearly three days, not the fourteen hours a naive + // "tomorrow at nine" would give. + let items = countdowns(friday, &office); + assert!(items[1].left > 48 * 3600, "got {}s", items[1].left); + } + + #[test] + fn a_saturday_is_not_a_working_day() { + let office = Office::from_config(&serde_json::json!({})); + let saturday = Local.with_ymd_and_hms(2026, 8, 22, 11, 0, 0).unwrap(); + assert!(!office.is_open(&saturday), "eleven on a Saturday is not office hours"); + assert_eq!(countdowns(saturday, &office)[1].label, "Start of Office Hour"); + } + + #[test] + fn the_working_week_can_be_configured() { + // A Sunday-to-Thursday week, as much of the Gulf works. + let office = Office::from_config(&serde_json::json!({ + "work_days": ["sun", "mon", "tue", "wed", "thu"], + "work_start_hour": 8, + "work_end_hour": 16 + })); + let sunday = Local.with_ymd_and_hms(2026, 8, 23, 9, 0, 0).unwrap(); + assert!(office.is_open(&sunday), "Sunday is a working day there"); + let friday = Local.with_ymd_and_hms(2026, 8, 21, 9, 0, 0).unwrap(); + assert!(!office.is_open(&friday), "Friday is not"); + // Numbers work as well as names, Monday being zero. + let by_number = Office::from_config(&serde_json::json!({"work_days": [0, 1, 2]})); + assert_eq!(by_number.days, vec![0, 1, 2]); + // And nonsense falls back rather than emptying the week. + let junk = Office::from_config(&serde_json::json!({"work_days": []})); + assert_eq!(junk.days, vec![0, 1, 2, 3, 4]); + } + + #[test] + fn each_countdown_gets_its_own_colour() { + let now = Local.with_ymd_and_hms(2026, 8, 22, 14, 30, 0).unwrap(); + let items = countdowns(now, &Office::from_config(&serde_json::json!({}))); + let inks: std::collections::HashSet = + items.iter().map(|c| c.ink.clone()).collect(); + assert_eq!(inks.len(), 3, "three clocks, three colours"); + } + + #[test] + fn the_world_clock_reads_more_than_light_and_dark() { + let p = palette(); + let tokyo: Tz = "Asia/Tokyo".parse().unwrap(); + let at = |h: u32, d: u32| { + tokyo.with_ymd_and_hms(2026, 8, d, h, 0, 0).unwrap() + }; + // Saturday the 22nd, Monday the 24th. + assert_eq!(phase_of(&at(3, 24), &p).1, "☾", "the small hours"); + assert_eq!(phase_of(&at(11, 24), &p), (p.work.clone(), "☀")); + assert_eq!(phase_of(&at(19, 24), &p), (p.eve.clone(), "☾")); + assert_eq!(phase_of(&at(8, 24), &p), (p.eve.clone(), "☀")); + // A weekday's working hours and a weekend's are different answers. + assert_eq!(phase_of(&at(11, 22), &p), (p.weekend.clone(), "☀")); + } + #[test] fn the_clock_is_two_colours_down_its_height() { // The Python paints the top three rows bright and the base dark; @@ -755,7 +977,7 @@ mod tests { // "Start of Office Hour" is exactly twenty characters, and a // twenty-wide field ran it straight into the time beside it. let now = Local.with_ymd_and_hms(2026, 8, 22, 7, 0, 0).unwrap(); - let longest = countdowns(now, 9, 18) + let longest = countdowns(now, &Office::from_config(&serde_json::json!({}))) .into_iter() .map(|c| c.label.chars().count()) .max() @@ -872,7 +1094,7 @@ mod tests { #[test] fn the_countdowns_stay_inside_their_spans() { let now = Local.with_ymd_and_hms(2026, 8, 22, 14, 30, 0).unwrap(); - let items = countdowns(now, 9, 18); + let items = countdowns(now, &Office::from_config(&serde_json::json!({}))); assert_eq!(items.len(), 3); for item in &items { assert!(item.left > 0, "{} had {}s left", item.label, item.left); @@ -883,11 +1105,14 @@ mod tests { } #[test] - fn after_hours_counts_to_tomorrow_morning() { - let evening = Local.with_ymd_and_hms(2026, 8, 22, 21, 0, 0).unwrap(); - let items = countdowns(evening, 9, 18); + fn a_weekday_evening_counts_to_the_next_morning() { + // Thursday 20 August 2026 at nine in the evening: twelve hours to + // Friday's opening. This test previously used a Saturday and + // expected the same answer, which is how the missing weekend + // handling went unnoticed - the assertion encoded the bug. + let evening = Local.with_ymd_and_hms(2026, 8, 20, 21, 0, 0).unwrap(); + let items = countdowns(evening, &Office::from_config(&serde_json::json!({}))); assert_eq!(items[1].label, "Start of Office Hour"); - // Twelve hours to nine the next morning. assert_eq!(items[1].left, 12 * 3600); } } From 8346dca69a4c81978807eb70570187b90769ac00 Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sat, 22 Aug 2026 23:26:31 +0800 Subject: [PATCH 010/147] clocks: pin the office countdown at every point in a week Yes, it counts to the close during working hours - and rather than say so, here is a test that walks a Monday-to-Sunday and asserts each case: inside hours counting down to six, the hour before opening counting up to nine, a weekday evening pointing at tomorrow morning, and Friday evening through Sunday all pointing at Monday. The boundary is in there too, since it is the one that gets written the wrong way round: five in the afternoon is still inside the working day. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/widgets/src/bin/clocks.rs | 41 ++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/rust/widgets/src/bin/clocks.rs b/rust/widgets/src/bin/clocks.rs index 4074d61..83c8c5e 100644 --- a/rust/widgets/src/bin/clocks.rs +++ b/rust/widgets/src/bin/clocks.rs @@ -854,6 +854,47 @@ fn palette() -> Palette { mod tests { use super::*; + #[test] + fn the_office_countdown_across_a_whole_week() { + let office = Office::from_config(&serde_json::json!({})); + // 2026-08-17 is a Monday, so +n days walks the week. + let at = |day: u32, hour: u32| { + Local.with_ymd_and_hms(2026, 8, day, hour, 0, 0).unwrap() + }; + let read = |when| { + let items = countdowns(when, &office); + (items[1].label.clone(), items[1].left) + }; + + // Inside hours on a working day: counting to the close. + let (label, left) = read(at(18, 11)); // Tuesday 11:00 + assert_eq!(label, "End of Office Hour"); + assert_eq!(left, 7 * 3600, "seven hours until six"); + + // Just before opening: counting to it, an hour off. + let (label, left) = read(at(18, 8)); + assert_eq!(label, "Start of Office Hour"); + assert_eq!(left, 3600); + + // After the close on a weekday: tomorrow morning. + let (label, left) = read(at(18, 19)); + assert_eq!(label, "Start of Office Hour"); + assert_eq!(left, 14 * 3600); + + // The last minute of the working day is still inside it. + let (label, _) = read(at(18, 17)); + assert_eq!(label, "End of Office Hour"); + + // Friday evening, Saturday, Sunday: all pointing at Monday. + for (day, hour) in [(21, 19), (22, 11), (23, 11)] { + let (label, left) = read(at(day, hour)); + assert_eq!(label, "Start of Office Hour", "on day {}", day); + let opens = office.next_open(&at(day, hour)); + assert_eq!(opens.weekday(), chrono::Weekday::Mon, "on day {}", day); + assert!(left > 0); + } + } + #[test] fn friday_evening_counts_to_monday_not_saturday() { let office = Office::from_config(&serde_json::json!({})); From 5802474e704a770ff336ac1c0ea61d19db9525c3 Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sat, 22 Aug 2026 23:47:29 +0800 Subject: [PATCH 011/147] clocks: the pomodoro's controls, and a footer that reads properly MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The keys existed and nothing said so. space, restart and advance were all bound and none appeared in the footer, which makes them unreachable unless you read the source. They are there now, with [±] to nudge the focus length and [0]reset, which stays hidden until there is a tally worth resetting. One key for the break, named for what it will do: [b]reak start during focus, [b]reak stop during one, and [b]reak start (long) on the block before a long one - the label follows the phase rather than being a fixed word like "skip" that describes neither direction. The tips start hidden. Four extra hints is a lot of bottom line for a timer that is usually just sitting there, and [?] is always on show to bring them back; show_hints in the config still decides either way. This is a step away from clocks.py, which starts them visible. [p]off now reads [p]omodoro off, and the cities hint leads the footer as navigation does in every other widget. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/widgets/src/bin/clocks.rs | 130 +++++++++++++++++++++++++++++++-- 1 file changed, 122 insertions(+), 8 deletions(-) diff --git a/rust/widgets/src/bin/clocks.rs b/rust/widgets/src/bin/clocks.rs index 83c8c5e..3d3c734 100644 --- a/rust/widgets/src/bin/clocks.rs +++ b/rust/widgets/src/bin/clocks.rs @@ -440,6 +440,39 @@ impl Pomodoro { self.rang_at = -1; } + /// What pressing the break key will do, right now. + /// + /// One key for both directions, and the label says which it is about to + /// do rather than a fixed word like "skip" that describes neither. The + /// long break is called out because it is the one worth waiting for. + fn next_label(&self) -> String { + if self.phase != Phase::Focus { + return "[b]reak stop".into(); + } + let long_next = self.before_long > 0 && (self.done + 1) % self.before_long == 0; + if long_next { + "[b]reak start (long)".into() + } else { + "[b]reak start".into() + } + } + + /// Zero the tally, once there is something to zero. + fn reset_count(&mut self) { + self.done = 0; + } + + /// Lengthen or shorten the focus block, in minutes. + fn adjust(&mut self, delta: f64, now: f64) { + self.focus = (self.focus + delta).clamp(1.0, 180.0); + if self.phase == Phase::Focus { + self.left = self.duration(); + if self.running { + self.deadline = now + self.left; + } + } + } + fn restart(&mut self, now: f64) { self.left = self.duration(); self.deadline = now + self.left; @@ -502,6 +535,14 @@ fn main() { .and_then(|v| v.as_bool()) .unwrap_or(true); let mut flash_started: Option = None; + // Hidden by default: four extra hints on the bottom line is a lot of + // footer for a timer that is usually just sitting there, and [?] is + // always on show to bring them back. clocks.py starts them visible; + // show_hints in the config still decides either way. + let mut tips = cfg + .get("show_hints") + .and_then(|v| v.as_bool()) + .unwrap_or(false); tc::setup(); let mut keyboard = tc::Keyboard::new(); let mut scroll = 0usize; @@ -518,8 +559,12 @@ fn main() { "down" | "j" | "J" => scroll += 1, "p" | "P" => pomo.toggle(seconds()), " " => pomo.start_stop(seconds()), - "n" | "N" => pomo.advance(seconds()), + "b" | "B" => pomo.advance(seconds()), "r" | "R" => pomo.restart(seconds()), + "0" | "c" => pomo.reset_count(), + "+" | "=" => pomo.adjust(1.0, seconds()), + "-" | "_" => pomo.adjust(-1.0, seconds()), + "?" | "h" => tips = !tips, _ => {} } } @@ -693,14 +738,50 @@ fn main() { } } - let hints: Vec> = vec![ - vec![( + // Navigation first, as every other widget in the collection has it, + // then the pomodoro's own controls, then the panel keys. Only the + // pomodoro controls hide behind ?: hiding the way back would leave + // no way back. + let mut hints: Vec> = vec![vec![ + (p.accent.as_str(), "↑↓".into()), + (p.dim.as_str(), " cities".into()), + ]]; + if pomo.shown && tips { + hints.push(vec![ + (p.dim.as_str(), "[space] ".into()), + ( + p.txt.as_str(), + if pomo.running { "pause".into() } else { "start".into() }, + ), + ]); + hints.push(vec![(p.dim.as_str(), pomo.next_label())]); + hints.push(vec![(p.dim.as_str(), "[r]estart".into())]); + hints.push(vec![(p.dim.as_str(), format!("[±]{}min", pomo.focus as i64))]); + if pomo.done > 0 { + // Nothing to reset at zero, so it only appears once it counts. + hints.push(vec![( + p.dim.as_str(), + format!("[0]reset {} done", pomo.done), + )]); + } + } + hints.push(vec![( + p.dim.as_str(), + if pomo.shown { + "[p]omodoro off".into() + } else { + "[p]omodoro".into() + }, + )]); + if pomo.shown { + // Shown even when the controls are hidden, so there is always a + // way back. Names the action rather than the state. + hints.push(vec![( p.dim.as_str(), - format!("[p]{}", if pomo.shown { "off" } else { "omodoro" }), - )], - vec![(p.accent.as_str(), "↑↓".into()), (p.dim.as_str(), " cities".into())], - vec![(p.dim.as_str(), "[q]uit".into())], - ]; + format!("[?]{} pomodoro tips", if tips { "hide" } else { "show" }), + )]); + } + hints.push(vec![(p.dim.as_str(), "[q]uit".into())]); let foot: Vec = tc::pack_hints(&hints, w - 2, " ") .into_iter() .map(|l| format!(" {}", l)) @@ -854,6 +935,39 @@ fn palette() -> Palette { mod tests { use super::*; + #[test] + fn the_advance_key_says_what_it_will_do() { + let mut pomo = Pomodoro::new(&serde_json::json!({})); + // Three blocks done, so the fourth leads to the long break and the + // hint has to say so rather than promising an ordinary one. + assert_eq!(pomo.next_label(), "[b]reak start"); + pomo.done = 3; + assert_eq!(pomo.next_label(), "[b]reak start (long)"); + pomo.phase = Phase::Short; + assert_eq!(pomo.next_label(), "[b]reak stop"); + } + + #[test] + fn the_focus_length_can_be_nudged_and_stays_sane() { + let mut pomo = Pomodoro::new(&serde_json::json!({})); + pomo.adjust(5.0, 0.0); + assert_eq!(pomo.focus, 30.0); + assert_eq!(pomo.duration(), 30.0 * 60.0); + // It cannot be driven to zero or beyond a working day. + for _ in 0..100 { + pomo.adjust(-10.0, 0.0); + } + assert!(pomo.focus >= 1.0, "focus fell to {}", pomo.focus); + } + + #[test] + fn the_tally_resets_only_when_there_is_one() { + let mut pomo = Pomodoro::new(&serde_json::json!({})); + pomo.done = 4; + pomo.reset_count(); + assert_eq!(pomo.done, 0); + } + #[test] fn the_office_countdown_across_a_whole_week() { let office = Office::from_config(&serde_json::json!({})); From cf5948383a1c8369a0f385ce44e92ac849926fbe Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sat, 22 Aug 2026 23:50:11 +0800 Subject: [PATCH 012/147] clocks: the focus hint says both the step and the length MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [±]25min was ambiguous in a way I had not noticed until it was asked about: it could as easily mean "sets it to 25" as "adjusts a 25-minute block", and it never said what the 25 minutes was. It now reads [±]1min (focus 25min), which answers both questions. The step says what the key will do, and is the half a footer is normally for. The value is worth carrying too, because it is the only place the block length appears while the timer is running - the countdown shows what is left rather than what it started from, and the bar is a fraction of a number that is not on screen. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/widgets/src/bin/clocks.rs | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/rust/widgets/src/bin/clocks.rs b/rust/widgets/src/bin/clocks.rs index 3d3c734..aa291d3 100644 --- a/rust/widgets/src/bin/clocks.rs +++ b/rust/widgets/src/bin/clocks.rs @@ -756,7 +756,15 @@ fn main() { ]); hints.push(vec![(p.dim.as_str(), pomo.next_label())]); hints.push(vec![(p.dim.as_str(), "[r]estart".into())]); - hints.push(vec![(p.dim.as_str(), format!("[±]{}min", pomo.focus as i64))]); + // Both halves, because each answers a question the other does + // not. The step says what the key will do; the value is the + // only place the block length appears while the timer runs, + // since the countdown shows what is left rather than what it + // started from. + hints.push(vec![ + (p.dim.as_str(), "[±]1min ".to_string()), + (p.txt.as_str(), format!("(focus {}min)", pomo.focus as i64)), + ]); if pomo.done > 0 { // Nothing to reset at zero, so it only appears once it counts. hints.push(vec![( From 2d6711967bd1219be5a6479b8053b84ccae3aff3 Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sun, 23 Aug 2026 01:28:43 +0800 Subject: [PATCH 013/147] link: match the Python, which the port had drifted from Running the two side by side at the same width is the only thing that catches this class of bug, and it found several. The table's data columns sat three cells right of their own headings - the glyph carried a leading space and the name column was padded to twenty rather than eighteen - and each half looked plausible on its own, so nothing inside the file could have flagged it. The LOSS column was reporting a different number entirely: retransmits since the socket opened, rather than since the last poll. link.py measures the recent figure deliberately, because a session hours old has long since forgiven whatever went wrong at breakfast. A quiet SSH connection read 0.34% here and 0.00% there, and the higher number was the wrong question. Also restored from the original: the round-trip cell's colour, which is judged against the socket's own minrtt rather than a fixed threshold, so forty milliseconds reads as excellent from Hong Kong and poor from the next rack; the dimming of unselected names; kbps rather than Kbps; "--" for an absent reading rather than an em dash, at the column's own width so a missing value cannot shift the row; and span()'s thresholds, which had been sitting half again past where the unit changes, calling ninety seconds "90s". The detail view had not been ported at all - Enter, escape, the [r]efresh key and their two footer hints were all missing, and with them the only screen that reports lifetime loss, pacing rate, packet size, reordering and the logins behind an address. `who` now keeps the tty and the repeats it needs to name two sessions from one laptop. The tests are pinned to a row captured from link.py in an 85-column pty rather than to my own reading of the code. Two of the existing ones asserted the drift. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/widgets/src/bin/link.rs | 600 ++++++++++++++++++++++++++++++++--- 1 file changed, 548 insertions(+), 52 deletions(-) diff --git a/rust/widgets/src/bin/link.rs b/rust/widgets/src/bin/link.rs index 4bcbcd4..a20dc7e 100644 --- a/rust/widgets/src/bin/link.rs +++ b/rust/widgets/src/bin/link.rs @@ -22,7 +22,7 @@ //! measured for each established socket. use std::collections::HashMap; -use std::sync::{Arc, Mutex}; +use std::sync::{Arc, Condvar, Mutex}; use std::time::Duration; use toys_core as tc; @@ -42,6 +42,10 @@ struct Session { sent: f64, recv: f64, retrans_bytes: f64, + /// Retransmits since the previous poll, as a percentage of what was + /// sent in that gap. Filled in by the poller, which is the only place + /// that has the previous reading to subtract. + recent_loss: Option, delivery: Option, cwnd: Option, mss: Option, @@ -162,6 +166,7 @@ fn sessions() -> Vec { sent: num(&m, "bytes_sent").unwrap_or(0.0), recv: num(&m, "bytes_received").unwrap_or(0.0), retrans_bytes: num(&m, "bytes_retrans").unwrap_or(0.0), + recent_loss: None, delivery: num(&m, "delivery_rate"), cwnd: num(&m, "cwnd"), mss: num(&m, "mss"), @@ -175,25 +180,28 @@ fn sessions() -> Vec { } /// Who is logged in from where, to put a name against an address. -fn who() -> HashMap> { - let mut seen: HashMap> = HashMap::new(); +/// +/// Login and tty, not just the login: two SSH sessions from one laptop share +/// an address, and the detail view names the ttys to say so. Repeats are +/// kept for the same reason - deduplicating by user threw away the second +/// session, which is the fact that line exists to report. +fn who() -> HashMap> { + let mut seen: HashMap> = HashMap::new(); for line in run(&["who"]).lines() { let cols: Vec<&str> = line.split_whitespace().collect(); if cols.len() < 2 { continue; } - let user = cols[0]; - // The address is in parentheses at the end, where there is one. - if let Some(open) = line.rfind('(') { - if let Some(close) = line[open..].find(')') { - let host = &line[open + 1..open + close]; - if !host.is_empty() { - let names = seen.entry(host.to_string()).or_default(); - if !names.iter().any(|n| n == user) { - names.push(user.to_string()); - } - } - } + // The address is the last field, in parentheses, where there is one. + let last = cols[cols.len() - 1]; + if !last.starts_with('(') { + continue; + } + let host = last.trim_matches(|c| c == '(' || c == ')'); + if !host.is_empty() { + seen.entry(host.to_string()) + .or_default() + .push((cols[0].to_string(), cols[1].to_string())); } } seen @@ -201,22 +209,32 @@ fn who() -> HashMap> { fn rate(n: Option) -> String { let v = match n { - Some(v) if v > 0.0 => v, - _ => return "—".into(), + Some(v) => v, + None => return "--".into(), }; - for (suffix, scale) in [("Gbps", 1e9), ("Mbps", 1e6), ("Kbps", 1e3)] { + for (suffix, scale) in [("Gbps", 1e9), ("Mbps", 1e6), ("kbps", 1e3)] { if v >= scale { return format!("{:.1}{}", v / scale, suffix); } } - format!("{:.0}bps", v) + format!("{}bps", v as i64) +} + +/// A byte count as a person would say it. +fn size_of(n: f64) -> String { + for (unit, step) in [("G", 1e9), ("M", 1e6), ("k", 1e3)] { + if n >= step { + return format!("{:.1}{}", n / step, unit); + } + } + format!("{}B", n as i64) } /// Milliseconds on link.py's own scale, which drops to microseconds below /// one: a loopback socket reads 22us, and 0.02ms hides what that means. fn ms(value: Option) -> String { match value { - None => "—".into(), + None => "--".into(), Some(v) if v >= 100.0 => format!("{}ms", v.round() as i64), Some(v) if v >= 10.0 => format!("{:.0}ms", v), Some(v) if v >= 1.0 => format!("{:.1}ms", v), @@ -228,19 +246,48 @@ fn ms(value: Option) -> String { fn span(milliseconds: Option) -> String { let s = match milliseconds { Some(v) => v / 1000.0, - None => return "—".into(), + None => return "--".into(), }; - if s < 90.0 { + if s < 60.0 { format!("{}s", s as i64) - } else if s < 5400.0 { + } else if s < 3600.0 { format!("{}m", (s / 60.0) as i64) - } else if s < 172_800.0 { + } else if s < 86400.0 { format!("{}h", (s / 3600.0) as i64) } else { format!("{}d", (s / 86400.0) as i64) } } +/// How much worse than this path's best the connection is right now. +/// +/// Compared against the socket's own minrtt rather than a fixed threshold: +/// forty milliseconds is excellent from Hong Kong and poor from the next +/// rack, and the kernel already knows which this is. +fn quality(row: &Session) -> Option { + match (row.rtt, row.floor) { + (Some(rtt), Some(floor)) if rtt != 0.0 && floor != 0.0 => Some(rtt / floor), + _ => None, + } +} + +fn colour_for<'a>(ratio: Option, loss: Option, p: &'a Palette) -> &'a str { + if loss.is_some_and(|l| l >= 2.0) { + return &p.bad; + } + let ratio = match ratio { + Some(r) => r, + None => return &p.dim, + }; + if ratio >= 3.0 || loss.unwrap_or(0.0) >= 0.5 { + &p.bad + } else if ratio >= 1.6 { + &p.warn + } else { + &p.ok + } +} + fn sparkline(values: &[f64], width: usize) -> String { if values.is_empty() { return String::new(); @@ -291,7 +338,7 @@ fn window_label(seconds: f64) -> String { struct State { rows: Vec, - names: HashMap>, + names: HashMap>, history: HashMap>, err: String, } @@ -330,10 +377,30 @@ fn main() { history: HashMap::new(), err: String::new(), })); + // [r] asks for a reading now rather than at the end of the interval, so + // the poller sleeps on a condition it can be woken out of. + let wake = Arc::new((Mutex::new(false), Condvar::new())); let poller = Arc::clone(&state); - std::thread::spawn(move || loop { - let found = sessions(); + let poller_wake = Arc::clone(&wake); + std::thread::spawn(move || { + let mut last: HashMap = HashMap::new(); + loop { + let mut found = sessions(); let names = who(); + for row in &mut found { + // Retransmits since the last look, rather than since the + // connection opened: a session hours old has long since + // forgiven whatever went wrong at breakfast. + if let Some((sent, retrans)) = last.get(&row.peer) { + let moved = row.sent - sent; + row.recent_loss = Some(if moved > 0.0 { + 100.0 * (row.retrans_bytes - retrans) / moved + } else { + 0.0 + }); + } + last.insert(row.peer.clone(), (row.sent, row.retrans_bytes)); + } { let mut guard = match poller.lock() { Ok(g) => g, @@ -352,12 +419,25 @@ fn main() { guard.rows = found; guard.names = names; } - std::thread::sleep(Duration::from_secs_f64(refresh)); + let (lock, cond) = &*poller_wake; + let mut asked = match lock.lock() { + Ok(g) => g, + Err(_) => return, + }; + if !*asked { + asked = match cond.wait_timeout(asked, Duration::from_secs_f64(refresh)) { + Ok((g, _)) => g, + Err(_) => return, + }; + } + *asked = false; + } }); tc::setup(); let mut keyboard = tc::Keyboard::new(); let (mut selected, mut hide_idle, mut span_at) = (0usize, false, 0usize); + let mut detail = false; loop { for key in keyboard.poll() { @@ -369,8 +449,17 @@ fn main() { } "up" | "k" | "K" => selected = selected.saturating_sub(1), "down" | "j" | "J" => selected += 1, + "enter" | "i" | "I" => detail = !detail, + "esc" => detail = false, "o" | "O" => hide_idle = !hide_idle, "w" | "W" => span_at = (span_at + 1) % windows.len(), + "r" | "R" => { + let (lock, cond) = &*wake; + if let Ok(mut asked) = lock.lock() { + *asked = true; + cond.notify_all(); + } + } _ => {} } } @@ -391,6 +480,42 @@ fn main() { } let window = windows[span_at]; + // One connection in full, on its own screen. The list is for + // noticing; this is for looking into, and the two want different + // amounts of room for the same chart. + if detail && !shown.is_empty() { + let pick = selected.min(shown.len() - 1); + // The footer is measured before the body is built, and the body + // is told the height it actually has. Sizing the chart to the + // whole pane and appending the hints afterwards pushed them off + // the bottom of it - the keys out of this screen were the rows + // being lost. + let hints: Vec> = vec![ + vec![(p.dim.as_str(), "[esc] back".into())], + vec![ + (p.accent.as_str(), "[w]".into()), + (p.dim.as_str(), format!(" {}", window_label(window))), + ], + vec![(p.dim.as_str(), "[r]efresh".into())], + vec![(p.dim.as_str(), "[q]uit".into())], + ]; + let foot: Vec = tc::pack_hints(&hints, w - 2, " ") + .into_iter() + .map(|l| format!(" {}", l)) + .collect(); + let room = h.saturating_sub(foot.len() + 1).max(1); + let mut body = detail_view(&shown[pick], &guard, w, room, pick, window, refresh, &p); + drop(guard); + body.truncate(room); + while body.len() < room { + body.push(String::new()); + } + body.extend(foot); + tc::draw(&body, w, h); + std::thread::sleep(Duration::from_millis(200)); + continue; + } + let mut rows = vec![tc::title("connections", w, &p.link)]; rows.push(tc::seg( &[ @@ -428,7 +553,7 @@ fn main() { rows.push(String::new()); let room = h.saturating_sub(rows.len() + 4); if room >= 5 { - rows.extend(graph(&shown, &guard.history, w, room, window, refresh, &p)); + rows.extend(graph(&shown, &guard.history, w, room, 0, window, refresh, &p)); rows.push(tc::seg( &[ (p.dim.as_str(), " ".repeat(7)), @@ -439,7 +564,7 @@ fn main() { let covered = plotted_span(&shown, &guard.history, window, refresh, w); rows.push(tc::seg( &[ - (p.dim.as_str(), format!(" {} ago", window_label(covered))), + (p.dim.as_str(), format!(" {} ago", span(Some(covered * 1000.0)))), (p.dim.as_str(), " ".repeat(w.saturating_sub(26).max(1))), (p.dim.as_str(), "now".into()), ], @@ -450,6 +575,7 @@ fn main() { let hints: Vec> = vec![ vec![(p.accent.as_str(), "↑↓".into()), (p.dim.as_str(), " select".into())], + vec![(p.dim.as_str(), "[↵] open".into())], vec![ (p.accent.as_str(), "[w]".into()), (p.dim.as_str(), format!(" {}", window_label(window))), @@ -458,6 +584,7 @@ fn main() { p.dim.as_str(), format!("[o]{} idle", if hide_idle { "show" } else { "hide" }), )], + vec![(p.dim.as_str(), "[r]efresh".into())], vec![(p.dim.as_str(), "[q]uit".into())], ]; drop(guard); @@ -495,7 +622,11 @@ fn table(rows: &[Session], state: &State, w: usize, selected: usize, p: &Palette // The Python's header, column for column: the two have to sit side by // side in a wall and read as the same widget. let wide = w >= 74; - let name_w = 20usize; + // Two for the glyph and its space, eighteen for the name: together they + // land the NOW column under its heading. Three and twenty also add up to + // a plausible-looking row, and put every number three cells right of the + // word above it. + let name_w = 18usize; let mut out = vec![tc::seg( &[ (p.dim.as_str(), " PEER".into()), @@ -511,36 +642,52 @@ fn table(rows: &[Session], state: &State, w: usize, selected: usize, p: &Palette let tint = if here { tc::bg(28, 44, 62) } else { String::new() }; let hue = &p.hues[i % p.hues.len()]; let glyph = SERIES[i % SERIES.len()]; + // One login, and only where there is room for it: the address is + // what identifies the session, the name is a courtesy. let who = state .names .get(&row.ip) - .map(|names| names.join(",")) + .and_then(|names| names.first()) + .map(|(user, _tty)| user.clone()) .unwrap_or_default(); - let label = if who.is_empty() { + let label = if who.is_empty() || !wide { row.ip.clone() } else { format!("{} {}", row.ip, who) }; - let loss = if row.sent > 0.0 { - 100.0 * row.retrans_bytes / row.sent - } else { - 0.0 - }; + let loss = row.recent_loss; + let tone = format!("{}{}", tint, colour_for(quality(row), loss, p)); let name_c = format!("{}{}", tint, hue); - let txt_c = format!("{}{}", tint, p.txt); + let label_c = format!("{}{}", tint, if here { &p.txt } else { &p.dim }); let dim_c = format!("{}{}", tint, p.dim); - let loss_c = format!("{}{}", tint, if loss > 0.5 { &p.bad } else { &p.dim }); + let loss_c = format!( + "{}{}", + tint, + if loss.unwrap_or(0.0) >= 0.5 { &p.bad } else { &p.dim } + ); let idle = [row.lastsnd, row.lastrcv] .into_iter() .flatten() .fold(None, |acc: Option, v| Some(acc.map_or(v, |a| a.min(v)))); + // A missing reading is a dash of the column's own width, not a + // narrower cell - anything else shifts every number to its right. + let cell = |value: Option, width: usize| match value { + Some(v) if v != 0.0 => format!("{:>width$}", ms(Some(v)), width = width), + _ => format!("{:>width$}", "--", width = width), + }; let mut line = vec![ - (name_c.as_str(), format!(" {} ", glyph)), - (txt_c.as_str(), tc::pad(&label, name_w)), - (txt_c.as_str(), format!("{:>7}", ms(row.rtt))), - (dim_c.as_str(), format!("{:>8}", ms(row.floor))), - (dim_c.as_str(), format!("{:>8}", ms(row.jitter))), - (loss_c.as_str(), format!("{:>7.2}%", loss)), + (name_c.as_str(), format!("{} ", glyph)), + (label_c.as_str(), tc::pad(&label, name_w)), + (tone.as_str(), cell(row.rtt, 7)), + (dim_c.as_str(), cell(row.floor, 8)), + (dim_c.as_str(), cell(row.jitter, 8)), + ( + loss_c.as_str(), + format!( + "{:>7}", + loss.map_or("--".to_string(), |v| format!("{:.2}%", v)) + ), + ), ]; if wide { line.push((dim_c.as_str(), format!("{:>10}", rate(row.delivery)))); @@ -555,11 +702,231 @@ fn table(rows: &[Session], state: &State, w: usize, selected: usize, p: &Palette } /// Log-scale multi-series plot of round-trip time. +/// One connection, in full. +/// +/// The list answers "is anything wrong"; this answers "with what, and how +/// badly". Everything here is a number the kernel already keeps for this +/// socket - nothing is derived beyond the two percentages, and both say +/// what they are measured over. +#[allow(clippy::too_many_arguments)] +fn detail_view( + row: &Session, + state: &State, + w: usize, + h: usize, + idx: usize, + window: f64, + refresh: f64, + p: &Palette, +) -> Vec { + let empty = Vec::new(); + let users = state.names.get(&row.ip).unwrap_or(&empty); + let mut rows = vec![tc::title("connection", w, &p.link)]; + rows.push(tc::seg( + &[ + ( + p.hues[idx % p.hues.len()].as_str(), + format!(" {} ", SERIES[idx % SERIES.len()]), + ), + (p.txt.as_str(), row.ip.clone()), + (p.dim.as_str(), format!(" · port {}", row.port)), + ( + p.dim.as_str(), + users.first().map_or(String::new(), |(u, _)| format!(" {}", u)), + ), + ], + w - 1, + )); + // `who` maps logins to an address, not to a socket, and two SSH sessions + // from one laptop share the address. Naming both against each socket + // read as "this connection is pts/0 and pts/35", which it is not - so + // the ttys are labelled as what they are: the logins from that address. + if !users.is_empty() { + rows.push(tc::seg( + &[ + (p.dim.as_str(), " logins from this address: ".into()), + ( + p.txt.as_str(), + users + .iter() + .map(|(_u, tty)| tty.clone()) + .collect::>() + .join(", "), + ), + ], + w - 1, + )); + } + rows.push(String::new()); + + // A field with nothing behind it is left out rather than shown empty: + // the screen is a list of what the kernel knows, so a missing line says + // "not reported for this socket". + macro_rules! field { + ($label:expr, $value:expr, $colour:expr, $note:expr $(,)?) => {{ + if let Some(v) = $value { + if !v.is_empty() && v != "--" { + let note: &str = $note; + rows.push(tc::seg( + &[ + (p.dim.as_str(), format!(" {:<16}", $label)), + ($colour, v), + ( + p.dim.as_str(), + if note.is_empty() { + String::new() + } else { + format!(" {}", note) + }, + ), + ], + w - 1, + )); + } + } + }}; + } + + let ratio = quality(row); + let live = |v: Option| v.filter(|x| *x != 0.0).map(|x| ms(Some(x))); + field!( + "round trip", + live(row.rtt), + colour_for(ratio, row.recent_loss, p), + &ratio.map_or(String::new(), |r| format!("{:.1}x this path's best", r)), + ); + field!( + "best ever", + live(row.floor), + &p.dim, + "the floor; the gap above it is congestion", + ); + field!("jitter", live(row.jitter), &p.dim, "variation in the round trip"); + field!( + "timeout", + num(&row.raw, "rto").map(|v| ms(Some(v))), + &p.dim, + "how long before a lost packet is resent", + ); + rows.push(String::new()); + + // Lifetime loss lives here rather than in the table because it is a fact + // about the whole session and changes by the hour, while the table's + // loss column is about the last two seconds. + let lifetime = if row.sent > 0.0 { + 100.0 * row.retrans_bytes / row.sent + } else { + 0.0 + }; + let loss = row.recent_loss; + field!( + "loss just now", + loss.map(|v| format!("{:.2}%", v)), + if loss.unwrap_or(0.0) >= 0.5 { &p.bad } else { &p.txt }, + "resent since the last look", + ); + field!( + "loss lifetime", + Some(format!("{:.2}%", lifetime)), + &p.dim, + &format!( + "{} resent of {}", + size_of(row.retrans_bytes), + size_of(row.sent) + ), + ); + field!( + "reordering", + row.raw.get("reord_seen").cloned(), + &p.dim, + "times packets arrived out of order", + ); + rows.push(String::new()); + + field!("sent", Some(size_of(row.sent)), &p.txt, ""); + field!("received", Some(size_of(row.recv)), &p.txt, ""); + field!( + "achieved", + Some(rate(row.delivery)), + &p.txt, + "what it has delivered, not its capacity", + ); + field!( + "pacing at", + Some(rate(num(&row.raw, "pacing_rate"))), + &p.dim, + "the rate the kernel is willing to send at", + ); + field!( + "in flight", + row.raw.get("cwnd").cloned(), + &p.dim, + "packets allowed unacknowledged at once", + ); + field!( + "packet size", + row.mss.map(|v| format!("{} bytes", v as i64)), + &p.dim, + "", + ); + let idle = [row.lastsnd, row.lastrcv] + .into_iter() + .flatten() + .fold(None, |acc: Option, v| Some(acc.map_or(v, |a| a.min(v)))); + field!( + "idle", + Some(span(idle)), + &p.dim, + "since anything crossed either way", + ); + rows.push(String::new()); + + let one = [row.clone()]; + let room = h.saturating_sub(rows.len() + 4); + if room >= 5 { + rows.extend(graph( + &one, + &state.history, + w, + room, + idx, + window, + refresh, + p, + )); + rows.push(tc::seg( + &[ + (p.dim.as_str(), " ".repeat(7)), + ( + p.grid.as_str(), + format!("└{}", "─".repeat(w.saturating_sub(9).max(10))), + ), + ], + w - 1, + )); + let covered = plotted_span(&one, &state.history, window, refresh, w); + rows.push(tc::seg( + &[ + (p.dim.as_str(), format!(" {} ago", span(Some(covered * 1000.0)))), + (p.dim.as_str(), " ".repeat(w.saturating_sub(26).max(1))), + (p.dim.as_str(), "now".into()), + ], + w - 1, + )); + } + rows +} + +#[allow(clippy::too_many_arguments)] fn graph( rows: &[Session], history: &HashMap>, w: usize, h: usize, + // `start` keeps a session's glyph and hue the same on its own screen as + // in the list: opening the ▲ row and finding a ● chart reads as a + // different connection. + start_at: usize, window: f64, refresh: f64, p: &Palette, @@ -577,7 +944,7 @@ fn graph( if vals.is_empty() { None } else { - Some((i, vals)) + Some((start_at + i, vals)) } }) .collect(); @@ -693,6 +1060,8 @@ fn hold(needed: &[String]) { } struct Palette { + ok: String, + warn: String, bad: String, dim: String, grid: String, @@ -704,6 +1073,8 @@ struct Palette { fn palette() -> Palette { Palette { + ok: tc::rgb(90, 240, 160), + warn: tc::rgb(255, 200, 90), bad: tc::rgb(255, 100, 110), dim: tc::rgb(127, 147, 172), grid: tc::rgb(60, 78, 98), @@ -744,23 +1115,148 @@ mod tests { assert_eq!(ms(Some(2.74)), "2.7ms"); // Below a millisecond it changes unit rather than losing the value. assert_eq!(ms(Some(0.022)), "22µs"); - assert_eq!(ms(None), "—"); + assert_eq!(ms(None), "--"); } #[test] fn rates_read_as_a_person_would_say_them() { assert_eq!(rate(Some(6_287_464.0)), "6.3Mbps"); - assert_eq!(rate(Some(1_500.0)), "1.5Kbps"); + // Lower-case k, as link.py writes it: the two sit side by side on a + // wall and a capital there reads as a different widget. + assert_eq!(rate(Some(1_500.0)), "1.5kbps"); assert_eq!(rate(Some(45_000_000_000.0)), "45.0Gbps"); - assert_eq!(rate(None), "—"); - assert_eq!(rate(Some(0.0)), "—"); + assert_eq!(rate(None), "--"); + // A socket that has delivered nothing has delivered nothing; it is + // not an absent reading. + assert_eq!(rate(Some(0.0)), "0bps"); + } + + #[test] + fn byte_counts_read_as_a_person_would_say_them() { + assert_eq!(size_of(1_669.0), "1.7k"); + assert_eq!(size_of(15_900_000.0), "15.9M"); + assert_eq!(size_of(512.0), "512B"); } #[test] fn spans_come_from_milliseconds() { assert_eq!(span(Some(45_000.0)), "45s"); assert_eq!(span(Some(600_000.0)), "10m"); - assert_eq!(span(None), "—"); + // The unit changes at the unit, not half again past it: 90s is a + // minute and a half, and reading it as "90s" was a threshold this + // port had invented. + assert_eq!(span(Some(90_000.0)), "1m"); + assert_eq!(span(Some(7_200_000.0)), "2h"); + assert_eq!(span(None), "--"); + } + + #[test] + fn a_connection_is_judged_against_its_own_best() { + let near = Session { + rtt: Some(1.2), + floor: Some(1.0), + ..Default::default() + }; + let far = Session { + rtt: Some(120.0), + floor: Some(100.0), + ..Default::default() + }; + // Both are 1.2x their floor, so both are fine - a fixed millisecond + // threshold would have called the second one bad. + assert_eq!(quality(&near), quality(&far)); + let p = palette(); + assert_eq!(colour_for(quality(&near), None, &p), p.ok); + assert_eq!(colour_for(quality(&far), None, &p), p.ok); + // Three times its own floor is congestion wherever it is. + let slow = Session { + rtt: Some(300.0), + floor: Some(100.0), + ..Default::default() + }; + assert_eq!(colour_for(quality(&slow), None, &p), p.bad); + // Loss outranks latency: a fast path dropping packets is not fine. + assert_eq!(colour_for(quality(&near), Some(2.5), &p), p.bad); + // Nothing measured yet is not a verdict. + assert_eq!(colour_for(None, None, &p), p.dim); + } + + /// Drop the colour, keep the cells - alignment is a question about text. + #[cfg(test)] + fn plain(s: &str) -> String { + let mut out = String::new(); + let mut chars = s.chars(); + while let Some(c) = chars.next() { + if c == '\x1b' { + for c in chars.by_ref() { + if c == 'm' { + break; + } + } + } else { + out.push(c); + } + } + out.trim_end().to_string() + } + + #[test] + fn a_row_matches_the_python_cell_for_cell() { + // Captured from link.py in an 85-column pty. The row is built from + // eight separate formats and the header is one fixed string, so + // nothing inside this file can catch a drift between them - only + // the other implementation can. This port had three cells of it, + // and every half looked plausible on its own. + let want = "● 219.73.78.221 will 37ms 20ms 10ms 0.00% 11.1Mbps 1m"; + let row = Session { + peer: "219.73.78.221:22".into(), + ip: "219.73.78.221".into(), + port: 22, + rtt: Some(37.0), + jitter: Some(10.0), + floor: Some(20.0), + recent_loss: Some(0.0), + delivery: Some(11_100_000.0), + lastsnd: Some(60_000.0), + lastrcv: Some(90_000.0), + ..Default::default() + }; + let state = State { + rows: vec![row.clone()], + names: HashMap::from([( + "219.73.78.221".to_string(), + vec![("williamli".to_string(), "pts/0".to_string())], + )]), + history: HashMap::new(), + err: String::new(), + }; + // Nothing selected, so no row carries the highlight. + let drawn = table(&[row], &state, 86, 9, &palette()); + assert_eq!(plain(&drawn[1]), want); + } + + #[test] + fn a_missing_reading_keeps_its_column() { + // A socket the kernel has no round trip for still has to leave the + // numbers to its right where they were, or the whole table shifts + // on one absent value. + let row = Session { + peer: "203.0.113.9:22".into(), + ip: "203.0.113.9".into(), + port: 22, + ..Default::default() + }; + let state = State { + rows: vec![row.clone()], + names: HashMap::new(), + history: HashMap::new(), + err: String::new(), + }; + let drawn = table(&[row], &state, 86, 9, &palette()); + assert_eq!( + plain(&drawn[1]), + "● 203.0.113.9 -- -- -- -- -- --" + ); } #[test] From a9d844e81db639676b53313ad34a57b103e3d144 Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sun, 23 Aug 2026 01:41:29 +0800 Subject: [PATCH 014/147] ports: the half of the widget that does something What was ported was the table. Everything reached by a key was not: the second screen, the kill, the addresses, tailscale serve and funnel, the cloudflare tunnel, the copy. The footer already advertised [r]efresh, which was not bound to anything either. This finishes it. The kill is the same three-step it is in ports.py, and for the same reasons. It asks first, and only y consents - every other key cancels, deliberately including q, because quitting must never double as agreement to signal something. It signals the process group rather than the process, which is what Ctrl-C does and what a dev server needs, since `npm run dev` is a shell, a package manager and the server sharing a group. It refuses a pid it does not own, one at or below 1, and its own group. Then it waits three seconds and offers SIGKILL only if the thing is still up. A zombie is read out of /proc//stat rather than trusted to signal 0, which answers for one forever. The second screen resolves where a port can actually be reached, bounded by what the socket is bound to: a server on 127.0.0.1 is not reachable at this machine's LAN address however many addresses the machine has, and offering one to copy would hand somebody a URL that cannot work. A served port is the one exception, because Tailscale proxies to it over loopback. Funnel takes the first free of 443, 8443 and 10000 rather than defaulting to 443, so a node can hold the three Tailscale actually accepts. Unserve looks up the mount that was chosen at publish time instead of assuming one, and never `serve reset`, which would clear configuration this widget never made. The operator bit is read from `tailscale debug prefs`, so a node that would refuse every write says so on the line instead of after the keypress. Two things the Python does with a regex are done by hand here, and the first is the one that matters: a proxy target names :3000 or :3000/ and not :30001, which a substring search would have accepted - it would have reported a port as served and offered a URL answering nothing. There is a test for exactly that. Also fixed: span() changed unit half again past where it should - 90 seconds read as "90s" and ninety minutes as "90m". OSC 52 clipboard and a base64 encoder now live in core, where common.py keeps them. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/core/src/lib.rs | 36 + rust/widgets/src/bin/ports.rs | 1559 ++++++++++++++++++++++++++++++++- 2 files changed, 1573 insertions(+), 22 deletions(-) diff --git a/rust/core/src/lib.rs b/rust/core/src/lib.rs index bac70a4..cd6b919 100644 --- a/rust/core/src/lib.rs +++ b/rust/core/src/lib.rs @@ -288,6 +288,42 @@ pub fn cfg_strings(cfg: &serde_json::Value, key: &str, fallback: &[&str]) -> Vec } } +/// Ask the terminal to put `text` on the system clipboard, via OSC 52. +/// +/// The terminal emulator performs the copy, so this reaches the machine you +/// are sitting at even when the program runs on a remote host over SSH. +/// Multiplexers must be willing to forward it. Returns false when stdout is +/// not a terminal, so callers can fall back to showing the text instead. +pub fn clipboard(text: &str) -> bool { + if unsafe { libc::isatty(1) } == 0 { + return false; + } + out(&format!("\x1b]52;c;{}\x07", base64(text.as_bytes()))); + flush(); + true +} + +/// Standard base64, because OSC 52 carries its payload that way. +fn base64(data: &[u8]) -> String { + const SET: &[u8] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"; + let mut out = String::with_capacity(data.len().div_ceil(3) * 4); + for chunk in data.chunks(3) { + let mut block = [0u8; 3]; + block[..chunk.len()].copy_from_slice(chunk); + let packed = u32::from(block[0]) << 16 | u32::from(block[1]) << 8 | u32::from(block[2]); + for i in 0..4 { + // Each output character is six bits; the ones past the end of a + // short chunk are padding rather than zeroes. + if i <= chunk.len() { + out.push(SET[(packed >> (18 - 6 * i) & 0x3f) as usize] as char); + } else { + out.push('='); + } + } + } + out +} + /// Which of these required commands are not on PATH. pub fn missing(programs: &[&str]) -> Vec { let path = std::env::var("PATH").unwrap_or_default(); diff --git a/rust/widgets/src/bin/ports.rs b/rust/widgets/src/bin/ports.rs index 750b2ee..fa27bdf 100644 --- a/rust/widgets/src/bin/ports.rs +++ b/rust/widgets/src/bin/ports.rs @@ -27,7 +27,7 @@ //! q quits. use std::collections::HashMap; -use std::sync::{Arc, Mutex}; +use std::sync::{Arc, Condvar, Mutex}; use std::time::{Duration, SystemTime, UNIX_EPOCH}; use toys_core as tc; @@ -80,9 +80,8 @@ const BY_PORT: &[(u16, &str)] = &[ (27017, "MongoDB"), ]; -// cmdline, cwd and families are carried for the detail screen, which is -// the next thing to be ported; the table itself does not read them. -#[allow(dead_code)] +// cmdline, cwd and families are carried for the detail screen; the table +// itself has no room for them. #[derive(Clone, Default)] struct Row { port: u16, @@ -496,11 +495,11 @@ fn span(seconds: Option) -> String { Some(s) if s >= 0.0 => s, _ => return "--".into(), }; - if s < 90.0 { + if s < 60.0 { format!("{}s", s as i64) - } else if s < 5400.0 { + } else if s < 3600.0 { format!("{}m", (s / 60.0) as i64) - } else if s < 172_800.0 { + } else if s < 86400.0 { format!("{}h", (s / 3600.0) as i64) } else { format!("{}d", (s / 86400.0) as i64) @@ -515,8 +514,1100 @@ fn theirs(row: &Row) -> bool { SYSTEM_PORTS.contains(&row.port) || !row.user.is_empty() } +/// Every address this machine holds, by interface. +/// +/// Link-local is dropped: an fe80:: address needs a zone index to be usable +/// and is never what somebody wants pasted into a browser. +fn interfaces() -> Vec<(String, String, bool)> { + let mut found = Vec::new(); + let data: serde_json::Value = + serde_json::from_str(&run(&["ip", "-j", "addr"])).unwrap_or(serde_json::Value::Null); + for link in data.as_array().unwrap_or(&Vec::new()) { + let name = link["ifname"].as_str().unwrap_or("?").to_string(); + for addr in link["addr_info"].as_array().unwrap_or(&Vec::new()) { + let ip = addr["local"].as_str().unwrap_or(""); + if ip.is_empty() || ip.starts_with("fe80:") { + continue; + } + found.push(( + name.clone(), + ip.to_string(), + addr["family"].as_str() == Some("inet6"), + )); + } + } + found +} + +#[derive(Clone, Default)] +struct Net { + name: String, + ips: Vec, + funnel: bool, + operator: bool, +} + +/// This node's tailnet name and addresses, and whether it may Funnel. +/// +/// Funnel is off unless the tailnet's policy grants the node the attribute, +/// and the node knows: the capability is in the map the coordination server +/// hands it. Asking here means the widget can say so instead of offering a +/// key that only ever returns an error. +fn tailnet_self() -> Net { + let mut out = Net::default(); + let data: serde_json::Value = serde_json::from_str(&run(&["tailscale", "status", "--json"])) + .unwrap_or(serde_json::Value::Null); + let node = &data["Self"]; + out.name = node["DNSName"] + .as_str() + .unwrap_or("") + .trim_end_matches('.') + .to_string(); + out.ips = node["TailscaleIPs"] + .as_array() + .map(|a| { + a.iter() + .filter_map(|v| v.as_str().map(String::from)) + .collect() + }) + .unwrap_or_default(); + out.funnel = node["CapMap"] + .as_object() + .is_some_and(|m| m.keys().any(|k| k.contains("cap/funnel"))); + // Changing the serve config is a root operation unless this user has + // been named the operator. Worth knowing before the key is pressed, + // since the fix is a one-off command rather than anything this can do. + let prefs: serde_json::Value = serde_json::from_str(&run(&["tailscale", "debug", "prefs"])) + .unwrap_or(serde_json::Value::Null); + let who = prefs["OperatorUser"].as_str().unwrap_or(""); + out.operator = unsafe { libc::getuid() } == 0 || (!who.is_empty() && who == username()); + out +} + +fn username() -> String { + std::env::var("USER") + .ok() + .filter(|s| !s.is_empty()) + .unwrap_or_else(|| owner_name(unsafe { libc::getuid() })) +} + +/// An address as it goes in a URL - IPv6 needs its brackets. +fn host_part(ip: &str, v6: bool) -> String { + if v6 { + format!("[{}]", ip) + } else { + ip.to_string() + } +} + +/// A URL for a host and port, with the scheme the port implies. +fn url_for(host: &str, v6: bool, port: u16) -> String { + let scheme = if port == 443 || port == 8443 { + "https" + } else { + "http" + }; + format!("{}://{}:{}", scheme, host_part(host, v6), port) +} + +/// Where this port can actually be reached, most local first. +/// +/// Bounded by what the socket is bound to, which is the part that gets got +/// wrong: a server on 127.0.0.1 is not reachable at this machine's LAN +/// address no matter how many addresses the machine has, and offering one +/// to copy would hand somebody a URL that cannot work. Only a socket bound +/// to every interface gets the full list. +/// +/// A served port is the exception worth keeping: Tailscale proxies to it +/// over loopback, so its https URL works even for a loopback-only server. +fn addresses(row: &Row, net: &Net, cfg: &serde_json::Value) -> Vec<(String, String)> { + let (port, reach) = (row.port, bind_class(&row.bind)); + let mut found = Vec::new(); + let served = served_url(cfg, port); + if !served.is_empty() { + found.push((served, "tailnet · via serve".to_string())); + } + // Nothing is listening, so every address below would refuse the + // connection. The serve URL above is the only one that exists, and it + // answers 502 - which is the whole reason this row is on screen. + if row.orphan { + return found; + } + if reach == "local" { + found.push(( + url_for("127.0.0.1", false, port), + "this machine only".to_string(), + )); + return found; + } + if reach == "tailnet" { + for ip in &net.ips { + found.push((url_for(ip, ip.contains(':'), port), "tailnet".to_string())); + } + if !net.name.is_empty() { + found.push(( + url_for(&net.name, false, port), + "tailnet · name".to_string(), + )); + } + return found; + } + if reach != "all" { + // Bound to one particular address, so that address is the answer. + found.push(( + url_for(&row.bind, row.bind.contains(':'), port), + "this interface".to_string(), + )); + return found; + } + found.push(( + url_for("127.0.0.1", false, port), + "this machine".to_string(), + )); + for (name, ip, v6) in interfaces() { + if ip.starts_with("127.") || ip == "::1" { + continue; + } + let note = if net.ips.iter().any(|t| *t == ip) { + "tailnet".to_string() + } else { + name + }; + found.push((url_for(&ip, v6, port), note)); + } + if !net.name.is_empty() { + found.push(( + url_for(&net.name, false, port), + "tailnet · name".to_string(), + )); + } + found +} + +/// Tailscale's own serve configuration, as it reports it. +/// +/// The JSON form rather than the text: the detail view needs the URL a +/// served port answers on, and putting a second port behind the same node +/// needs to know which mounts are already taken. Both are structure the +/// text output only implies. +fn serve_config() -> serde_json::Value { + serde_json::from_str(&run(&["tailscale", "serve", "status", "--json"])) + .unwrap_or(serde_json::Value::Null) +} + +/// Whether a proxy target names this port - `:3000` or `:3000/`, not +/// `:30001`, which a plain substring search would have accepted. +fn proxies_port(proxy: &str, port: u16) -> bool { + let want = format!(":{}", port); + let mut rest = proxy; + while let Some(at) = rest.find(&want) { + let after = &rest[at + want.len()..]; + if after.is_empty() || after.starts_with('/') { + return true; + } + rest = &rest[at + 1..]; + } + false +} + +/// The https URL a served port answers on, where one is configured. +fn served_url(cfg: &serde_json::Value, port: u16) -> String { + let web = match cfg["Web"].as_object() { + Some(w) => w, + None => return String::new(), + }; + for (mount, entry) in web { + for (path, handler) in entry["Handlers"].as_object().into_iter().flatten() { + if !proxies_port(handler["Proxy"].as_str().unwrap_or(""), port) { + continue; + } + let (host, listen) = mount.split_once(':').unwrap_or((mount.as_str(), "")); + let port_part = if listen.is_empty() || listen == "443" { + String::new() + } else { + format!(":{}", listen) + }; + return format!("https://{}{}{}", host, port_part, path); + } + } + String::new() +} + +#[derive(Clone)] +struct Tunnel { + pid: i32, + url: String, +} + +/// Where a launched quick tunnel's pid and URL are remembered. +/// +/// cloudflared holds no listening socket - it dials out - so nothing in +/// /proc ties it to the port it serves. Without a note on disk the widget +/// would lose a tunnel the moment it restarted, and leave it running with +/// no way to find or stop it. +fn tunnel_dir() -> String { + let base = std::env::var("XDG_STATE_HOME") + .ok() + .filter(|s| !s.is_empty()) + .unwrap_or_else(|| format!("{}/.local/state", std::env::var("HOME").unwrap_or_default())); + let path = format!("{}/terminal-toys/tunnels", base); + match std::fs::create_dir_all(&path) { + Ok(()) => path, + Err(_) => String::new(), + } +} + +/// The quick tunnel for a port: its pid, its URL, whether it still runs. +fn tunnel_state(port: u16) -> Option { + let dir = tunnel_dir(); + if dir.is_empty() { + return None; + } + let text = std::fs::read_to_string(format!("{}/{}.json", dir, port)).ok()?; + let note: serde_json::Value = serde_json::from_str(&text).ok()?; + let pid = note["pid"].as_i64().unwrap_or(0) as i32; + if !alive(pid) { + forget_tunnel(port); + return None; + } + Some(Tunnel { + pid, + url: note["url"].as_str().unwrap_or("").to_string(), + }) +} + +fn forget_tunnel(port: u16) { + let dir = tunnel_dir(); + if !dir.is_empty() { + let _ = std::fs::remove_file(format!("{}/{}.json", dir, port)); + } +} + +/// The first trycloudflare URL in a log, if it has printed one yet. +fn quick_url(text: &str) -> String { + const TAIL: &str = ".trycloudflare.com"; + let at = match text.find(TAIL) { + Some(at) => at, + None => return String::new(), + }; + let head = &text[..at]; + let start = match head.rfind("https://") { + Some(s) => s, + None => return String::new(), + }; + let name = &head[start + 8..]; + if name.is_empty() || !name.chars().all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-') { + return String::new(); + } + format!("https://{}{}", name, TAIL) +} + +/// Run a cloudflared quick tunnel for a port and return its URL. +/// +/// A quick tunnel needs no account and no DNS: cloudflared picks a random +/// trycloudflare.com name and prints it. A named tunnel on a domain of your +/// own needs credentials and a DNS record, which is a setup task rather +/// than a keypress, and is deliberately not attempted here. +fn start_tunnel(port: u16, wait: f64) -> (String, String) { + let dir = tunnel_dir(); + if dir.is_empty() { + return ( + String::new(), + "no state directory to record the tunnel in".into(), + ); + } + let log = format!("{}/{}.log", dir, port); + let handle = match std::fs::File::create(&log) { + Ok(f) => f, + Err(e) => return (String::new(), e.to_string()), + }; + let errors = match handle.try_clone() { + Ok(f) => f, + Err(e) => return (String::new(), e.to_string()), + }; + let child = std::process::Command::new("cloudflared") + .args([ + "tunnel", + "--no-autoupdate", + "--url", + &format!("http://127.0.0.1:{}", port), + ]) + .stdout(handle) + .stderr(errors) + .stdin(std::process::Stdio::null()) + .spawn(); + let child = match child { + Ok(c) => c, + Err(e) => return (String::new(), e.to_string()), + }; + let pid = child.id() as i32; + let deadline = now() + wait; + let mut found = String::new(); + while now() < deadline && found.is_empty() { + std::thread::sleep(Duration::from_millis(400)); + let text = std::fs::read_to_string(&log).unwrap_or_default(); + found = quick_url(&text); + if found.is_empty() && !alive(pid) { + break; + } + } + if found.is_empty() { + end(pid, libc::SIGTERM); + return ( + String::new(), + format!("no URL after {}s - see {}", wait as i64, log), + ); + } + let note = serde_json::json!({"pid": pid, "url": found, "port": port}); + let _ = std::fs::write(format!("{}/{}.json", dir, port), note.to_string()); + (found, String::new()) +} + +/// Whether a pid is still running. Signal 0 checks without delivering. +/// +/// A zombie answers signal 0 and is not running: it is an exit status its +/// parent has not collected yet. Reporting one as alive would leave the +/// widget offering to SIGKILL something already dead, forever, since no +/// signal moves a zombie. /proc knows the difference. +fn alive(pid: i32) -> bool { + if pid <= 0 { + return false; + } + if unsafe { libc::kill(pid, 0) } != 0 && std::io::Error::last_os_error().raw_os_error() == Some(libc::ESRCH) { + return false; + } + match std::fs::read_to_string(format!("/proc/{}/stat", pid)) { + Ok(text) => match text.rsplit_once(')') { + Some((_, rest)) => rest.split_whitespace().next() != Some("Z"), + None => true, + }, + Err(_) => true, + } +} + +/// Whether this row can be signalled, and why not when it cannot. +/// +/// Only one of the two is ever set. The checks are all about not doing +/// damage past what was asked for: a row whose owner /proc would not name +/// is somebody else's process, and a process in this widget's own group +/// cannot be group-killed without taking the widget down with it. +fn killable(row: &Row) -> (Option, String) { + let pid = match row.pid { + Some(p) => p, + None => { + return ( + None, + "not yours - no owner for this socket in /proc".into(), + ) + } + }; + if pid <= 1 { + return (None, format!("refusing to signal pid {}", pid)); + } + match std::fs::metadata(format!("/proc/{}", pid)) { + Ok(meta) => { + use std::os::unix::fs::MetadataExt; + if meta.uid() != unsafe { libc::getuid() } { + return (None, format!("pid {} is not yours", pid)); + } + } + Err(_) => return (None, format!("pid {} is already gone", pid)), + } + (Some(pid), String::new()) +} + +/// Signal the process group, falling back to the process alone. +/// +/// A dev server is rarely one process: `npm run dev` is a shell, a package +/// manager and the server itself, sharing a process group precisely so that +/// Ctrl-C reaches all three. Signalling the group is what Ctrl-C does. The +/// fallback covers a process whose group we cannot read, and the guard +/// covers the case where the group is this widget's own. +fn end(pid: i32, sig: libc::c_int) -> String { + let group = unsafe { libc::getpgid(pid) }; + let ours = unsafe { libc::getpgrp() }; + let sent = if group > 0 && group != ours { + unsafe { libc::killpg(group, sig) } + } else { + unsafe { libc::kill(pid, sig) } + }; + if sent == 0 { + return String::new(); + } + match std::io::Error::last_os_error().raw_os_error() { + Some(libc::ESRCH) => "already gone".into(), + Some(libc::EPERM) => "not permitted".into(), + _ => "failed".into(), + } +} + +/// Whether a command exists, so a key can say so instead of failing. +fn have(program: &str) -> bool { + tc::missing(&[program]).is_empty() +} + +// Tailscale accepts Funnel traffic on these three public ports and no +// others, so a node can have three funnels at once - not the one that +// defaulting to 443 every time would suggest. +const FUNNEL_PORTS: &[u16] = &[443, 8443, 10000]; + +/// The tailnet-side ports this node's serve config already occupies. +fn taken_ports(cfg: &serde_json::Value) -> Vec { + let mut used = Vec::new(); + for key in cfg["TCP"].as_object().into_iter().flatten().map(|(k, _)| k) { + if let Ok(port) = key.parse() { + used.push(port); + } + } + for mount in cfg["Web"].as_object().into_iter().flatten().map(|(k, _)| k) { + if let Some((_, listen)) = mount.rsplit_once(':') { + if let Ok(port) = listen.parse() { + used.push(port); + } + } + } + used +} + +/// The first public port free to funnel on, or 0 when all three are used. +fn free_funnel_port(cfg: &serde_json::Value) -> u16 { + let used = taken_ports(cfg); + FUNNEL_PORTS + .iter() + .copied() + .find(|p| !used.contains(p)) + .unwrap_or(0) +} + +/// What a subprocess said when it refused, on one line. +fn refusal(out: std::process::Output, fallback: &str) -> String { + if out.status.success() { + return String::new(); + } + let text = String::from_utf8_lossy(&out.stderr).to_string() + + &String::from_utf8_lossy(&out.stdout).to_string(); + let joined: String = text.split_whitespace().collect::>().join(" "); + if joined.is_empty() { + fallback.to_string() + } else { + joined.chars().take(200).collect() + } +} + +/// Put a local port behind this node's HTTPS name. +/// +/// Serve listens on the port's own number rather than 443. Nothing forces +/// that, but 443 is where an unflagged `tailscale serve` lands, so leaving +/// it as the default would mean the second port published quietly took the +/// first one's mount. +/// +/// Funnel has only the three ports Tailscale accepts from the internet, so +/// it takes the first of them that is free - a node can hold three at once, +/// and defaulting all of them to 443 would allow one. +fn serve_port(port: u16, public: bool) -> String { + let mut listen = port; + if public { + listen = free_funnel_port(&serve_config()); + if listen == 0 { + return format!( + "all three funnel ports are in use ({}) - stop one first", + FUNNEL_PORTS + .iter() + .map(|p| p.to_string()) + .collect::>() + .join(", ") + ); + } + } + let verb = if public { "funnel" } else { "serve" }; + match std::process::Command::new("tailscale") + .args([verb, "--bg", &format!("--https={}", listen), &port.to_string()]) + .output() + { + Ok(out) => refusal(out, "tailscale refused"), + Err(e) => e.to_string(), + } +} + +/// Which tailnet-side port a local port is currently published on. +fn listen_for(cfg: &serde_json::Value, port: u16) -> u16 { + for (mount, entry) in cfg["Web"].as_object().into_iter().flatten() { + for handler in entry["Handlers"].as_object().into_iter().flatten().map(|(_, v)| v) { + if proxies_port(handler["Proxy"].as_str().unwrap_or(""), port) { + return mount + .rsplit_once(':') + .and_then(|(_, l)| l.parse().ok()) + .unwrap_or(0); + } + } + } + 0 +} + +/// Take back one port, leaving every other mount as it was. +/// +/// The mount to remove is looked up rather than assumed: it was chosen when +/// the port was published, and on a funnel that is whichever of the three +/// public ports happened to be free at the time. +/// +/// Never `serve reset`: that clears the whole configuration, including +/// whatever was already published before this widget was ever run. +fn unserve_port(port: u16, public: bool) -> String { + let mut listen = listen_for(&serve_config(), port); + if listen == 0 { + listen = if public { 443 } else { port }; + } + let verb = if public { "funnel" } else { "serve" }; + match std::process::Command::new("tailscale") + .args([verb, &format!("--https={}", listen), "off"]) + .output() + { + Ok(out) => refusal(out, "tailscale refused"), + Err(e) => e.to_string(), + } +} + +/// What a kill would take down, in whatever room the pane has. +/// +/// Everything here identifies the target, but not equally: the port is the +/// one thing the person is looking at, and the framework name without the +/// project it belongs to is no use on a machine running four of them. The +/// pid is the first to go, then the kind. +fn kill_label(row: &Row, room: usize) -> String { + // An orphan's kind is the words "nothing listening", which reads badly + // in the middle of a sentence about it. The port is the whole subject. + if row.orphan { + return format!(":{}", row.port); + } + let what = if row.kind.is_empty() { + "unidentified" + } else { + &row.kind + }; + let wherein = if row.project.is_empty() { + String::new() + } else { + format!(" in {}", row.project) + }; + // Not every row has a pid. A port Tailscale serves with nothing behind + // it has none by definition, and one that exits while its screen is + // open loses the one it had - both can still be the subject of a prompt. + let who = row.pid.map_or(String::new(), |p| format!(" (pid {})", p)); + let bare = format!(":{}", row.port); + for text in [ + format!("{}{} on :{}{}", what, wherein, row.port, who), + format!("{}{} on :{}", what, wherein, row.port), + format!( + "{} on :{}", + if row.project.is_empty() { + what + } else { + &row.project + }, + row.port + ), + bare.clone(), + ] { + if text.chars().count() <= room { + return text; + } + } + bare +} + +/// A question and the key that answers it, fitted to the pane. +/// +/// On one line where both fit, on two where they do not, because the key is +/// never the half that may be truncated: a prompt with its `[y]` pushed off +/// the right edge is a prompt nobody can act on. The wording after the key +/// has shorter forms for the same reason, longest first. +fn prompt( + ask: Vec<(String, String)>, + key: (String, String), + options: &[&str], + w: usize, + dim: &str, +) -> Vec { + let answer = |room: usize| -> Vec<(String, String)> { + let text = options + .iter() + .find(|o| key.1.chars().count() + o.chars().count() <= room) + .copied() + .unwrap_or(""); + vec![key.clone(), (dim.to_string(), text.to_string())] + }; + let line = |parts: &[(String, String)]| -> String { + let refs: Vec<(&str, String)> = parts + .iter() + .map(|(c, t)| (c.as_str(), t.clone())) + .collect(); + tc::seg(&refs, w - 1) + }; + // The bare last form - "[y] yes", with no word on what anything else + // does - is a fallback for a pane too narrow for two lines, not a thing + // to choose while a second line is going spare. + let keep = if options.len() > 1 { + options[options.len() - 2] + } else { + options[options.len() - 1] + }; + let asked: usize = ask.iter().map(|(_, t)| t.chars().count()).sum(); + let room = (w - 1).saturating_sub(asked + 2); + if room >= key.1.chars().count() + keep.chars().count() { + let mut parts = ask; + parts.push((dim.to_string(), " ".into())); + parts.extend(answer(room)); + return vec![line(&parts)]; + } + let mut second = vec![(dim.to_string(), " ".to_string())]; + second.extend(answer(w - 2)); + vec![line(&ask), line(&second)] +} + +/// The verb and the cost of each exposure change, for the confirmation. +fn action(kind: &str) -> (&'static str, &'static str) { + match kind { + "serve" => ("publish", "tailnet only"), + "funnel" => ("publish publicly", "anyone with the URL"), + "unserve" => ("stop serving", ""), + "unfunnel" => ("stop the funnel", ""), + "tunnel" => ("open a cloudflare tunnel", "anyone with the URL"), + "untunnel" => ("close the cloudflare tunnel", ""), + _ => ("kill", ""), + } +} + +/// Whether there is anything behind this row worth a second screen. +/// +/// A process of ours carries a command line, a directory and an age that +/// the table has no room for, and any row at all can be given an address to +/// copy or an exposure to set up. Another user's socket carries none of +/// that: the four columns already say everything /proc will tell us, and +/// opening a screen to repeat them would be a screen that wastes a press. +fn has_detail(row: &Row) -> bool { + row.pid.is_some() || row.orphan || !row.exposed.is_empty() +} + +/// Break a long value across lines at spaces, then anywhere. +fn wrap(text: &str, width: usize) -> Vec { + let mut lines = Vec::new(); + let mut rest: Vec = text.chars().collect(); + while !rest.is_empty() && lines.len() < 4 { + if rest.len() <= width { + lines.push(rest.iter().collect()); + break; + } + let cut = rest[..(width + 1).min(rest.len())] + .iter() + .rposition(|c| *c == ' ') + .filter(|c| *c > width / 2) + .unwrap_or(width); + lines.push(rest[..cut].iter().collect()); + rest = rest[cut..].iter().skip_while(|c| **c == ' ').copied().collect(); + } + if lines.is_empty() { + vec![String::new()] + } else { + lines + } +} + +/// One `label value` line, wrapped under its own label. +fn field(label: &str, value: &str, w: usize, colour: &str, p: &Palette) -> Vec { + let label_w = 10usize; + wrap(value, ((w - 3).saturating_sub(label_w)).max(8)) + .into_iter() + .enumerate() + .map(|(i, line)| { + tc::seg( + &[ + ( + p.dim.as_str(), + format!(" {}", tc::pad(if i == 0 { label } else { "" }, label_w)), + ), + (colour, line), + ], + w - 1, + ) + }) + .collect() +} + +/// The ways this port could be published, and why one is unavailable. +/// +/// Each is a key, a name, and the state that decides whether pressing it +/// does anything. An option that cannot work says so on the line rather +/// than failing after the keypress - except Funnel, which is offered even +/// when the capability is missing, because Tailscale's own error names the +/// setting to change in the admin console better than this can. +fn expose_options( + row: &Row, + net: &Net, + tunnel: &Option, +) -> Vec<(char, &'static str, String, bool)> { + let how = row.exposed.as_str(); + // One blocker outranks the others: without the operator bit every serve + // and funnel write is refused, whatever else is true of them. + let barred = if net.operator { + "" + } else { + "needs: tailscale set --operator" + }; + vec![ + ( + 's', + "tailscale serve", + if how == "tailnet" { + "serving · tailnet only".to_string() + } else if barred.is_empty() { + "tailnet only".to_string() + } else { + barred.to_string() + }, + how == "tailnet", + ), + ( + 't', + "tailscale funnel", + if how == "public" { + "public · anyone with the URL".to_string() + } else if !barred.is_empty() { + barred.to_string() + } else if net.funnel { + "public".to_string() + } else { + "not enabled for this node".to_string() + }, + how == "public", + ), + ( + 'd', + "cloudflare tunnel", + match tunnel { + Some(t) => format!("running · {}", t.url), + None if have("cloudflared") => "quick tunnel, random domain".to_string(), + None => "cloudflared not installed".to_string(), + }, + tunnel.is_some(), + ), + ] +} + +/// The second screen: everything known about one port, and what to do. +#[allow(clippy::too_many_arguments)] +fn detail_rows( + row: &Row, + net: &Net, + tunnel: &Option, + links: &[(String, String)], + sel: usize, + w: usize, + p: &Palette, +) -> Vec { + let mut rows = vec![tc::title(&format!(":{}", row.port), w, &p.port)]; + let mut head = if !row.kind.is_empty() { + row.kind.clone() + } else if !row.user.is_empty() { + format!("{}'s", row.user) + } else { + String::new() + }; + if !row.project.is_empty() { + head += &format!(" in {}", row.project); + } + rows.push(tc::seg( + &[ + (p.txt.as_str(), format!(" {}", head.trim())), + ( + p.dim.as_str(), + match row.up { + Some(_) => format!(" · up {}", span(row.up)), + None => String::new(), + }, + ), + ], + w - 1, + )); + rows.push(String::new()); + + if let Some(pid) = row.pid { + rows.push(tc::seg(&[(p.lbl.as_str(), " ── PROCESS ── ".into())], w - 1)); + let cmd = if row.cmdline.is_empty() { "?" } else { &row.cmdline }; + rows.extend(field("command", cmd, w, &p.txt, p)); + let cwd = if row.cwd.is_empty() { "?" } else { &row.cwd }; + let cwd_c = if row.gone { &p.warn } else { &p.txt }; + rows.extend(field("directory", cwd, w, cwd_c, p)); + let group = match unsafe { libc::getpgid(pid) } { + g if g > 0 => format!(" · group {}", g), + _ => String::new(), + }; + rows.extend(field("pid", &format!("{}{}", pid, group), w, &p.txt, p)); + rows.push(String::new()); + } + + // A lone :: is not an IPv6-only server: Linux maps IPv4 onto it unless + // the process asked for IPV6_V6ONLY, and /proc cannot say which it did. + // Claiming "IPv6 only" here would be a guess dressed as a fact. + let note = if row.families > 1 { + "two sockets, IPv4 and IPv6" + } else if row.bind == "::" { + "IPv4 too, unless the server turned that off" + } else { + "one socket" + }; + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── LISTENING ON ── ".into()), + ( + p.txt.as_str(), + if row.bind.is_empty() { + "nothing".into() + } else { + row.bind.clone() + }, + ), + (p.dim.as_str(), format!(" {}", note)), + ], + w - 1, + )); + rows.push(String::new()); + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── REACHABLE AT ── ".into()), + (p.dim.as_str(), "↑↓ to pick, c copies".into()), + ], + w - 1, + )); + if links.is_empty() { + rows.push(tc::seg( + &[(p.dim.as_str(), " nothing is listening to reach".into())], + w - 1, + )); + } + for (i, (url, note)) in links.iter().enumerate() { + let here = i == sel; + rows.push(tc::seg( + &[ + ( + if here { p.accent.as_str() } else { p.dim.as_str() }, + if here { " ▸ ".into() } else { " ".into() }, + ), + ( + if here { p.txt.as_str() } else { p.dim.as_str() }, + url.clone(), + ), + (p.dim.as_str(), format!(" {}", note)), + ], + w - 1, + )); + } + rows.push(String::new()); + rows.push(tc::seg(&[(p.lbl.as_str(), " ── EXPOSE ── ".into())], w - 1)); + for (key, name, state, on) in expose_options(row, net, tunnel) { + rows.push(tc::seg( + &[ + (p.accent.as_str(), format!(" [{}] ", key)), + (p.txt.as_str(), tc::pad(name, 18)), + (if on { p.ok.as_str() } else { p.dim.as_str() }, state), + ], + w - 1, + )); + } + rows +} + +/// Something to say at the bottom of the screen until a moment passes. +type Notice = (String, String, f64); + +/// A SIGTERM that has been sent and not yet answered for. +struct Watch { + pid: i32, + row: Row, + asked: bool, + deadline: f64, +} + +/// An exposure change running on a thread, so the frame keeps drawing. +struct Working { + kind: String, + row: Row, + done: Arc>>, +} + +/// The second screen's own state: which port, and which address is picked. +struct Detail { + port: u16, + row: Row, + at: usize, + links: Vec<(String, String)>, + tunnel: Option, +} + +/// Carry out one exposure change and record how it went. +fn start_work(kind: &str, row: Row) -> Working { + let done = Arc::new(Mutex::new(Vec::new())); + let job = Arc::clone(&done); + let (what, port) = (kind.to_string(), row.port); + let p = rgb_ok(); + std::thread::spawn(move || { + let said: Notice = match what.as_str() { + "serve" | "funnel" => { + let failed = serve_port(port, what == "funnel"); + if failed.is_empty() { + ( + format!("{} now serves :{}", what, port), + p.ok, + now() + 6.0, + ) + } else { + (failed, p.bad, now() + 8.0) + } + } + "unserve" | "unfunnel" => { + let failed = unserve_port(port, what == "unfunnel"); + if failed.is_empty() { + (format!("stopped serving :{}", port), p.ok, now() + 5.0) + } else { + (failed, p.bad, now() + 8.0) + } + } + "tunnel" => { + let (url, failed) = start_tunnel(port, 25.0); + if failed.is_empty() { + (url, p.ok, now() + 20.0) + } else { + (failed, p.bad, now() + 10.0) + } + } + _ => { + if let Some(t) = tunnel_state(port) { + end(t.pid, libc::SIGTERM); + forget_tunnel(port); + } + ( + format!("closed the tunnel on :{}", port), + p.ok, + now() + 5.0, + ) + } + }; + if let Ok(mut guard) = job.lock() { + guard.push(said); + } + }); + Working { + kind: kind.to_string(), + row, + done, + } +} + +/// The bottom of either screen. +/// +/// One of five things, in the order they matter: a question that must be +/// answered before anything happens, the wait after answering it, a slow +/// action still running, the outcome of the last one, or the ordinary keys. +fn footer( + confirm: &Option<(String, Row)>, + watch: &Option, + working: &Option, + notice: &Option, + w: usize, + hints: &[Vec<(String, String)>], + p: &Palette, +) -> Vec { + if let Some((kind, row)) = confirm { + let (verb, cost) = action(kind); + let mut ask = vec![ + (p.bad.clone(), format!(" {} ", verb)), + ( + p.txt.clone(), + kill_label(row, w.saturating_sub(34 + verb.len())), + ), + ]; + if !cost.is_empty() { + ask.push((p.warn.clone(), format!(" - {}", cost))); + } + ask.push((p.dim.clone(), "?".into())); + return prompt( + ask, + (p.warn.clone(), "[y]".into()), + &[ + " yes · any other key cancels", + " yes · any key cancels", + " yes", + ], + w, + &p.dim, + ); + } + if let Some(state) = watch { + if state.asked { + return prompt( + vec![ + (p.warn.clone(), " still up: ".into()), + (p.txt.clone(), kill_label(&state.row, w - 30)), + ], + (p.bad.clone(), "[f]".into()), + &[ + " force kill · any other key leaves it", + " SIGKILL · any key leaves it", + " SIGKILL", + ], + w, + &p.dim, + ); + } + return vec![tc::seg( + &[ + (p.dim.as_str(), " SIGTERM sent, waiting for ".into()), + (p.txt.as_str(), kill_label(&state.row, w - 29)), + ], + w - 1, + )]; + } + if let Some(job) = working { + let verb = action(&job.kind).0; + return vec![tc::seg( + &[( + p.warn.as_str(), + format!(" {} :{} - this can take a moment", verb, job.row.port), + )], + w - 1, + )]; + } + if let Some((text, colour, _)) = notice { + return vec![tc::seg(&[(colour.as_str(), format!(" {}", text))], w - 1)]; + } + let refs: Vec> = hints + .iter() + .map(|group| { + group + .iter() + .map(|(c, t)| (c.as_str(), t.clone())) + .collect() + }) + .collect(); + tc::pack_hints(&refs, w - 2, " ") + .into_iter() + .map(|l| format!(" {}", l)) + .collect() +} + struct Store { rows: Mutex>, + // [r] asks for a scan now rather than at the end of the interval, and + // so does anything that has just changed what a scan would find. + wake: (Mutex, Condvar), +} + +impl Store { + fn wake(&self) { + if let Ok(mut asked) = self.wake.0.lock() { + *asked = true; + self.wake.1.notify_all(); + } + } } fn main() { @@ -536,6 +1627,7 @@ fn main() { let ok = rgb_ok(); let store = Arc::new(Store { rows: Mutex::new(Vec::new()), + wake: (Mutex::new(false), Condvar::new()), }); let poller = Arc::clone(&store); std::thread::spawn(move || loop { @@ -546,15 +1638,208 @@ fn main() { if let Ok(mut guard) = poller.rows.lock() { *guard = found; } - std::thread::sleep(Duration::from_secs_f64(refresh)); + let (lock, cond) = &poller.wake; + let mut asked = match lock.lock() { + Ok(g) => g, + Err(_) => return, + }; + if !*asked { + asked = match cond.wait_timeout(asked, Duration::from_secs_f64(refresh)) { + Ok((g, _)) => g, + Err(_) => return, + }; + } + *asked = false; }); tc::setup(); let mut keyboard = tc::Keyboard::new(); let (mut selected, mut hide_system, mut scroll) = (0usize, true, 0usize); + // The five things that can be happening besides the list: a question + // waiting on a key, the pause after a SIGTERM, a slow action on a + // thread, the outcome of the last one, and the second screen. + let mut confirm: Option<(String, Row)> = None; + let mut watch: Option = None; + let mut working: Option = None; + let mut notice: Option = None; + let mut detail: Option = None; + // Tailscale is asked once per visit to the second screen rather than + // once per frame: two subprocesses at 3Hz would cost more than the + // whole rest of the widget. Any change made there clears them. + let mut net: Option<(Net, serde_json::Value)> = None; loop { + let (w, h) = tc::size(); + + // A SIGTERM is given a moment to work before the harder question is + // asked, because most things do stop. + if let Some(state) = watch.as_mut() { + if !state.asked && (!alive(state.pid) || now() >= state.deadline) { + if !alive(state.pid) { + notice = Some(( + format!("stopped {}", kill_label(&state.row, w - 12)), + ok.ok.clone(), + now() + 4.0, + )); + watch = None; + store.wake(); + } else { + state.asked = true; + } + } + } + + // An action that talks to tailscaled or cloudflared takes seconds, + // which is far too long to hold a frame for, so it runs on a thread + // and its answer is collected here. + if let Some(job) = working.as_ref() { + let done = job.done.lock().ok().and_then(|g| g.first().cloned()); + if let Some(said) = done { + notice = Some(said); + working = None; + net = None; + store.wake(); + } + } + for key in keyboard.poll() { + // Only an explicit yes acts. Every other key cancels, + // deliberately including q: quitting must never double as + // consent to signal something or publish it. + if let Some((kind, row)) = confirm.take() { + if key != "y" && key != "Y" { + notice = Some(("cancelled".into(), ok.dim.clone(), now() + 2.0)); + continue; + } + if kind == "kill" { + let (pid, why) = killable(&row); + let pid = match pid { + Some(p) => p, + None => { + notice = Some((why, ok.bad.clone(), now() + 5.0)); + continue; + } + }; + let failed = end(pid, libc::SIGTERM); + if failed.is_empty() { + watch = Some(Watch { + pid, + row, + asked: false, + deadline: now() + 3.0, + }); + } else { + notice = Some(( + format!( + "{}: {}", + kill_label(&row, w.saturating_sub(4 + failed.len())), + failed + ), + ok.bad.clone(), + now() + 5.0, + )); + store.wake(); + } + } else if working.is_none() { + working = Some(start_work(&kind, row)); + } + continue; + } + if watch.as_ref().is_some_and(|s| s.asked) { + let state = watch.take().expect("just checked"); + if key == "f" || key == "F" { + let failed = end(state.pid, libc::SIGKILL); + notice = Some(if failed.is_empty() { + ( + format!("SIGKILL sent to {}", kill_label(&state.row, w - 19)), + ok.warn.clone(), + now() + 5.0, + ) + } else { + ( + format!( + "{}: {}", + kill_label(&state.row, w.saturating_sub(4 + failed.len())), + failed + ), + ok.bad.clone(), + now() + 5.0, + ) + }); + } else { + notice = Some(( + format!("left running: {}", kill_label(&state.row, w - 17)), + ok.dim.clone(), + now() + 3.0, + )); + } + store.wake(); + continue; + } + // The second screen keeps its own selection - of addresses + // rather than rows - and hands every other key back. + if let Some(view) = detail.as_mut() { + match key.as_str() { + "esc" | "left" | "q" | "Q" | "backspace" => { + detail = None; + } + "up" => view.at = view.at.saturating_sub(1), + "down" => view.at += 1, + "c" | "C" => { + if !view.links.is_empty() { + let url = &view.links[view.at.min(view.links.len() - 1)].0; + // The address goes in the notice either way: + // OSC 52 is refused by some terminals and + // swallowed by some multiplexers, and a copy + // that silently did nothing would leave nothing + // on screen to read instead. + let copied = tc::clipboard(url); + notice = Some(( + format!( + "{}{}", + if copied { "copied " } else { "no clipboard " }, + url + ), + if copied { ok.ok.clone() } else { ok.warn.clone() }, + now() + 8.0, + )); + } + } + "s" | "S" | "t" | "T" | "d" | "D" => { + let mut kind = match key.to_lowercase().as_str() { + "s" => "serve", + "t" => "funnel", + _ => "tunnel", + }; + let how = view.row.exposed.as_str(); + if kind == "serve" && how == "tailnet" { + kind = "unserve"; + } else if kind == "funnel" && how == "public" { + kind = "unfunnel"; + } else if kind == "tunnel" && view.tunnel.is_some() { + kind = "untunnel"; + } else if kind == "tunnel" && !have("cloudflared") { + notice = Some(( + "cloudflared is not installed - see the docs \ + for the one-line install" + .into(), + ok.warn.clone(), + now() + 8.0, + )); + continue; + } + if working.is_none() { + confirm = Some((kind.to_string(), view.row.clone())); + } + } + "r" | "R" => { + net = None; + store.wake(); + } + _ => {} + } + continue; + } match key.as_str() { "q" | "Q" => { keyboard.restore(); @@ -564,11 +1849,58 @@ fn main() { "up" => selected = selected.saturating_sub(1), "down" => selected += 1, "o" | "O" => hide_system = !hide_system, + "r" | "R" => store.wake(), + "enter" | "right" | "i" | "I" => { + let all: Vec = store.rows.lock().map(|g| g.clone()).unwrap_or_default(); + let shown: Vec = all + .into_iter() + .filter(|r| !(hide_system && theirs(r))) + .collect(); + if let Some(row) = shown.get(selected.min(shown.len().saturating_sub(1))) { + if has_detail(row) { + detail = Some(Detail { + port: row.port, + row: row.clone(), + at: 0, + links: Vec::new(), + tunnel: None, + }); + net = None; + } else { + notice = Some(( + "nothing more to show - /proc will not name \ + another user's process" + .into(), + ok.dim.clone(), + now() + 5.0, + )); + } + } + } + "k" | "K" => { + if watch.is_none() { + let all: Vec = + store.rows.lock().map(|g| g.clone()).unwrap_or_default(); + let shown: Vec = all + .into_iter() + .filter(|r| !(hide_system && theirs(r))) + .collect(); + if let Some(row) = shown.get(selected.min(shown.len().saturating_sub(1))) { + let (pid, why) = killable(row); + if pid.is_some() { + confirm = Some(("kill".into(), row.clone())); + } else { + notice = Some((why, ok.bad.clone(), now() + 5.0)); + } + } + } + } _ => {} } } - let (w, h) = tc::size(); + // Rebuilt after the keys rather than before them, so that a press of + // o is answered in the frame it was made in and not the next one. let all: Vec = store.rows.lock().map(|g| g.clone()).unwrap_or_default(); let shown: Vec<&Row> = all .iter() @@ -577,6 +1909,65 @@ fn main() { if !shown.is_empty() && selected >= shown.len() { selected = shown.len() - 1; } + if notice.as_ref().is_some_and(|n| now() >= n.2) { + notice = None; + } + + if let Some(view) = detail.as_mut() { + if net.is_none() { + net = Some((tailnet_self(), serve_config())); + } + let (self_node, cfg) = net.as_ref().expect("just filled"); + match all.iter().find(|r| r.port == view.port) { + Some(live) => view.row = live.clone(), + None => { + view.row.pid = None; + view.row.gone = true; + } + } + view.tunnel = tunnel_state(view.port); + view.links = addresses(&view.row, self_node, cfg); + if let Some(t) = view.tunnel.as_ref() { + view.links + .push((t.url.clone(), "public · cloudflare".to_string())); + } + view.at = view.at.min(view.links.len().saturating_sub(1)); + let mut rows = detail_rows( + &view.row, + self_node, + &view.tunnel, + &view.links, + view.at, + w, + &ok, + ); + let foot = footer( + &confirm, + &watch, + &working, + ¬ice, + w, + &[ + vec![(ok.accent.clone(), "↑↓".into()), (ok.dim.clone(), " address".into())], + vec![(ok.dim.clone(), "[c]opy".into())], + vec![(ok.dim.clone(), "[s]erve".into())], + vec![(ok.dim.clone(), "[t]unnel".into())], + vec![(ok.dim.clone(), "[d] cloudflare".into())], + vec![(ok.accent.clone(), "esc".into()), (ok.dim.clone(), " back".into())], + ], + &ok, + ); + let room = h.saturating_sub(foot.len() + 1); + rows.truncate(room); + while rows.len() < room { + rows.push(String::new()); + } + rows.extend(foot); + tc::draw(&rows, w, h); + std::thread::sleep(Duration::from_millis(300)); + continue; + } + let mine = all.iter().filter(|r| r.pid.is_some()).count(); let off_box = all.iter().filter(|r| !r.exposed.is_empty()).count(); @@ -626,6 +2017,9 @@ fn main() { let here = i == selected; let tint = if here { tc::bg(28, 44, 62) } else { String::new() }; let (note, note_colour) = bind_note(row, &ok); + // Another user's row names its owner rather than its project, + // which it has none of that we can read. That is the whole of + // what is knowable about it. let who = if !row.project.is_empty() { row.project.clone() } else if !row.user.is_empty() { @@ -693,19 +2087,25 @@ fn main() { rows.push(tc::seg(&line, w - 1)); } - let hints: Vec> = vec![ - vec![(ok.accent.as_str(), "↑↓".into()), (ok.dim.as_str(), " select".into())], - vec![( - ok.dim.as_str(), - format!("[o]{} system", if hide_system { "show" } else { "hide" }), - )], - vec![(ok.dim.as_str(), "[r]efresh".into())], - vec![(ok.dim.as_str(), "[q]uit".into())], - ]; - let foot: Vec = tc::pack_hints(&hints, w - 2, " ") - .into_iter() - .map(|l| format!(" {}", l)) - .collect(); + let foot = footer( + &confirm, + &watch, + &working, + ¬ice, + w, + &[ + vec![(ok.accent.clone(), "↑↓".into()), (ok.dim.clone(), " select".into())], + vec![(ok.accent.clone(), "↵".into()), (ok.dim.clone(), " details".into())], + vec![(ok.dim.clone(), "[k]ill".into())], + vec![( + ok.dim.clone(), + format!("[o]{} system", if hide_system { "show" } else { "hide" }), + )], + vec![(ok.dim.clone(), "[r]efresh".into())], + vec![(ok.dim.clone(), "[q]uit".into())], + ], + &ok, + ); while rows.len() < h.saturating_sub(foot.len() + 1) { rows.push(String::new()); } @@ -717,6 +2117,7 @@ fn main() { struct Palette { ok: String, + lbl: String, warn: String, bad: String, dim: String, @@ -731,6 +2132,7 @@ struct Palette { fn rgb_ok() -> Palette { Palette { ok: tc::rgb(90, 240, 160), + lbl: tc::rgb(130, 165, 200), warn: tc::rgb(255, 200, 90), bad: tc::rgb(255, 100, 110), dim: tc::rgb(127, 147, 172), @@ -835,9 +2237,122 @@ mod tests { ); } + #[test] + fn a_proxy_target_names_a_whole_port() { + // The Python matches `:3000` or `:3000/` and not `:30001`. A plain + // substring search would report a served port that is not served, + // and the detail screen would offer a URL that answers nothing. + assert!(proxies_port("http://127.0.0.1:3000", 3000)); + assert!(proxies_port("http://127.0.0.1:3000/", 3000)); + assert!(proxies_port("http://127.0.0.1:3000/app", 3000)); + assert!(!proxies_port("http://127.0.0.1:30001", 3000)); + assert!(!proxies_port("http://127.0.0.1:13000", 3000)); + } + + #[test] + fn the_serve_url_carries_its_mount() { + let cfg: serde_json::Value = serde_json::from_str( + r#"{"Web": {"host.ts.net:443": {"Handlers": {"/": + {"Proxy": "http://127.0.0.1:3003"}}}}}"#, + ) + .unwrap(); + // 443 is the default and is left off; anything else is spelled out. + assert_eq!(served_url(&cfg, 3003), "https://host.ts.net/"); + assert_eq!(served_url(&cfg, 3004), ""); + let other: serde_json::Value = serde_json::from_str( + r#"{"Web": {"host.ts.net:8443": {"Handlers": {"/": + {"Proxy": "http://127.0.0.1:3003"}}}}}"#, + ) + .unwrap(); + assert_eq!(served_url(&other, 3003), "https://host.ts.net:8443/"); + assert_eq!(listen_for(&other, 3003), 8443); + } + + #[test] + fn a_funnel_takes_the_first_port_that_is_free() { + // Tailscale accepts funnel traffic on three ports, so a node can + // hold three at once. Defaulting to 443 every time would allow one. + let cfg: serde_json::Value = + serde_json::from_str(r#"{"Web": {"host.ts.net:443": {"Handlers": {}}}}"#).unwrap(); + assert_eq!(free_funnel_port(&cfg), 8443); + let full: serde_json::Value = + serde_json::from_str(r#"{"Web": {"h:443": {}, "h:8443": {}, "h:10000": {}}}"#).unwrap(); + assert_eq!(free_funnel_port(&full), 0); + } + + #[test] + fn a_kill_prompt_gives_up_its_parts_in_order() { + let row = Row { + port: 3000, + kind: "Next.js 16.3.1".into(), + project: "piaf-web".into(), + pid: Some(4242), + ..Default::default() + }; + let full = "Next.js 16.3.1 in piaf-web on :3000 (pid 4242)"; + assert_eq!(kill_label(&row, 99), full); + // The pid is the first thing to go, then the kind - the port is the + // one thing the person is actually looking at. + assert_eq!( + kill_label(&row, full.len() - 1), + "Next.js 16.3.1 in piaf-web on :3000" + ); + assert_eq!(kill_label(&row, 25), "piaf-web on :3000"); + assert_eq!(kill_label(&row, 8), ":3000"); + // An orphan's kind is the words "nothing listening", which reads + // badly in the middle of a sentence about it. + let orphan = Row { + port: 4100, + orphan: true, + ..Default::default() + }; + assert_eq!(kill_label(&orphan, 99), ":4100"); + } + + #[test] + fn a_long_value_wraps_at_a_space_when_there_is_one() { + assert_eq!(wrap("one two three", 7), vec!["one two", "three"]); + // A word with no break in it is cut rather than dropped. + assert_eq!(wrap("abcdefghij", 4), vec!["abcd", "efgh", "ij"]); + assert_eq!(wrap("", 8), vec![""]); + } + + #[test] + fn only_a_row_with_something_behind_it_opens() { + assert!(has_detail(&Row { + pid: Some(7), + ..Default::default() + })); + assert!(has_detail(&Row { + orphan: true, + ..Default::default() + })); + assert!(has_detail(&Row { + exposed: "tailnet".into(), + ..Default::default() + })); + // Another user's socket: the four columns already say everything + // /proc will tell us, so a second screen would waste the press. + assert!(!has_detail(&Row { + user: "root".into(), + ..Default::default() + })); + } + + #[test] + fn a_quick_tunnel_url_is_read_out_of_the_log() { + let log = "INF +--------------------------------------+\n\ + INF | https://calm-fox-runs.trycloudflare.com |\n"; + assert_eq!(quick_url(log), "https://calm-fox-runs.trycloudflare.com"); + assert_eq!(quick_url("INF starting tunnel"), ""); + } + #[test] fn spans_read_as_a_person_would_say_them() { assert_eq!(span(Some(45.0)), "45s"); + // The unit changes at the unit, not half again past it. + assert_eq!(span(Some(90.0)), "1m"); + assert_eq!(span(Some(5000.0)), "1h"); assert_eq!(span(Some(600.0)), "10m"); assert_eq!(span(Some(7200.0)), "2h"); assert_eq!(span(Some(200_000.0)), "2d"); From 8c8214e1ad0047ea11a9d368914edb13bff81dbe Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sun, 23 Aug 2026 01:50:36 +0800 Subject: [PATCH 015/147] netwatch: the second screen, and a rate that was a terabyte a second Enter was advertised in the footer and bound to nothing. Behind it in netwatch.py is the screen that answers the question the table only raises: which host, which socket, and which file is getting bigger. That is now here - endpoints folded across the sockets that share a peer, the individual connections, the open files with how fast each is growing since the screen opened, reverse DNS off the drawing thread, and per-process and per-endpoint charts on the same axes as the machine's. Connections and endpoints needed their own accounting, so the rolling window that processes already used is now one macro the three share. That is where the bug turned up. A sample reads every socket at one instant, so a process with fifteen sockets folded fifteen entries carrying the same timestamp. The window then spanned no time at all, and dividing by the epsilon that guarded against zero turned five megabytes into 963 GB/s - which pinned the chart's axis at a scale nothing else could reach and flattened four minutes of real traffic against the baseline. With no elapsed time there is no rate to compute, so the previous one now stands until the next sample gives the window a width. netwatch.py does not have this: it divides each socket's delta by the sample interval rather than by the window, and there is a test here for the case that separates them. Reverse lookups go through `getent hosts` off the drawing thread, so they honour /etc/hosts and nsswitch like everything else on the machine, and an address with no name is remembered as having none rather than asked about every second. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/widgets/src/bin/netwatch.rs | 1047 ++++++++++++++++++++++++++++-- 1 file changed, 982 insertions(+), 65 deletions(-) diff --git a/rust/widgets/src/bin/netwatch.rs b/rust/widgets/src/bin/netwatch.rs index fc09665..69e870e 100644 --- a/rust/widgets/src/bin/netwatch.rs +++ b/rust/widgets/src/bin/netwatch.rs @@ -20,7 +20,7 @@ //! per-socket byte counters and the inode beside them, and /proc//fd //! for the process that owns the inode. -use std::collections::HashMap; +use std::collections::{BTreeSet, HashMap}; use std::sync::{Arc, Mutex}; use std::time::{Duration, SystemTime, UNIX_EPOCH}; @@ -362,6 +362,65 @@ fn wire_label(names: &[String]) -> String { /// read. The header says which window, so the number is not a mystery. const RATE_WINDOW: f64 = 4.0; +/// Fold one sample into a counter and re-average over the window. +/// +/// A macro rather than a trait because processes, connections and endpoints +/// carry the same six fields and want exactly the same arithmetic; the one +/// thing that must not happen is the three drifting apart on what a rate +/// means. +macro_rules! fold { + ($e:expr, $when:expr, $up:expr, $down:expr) => {{ + let e = &mut $e; + e.up += $up; + e.down += $down; + e.seen = $when; + e.alive = true; + e.recent.push(($when, $up, $down)); + e.recent.retain(|(t, _, _)| $when - t <= RATE_WINDOW); + let oldest = e.recent.first().map(|(t, _, _)| *t).unwrap_or($when); + // The span the samples actually cover, not the nominal window: for + // the first few seconds after launch there is less history than + // that, and dividing by the full window would read low. + let span = $when - oldest; + let (mut u, mut d) = (0u64, 0u64); + for (_, up, down) in &e.recent { + u += up; + d += down; + } + // A process with fifteen sockets folds fifteen samples at one + // timestamp, and the window then spans no time at all. Dividing by + // an epsilon turned five megabytes into a rate of a terabyte a + // second and pinned the chart's axis there for four minutes. With + // no elapsed time there is no rate to compute, so the last one + // stands until the next sample gives the window a width. + if e.recent.len() > 1 && span > 0.0 { + e.up_rate = u as f64 / span; + e.down_rate = d as f64 / span; + } + }}; +} + +/// Drop what has fallen out of the window, and say so when nothing is left. +macro_rules! settle { + ($e:expr, $when:expr) => {{ + let e = &mut $e; + e.alive = false; + e.recent.retain(|(t, _, _)| $when - t <= RATE_WINDOW); + if e.recent.is_empty() { + e.up_rate = 0.0; + e.down_rate = 0.0; + } + }}; +} + +/// Keep a series bounded without reallocating the whole thing each sample. +fn trim(series: &mut Vec, most: usize) { + if series.len() > most { + let drop = series.len() - most; + series.drain(..drop); + } +} + #[derive(Clone, Default)] struct Proc { pid: i32, @@ -371,37 +430,53 @@ struct Proc { up_rate: f64, down_rate: f64, alive: bool, + seen: f64, /// (when, up bytes, down bytes) for the last few samples. recent: Vec<(f64, u64, u64)>, + /// (down rate, up rate) per sample, for this process's own chart. + hist: Vec<(f64, f64)>, } -impl Proc { - /// Fold this sample in, and re-average over the window. - fn add(&mut self, when: f64, up: u64, down: u64) { - self.up += up; - self.down += down; - self.recent.push((when, up, down)); - self.recent.retain(|(t, _, _)| when - t <= RATE_WINDOW); - let oldest = self.recent.first().map(|(t, _, _)| *t).unwrap_or(when); - // The span the samples actually cover, not the nominal window: for - // the first few seconds after launch there is less history than - // that, and dividing by the full window would read low. - let span = (when - oldest).max(1e-6); - let (mut u, mut d) = (0u64, 0u64); - for (_, up, down) in &self.recent { - u += up; - d += down; - } - if self.recent.len() > 1 { - self.up_rate = u as f64 / span; - self.down_rate = d as f64 / span; - } - } +/// One socket, so the detail screen can say which of a process's dozen +/// connections is the one actually moving. +#[derive(Clone, Default)] +struct Conn { + pid: i32, + name: String, + peer: String, + port: u16, + up: u64, + down: u64, + up_rate: f64, + down_rate: f64, + alive: bool, + seen: f64, + recent: Vec<(f64, u64, u64)>, +} + +/// The sockets sharing a peer, folded together: a browser opening six +/// connections to one host is one thing being talked to, not six. +#[derive(Clone, Default)] +struct Spot { + pid: i32, + name: String, + peer: String, + up: u64, + down: u64, + up_rate: f64, + down_rate: f64, + alive: bool, + seen: f64, + ports: BTreeSet, + recent: Vec<(f64, u64, u64)>, + hist: Vec<(f64, f64)>, } #[derive(Default)] struct State { totals: HashMap<(i32, String), Proc>, + conns: HashMap, + spots: HashMap<(i32, String, String), Spot>, last: HashMap, series: Vec<(f64, f64, f64, f64)>, stamp: f64, @@ -429,14 +504,15 @@ fn sample(state: &mut State, external: bool) { }; state.err = err; + // A row with nothing left in the window really is idle, and says so. for row in state.totals.values_mut() { - row.alive = false; - // A row with nothing in the window really is idle, and says so. - row.recent.retain(|(t, _, _)| stamp - t <= RATE_WINDOW); - if row.recent.is_empty() { - row.up_rate = 0.0; - row.down_rate = 0.0; - } + settle!(*row, stamp); + } + for conn in state.conns.values_mut() { + settle!(*conn, stamp); + } + for spot in state.spots.values_mut() { + settle!(*spot, stamp); } let first = state.stamp == 0.0; @@ -477,12 +553,42 @@ fn sample(state: &mut State, external: bool) { .entry((pid, name.clone())) .or_insert_with(|| Proc { pid, - name, + name: name.clone(), ..Default::default() }); row.alive = true; + row.seen = stamp; + if gap > 0.0 { + fold!(*row, stamp, d_sent, d_recv); + } + + let conn = state.conns.entry(inode.clone()).or_insert_with(|| Conn { + pid, + name: name.clone(), + peer: seen.peer.clone(), + port: seen.port, + ..Default::default() + }); + conn.alive = true; + conn.seen = stamp; + if gap > 0.0 { + fold!(*conn, stamp, d_sent, d_recv); + } + + let spot = state + .spots + .entry((pid, name.clone(), seen.peer.clone())) + .or_insert_with(|| Spot { + pid, + name: name.clone(), + peer: seen.peer.clone(), + ..Default::default() + }); + spot.alive = true; + spot.seen = stamp; + spot.ports.insert(seen.port); if gap > 0.0 { - row.add(stamp, d_sent, d_recv); + fold!(*spot, stamp, d_sent, d_recv); } } @@ -505,9 +611,16 @@ fn sample(state: &mut State, external: bool) { let all_down: f64 = state.totals.values().map(|r| r.down_rate).sum(); let all_up: f64 = state.totals.values().map(|r| r.up_rate).sum(); state.series.push((mine_down, mine_up, all_down, all_up)); - if state.series.len() > SERIES { - let drop = state.series.len() - SERIES; - state.series.drain(..drop); + trim(&mut state.series, SERIES); + // Every process and every endpoint keeps its own series, so the + // second screen can draw one of them alone on the same axes. + for row in state.totals.values_mut() { + row.hist.push((row.down_rate, row.up_rate)); + trim(&mut row.hist, SERIES); + } + for spot in state.spots.values_mut() { + spot.hist.push((spot.down_rate, spot.up_rate)); + trim(&mut spot.hist, SERIES); } } @@ -526,6 +639,23 @@ fn sample(state: &mut State, external: bool) { state.last = found.iter().map(|(k, v)| (k.clone(), (v.sent, v.recv))).collect(); state.stamp = stamp; + + // A closed connection is worth keeping - it may be the one that did the + // damage - but not forever. The quiet dead ones go once there are + // enough of them to matter. + if state.conns.len() > 400 { + let mut order: Vec<(String, f64, bool)> = state + .conns + .iter() + .map(|(k, c)| (k.clone(), c.seen, c.alive)) + .collect(); + order.sort_by(|a, b| a.1.total_cmp(&b.1)); + for (inode, _, alive) in order.into_iter().take(100) { + if !alive { + state.conns.remove(&inode); + } + } + } } /// Plot a series on a dot canvas eight times finer than the cells. @@ -553,7 +683,7 @@ fn braille_canvas(values: &[f64], peak: f64, cols: usize, rows: usize, inverted: let magnitude = (scaled * (px_h as f64 - 1.0)).round() as i64; (x, if inverted { magnitude } else { px_h as i64 - 1 - magnitude }) }; - let mut dot = |x: i64, y: i64, grid: &mut Vec>| { + let dot = |x: i64, y: i64, grid: &mut Vec>| { if x >= 0 && (x as usize) < px_w && y >= 0 && (y as usize) < px_h { grid[y as usize / 4][x as usize / 2] |= BRAILLE[y as usize % 4][x as usize % 2]; } @@ -612,6 +742,635 @@ fn braille_row(masks: &[u8], colour: &str) -> Vec<(String, String)> { .collect() } +// ── the second screen ──────────────────────────────────────────────── +// +// The table answers "what is using the network"; this answers "with what, +// and what is it writing". Everything here comes out of /proc for our own +// processes and out of nothing at all for anybody else's, which is why the +// screen says so rather than showing empty lists. + +const SECTIONS: [&str; 3] = ["endpoints", "connections", "files"]; + +/// Reverse DNS, off the drawing thread. +/// +/// A PTR lookup takes half a second when it works and longer when it does +/// not, which is several frames. The address is shown until a name arrives, +/// and an address that has no name is remembered as having none so it is +/// not asked about again every second. +struct Resolver { + known: Arc>>, + wanted: Arc>>, +} + +impl Resolver { + fn new() -> Resolver { + let known: Arc>> = Arc::new(Mutex::new(HashMap::new())); + let wanted: Arc>> = Arc::new(Mutex::new(Vec::new())); + let (k, q) = (Arc::clone(&known), Arc::clone(&wanted)); + std::thread::spawn(move || loop { + let next = q.lock().ok().and_then(|mut g| g.pop()); + let ip = match next { + Some(ip) => ip, + None => { + std::thread::sleep(Duration::from_millis(300)); + continue; + } + }; + // getent rather than a resolver library: it is glibc's own + // lookup, so it honours /etc/hosts, nsswitch and the search + // domains exactly as everything else on the machine does. + let answer = run(&["getent", "hosts", &ip]); + let name = answer + .split_whitespace() + .nth(1) + .unwrap_or("") + .to_string(); + if let Ok(mut guard) = k.lock() { + guard.insert(ip, name); + } + }); + Resolver { known, wanted } + } + + /// A name for an address if one is known, queueing a lookup if not. + fn name(&self, ip: &str) -> String { + if let Ok(guard) = self.known.lock() { + if let Some(found) = guard.get(ip) { + return found.clone(); + } + } + if let Ok(mut queue) = self.wanted.lock() { + if !queue.iter().any(|q| q == ip) && queue.len() < 64 { + queue.push(ip.to_string()); + } + } + String::new() + } +} + +/// What a port number is conventionally for, from /etc/services. +fn service(port: u16) -> String { + if port == 0 { + return String::new(); + } + let text = match std::fs::read_to_string("/etc/services") { + Ok(t) => t, + Err(_) => return String::new(), + }; + let want = format!("{}/tcp", port); + for line in text.lines() { + let line = line.split('#').next().unwrap_or(""); + let mut cols = line.split_whitespace(); + let (name, entry) = (cols.next(), cols.next()); + if entry == Some(want.as_str()) { + return name.unwrap_or("").to_string(); + } + } + String::new() +} + +/// Whether the process still exists. +/// +/// Distinct from the `alive` flag on a row, which means "had a socket in +/// the last sample". A long-running server sitting idle has neither traffic +/// nor open connections and has certainly not exited, and saying it had +/// would be worse than saying nothing. +fn running(pid: i32) -> bool { + pid > 0 && std::path::Path::new(&format!("/proc/{}", pid)).is_dir() +} + +/// Disk bytes this process has read and written, from /proc//io. +fn proc_io(pid: i32) -> HashMap { + let mut out = HashMap::new(); + if let Ok(text) = std::fs::read_to_string(format!("/proc/{}/io", pid)) { + for line in text.lines() { + if let Some((key, value)) = line.split_once(':') { + if let Ok(n) = value.trim().parse() { + out.insert(key.trim().to_string(), n); + } + } + } + } + out +} + +struct OpenFile { + path: String, + size: u64, +} + +/// Regular files this process has open, largest first. +/// +/// A download has to land somewhere, and where it lands is a file getting +/// bigger. This is the closest thing to "which file" that exists outside +/// the encrypted stream - the name of the thing being written, rather than +/// the name of the thing being fetched. +fn open_files(pid: i32) -> Vec { + let mut found = Vec::new(); + let dir = match std::fs::read_dir(format!("/proc/{}/fd", pid)) { + Ok(d) => d, + Err(_) => return found, + }; + for entry in dir.flatten() { + let link = match std::fs::read_link(entry.path()) { + Ok(l) => l, + Err(_) => continue, + }; + let path = link.to_string_lossy().to_string(); + if !path.starts_with('/') + || path.starts_with("/dev/") + || path.starts_with("/proc/") + || path.starts_with("/sys/") + { + continue; + } + // Through the fd rather than the path: the target may have been + // unlinked, and a temporary file being written is exactly the case + // this screen exists for. + let size = match std::fs::metadata(entry.path()) { + Ok(m) => m.len(), + Err(_) => continue, + }; + found.push(OpenFile { path, size }); + } + found.sort_by(|a, b| b.size.cmp(&a.size)); + found +} + +#[derive(Default)] +struct Facts { + cmdline: String, + cwd: String, +} + +/// Command and directory - what the table has no room for. +fn process_facts(pid: i32) -> Facts { + let mut facts = Facts::default(); + if let Ok(raw) = std::fs::read(format!("/proc/{}/cmdline", pid)) { + facts.cmdline = String::from_utf8_lossy(&raw) + .replace('\0', " ") + .trim() + .to_string(); + } + if let Ok(link) = std::fs::read_link(format!("/proc/{}/cwd", pid)) { + facts.cwd = link.to_string_lossy().to_string(); + } + facts +} + +/// A path that fits, keeping the end - which is the filename. +fn short(path: &str, room: usize) -> String { + let home = std::env::var("HOME").unwrap_or_default(); + let path = if !home.is_empty() && path.starts_with(&home) { + format!("~{}", &path[home.len()..]) + } else { + path.to_string() + }; + let chars: Vec = path.chars().collect(); + if chars.len() <= room || room < 2 { + return path; + } + format!("…{}", chars[chars.len() - (room - 1)..].iter().collect::()) +} + +fn wrap(text: &str, width: usize) -> Vec { + let mut lines = Vec::new(); + let mut rest: Vec = text.chars().collect(); + while !rest.is_empty() && lines.len() < 3 { + if rest.len() <= width { + lines.push(rest.iter().collect()); + break; + } + let cut = rest[..(width + 1).min(rest.len())] + .iter() + .rposition(|c| *c == ' ') + .filter(|c| *c > width / 2) + .unwrap_or(width); + lines.push(rest[..cut].iter().collect()); + rest = rest[cut..].iter().skip_while(|c| **c == ' ').copied().collect(); + } + if lines.is_empty() { + vec![String::new()] + } else { + lines + } +} + +fn field_rows(label: &str, value: &str, w: usize, colour: &str, p: &Palette) -> Vec { + wrap(value, ((w - 3).saturating_sub(10)).max(8)) + .into_iter() + .enumerate() + .map(|(i, line)| { + tc::seg( + &[ + ( + p.dim.as_str(), + format!(" {}", tc::pad(if i == 0 { label } else { "" }, 10)), + ), + (colour, line), + ], + w - 1, + ) + }) + .collect() +} + +/// A section header that says whether it is the one taking the keys. +fn section_head( + name: &str, + count: usize, + note: &str, + focused: bool, + key: &str, + w: usize, + p: &Palette, +) -> String { + tc::seg( + &[ + ( + if focused { p.accent.as_str() } else { p.lbl.as_str() }, + format!("{}── {} ── ", if focused { " ▏" } else { " " }, name), + ), + ( + p.dim.as_str(), + format!("{} {}{}", count, note, if count == 1 { "" } else { "s" }), + ), + ( + if focused { p.accent.as_str() } else { p.grid.as_str() }, + format!(" [{}]", key), + ), + ], + w - 1, + ) +} + +/// The line above a chart: what it is, and how far back it reaches. +fn chart_head(len: usize, w: usize, label: &str, interval: f64, p: &Palette) -> String { + let span = if len > 0 { + elapsed(len as f64 * interval) + } else { + "nothing yet".to_string() + }; + tc::seg( + &[ + (p.lbl.as_str(), format!(" ── {} ── ", label)), + (p.up.as_str(), "↑ tx above".into()), + (p.dim.as_str(), " · ".into()), + (p.down.as_str(), "↓ rx below".into()), + (p.dim.as_str(), format!(" · {} of history", span)), + ], + w - 1, + ) +} + +/// Remote hosts, ranked by what they have carried since launch. +fn endpoint_rows( + spots: &[Spot], + at: usize, + focused: bool, + room: usize, + w: usize, + names: &Resolver, + p: &Palette, +) -> Vec { + let host_w = ((w - 1).saturating_sub(42)).clamp(14, 34); + spots + .iter() + .take(room.max(1)) + .enumerate() + .map(|(i, spot)| { + let here = focused && i == at; + let tint = if here { tc::bg(28, 44, 62) } else { String::new() }; + let name = { + let found = names.name(&spot.peer); + if found.is_empty() { spot.peer.clone() } else { found } + }; + let ports: Vec = spot + .ports + .iter() + .take(2) + .map(|port| { + let named = service(*port); + if named.is_empty() { port.to_string() } else { named } + }) + .collect(); + let moving = spot.down_rate + spot.up_rate; + let c = |colour: &str| format!("{}{}", tint, colour); + tc::seg( + &[ + ( + &c(if here { &p.accent } else { &p.dim }), + if here { " ▸ ".into() } else { " ".into() }, + ), + ( + &c(if spot.alive { &p.txt } else { &p.dim }), + tc::pad(&name.chars().take(host_w - 1).collect::(), host_w), + ), + ( + &c(&p.dim), + format!("{:<9}", ports.join("/").chars().take(9).collect::()), + ), + (&c(&p.down), format!("↓{:>9}", units(spot.down as f64))), + (&c(&p.up), format!(" ↑{:>9}", units(spot.up as f64))), + ( + &c(if moving > 0.0 { &p.ok } else { &p.dim }), + format!("{:>11}", rate(moving)), + ), + (&tint, if here { " ".repeat(w) } else { String::new() }), + ], + w - 1, + ) + }) + .collect() +} + +/// The sockets open right now, which is a different list from the hosts. +fn connection_rows( + conns: &[Conn], + at: usize, + focused: bool, + room: usize, + w: usize, + p: &Palette, +) -> Vec { + let host_w = ((w - 1).saturating_sub(34)).clamp(14, 38); + conns + .iter() + .take(room.max(1)) + .enumerate() + .map(|(i, conn)| { + let here = focused && i == at; + let tint = if here { tc::bg(28, 44, 62) } else { String::new() }; + let where_ = format!("{}:{}", conn.peer, conn.port); + let c = |colour: &str| format!("{}{}", tint, colour); + tc::seg( + &[ + ( + &c(if here { &p.accent } else { &p.dim }), + if here { " ▸ ".into() } else { " ".into() }, + ), + ( + &c(if conn.alive { &p.txt } else { &p.dim }), + tc::pad( + &where_.chars().take(host_w - 1).collect::(), + host_w, + ), + ), + ( + &c(if conn.alive { &p.ok } else { &p.dim }), + format!("{:<7}", if conn.alive { "open" } else { "closed" }), + ), + (&c(&p.down), format!("↓{:>9}", units(conn.down as f64))), + (&c(&p.up), format!(" ↑{:>9}", units(conn.up as f64))), + (&tint, if here { " ".repeat(w) } else { String::new() }), + ], + w - 1, + ) + }) + .collect() +} + +/// Open files, with how fast each is growing since this screen opened. +fn file_rows( + files: &[OpenFile], + sizes: &HashMap, + at: usize, + focused: bool, + room: usize, + w: usize, + p: &Palette, +) -> Vec { + let path_w = ((w - 1).saturating_sub(30)).max(18); + files + .iter() + .take(room.max(1)) + .enumerate() + .map(|(i, item)| { + let here = focused && i == at; + let tint = if here { tc::bg(28, 44, 62) } else { String::new() }; + let (grew, span) = match sizes.get(&item.path) { + Some((was, when)) => (item.size.saturating_sub(*was), now() - when), + None => (0, 0.0), + }; + let growth = if grew > 0 && span > 0.0 { + format!("+{}", rate(grew as f64 / span)) + } else { + String::new() + }; + let c = |colour: &str| format!("{}{}", tint, colour); + tc::seg( + &[ + ( + &c(if here { &p.accent } else { &p.dim }), + if here { " ▸ ".into() } else { " ".into() }, + ), + (&c(&p.txt), tc::pad(&short(&item.path, path_w), path_w)), + (&c(&p.dim), format!("{:>10}", units(item.size as f64))), + ( + &c(if grew > 0 { &p.ok } else { &p.dim }), + format!("{:>12}", growth), + ), + (&tint, if here { " ".repeat(w) } else { String::new() }), + ], + w - 1, + ) + }) + .collect() +} + +/// One process in full: what it is, who it talks to, what it writes. +#[allow(clippy::too_many_arguments)] +fn detail_rows( + row: &Proc, + spots: &[Spot], + conns: &[Conn], + files: &[OpenFile], + sizes: &HashMap, + focus: usize, + at: &[usize; 3], + w: usize, + h: usize, + interval: f64, + names: &Resolver, + p: &Palette, +) -> Vec { + let facts = process_facts(row.pid); + let here_now = running(row.pid); + let total = (row.up + row.down) as f64; + let mut out = vec![tc::title( + &format!("{} · pid {}", row.name, row.pid), + w, + &p.accent, + )]; + out.push(tc::seg( + &[ + (p.txt.as_str(), format!(" {}", units(total))), + (p.dim.as_str(), " since first seen · ".into()), + (p.down.as_str(), format!("↓ {}", rate(row.down_rate))), + (p.dim.as_str(), " ".into()), + (p.up.as_str(), format!("↑ {}", rate(row.up_rate))), + ], + w - 1, + )); + if row.pid == 0 { + out.push(tc::seg( + &[( + p.dim.as_str(), + " another user's process - named from its control group, \ + since /proc is closed to us" + .into(), + )], + w - 1, + )); + } else if !here_now { + out.push(tc::seg( + &[( + p.warn.as_str(), + " this process has exited - its total is kept, and nothing \ + below is live" + .into(), + )], + w - 1, + )); + } else if !row.alive { + out.push(tc::seg( + &[( + p.dim.as_str(), + " no connection open at the moment - what is below is the \ + last that was seen" + .into(), + )], + w - 1, + )); + } + out.push(String::new()); + + // This process's own traffic, on the same chart as the machine's. + let spare = h.saturating_sub(out.len()); + let graph_h = if spare >= 30 { + 7 + } else if spare >= 24 { + 5 + } else { + 0 + }; + if graph_h > 0 && !row.hist.is_empty() { + out.push(chart_head(row.hist.len(), w, "THIS PROCESS", interval, p)); + out.extend(chart(&row.hist, w, graph_h, p)); + out.push(String::new()); + } + + if h.saturating_sub(out.len()) >= 12 { + out.push(tc::seg(&[(p.lbl.as_str(), " ── PROCESS ── ".into())], w - 1)); + let cmd = if facts.cmdline.is_empty() { "?" } else { &facts.cmdline }; + out.extend(field_rows("command", cmd, w, &p.txt, p)); + if !facts.cwd.is_empty() { + let cwd = short(&facts.cwd, w.saturating_sub(14)); + out.extend(field_rows("directory", &cwd, w, &p.txt, p)); + } + out.push(String::new()); + } + + // What is left is split between the three lists, with the focused one + // given the room: it is the one being read, and the others still say + // how much they are holding in their headers. + let left = h.saturating_sub(out.len() + 4).max(3); + let counts = [spots.len(), conns.len(), files.len()]; + let mut shares = [1usize; 3]; + shares[focus] = left.saturating_sub(2 + 3 * 2).max(1); + + for (which, (name, key, note)) in [ + ("TALKING TO", "e", "endpoint"), + ("CONNECTIONS", "tab", "socket"), + ("FILES", "f", "file"), + ] + .into_iter() + .enumerate() + { + let focused = focus == which; + out.push(section_head(name, counts[which], note, focused, key, w, p)); + let room = shares[which].min(h.saturating_sub(out.len() + 3).max(1)); + if counts[which] == 0 { + out.push(tc::seg(&[(p.dim.as_str(), " none".into())], w - 1)); + } else if which == 0 { + out.extend(endpoint_rows(spots, at[which], focused, room, w, names, p)); + // The highlighted host gets its own small chart, which is the + // quickest way to see whether it is the one doing the work. + let pick = &spots[at[which].min(spots.len() - 1)]; + if focused && !pick.hist.is_empty() && h.saturating_sub(out.len()) >= 7 { + let found = names.name(&pick.peer); + out.push(tc::seg( + &[ + (p.dim.as_str(), " ── ".into()), + ( + p.accent.as_str(), + if found.is_empty() { pick.peer.clone() } else { found }, + ), + (p.dim.as_str(), " alone ──".into()), + ], + w - 1, + )); + out.extend(chart(&pick.hist, w, 4, p)); + } + } else if which == 1 { + out.extend(connection_rows(conns, at[which], focused, room, w, p)); + } else { + out.extend(file_rows(files, sizes, at[which], focused, room, w, p)); + } + out.push(String::new()); + } + + let io = if here_now { + proc_io(row.pid) + } else { + HashMap::new() + }; + if !io.is_empty() && h.saturating_sub(out.len()) >= 2 { + out.push(tc::seg( + &[ + (p.lbl.as_str(), " ── DISK ── ".into()), + ( + p.dim.as_str(), + format!( + "read {} · written {} since it started", + units(*io.get("read_bytes").unwrap_or(&0) as f64), + units(*io.get("write_bytes").unwrap_or(&0) as f64) + ), + ), + ], + w - 1, + )); + } + out +} + +/// The table's order, which is also the order Enter indexes into. +fn ordered(state: &Arc>, mine: bool, live: bool) -> Vec { + let mut rows: Vec = match state.lock() { + Ok(guard) => guard + .totals + .values() + .filter(|r| !mine || r.pid != 0) + .cloned() + .collect(), + Err(_) => return Vec::new(), + }; + if live { + rows.sort_by(|a, b| { + (b.up_rate + b.down_rate) + .total_cmp(&(a.up_rate + a.down_rate)) + .then((b.up + b.down).cmp(&(a.up + a.down))) + }); + } else { + rows.sort_by(|a, b| { + (b.up + b.down) + .cmp(&(a.up + a.down)) + .then((b.up_rate + b.down_rate).total_cmp(&(a.up_rate + a.down_rate))) + }); + } + rows +} + fn main() { tc::maybe_help(include_str!("netwatch_help.txt")); let mut interval = 1.0f64; @@ -671,9 +1430,66 @@ fn main() { tc::setup(); let mut keyboard = tc::Keyboard::new(); let mut selected = 0usize; + // The second screen: which process, which of its three lists is taking + // the keys, and where each list is scrolled to. + let mut detail: Option<(i32, String)> = None; + let mut focus = 0usize; + let mut at = [0usize; 3]; + // What each open file measured when this screen opened, so the growth + // column is over the time you have been looking rather than the life + // of the file. + let mut sizes: HashMap = HashMap::new(); + let mut notice: Option<(String, String, f64)> = None; + // What `c` would copy: known while drawing, wanted when the key is hit. + let mut pending_copy = String::new(); + let names = Resolver::new(); loop { for key in keyboard.poll() { + if detail.is_some() { + match key.as_str() { + "esc" | "left" | "q" | "Q" | "backspace" => { + detail = None; + sizes.clear(); + } + "r" | "R" => { + if let Ok(mut guard) = state.lock() { + guard.totals.clear(); + guard.conns.clear(); + guard.spots.clear(); + guard.series.clear(); + guard.started = now(); + } + detail = None; + sizes.clear(); + } + "up" | "k" | "K" => at[focus] = at[focus].saturating_sub(1), + "down" | "j" | "J" => at[focus] += 1, + "tab" => focus = (focus + 1) % SECTIONS.len(), + "e" | "E" => focus = 0, + "f" | "F" => focus = 2, + "c" | "C" => { + if !pending_copy.is_empty() { + // The value goes in the message either way: OSC + // 52 is refused by some terminals and swallowed + // by some multiplexers, and a copy that quietly + // did nothing would leave nothing to read. + let copied = tc::clipboard(&pending_copy); + notice = Some(( + format!( + "{}{}", + if copied { "copied " } else { "no clipboard " }, + pending_copy + ), + if copied { p.ok.clone() } else { p.warn.clone() }, + now() + 8.0, + )); + } + } + _ => {} + } + continue; + } match key.as_str() { "q" | "Q" => { keyboard.restore(); @@ -689,44 +1505,124 @@ fn main() { } "up" | "k" | "K" => selected = selected.saturating_sub(1), "down" | "j" | "J" => selected += 1, + "enter" | "right" | "i" | "I" => { + if let Some(pick) = ordered(&state, mine, sort_live).get(selected) { + detail = Some((pick.pid, pick.name.clone())); + focus = 0; + at = [0; 3]; + sizes.clear(); + } + } "r" | "R" => { if let Ok(mut guard) = state.lock() { guard.totals.clear(); + guard.conns.clear(); + guard.spots.clear(); guard.series.clear(); guard.started = now(); } + selected = 0; } _ => {} } } let (w, h) = tc::size(); + if notice.as_ref().is_some_and(|n| now() >= n.2) { + notice = None; + } + + // One process in full. Its row is looked up fresh each frame so the + // figures keep moving while the screen is open, and it survives the + // process exiting - which is often when it is being looked at. + if let Some((pid, name)) = detail.clone() { + let (row, spots, conns) = { + let guard = match state.lock() { + Ok(g) => g, + Err(_) => return, + }; + let row = guard.totals.get(&(pid, name.clone())).cloned(); + let mut spots: Vec = guard + .spots + .values() + .filter(|s| s.pid == pid && s.name == name) + .cloned() + .collect(); + spots.sort_by(|a, b| { + (b.up + b.down) + .cmp(&(a.up + a.down)) + .then(a.peer.cmp(&b.peer)) + }); + let mut conns: Vec = guard + .conns + .values() + .filter(|c| c.pid == pid && c.name == name) + .cloned() + .collect(); + conns.sort_by(|a, b| { + (b.up + b.down) + .cmp(&(a.up + a.down)) + .then(a.peer.cmp(&b.peer)) + }); + (row, spots, conns) + }; + let row = match row { + Some(r) => r, + None => { + detail = None; + continue; + } + }; + let files = if running(pid) { open_files(pid) } else { Vec::new() }; + for file in &files { + sizes.entry(file.path.clone()).or_insert((file.size, now())); + } + let counts = [spots.len(), conns.len(), files.len()]; + at[focus] = at[focus].min(counts[focus].saturating_sub(1)); + // The selection is known here and the key is pressed elsewhere, + // so what `c` would copy is recorded while the frame is drawn. + pending_copy = match focus { + 0 => spots.get(at[0]).map(|s| s.peer.clone()).unwrap_or_default(), + 1 => conns + .get(at[1]) + .map(|c| format!("{}:{}", c.peer, c.port)) + .unwrap_or_default(), + _ => files.get(at[2]).map(|f| f.path.clone()).unwrap_or_default(), + }; + let hints: Vec> = vec![ + vec![(p.accent.as_str(), "↑↓".into()), (p.dim.as_str(), " scroll".into())], + vec![(p.accent.as_str(), "tab".into()), (p.dim.as_str(), " section".into())], + vec![(p.dim.as_str(), "[c]opy".into())], + vec![(p.dim.as_str(), "[r]ezero".into())], + vec![(p.accent.as_str(), "esc".into()), (p.dim.as_str(), " back".into())], + vec![(p.dim.as_str(), "[q]uit".into())], + ]; + let mut foot: Vec = tc::pack_hints(&hints, w - 2, " ") + .into_iter() + .map(|l| format!(" {}", l)) + .collect(); + if let Some((text, colour, _)) = notice.as_ref() { + foot = vec![tc::seg(&[(colour.as_str(), format!(" {}", text))], w - 1)]; + } + let room = h.saturating_sub(foot.len() + 1).max(1); + let mut body = detail_rows( + &row, &spots, &conns, &files, &sizes, focus, &at, w, room, interval, &names, &p, + ); + body.truncate(room); + while body.len() < room { + body.push(String::new()); + } + body.extend(foot); + tc::draw(&body, w, h); + std::thread::sleep(Duration::from_millis(300)); + continue; + } + + let rows = ordered(&state, mine, sort_live); let guard = match state.lock() { Ok(g) => g, Err(_) => return, }; - let mut rows: Vec = guard - .totals - .values() - .filter(|r| !mine || r.pid != 0) - .cloned() - .collect(); - if sort_live { - rows.sort_by(|a, b| { - (b.up_rate + b.down_rate) - .partial_cmp(&(a.up_rate + a.down_rate)) - .unwrap_or(std::cmp::Ordering::Equal) - .then((b.up + b.down).cmp(&(a.up + a.down))) - }); - } else { - rows.sort_by(|a, b| { - (b.up + b.down).cmp(&(a.up + a.down)).then( - (b.up_rate + b.down_rate) - .partial_cmp(&(a.up_rate + a.down_rate)) - .unwrap_or(std::cmp::Ordering::Equal), - ) - }); - } if !rows.is_empty() && selected >= rows.len() { selected = rows.len() - 1; } @@ -1076,20 +1972,41 @@ mod tests { // A kilobyte at t=0 and nothing for the next three seconds. The // instantaneous rate is zero for most of that; the windowed one // stays up, which is the whole point. - row.add(0.0, 0, 1000); - row.add(1.0, 0, 0); - row.add(2.0, 0, 0); - row.add(3.0, 0, 0); + fold!(row, 0.0, 0, 1000); + fold!(row, 1.0, 0, 0); + fold!(row, 2.0, 0, 0); + fold!(row, 3.0, 0, 0); assert!(row.down_rate > 0.0, "the rate flickered to nothing"); assert_eq!(row.down, 1000, "the total is unaffected by smoothing"); } + #[test] + fn many_sockets_at_one_instant_are_not_a_rate() { + let mut row = Proc::default(); + // One process, fifteen sockets, all folded at the same timestamp - + // which is every sample, since a sample reads them all at once. + // The window spans no time, so there is no rate to compute yet. + for _ in 0..15 { + fold!(row, 0.0, 0, 400_000); + } + assert_eq!(row.down, 6_000_000); + assert_eq!( + row.down_rate, 0.0, + "six megabytes in no time at all read as {} B/s", + row.down_rate + ); + // The next sample gives the window a width, and the rate is the + // whole window over the time it covers. + fold!(row, 1.0, 0, 0); + assert!((row.down_rate - 6_000_000.0).abs() < 1.0, "got {}", row.down_rate); + } + #[test] fn a_rate_is_the_window_it_claims() { let mut row = Proc::default(); // Two kilobytes a second, steadily, for four seconds. for i in 0..5 { - row.add(i as f64, 0, 2000); + fold!(row, i as f64, 0, 2000); } // Averaged over the span the samples cover, which is 4s for 5 // samples: 10000 bytes over 4 seconds. @@ -1099,8 +2016,8 @@ mod tests { #[test] fn history_older_than_the_window_is_dropped() { let mut row = Proc::default(); - row.add(0.0, 0, 5000); - row.add(100.0, 0, 1000); + fold!(row, 0.0, 0, 5000); + fold!(row, 100.0, 0, 1000); // The ancient sample is gone, so it cannot prop the rate up. assert_eq!(row.recent.len(), 1); assert_eq!(row.down, 6000); From eab4c9f976beb37c766529ddafb184cfe80ac61d Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sun, 23 Aug 2026 01:55:42 +0800 Subject: [PATCH 016/147] tests: stop using this machine's own addresses as fixtures A test that wants a tailnet address does not need this node's tailnet address, and one that wants a cloud-internal address does not need this host's. Together they name the machine, and the repository is public. Replaced with generic addresses from the same ranges, plus RFC 5737 documentation space for the one public peer, which is what that space is for. The link row fixture was worse: it was captured live and carried a real client IP alongside the login it belongs to. The substitute is the same width, so the column alignment the test exists to prove is unchanged. Some of these are already in the pushed history. This stops them spreading rather than pretending they were never there. Also adds RFC 4648's own vectors for the base64 in core. It is hand-rolled and its output is invisible - the copy notice shows the URL whatever actually reached the clipboard - so a wrong encoder would have looked like it worked. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/core/src/lib.rs | 19 +++++++++++++++++++ rust/widgets/src/bin/link.rs | 13 ++++++++----- rust/widgets/src/bin/netwatch.rs | 14 +++++++------- rust/widgets/src/bin/ports.rs | 4 ++-- 4 files changed, 36 insertions(+), 14 deletions(-) diff --git a/rust/core/src/lib.rs b/rust/core/src/lib.rs index cd6b919..e01e38c 100644 --- a/rust/core/src/lib.rs +++ b/rust/core/src/lib.rs @@ -471,6 +471,25 @@ pub fn maybe_help(doc: &str) { mod tests { use super::*; + #[test] + fn base64_matches_the_rfc_vectors() { + // Hand-rolled, and its output is invisible: the copy notice shows + // the URL whatever actually landed on the clipboard, so a wrong + // encoder would look like it worked. RFC 4648 section 10. + assert_eq!(base64(b""), ""); + assert_eq!(base64(b"f"), "Zg=="); + assert_eq!(base64(b"fo"), "Zm8="); + assert_eq!(base64(b"foo"), "Zm9v"); + assert_eq!(base64(b"foob"), "Zm9vYg=="); + assert_eq!(base64(b"fooba"), "Zm9vYmE="); + assert_eq!(base64(b"foobar"), "Zm9vYmFy"); + // The two characters that separate base64 from base64url, and a + // byte above 127, since a URL may carry either. + assert_eq!(base64(&[0xfb, 0xff]), "+/8="); + assert_eq!(base64("é".as_bytes()), "w6k="); + } + + #[test] fn the_config_search_includes_the_working_directory() { // The bug this exists for: a compiled binary looked only beside diff --git a/rust/widgets/src/bin/link.rs b/rust/widgets/src/bin/link.rs index a20dc7e..a56e8bb 100644 --- a/rust/widgets/src/bin/link.rs +++ b/rust/widgets/src/bin/link.rs @@ -1202,15 +1202,18 @@ mod tests { #[test] fn a_row_matches_the_python_cell_for_cell() { - // Captured from link.py in an 85-column pty. The row is built from + // Captured from link.py in an 85-column pty, with the address + // replaced by one from RFC 5737's documentation range - it is the + // same width, so the alignment this exists to check is unchanged, + // and this repository is public. The row is built from // eight separate formats and the header is one fixed string, so // nothing inside this file can catch a drift between them - only // the other implementation can. This port had three cells of it, // and every half looked plausible on its own. - let want = "● 219.73.78.221 will 37ms 20ms 10ms 0.00% 11.1Mbps 1m"; + let want = "● 203.0.113.221 will 37ms 20ms 10ms 0.00% 11.1Mbps 1m"; let row = Session { - peer: "219.73.78.221:22".into(), - ip: "219.73.78.221".into(), + peer: "203.0.113.221:22".into(), + ip: "203.0.113.221".into(), port: 22, rtt: Some(37.0), jitter: Some(10.0), @@ -1224,7 +1227,7 @@ mod tests { let state = State { rows: vec![row.clone()], names: HashMap::from([( - "219.73.78.221".to_string(), + "203.0.113.221".to_string(), vec![("williamli".to_string(), "pts/0".to_string())], )]), history: HashMap::new(), diff --git a/rust/widgets/src/bin/netwatch.rs b/rust/widgets/src/bin/netwatch.rs index 69e870e..b904d63 100644 --- a/rust/widgets/src/bin/netwatch.rs +++ b/rust/widgets/src/bin/netwatch.rs @@ -2033,23 +2033,23 @@ mod tests { #[test] fn traffic_that_never_leaves_is_recognised() { - let own = vec!["10.240.0.46".to_string(), "100.89.99.102".to_string()]; + let own = vec!["10.0.0.46".to_string(), "100.64.0.102".to_string()]; assert!(local_peer("127.0.0.1", &own)); assert!(local_peer("::1", &own)); // The half that is easy to miss: our own non-loopback address. - assert!(local_peer("10.240.0.46", &own)); - assert!(local_peer("::ffff:10.240.0.46", &own)); - assert!(!local_peer("10.240.0.99", &own)); + assert!(local_peer("10.0.0.46", &own)); + assert!(local_peer("::ffff:10.0.0.46", &own)); + assert!(!local_peer("10.0.0.99", &own)); } #[test] fn only_globally_routable_peers_are_off_box() { - let own = vec!["10.240.0.46".to_string()]; - assert!(off_box("160.79.104.10", &own)); + let own = vec!["10.0.0.46".to_string()]; + assert!(off_box("203.0.113.10", &own)); assert!(!off_box("10.0.0.5", &own)); assert!(!off_box("172.16.0.1", &own)); assert!(!off_box("192.168.1.1", &own)); - assert!(!off_box("100.89.99.102", &own)); + assert!(!off_box("100.64.0.102", &own)); assert!(!off_box("127.0.0.1", &own)); // 172.32 is outside the private range and really is out there. assert!(off_box("172.32.0.1", &own)); diff --git a/rust/widgets/src/bin/ports.rs b/rust/widgets/src/bin/ports.rs index fa27bdf..8de6361 100644 --- a/rust/widgets/src/bin/ports.rs +++ b/rust/widgets/src/bin/ports.rs @@ -2194,11 +2194,11 @@ mod tests { assert_eq!(bind_class("::"), "all"); assert_eq!(bind_class("127.0.0.1"), "local"); assert_eq!(bind_class("::1"), "local"); - assert_eq!(bind_class("100.89.99.102"), "tailnet"); + assert_eq!(bind_class("100.64.0.102"), "tailnet"); assert_eq!(bind_class("fd7a:115c:a1e0::1"), "tailnet"); // A LAN address is its own answer, not one of the three. assert_eq!(bind_class("192.168.1.9"), "192.168.1.9"); - assert_eq!(bind_class("10.240.0.46"), "10.240.0.46"); + assert_eq!(bind_class("10.0.0.46"), "10.0.0.46"); } #[test] From 936971c719259510d5b51562e61c89acc10e10bf Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sun, 23 Aug 2026 01:59:14 +0800 Subject: [PATCH 017/147] clocks, netwatch: the keys and the flags that were left behind MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit clocks lost page-up, page-down, home and end from the city list, and two of the three mnemonics for advancing the pomodoro - clocks.py binds s, b and e to one action on purpose, because the thing you want is called skip or break or end depending on which end of it you are at. It also acted on space, r, 0 and +/- while the pomodoro was switched off, where the Python ignores them: a key that moves a timer nobody is running should do nothing rather than something invisible. The ±1 minute step stays as it is. That was decided here rather than inherited - clocks.py steps by five - and the footer says which it does. netwatch had --plain and --external missing, and answered an unknown option by ignoring it. --plain writes one block per interval to stdout and never touches the screen, so it can be redirected to a file and left running, which is the only reason it exists. An unrecognised option now exits 2 and says so, as the Python does: a typo that silently does nothing is worse than one that complains. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/widgets/src/bin/clocks.rs | 14 ++++++- rust/widgets/src/bin/netwatch.rs | 65 +++++++++++++++++++++++++++++++- 2 files changed, 76 insertions(+), 3 deletions(-) diff --git a/rust/widgets/src/bin/clocks.rs b/rust/widgets/src/bin/clocks.rs index aa291d3..3eaf9f1 100644 --- a/rust/widgets/src/bin/clocks.rs +++ b/rust/widgets/src/bin/clocks.rs @@ -557,14 +557,24 @@ fn main() { } "up" | "k" | "K" => scroll = scroll.saturating_sub(1), "down" | "j" | "J" => scroll += 1, + "pgup" => scroll = scroll.saturating_sub(8), + "pgdn" => scroll += 8, + "home" => scroll = 0, + // Clamped to the last city further down, which is the only + // place that knows how many there are. + "end" => scroll = usize::MAX / 2, "p" | "P" => pomo.toggle(seconds()), + "?" | "h" => tips = !tips, + // Everything below moves a timer that is not running, so + // it is ignored rather than silently acted on. + _ if !pomo.shown => {} " " => pomo.start_stop(seconds()), - "b" | "B" => pomo.advance(seconds()), + // One action, three mnemonics: skip / break / end. + "s" | "S" | "b" | "B" | "e" | "E" => pomo.advance(seconds()), "r" | "R" => pomo.restart(seconds()), "0" | "c" => pomo.reset_count(), "+" | "=" => pomo.adjust(1.0, seconds()), "-" | "_" => pomo.adjust(-1.0, seconds()), - "?" | "h" => tips = !tips, _ => {} } } diff --git a/rust/widgets/src/bin/netwatch.rs b/rust/widgets/src/bin/netwatch.rs index b904d63..e66a3b6 100644 --- a/rust/widgets/src/bin/netwatch.rs +++ b/rust/widgets/src/bin/netwatch.rs @@ -1344,6 +1344,31 @@ fn detail_rows( out } +/// One block per interval, for a log or a pipe. +fn plain_line(rows: &[Proc], started: f64, live: bool, limit: usize) -> String { + let mut lines = vec![format!( + "--- {} elapsed · sorted by {} ---", + elapsed(now() - started), + if live { "live" } else { "total" } + )]; + for row in rows.iter().take(limit) { + lines.push(format!( + "{:<22} {:<8} {:>11} {:>11} {:>11} {:>11}", + row.name, + if row.pid > 0 { + row.pid.to_string() + } else { + "-".to_string() + }, + units((row.up + row.down) as f64), + rate(row.up_rate + row.down_rate), + rate(row.down_rate), + rate(row.up_rate) + )); + } + lines.join("\n") +} + /// The table's order, which is also the order Enter indexes into. fn ordered(state: &Arc>, mine: bool, live: bool) -> Vec { let mut rows: Vec = match state.lock() { @@ -1378,6 +1403,7 @@ fn main() { let mut external = true; let mut mine = true; let mut sort_live = false; + let mut plain = false; let args: Vec = std::env::args().skip(1).collect(); let mut i = 0; while i < args.len() { @@ -1394,6 +1420,10 @@ fn main() { sort_live = args[i + 1] == "live"; i += 2; } + "--external" => { + external = true; + i += 1; + } "--all-external" => { external = false; i += 1; @@ -1402,11 +1432,21 @@ fn main() { mine = false; i += 1; } + "--plain" => { + plain = true; + i += 1; + } "-V" | "--version" => { println!("netwatch 1.1"); return; } - _ => i += 1, + // Refused rather than ignored: a typo that silently does + // nothing is worse than one that says so, and the Python has + // always said so. + other => { + eprintln!("unknown option {:?} - try --help", other); + std::process::exit(2); + } } } @@ -1427,6 +1467,29 @@ fn main() { std::thread::sleep(Duration::from_secs_f64(interval)); }); + // One block per interval, for a log or a pipe. Nothing here touches + // the screen, so it can be redirected to a file and left running. + if plain { + loop { + std::thread::sleep(Duration::from_secs_f64(interval)); + let (started, err) = { + let guard = match state.lock() { + Ok(g) => g, + Err(_) => return, + }; + (guard.started, guard.err.clone()) + }; + if !err.is_empty() { + eprintln!("{}", err); + } + let rows = ordered(&state, mine, sort_live); + let show = if limit > 0 { limit } else { rows.len() }; + println!("{}", plain_line(&rows, started, sort_live, show)); + use std::io::Write; + let _ = std::io::stdout().flush(); + } + } + tc::setup(); let mut keyboard = tc::Keyboard::new(); let mut selected = 0usize; From 532b383ff1726925b5ca4af07cb21f2edb31ee12 Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sun, 23 Aug 2026 02:02:05 +0800 Subject: [PATCH 018/147] help: say what the widgets now do These were written to describe the reduced ports of the widgets, so they listed only the keys that had been ported and quietly dropped the rest - no kill, no second screen, no serve or funnel or tunnel, no copy. A --help that under-reports is the same defect as a footer hint bound to nothing: it tells you the feature is not there. Taken from the Python docstrings they now match, with only the invocation line changed, because a binary is not a script. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/widgets/src/bin/clocks_help.txt | 37 +++++++++++++++++++------- rust/widgets/src/bin/matrix_help.txt | 4 +-- rust/widgets/src/bin/netwatch_help.txt | 26 +++++++++++------- rust/widgets/src/bin/ports_help.txt | 15 ++++++++++- 4 files changed, 59 insertions(+), 23 deletions(-) diff --git a/rust/widgets/src/bin/clocks_help.txt b/rust/widgets/src/bin/clocks_help.txt index 86c71d2..5da57d2 100644 --- a/rust/widgets/src/bin/clocks_help.txt +++ b/rust/widgets/src/bin/clocks_help.txt @@ -1,17 +1,34 @@ Clocks: this server's, everyone else's, and the ones counting down. A big clock in the machine's own timezone, countdown bars for the next hour, -office hours and the end of day, and a world clock covering the hubs you care -about. +office hours and the end of day, an optional pomodoro, and a world clock +covering the hubs you care about. - clocks +The pomodoro is off until you press p. It runs the standard 25/5 with a longer +break every fourth session, all configurable, and persists across restarts so +relaunching the panel does not cost you a session. -The world clock marks each city with a sun or a moon by its local hour, which -is the fastest way to read whether it is a reasonable time to message someone -there, and shows the day offset where the date differs from this machine's. +A phase does not end itself. When the time is up the counter keeps going, +showing how far over you are, and the bar rescales so a growing red section +represents the overrun — the longer you ignore it, the more of the bar is red. +The whole panel also flashes twice, a second apart, on every alert - visible +with the sound muted. The terminal is alerted when the phase elapses and again +every minute it keeps running: BEL plus OSC 9 and OSC 777 desktop notifications, which are the only +channels that survive SSH. Under Herdr it additionally raises a native toast +with a sound — additive, never required, and skipped entirely elsewhere. -Timezones come from the IANA database, so the offsets are right across a -daylight-saving boundary rather than fixed at whatever they were when the -config was written. +Keys: up/down (and PgUp/PgDn, Home/End) scroll the city list while the clock, +countdowns and footer stay pinned. p shows or hides the pomodoro and suspends +it with them, space pauses or +resumes, r restarts the phase, s starts a break during focus and ends one during +a break - b and e do the same, and the footer names whichever applies - +/- +change the focus length, ? hides or shows the pomodoro controls, +0 zeroes today's completed count, q quits. -Keys: up/down scroll the cities, q quits. +The completed tally is per day: it resets when the date changes, including +while the panel is running. Preferences - focus length, whether the timer is +shown - are not tied to the day and persist. + +Big digits show this server's system-timezone clock. Below it, each hub +is shown in its own timezone, sorted west to east, coloured by whether people +there are plausibly at work. diff --git a/rust/widgets/src/bin/matrix_help.txt b/rust/widgets/src/bin/matrix_help.txt index 015152c..b404ac4 100644 --- a/rust/widgets/src/bin/matrix_help.txt +++ b/rust/widgets/src/bin/matrix_help.txt @@ -1,9 +1,7 @@ Digital rain. Falling glyphs with truecolor fade trails: near-white head, bright green -shoulder, and a smooth decay over each drop length. Glyphs mutate in place +shoulder, and a smooth decay over each drop's length. Glyphs mutate in place independently of the drops, and the field reflows on terminal resize. matrix - -Keys: q quits. diff --git a/rust/widgets/src/bin/netwatch_help.txt b/rust/widgets/src/bin/netwatch_help.txt index 9c86a15..8d74310 100644 --- a/rust/widgets/src/bin/netwatch_help.txt +++ b/rust/widgets/src/bin/netwatch_help.txt @@ -7,19 +7,27 @@ appears in /proc//fd, which is what ties bytes to a process. No packet capture, no kernel module, no root. netwatch [-i SECONDS] [-n COUNT] [--sort total|live] - [--all-external] [--all-users] + [--external] [--plain] Only traffic that leaves the machine is counted. Loopback is excluded, and so is any connection to one of this machine's own addresses - talking to your own -10.x or tailnet address never reaches a wire. +10.x or tailnet address never reaches a wire, however external it looks in the +socket table. --external is the narrower question of internet-only, and drops +the local network and the tailnet too. Totals start at zero: the first sample is a baseline and only what happens -after it is counted. A process that exits keeps what it used. +after it is counted. A process that exits keeps what it used, marked so, since +"what has been eating the connection" is usually asked after the thing has +stopped. -TCP only, which is the honest limit of this method: ss keeps no byte counters -for UDP, so QUIC, DNS and everything Tailscale carries over WireGuard are -invisible. The interfaces line says how much of the machine's traffic the -table can actually account for. +TCP only, which is the honest limit of this method - see docs/netwatch.md. -Keys: up/down select, 1 sorts by total, 2 by current rate, o shows the -daemons you do not own, r rezeroes, q quits. +Enter opens one process: its command, every connection it holds separately, +and the files it currently has open with how fast each is growing - which is +the closest thing to "which file is it downloading" that exists outside the +encrypted stream. The URL and the remote filename are inside TLS and are not +readable from here by any means. + +Keys: up/down select, enter opens one, esc goes back, 1 sorts by total, +2 by current rate, o shows the daemons you do not own, r rezeroes, +q quits. diff --git a/rust/widgets/src/bin/ports_help.txt b/rust/widgets/src/bin/ports_help.txt index e46ad27..b5369c9 100644 --- a/rust/widgets/src/bin/ports_help.txt +++ b/rust/widgets/src/bin/ports_help.txt @@ -18,4 +18,17 @@ where Tailscale is installed. Another user's sockets cannot be tied to a process without root, so those rows name the owner the socket table gives and are hidden behind o along with the system ports. -Keys: up/down select, o hides the machine's own ports, r refreshes, q quits. +k stops the selected server, after a confirmation and only for a process you +own: SIGTERM to its process group, which is what Ctrl-C in its own terminal +would have sent, then the offer of SIGKILL if it is still up three seconds +later. + +Enter opens a second screen for one port, where there is more to show than the +table holds: the command behind it, every address it can actually be reached +at - bounded by what the socket is bound to - and c to copy one. From there s +and t publish it over Tailscale, to the tailnet or to the internet, and d +opens a Cloudflare quick tunnel. Each asks first. + +Keys: up/down select, enter opens, esc goes back, c copies, s serves, +t funnels, d tunnels, k kills, o hides the machine's own ports, r refreshes, +q quits. From abc5956700176c447b06dcf8e36a62a7f1e2d3ec Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sun, 23 Aug 2026 02:04:09 +0800 Subject: [PATCH 019/147] core: understand both encodings of Home and End Terminals send either \e[H / \e[F or \e[1~ / \e[4~ for the same two keys, depending on the emulator and on whether it is in application cursor mode. common.py has always accepted both; this accepted only the first, so Home and End worked on some clients and silently did nothing on others - which reads as a broken key rather than a missing one. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/core/src/lib.rs | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/rust/core/src/lib.rs b/rust/core/src/lib.rs index e01e38c..ba12dc3 100644 --- a/rust/core/src/lib.rs +++ b/rust/core/src/lib.rs @@ -423,6 +423,12 @@ fn decode(text: &str) -> Vec { ("\x1b[6~", "pgdn"), ("\x1b[H", "home"), ("\x1b[F", "end"), + // The other encoding of the same two keys. Which one arrives + // depends on the terminal and on whether it is in application + // cursor mode, so both have to be understood or Home and End work + // on some clients and not others. + ("\x1b[1~", "home"), + ("\x1b[4~", "end"), ]; let mut keys = Vec::new(); let chars: Vec = text.chars().collect(); @@ -533,6 +539,11 @@ mod tests { assert_eq!(decode("\x1b[B\x1b[B"), vec!["down", "down"]); assert_eq!(decode("q"), vec!["q"]); assert_eq!(decode("\x1b"), vec!["esc"]); + // Both encodings of Home and End, since terminals disagree. + assert_eq!(decode("\x1b[H"), vec!["home"]); + assert_eq!(decode("\x1b[1~"), vec!["home"]); + assert_eq!(decode("\x1b[F"), vec!["end"]); + assert_eq!(decode("\x1b[4~"), vec!["end"]); assert_eq!(decode("\r"), vec!["enter"]); } From f35ff96c96458e9f13003bb78b620b680e9e37b7 Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sun, 23 Aug 2026 02:16:35 +0800 Subject: [PATCH 020/147] latency, link: the charts netwatch already draws MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Both plotted one glyph per sample and filled │ between the steps, so a round trip that moved quickly read as a column of marks rather than as a line. netwatch has drawn on a braille dot canvas since it was ported - two dots to a character across and four down, with consecutive samples joined - and these two now do the same. The side effect worth having is resolution: a cell that used to hold one sample holds two, so latency's chart reaches twice as far back and link condenses its window half as hard. netwatch plots one signal at a time and keeps a single grid of masks with a single colour. These charts carry several at once, so each series is drawn on its own canvas and the canvases are laid over one another at the end. Where two traces meet in a cell the dots are merged, so no sample is lost, and the colour goes to whichever series comes later in the table above. Only one of the two can have the cell, and this way which one is hidden follows from the order of a list on the same screen rather than from which sample happened to be drawn last. The glyphs stay in the table. A braille cell has no shape to lend a row, so the hue is the only thing left that ties a line in the table to a trace in the chart, and every hue is where it was. link's chart also stops shrinking as the window narrows. Its x axis is now anchored to the number of samples the longest session has, which is the same number the "N ago" under the corner is computed from, so the left edge and the label state the same thing. At the default one-minute window that fills the width rather than the right two-fifths of it, and a session younger than the chart still sits at its own share of the axis instead of being stretched across all of it. This is a deliberate divergence from latency.py and link.py, which still plot glyphs, and it was asked for. docs/link.md's account of the chart - one glyph and hue per session - now describes the Python only. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/widgets/src/bin/latency.rs | 178 ++++++++++++++++++++++----- rust/widgets/src/bin/link.rs | 205 +++++++++++++++++++++++++++----- 2 files changed, 327 insertions(+), 56 deletions(-) diff --git a/rust/widgets/src/bin/latency.rs b/rust/widgets/src/bin/latency.rs index 6e92eac..55754f9 100644 --- a/rust/widgets/src/bin/latency.rs +++ b/rust/widgets/src/bin/latency.rs @@ -178,6 +178,92 @@ fn watch(host: String, index: usize, interval: f64, window: usize, shared: Arc Vec> { + let (px_w, px_h) = (cols * 2, rows * 4); + let mut grid = vec![vec![0u8; cols]; rows]; + if values.is_empty() || px_w == 0 || px_h == 0 { + return grid; + } + let vals: Vec = values.iter().rev().take(px_w).rev().copied().collect(); + // Newest against the right edge: a target that has answered five times + // shows five samples there, not five stretched across the whole width. + let left = px_w - vals.len(); + let decade = (lhi - llo).max(1e-9); + let point = |i: usize| -> (i64, i64) { + let frac = ((vals[i].max(1e-3).log10() - llo) / decade).clamp(0.0, 1.0); + ( + (left + i) as i64, + ((1.0 - frac) * (px_h as f64 - 1.0)).round() as i64, + ) + }; + let dot = |x: i64, y: i64, grid: &mut Vec>| { + if x >= 0 && (x as usize) < px_w && y >= 0 && (y as usize) < px_h { + grid[y as usize / 4][x as usize / 2] |= BRAILLE[y as usize % 4][x as usize % 2]; + } + }; + // Every value here is a reply that arrived, so unlike netwatch's idle + // zero there is no reading that means "nothing happened" and should be + // left blank. One sample is a measurement and gets its dot. + let (x, y) = point(0); + dot(x, y, &mut grid); + for i in 1..vals.len() { + let (mut x0, mut y0) = point(i - 1); + let (x1, y1) = point(i); + let (dx, dy) = ((x1 - x0).abs(), -(y1 - y0).abs()); + let sx = if x0 < x1 { 1 } else { -1 }; + let sy = if y0 < y1 { 1 } else { -1 }; + let mut err = dx + dy; + loop { + dot(x0, y0, &mut grid); + if x0 == x1 && y0 == y1 { + break; + } + let twice = 2 * err; + if twice >= dy { + err += dy; + x0 += sx; + } + if twice <= dx { + err += dx; + y0 += sy; + } + } + } + grid +} + +/// Lay the canvases over one another, cell by cell. +/// +/// The dots are merged so that no sample is lost where two targets cross. +/// A cell can carry only one colour, and it goes to whichever series comes +/// later in the table above: which trace is hidden is then something the +/// reader can work out from that list rather than something the data decides +/// afresh every frame. +fn overlay(layers: &[(String, Vec>)], cols: usize, rows: usize) -> Vec> { + let mut cells = vec![vec![(String::new(), 0u8); cols]; rows]; + for (colour, canvas) in layers { + for (y, line) in canvas.iter().enumerate().take(rows) { + for (x, mask) in line.iter().enumerate().take(cols) { + if *mask != 0 { + cells[y][x].0 = colour.clone(); + cells[y][x].1 |= mask; + } + } + } + } + cells +} + /// Log-scale plot of every target's round trip. /// /// Log because the targets on one screen can differ by two orders of @@ -191,7 +277,9 @@ fn graph(targets: &[Target], w: usize, h: usize, p: &Palette) -> Vec { .enumerate() .map(|(i, t)| { let all = t.rtts(); - let start = all.len().saturating_sub(gw); + // Two dots to a cell across, so the chart holds twice the pings + // it did when each one had a character to itself. + let start = all.len().saturating_sub(gw * 2); (i, all[start..].to_vec()) }) .filter(|(_, v)| !v.is_empty()) @@ -215,34 +303,22 @@ fn graph(targets: &[Target], w: usize, h: usize, p: &Palette) -> Vec { * 1.25; let (llo, lhi) = (lo.log10(), hi.log10()); - let mut grid = vec![vec![(p.grid.clone(), " ".to_string()); gw]; gh]; - for (idx, values) in &series { - let glyph = SERIES[idx % SERIES.len()]; - let colour = &p.hues[idx % p.hues.len()]; - let start = gw - values.len(); - let mut previous: Option = None; - for (x, value) in values.iter().enumerate() { - let frac = (value.max(1e-3).log10() - llo) / (lhi - llo); - let y = ((1.0 - frac) * (gh as f64 - 1.0)).round().clamp(0.0, gh as f64 - 1.0) as usize; - let col = start + x; - if let Some(prev) = previous { - if prev.abs_diff(y) > 1 { - // Join consecutive samples so a series reads as a trace - // rather than as marks a row apart. - for fill in prev.min(y) + 1..prev.max(y) { - if grid[fill][col].1 == " " { - grid[fill][col] = (colour.clone(), "│".into()); - } - } - } - } - grid[y][col] = (colour.clone(), glyph.to_string()); - previous = Some(y); - } - } + // One canvas per target rather than one shared grid: the glyphs used to + // tell the traces apart, and with braille the hue is all that is left to + // do it with, so each series has to keep its own until the last moment. + let layers: Vec<(String, Vec>)> = series + .iter() + .map(|(idx, values)| { + ( + p.hues[idx % p.hues.len()].clone(), + braille_canvas(values, llo, lhi, gw, gh), + ) + }) + .collect(); + let cells = overlay(&layers, gw, gh); let mut out = Vec::new(); - for (y, line) in grid.iter().enumerate() { + for (y, line) in cells.iter().enumerate() { let frac = 1.0 - (y as f64 / (gh as f64 - 1.0).max(1.0)); let value = 10f64.powf(llo + frac * (lhi - llo)); // Label only the top, middle and bottom: a number on every row is a @@ -254,8 +330,14 @@ fn graph(targets: &[Target], w: usize, h: usize, p: &Palette) -> Vec { }; let mut parts: Vec<(&str, String)> = vec![(p.dim.as_str(), label), (p.grid.as_str(), "│".into())]; - for (colour, ch) in line { - parts.push((colour.as_str(), ch.clone())); + for (colour, mask) in line { + parts.push(match mask { + 0 => (p.grid.as_str(), " ".into()), + m => ( + colour.as_str(), + char::from_u32(0x2800 + *m as u32).unwrap_or(' ').to_string(), + ), + }); } out.push(tc::seg(&parts, w - 1)); } @@ -556,4 +638,42 @@ mod tests { assert_eq!(label_for("box.example.internal", &strip), "box"); assert_eq!(label_for("1.1.1.1", &strip), "1.1.1.1"); } + + #[test] + fn a_rising_series_climbs_the_canvas() { + // Eight samples across four cells - two dots each - from the bottom + // of the decade the axis covers to the top of it. + let values: Vec = (0..8).map(|i| 10f64.powf(1.0 + i as f64 / 7.0)).collect(); + let grid = braille_canvas(&values, 1.0, 2.0, 4, 4); + let highest: Vec = (0..4) + .map(|x| { + grid.iter() + .position(|row| row[x] != 0) + .expect("every column carries part of the trace") + }) + .collect(); + // Row zero is the top of the canvas, so climbing counts down. + assert_eq!(highest.first(), Some(&3)); + assert_eq!(highest.last(), Some(&0)); + assert!(highest.windows(2).all(|p| p[0] >= p[1]), "{:?}", highest); + } + + #[test] + fn two_traces_in_one_cell_keep_both_their_dots() { + let top = braille_canvas(&[10.0, 10.0], 0.0, 1.0, 1, 1); + let bottom = braille_canvas(&[1.0, 1.0], 0.0, 1.0, 1, 1); + assert!(top[0][0] != 0 && bottom[0][0] != 0); + let cells = overlay( + &[ + ("first".to_string(), top.clone()), + ("second".to_string(), bottom.clone()), + ], + 1, + 1, + ); + assert_eq!(cells[0][0].1, top[0][0] | bottom[0][0]); + // Only the hue has to be given up, and it goes to the lower row of + // the table, which is the rule the reader can apply from outside. + assert_eq!(cells[0][0].0, "second"); + } } diff --git a/rust/widgets/src/bin/link.rs b/rust/widgets/src/bin/link.rs index a56e8bb..e1e8ead 100644 --- a/rust/widgets/src/bin/link.rs +++ b/rust/widgets/src/bin/link.rs @@ -917,6 +917,105 @@ fn detail_view( rows } +/// A braille cell is two dots wide and four tall, so one character holds +/// eight addressable points. The bit for each is fixed by the encoding. +const BRAILLE: [[u8; 2]; 4] = [[0x01, 0x08], [0x02, 0x10], [0x04, 0x20], [0x40, 0x80]]; + +/// Plot one session's round trips on a dot canvas finer than the cells. +/// +/// Consecutive samples are joined rather than left as marks, which is the +/// difference between a line that reads as a path moving and one that reads +/// as specks a row apart. The masks come back per cell instead of as text so +/// that several sessions can be laid over one another first. +/// +/// `slots` is how many samples the axis holds, which is not how many this +/// session has: newest sits against the right edge either way, and a session +/// younger than the chart takes its own share of the width rather than being +/// stretched over all of it. The longest session fills the axis by +/// definition, and it is the one the "N ago" under the corner is measured +/// from, so the label and the left edge cannot drift apart. +fn braille_canvas( + values: &[f64], + llo: f64, + lhi: f64, + cols: usize, + rows: usize, + slots: usize, +) -> Vec> { + let (px_w, px_h) = (cols * 2, rows * 4); + let mut grid = vec![vec![0u8; cols]; rows]; + if values.is_empty() || px_w == 0 || px_h == 0 { + return grid; + } + let vals: Vec = values.iter().rev().take(px_w).rev().copied().collect(); + let step = (px_w as f64 - 1.0) / (slots.max(2) as f64 - 1.0); + let decade = (lhi - llo).max(1e-9); + let point = |i: usize| -> (i64, i64) { + let frac = ((vals[i].max(1e-3).log10() - llo) / decade).clamp(0.0, 1.0); + let age = (vals.len() - 1 - i) as f64; + ( + px_w as i64 - 1 - (age * step).round() as i64, + ((1.0 - frac) * (px_h as f64 - 1.0)).round() as i64, + ) + }; + let dot = |x: i64, y: i64, grid: &mut Vec>| { + if x >= 0 && (x as usize) < px_w && y >= 0 && (y as usize) < px_h { + grid[y as usize / 4][x as usize / 2] |= BRAILLE[y as usize % 4][x as usize % 2]; + } + }; + // Every value here is a round trip the kernel measured, so unlike + // netwatch's idle zero there is no reading that means "nothing happened" + // and should be left blank. One sample is a measurement and gets its dot. + let (x, y) = point(0); + dot(x, y, &mut grid); + for i in 1..vals.len() { + let (mut x0, mut y0) = point(i - 1); + let (x1, y1) = point(i); + let (dx, dy) = ((x1 - x0).abs(), -(y1 - y0).abs()); + let sx = if x0 < x1 { 1 } else { -1 }; + let sy = if y0 < y1 { 1 } else { -1 }; + let mut err = dx + dy; + loop { + dot(x0, y0, &mut grid); + if x0 == x1 && y0 == y1 { + break; + } + let twice = 2 * err; + if twice >= dy { + err += dy; + x0 += sx; + } + if twice <= dx { + err += dx; + y0 += sy; + } + } + } + grid +} + +/// Lay the canvases over one another, cell by cell. +/// +/// The dots are merged so that no sample is lost where two sessions cross. +/// A cell can carry only one colour, and it goes to whichever session comes +/// later in the list above: which trace is hidden is then something the +/// reader can work out from that list rather than something the data decides +/// afresh every frame. +fn overlay(layers: &[(String, Vec>)], cols: usize, rows: usize) -> Vec> { + let mut cells = vec![vec![(String::new(), 0u8); cols]; rows]; + for (colour, canvas) in layers { + for (y, line) in canvas.iter().enumerate().take(rows) { + for (x, mask) in line.iter().enumerate().take(cols) { + if *mask != 0 { + cells[y][x].0 = colour.clone(); + cells[y][x].1 |= mask; + } + } + } + } + cells +} + #[allow(clippy::too_many_arguments)] fn graph( rows: &[Session], @@ -940,7 +1039,9 @@ fn graph( .filter_map(|(i, row)| { let all = history.get(&row.peer)?; let start = all.len().saturating_sub(want); - let vals = condense(&all[start..], gw); + // The same span of history as before, condensed to twice as many + // points: two dots to a cell across. + let vals = condense(&all[start..], gw * 2); if vals.is_empty() { None } else { @@ -967,32 +1068,26 @@ fn graph( .max(lo * 1.6); let (llo, lhi) = (lo.log10(), hi.log10()); - let mut grid = vec![vec![(p.grid.clone(), ' '); gw]; gh]; - for (idx, values) in &series { - let glyph = SERIES[idx % SERIES.len()]; - let colour = &p.hues[idx % p.hues.len()]; - let start = gw - values.len(); - let mut previous: Option = None; - for (x, value) in values.iter().enumerate() { - let frac = (value.max(1e-3).log10() - llo) / (lhi - llo); - let y = ((1.0 - frac) * (gh as f64 - 1.0)).round().clamp(0.0, gh as f64 - 1.0) as usize; - let col = start + x; - if let Some(prev) = previous { - if prev.abs_diff(y) > 1 { - for fill in prev.min(y) + 1..prev.max(y) { - if grid[fill][col].1 == ' ' { - grid[fill][col] = (colour.clone(), '│'); - } - } - } - } - grid[y][col] = (colour.clone(), glyph); - previous = Some(y); - } - } + // The axis holds as many samples as the longest session has, which is + // the same number plotted_span turns into the "N ago" beneath the chart: + // one quantity, so the label and the left edge state the same thing. + let slots = series.iter().map(|(_, v)| v.len()).max().unwrap_or(1); + // One canvas per session rather than one shared grid: the glyphs used to + // tell the traces apart, and with braille the hue is all that is left to + // do it with, so each series has to keep its own until the last moment. + let layers: Vec<(String, Vec>)> = series + .iter() + .map(|(idx, values)| { + ( + p.hues[idx % p.hues.len()].clone(), + braille_canvas(values, llo, lhi, gw, gh, slots), + ) + }) + .collect(); + let cells = overlay(&layers, gw, gh); let mut out = Vec::new(); - for (y, line) in grid.iter().enumerate() { + for (y, line) in cells.iter().enumerate() { let frac = 1.0 - (y as f64 / (gh as f64 - 1.0).max(1.0)); let value = 10f64.powf(llo + frac * (lhi - llo)); let label = if y == 0 || y == gh / 2 || y == gh - 1 { @@ -1002,8 +1097,14 @@ fn graph( }; let mut parts: Vec<(&str, String)> = vec![(p.dim.as_str(), label), (p.grid.as_str(), "│".into())]; - for (colour, ch) in line { - parts.push((colour.as_str(), ch.to_string())); + for (colour, mask) in line { + parts.push(match mask { + 0 => (p.grid.as_str(), " ".into()), + m => ( + colour.as_str(), + char::from_u32(0x2800 + *m as u32).unwrap_or(' ').to_string(), + ), + }); } out.push(tc::seg(&parts, w - 1)); } @@ -1289,4 +1390,54 @@ mod tests { assert_eq!(window_label(3600.0), "1h"); assert_eq!(window_label(45.0), "45s"); } + + #[test] + fn a_rising_series_climbs_the_canvas() { + // Eight samples across four cells - two dots each - from the bottom + // of the decade the axis covers to the top of it. + let values: Vec = (0..8).map(|i| 10f64.powf(1.0 + i as f64 / 7.0)).collect(); + let grid = braille_canvas(&values, 1.0, 2.0, 4, 4, 8); + let highest: Vec = (0..4) + .map(|x| { + grid.iter() + .position(|row| row[x] != 0) + .expect("every column carries part of the trace") + }) + .collect(); + // Row zero is the top of the canvas, so climbing counts down. + assert_eq!(highest.first(), Some(&3)); + assert_eq!(highest.last(), Some(&0)); + assert!(highest.windows(2).all(|p| p[0] >= p[1]), "{:?}", highest); + } + + #[test] + fn a_young_session_keeps_to_its_share_of_the_axis() { + // Four samples on an axis holding eight: half the width, against the + // right edge, because half the chart is older than the session is. + let grid = braille_canvas(&[10.0, 10.0, 10.0, 10.0], 0.0, 1.0, 4, 1, 8); + assert_eq!((grid[0][0], grid[0][1]), (0, 0)); + assert!(grid[0][2] != 0 && grid[0][3] != 0); + // The same four with the axis to themselves reach the left edge. + let full = braille_canvas(&[10.0, 10.0, 10.0, 10.0], 0.0, 1.0, 4, 1, 4); + assert!(full[0].iter().all(|m| *m != 0)); + } + + #[test] + fn two_traces_in_one_cell_keep_both_their_dots() { + let top = braille_canvas(&[10.0, 10.0], 0.0, 1.0, 1, 1, 2); + let bottom = braille_canvas(&[1.0, 1.0], 0.0, 1.0, 1, 1, 2); + assert!(top[0][0] != 0 && bottom[0][0] != 0); + let cells = overlay( + &[ + ("first".to_string(), top.clone()), + ("second".to_string(), bottom.clone()), + ], + 1, + 1, + ); + assert_eq!(cells[0][0].1, top[0][0] | bottom[0][0]); + // Only the hue has to be given up, and it goes to the lower row of + // the list, which is the rule the reader can apply from outside. + assert_eq!(cells[0][0].0, "second"); + } } From fbbf62cd904c98e0bac26f2d3f0eaa294b060028 Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sun, 23 Aug 2026 02:32:52 +0800 Subject: [PATCH 021/147] latency: port the widget, not a sketch of it This one was never a port. It shared a name and a subject with latency.py and almost nothing else: four columns instead of seven, no sparklines, no event log, no spike detection, no interval, grouping or column keys, and five of the seven config keys ignored. It looked finished because the screen it drew was coherent, which is the only reason it survived a side-by-side comparison of the main view. What is here now: NOW, AVG, MEDIAN, MIN, MAX, JITTER and LOSS over the retained window; the per-target sparkline, scaled to that target's own range rather than the chart's, because the question it answers is the shape of one link's variation and the shared chart cannot show that for a target that never leaves a two-millisecond band; and the event log, which exists because a link that is fine except once a minute is a different problem from one that is slow, and the median in the table will never say so. Jitter is now the mean gap between one reply and the next, which is what the word means on a link. It had been the median absolute deviation - a defensible number, and not the one the column is headed with. The graph buckets samples onto a fixed time grid before plotting, so a sample never migrates between columns and the plot steps left exactly once per bucket instead of shuffling as the clock slides. [c] sets how many seconds a column covers and [g] how the samples inside one combine - median by default, because latency is right-skewed and a mean lets one spike misrepresent a whole block. A bucket with no reply stays a gap: joining across it would draw a line where the link was down. [i] changes the ping interval and applies it now, by signalling the running pings rather than waiting for them to end - at five seconds a change would otherwise take five seconds to appear, which reads as the key not having worked. The reader tells its own SIGTERM from an outage. The braille chart from the previous commit is kept, and the table's glyph column is gone with it: latency.py distinguishes targets by hue and uses the dot beside the name only to say whether the target is answering. The palette is latency.py's own nine rather than the six the other widgets share, since colour is now the only thing telling nine traces apart. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/widgets/src/bin/latency.rs | 820 +++++++++++++++++++++----- rust/widgets/src/bin/latency_help.txt | 34 +- rust/widgets/src/bin/link_help.txt | 19 +- 3 files changed, 700 insertions(+), 173 deletions(-) diff --git a/rust/widgets/src/bin/latency.rs b/rust/widgets/src/bin/latency.rs index 55754f9..bfba670 100644 --- a/rust/widgets/src/bin/latency.rs +++ b/rust/widgets/src/bin/latency.rs @@ -35,11 +35,31 @@ fn now() -> f64 { #[derive(Clone, Default)] struct Target { - host: String, label: String, ip: String, samples: Vec<(f64, Option)>, // (when, rtt or a loss) down_since: Option, + /// Whether the last reading was an answer, for the dot beside the name. + alive: bool, + /// The live ping, so a new interval can be applied without waiting for + /// the old one to notice. + pid: Option, + /// Set while we are killing our own ping on purpose, so its exit is not + /// logged as an outage. + restarting: bool, +} + +/// Everything the table says about one target over the retained window. +#[derive(Default)] +struct Stats { + now: Option, + avg: Option, + med: Option, + min: Option, + max: Option, + jit: Option, + loss: f64, + n: usize, } impl Target { @@ -48,55 +68,144 @@ impl Target { self.samples.iter().filter_map(|(_, r)| *r).collect() } - fn median(&self) -> Option { - let mut got = self.rtts(); + fn stats(&self) -> Stats { + let got = self.rtts(); + let total = self.samples.len(); + let lost = total - got.len(); + let loss = if total > 0 { + 100.0 * lost as f64 / total as f64 + } else { + 0.0 + }; if got.is_empty() { - return None; + return Stats { + loss: if total > 0 { 100.0 } else { 0.0 }, + n: total, + ..Default::default() + }; } - got.sort_by(|a, b| a.partial_cmp(b).unwrap()); - Some(got[got.len() / 2]) - } - - /// The spread of the middle of the distribution, not the extremes. - /// - /// A single 400ms spike in a thousand samples is worth knowing about, - /// but it is not what the link feels like, and a standard deviation - /// would let it dominate the number. - fn jitter(&self) -> Option { - let got = self.rtts(); - if got.len() < 2 { - return None; + let mut ordered = got.clone(); + ordered.sort_by(f64::total_cmp); + // The mean gap between one reply and the next, which is what jitter + // means on a link: how much the round trip moves from ping to ping, + // not how far it sits from its own average. + let jit = if got.len() > 1 { + Some( + got.windows(2).map(|w| (w[1] - w[0]).abs()).sum::() + / (got.len() - 1) as f64, + ) + } else { + Some(0.0) + }; + Stats { + now: self.samples.last().and_then(|(_, r)| *r), + avg: Some(got.iter().sum::() / got.len() as f64), + med: Some(ordered[ordered.len() / 2]), + min: Some(ordered[0]), + max: Some(ordered[ordered.len() - 1]), + jit, + loss, + n: total, } - let median = self.median()?; - let mut deviations: Vec = got.iter().map(|r| (r - median).abs()).collect(); - deviations.sort_by(|a, b| a.partial_cmp(b).unwrap()); - Some(deviations[deviations.len() / 2]) } +} - fn worst(&self) -> Option { - self.rtts().into_iter().fold(None, |acc: Option, r| { - Some(acc.map_or(r, |a: f64| a.max(r))) - }) +/// A round trip in a fixed seven cells, so the columns cannot shift. +/// +/// Below a millisecond it changes unit rather than losing the value: a +/// loopback reply reads 0.21ms as 210µs, and two decimal places of a +/// millisecond hides what that means. +fn fmt_ms(value: Option) -> String { + match value { + None => " -- ".to_string(), + Some(v) if v < 1.0 => format!("{:>5.0}µs", v * 1000.0), + Some(v) if v < 100.0 => format!("{:>5.2}ms", v), + Some(v) => format!("{:>5.1}ms", v), } +} + +const SPARK: &[char] = &['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█']; - fn loss(&self) -> f64 { - if self.samples.is_empty() { - return 0.0; +/// One target's recent history at one character per ping. +/// +/// Scaled to its own range rather than the chart's, so a target that never +/// leaves a two-millisecond band still shows the shape of its variation - +/// which is the question this line answers and the shared chart does not. +fn sparkline(samples: &[(f64, Option)], n: usize, p: &Palette) -> Vec<(String, String)> { + let window = &samples[samples.len().saturating_sub(n)..]; + let got: Vec = window.iter().filter_map(|(_, r)| *r).collect(); + if got.is_empty() { + return vec![(p.bad.clone(), "×".repeat(window.len().min(n)))]; + } + let lo = got.iter().cloned().fold(f64::INFINITY, f64::min); + let hi = got.iter().cloned().fold(f64::NEG_INFINITY, f64::max); + let span = if hi > lo { hi - lo } else { 1.0 }; + let mut out: Vec<(String, String)> = Vec::new(); + for (_, r) in window { + let (colour, glyph) = match r { + None => (p.bad.clone(), '×'), + Some(v) => { + let frac = (v - lo) / span; + let colour = if frac < 0.5 { + &p.ok + } else if frac < 0.85 { + &p.warn + } else { + &p.bad + }; + (colour.clone(), SPARK[((frac * 7.99) as usize).min(7)]) + } + }; + match out.last_mut() { + Some((was, text)) if *was == colour => text.push(glyph), + _ => out.push((colour, glyph.to_string())), } - let lost = self.samples.iter().filter(|(_, r)| r.is_none()).count(); - 100.0 * lost as f64 / self.samples.len() as f64 } + out } -fn ms(value: Option) -> String { - match value { - None => "—".into(), - Some(v) if v >= 100.0 => format!("{:.0}ms", v), - Some(v) if v >= 10.0 => format!("{:.1}ms", v), - Some(v) => format!("{:.2}ms", v), +/// A loss, a recovery or a spike, with the time it happened. +#[derive(Clone)] +struct Event { + at: String, + hue: String, + host: String, + kind: &'static str, + detail: String, +} + +/// How samples sharing one graph column combine. +/// +/// Median by default: latency is right-skewed, so a single spike inside a +/// bucket would drag a mean well above the latency actually experienced +/// most of the time. +fn aggregate(values: &[f64], how: &str) -> f64 { + let mut ordered = values.to_vec(); + ordered.sort_by(f64::total_cmp); + let n = ordered.len(); + if n == 1 { + return ordered[0]; + } + match how { + "mean" => ordered.iter().sum::() / n as f64, + "min" => ordered[0], + "max" => ordered[n - 1], + "p95" => ordered[(n - 1).min((n as f64 * 0.95) as usize)], + _ if n % 2 == 1 => ordered[n / 2], + _ => (ordered[n / 2 - 1] + ordered[n / 2]) / 2.0, } } +const AGGREGATORS: &[&str] = &["median", "mean", "min", "max", "p95"]; +const INTERVAL_CHOICES: &[f64] = &[0.2, 0.5, 1.0, 2.0, 5.0]; +const COLUMN_CHOICES: &[f64] = &[0.0, 2.0, 5.0, 10.0]; + +/// The next entry after `current`, wrapping. Used by the cycling keys. +fn cycle(choices: &[T], current: T) -> T { + let at = choices.iter().position(|c| *c == current).unwrap_or(0); + choices[(at + 1) % choices.len()] +} + /// The round trip out of one ping reply line. /// /// Both shapes ping writes are read - `time=12.3 ms` and `time=12.3ms` - @@ -126,9 +235,39 @@ fn ip_of(line: &str) -> Option { } } +/// What the cycling keys change, shared with the reader threads. +/// +/// The interval lives here rather than being handed to each thread once, +/// because pressing i has to reach pings that are already running. +#[derive(Default)] +struct Settings { + interval: f64, + seconds_per_column: f64, + aggregate: String, + spike_factor: f64, +} + /// Keep one ping running per target, forever. -fn watch(host: String, index: usize, interval: f64, window: usize, shared: Arc>>) { +/// +/// Wrapped in its own thread per target and never allowed to end: if ping +/// exits - a name that stopped resolving, a network that went away - the +/// row would otherwise just stop updating, which reads as a quiet link +/// rather than as a broken widget. +fn watch( + host: String, + index: usize, + window: usize, + shared: Arc>>, + settings: Arc>, + events: Arc>>, + hue: String, + label: String, +) { loop { + let (interval, spike_factor) = match settings.lock() { + Ok(s) => (s.interval, s.spike_factor), + Err(_) => return, + }; let child = std::process::Command::new("ping") .args(["-n", "-O", "-i", &interval.to_string(), &host]) .stdout(std::process::Stdio::piped()) @@ -141,11 +280,15 @@ fn watch(host: String, index: usize, interval: f64, window: usize, shared: Arc s, None => continue, }; for line in BufReader::new(stdout).lines().map_while(Result::ok) { + let stamp = now(); let mut guard = match shared.lock() { Ok(g) => g, Err(_) => return, @@ -156,15 +299,32 @@ fn watch(host: String, index: usize, interval: f64, window: usize, shared: Arc 10 && rtt > med * spike_factor { + log(&events, &hue, &label, "SPIKE", + format!("{} (median {})", fmt_ms(Some(rtt)).trim(), + fmt_ms(Some(med)).trim())); + } + } + if let Some(since) = target.down_since.take() { + log(&events, &hue, &label, "UP", + format!("recovered after {:.0}s", stamp - since)); + } + target.alive = true; target.samples.push((stamp, Some(rtt))); - target.down_since = None; } else if is_loss(&line) { - target.samples.push((stamp, None)); if target.down_since.is_none() { target.down_since = Some(stamp); + log(&events, &hue, &label, "LOSS", "no reply".into()); } + target.alive = false; + target.samples.push((stamp, None)); } if target.samples.len() > window { let drop = target.samples.len() - window; @@ -172,12 +332,83 @@ fn watch(host: String, index: usize, interval: f64, window: usize, shared: Arc { + guard[index].pid = None; + let deliberate = guard[index].restarting; + guard[index].restarting = false; + deliberate + } + Err(_) => return, + }; + // We killed it ourselves to apply a new interval; not an outage, and + // it starts again immediately rather than after the retry pause. + if ours { + continue; + } + if let Ok(mut guard) = shared.lock() { + let target = &mut guard[index]; + if target.down_since.is_none() { + target.down_since = Some(now()); + drop(guard); + log(&events, &hue, &label, "DOWN", "ping exited, retrying".into()); + } else { + drop(guard); + } + } + if let Ok(mut guard) = shared.lock() { + guard[index].alive = false; + guard[index].samples.push((now(), None)); + } std::thread::sleep(Duration::from_secs(2)); } } +fn log(events: &Arc>>, hue: &str, host: &str, kind: &'static str, detail: String) { + if let Ok(mut guard) = events.lock() { + guard.push(Event { + at: clock_time(), + hue: hue.to_string(), + host: host.to_string(), + kind, + detail, + }); + let most = 40; + if guard.len() > most { + let drop = guard.len() - most; + guard.drain(..drop); + } + } +} + +/// Wall-clock time of day, without pulling in a date library for it. +fn clock_time() -> String { + let secs = now() as i64; + let day = secs.rem_euclid(86_400); + // UTC, because this is only ever compared against the other lines in + // the same log - and a widget that guessed at the local offset would be + // wrong for half the year. + format!("{:02}:{:02}:{:02}", day / 3600, (day % 3600) / 60, day % 60) +} + +/// Restart every ping so a new interval takes effect at once. +/// +/// SIGTERM rather than waiting for the current one to end: at five seconds +/// a change would otherwise take five seconds to become visible, which +/// reads as the key not having worked. +fn apply_interval(shared: &Arc>>) { + if let Ok(mut guard) = shared.lock() { + for target in guard.iter_mut() { + if let Some(pid) = target.pid { + target.restarting = true; + if unsafe { libc::kill(pid, libc::SIGTERM) } != 0 { + target.restarting = false; + } + } + } + } +} + /// A braille cell is two dots wide and four tall, so one character holds /// eight addressable points. The bit for each is fixed by the encoding. const BRAILLE: [[u8; 2]; 4] = [[0x01, 0x08], [0x02, 0x10], [0x04, 0x20], [0x40, 0x80]]; @@ -188,37 +419,51 @@ const BRAILLE: [[u8; 2]; 4] = [[0x01, 0x08], [0x02, 0x10], [0x04, 0x20], [0x40, /// difference between a line that reads as a round trip moving and one that /// reads as specks a row apart. The masks come back per cell instead of as /// text so that several series can be laid over one another first. -fn braille_canvas(values: &[f64], llo: f64, lhi: f64, cols: usize, rows: usize) -> Vec> { +fn braille_canvas( + values: &[Option], + llo: f64, + lhi: f64, + cols: usize, + rows: usize, +) -> Vec> { let (px_w, px_h) = (cols * 2, rows * 4); let mut grid = vec![vec![0u8; cols]; rows]; if values.is_empty() || px_w == 0 || px_h == 0 { return grid; } - let vals: Vec = values.iter().rev().take(px_w).rev().copied().collect(); + let vals: Vec> = values.iter().rev().take(px_w).rev().copied().collect(); // Newest against the right edge: a target that has answered five times // shows five samples there, not five stretched across the whole width. let left = px_w - vals.len(); let decade = (lhi - llo).max(1e-9); - let point = |i: usize| -> (i64, i64) { - let frac = ((vals[i].max(1e-3).log10() - llo) / decade).clamp(0.0, 1.0); - ( + let point = |i: usize| -> Option<(i64, i64)> { + let v = vals[i]?; + let frac = ((v.max(1e-3).log10() - llo) / decade).clamp(0.0, 1.0); + Some(( (left + i) as i64, ((1.0 - frac) * (px_h as f64 - 1.0)).round() as i64, - ) + )) }; let dot = |x: i64, y: i64, grid: &mut Vec>| { if x >= 0 && (x as usize) < px_w && y >= 0 && (y as usize) < px_h { grid[y as usize / 4][x as usize / 2] |= BRAILLE[y as usize % 4][x as usize % 2]; } }; - // Every value here is a reply that arrived, so unlike netwatch's idle - // zero there is no reading that means "nothing happened" and should be - // left blank. One sample is a measurement and gets its dot. - let (x, y) = point(0); - dot(x, y, &mut grid); + // A single reading is a measurement and gets its dot: unlike netwatch's + // idle zero, there is no value here that means "nothing happened". + if let Some((x, y)) = point(0) { + dot(x, y, &mut grid); + } for i in 1..vals.len() { - let (mut x0, mut y0) = point(i - 1); - let (x1, y1) = point(i); + // A column with no reply is a gap, and a gap is not drawn through. + // Joining across one would draw a line where the link was down, + // which is the opposite of what happened. + let (Some((mut x0, mut y0)), Some((x1, y1))) = (point(i - 1), point(i)) else { + if let Some((x, y)) = point(i) { + dot(x, y, &mut grid); + } + continue; + }; let (dx, dy) = ((x1 - x0).abs(), -(y1 - y0).abs()); let sx = if x0 < x1 { 1 } else { -1 }; let sy = if y0 < y1 { 1 } else { -1 }; @@ -269,38 +514,58 @@ fn overlay(layers: &[(String, Vec>)], cols: usize, rows: usize) -> Vec Vec { +/// +/// Columns are anchored to a fixed time grid rather than measured backwards +/// from now, so a sample never migrates between columns: the plot steps left +/// exactly once per bucket instead of shuffling as the clock slides. +fn graph( + targets: &[Target], + w: usize, + h: usize, + bucket: f64, + how: &str, + p: &Palette, +) -> (Vec, f64) { let gw = w.saturating_sub(9).max(10); let gh = h.max(4); - let series: Vec<(usize, Vec)> = targets + // Two dot columns to a cell, so the chart holds twice the buckets it + // did when each one had a whole character to itself. + let slots = gw * 2; + let newest = (now() / bucket).floor(); + let series: Vec<(usize, Vec>)> = targets .iter() .enumerate() .map(|(i, t)| { - let all = t.rtts(); - // Two dots to a cell across, so the chart holds twice the pings - // it did when each one had a character to itself. - let start = all.len().saturating_sub(gw * 2); - (i, all[start..].to_vec()) + let mut columns: Vec> = vec![Vec::new(); slots]; + for (at, rtt) in &t.samples { + let Some(rtt) = rtt else { continue }; + let age = newest - (at / bucket).floor(); + if age < 0.0 || age >= slots as f64 { + continue; + } + columns[slots - 1 - age as usize].push(*rtt); + } + let values = columns + .into_iter() + .map(|c| if c.is_empty() { None } else { Some(aggregate(&c, how)) }) + .collect(); + (i, values) }) - .filter(|(_, v)| !v.is_empty()) .collect(); - if series.is_empty() { - return vec![tc::seg(&[(p.dim.as_str(), " collecting…".into())], w - 1)]; - } - let lo = series + let span = bucket * slots as f64; + let seen: Vec = series .iter() - .flat_map(|(_, v)| v.iter()) - .cloned() - .fold(f64::INFINITY, f64::min) - .max(0.05) - * 0.8; - let hi = series - .iter() - .flat_map(|(_, v)| v.iter()) - .cloned() - .fold(0.0f64, f64::max) - .max(lo * 1.6) - * 1.25; + .flat_map(|(_, v)| v.iter().flatten()) + .copied() + .collect(); + if seen.is_empty() { + return ( + vec![tc::seg(&[(p.dim.as_str(), " collecting…".into())], w - 1)], + span, + ); + } + let lo = seen.iter().cloned().fold(f64::INFINITY, f64::min).max(0.05) * 0.8; + let hi = (seen.iter().cloned().fold(0.0f64, f64::max) * 1.25).max(lo * 1.6); let (llo, lhi) = (lo.log10(), hi.log10()); // One canvas per target rather than one shared grid: the glyphs used to @@ -324,7 +589,7 @@ fn graph(targets: &[Target], w: usize, h: usize, p: &Palette) -> Vec { // Label only the top, middle and bottom: a number on every row is a // table pretending to be an axis. let label = if y == 0 || y == gh / 2 || y == gh - 1 { - format!("{:>7}", ms(Some(value))) + fmt_ms(Some(value)) } else { " ".repeat(7) }; @@ -341,18 +606,21 @@ fn graph(targets: &[Target], w: usize, h: usize, p: &Palette) -> Vec { } out.push(tc::seg(&parts, w - 1)); } - out + (out, span) } -const SERIES: &[char] = &['●', '▲', '■', '◆', '✚', '✦']; - fn main() { tc::maybe_help(include_str!("latency_help.txt")); let cfg = tc::load_config("latency"); let hosts = tc::cfg_strings(&cfg, "hosts", &["1.1.1.1", "8.8.8.8"]); - let mut interval = tc::cfg_f64(&cfg, "interval", 0.5); let window = tc::cfg_usize(&cfg, "window", 600); let strip: Vec = tc::cfg_strings(&cfg, "strip_suffixes", &[]); + let mut live = Settings { + interval: tc::cfg_f64(&cfg, "interval", 0.5), + seconds_per_column: tc::cfg_f64(&cfg, "seconds_per_column", 0.0), + aggregate: tc::cfg_str(&cfg, "aggregate", "median"), + spike_factor: tc::cfg_f64(&cfg, "spike_factor", 3.0), + }; let args: Vec = std::env::args().skip(1).collect(); let mut named: Vec = Vec::new(); @@ -360,7 +628,19 @@ fn main() { while i < args.len() { match args[i].as_str() { "-i" | "--interval" if i + 1 < args.len() => { - interval = args[i + 1].parse::().unwrap_or(0.5).max(0.1); + live.interval = args[i + 1].parse::().unwrap_or(0.5).max(0.2); + i += 2; + } + "-c" | "--column-seconds" if i + 1 < args.len() => { + live.seconds_per_column = args[i + 1].parse::().unwrap_or(0.0).max(0.0); + i += 2; + } + "-g" | "--group" if i + 1 < args.len() => { + if !AGGREGATORS.contains(&args[i + 1].as_str()) { + eprintln!("-g must be one of: {}", AGGREGATORS.join(", ")); + std::process::exit(2); + } + live.aggregate = args[i + 1].clone(); i += 2; } other if !other.starts_with('-') => { @@ -382,26 +662,57 @@ fn main() { let targets: Vec = hosts .iter() .map(|h| Target { - host: h.clone(), label: label_for(h, &strip), ..Default::default() }) .collect(); + let labels: Vec = targets.iter().map(|t| t.label.clone()).collect(); let shared = Arc::new(Mutex::new(targets)); + let settings = Arc::new(Mutex::new(live)); + let events: Arc>> = Arc::new(Mutex::new(Vec::new())); for (index, host) in hosts.iter().enumerate() { let shared = Arc::clone(&shared); + let settings = Arc::clone(&settings); + let events = Arc::clone(&events); let host = host.clone(); - std::thread::spawn(move || watch(host, index, interval, window, shared)); + let hue = p.hues[index % p.hues.len()].clone(); + let label = labels[index].clone(); + std::thread::spawn(move || { + watch(host, index, window, shared, settings, events, hue, label) + }); } tc::setup(); let mut keyboard = tc::Keyboard::new(); loop { for key in keyboard.poll() { - if key == "q" || key == "Q" { - keyboard.restore(); - tc::restore_screen(); - return; + match key.as_str() { + "q" | "Q" => { + keyboard.restore(); + tc::restore_screen(); + return; + } + "i" | "I" => { + if let Ok(mut s) = settings.lock() { + s.interval = cycle(INTERVAL_CHOICES, s.interval); + } + apply_interval(&shared); + } + "g" | "G" => { + if let Ok(mut s) = settings.lock() { + let at = AGGREGATORS + .iter() + .position(|a| *a == s.aggregate) + .unwrap_or(0); + s.aggregate = AGGREGATORS[(at + 1) % AGGREGATORS.len()].to_string(); + } + } + "c" | "C" => { + if let Ok(mut s) = settings.lock() { + s.seconds_per_column = cycle(COLUMN_CHOICES, s.seconds_per_column); + } + } + _ => {} } } let (w, h) = tc::size(); @@ -409,74 +720,180 @@ fn main() { Ok(g) => g.clone(), Err(_) => return, }; + let (interval, per_column, how) = match settings.lock() { + Ok(s) => (s.interval, s.seconds_per_column, s.aggregate.clone()), + Err(_) => return, + }; + // Zero means one bucket per ping, which is the finest motion the + // grid allows; anything larger trades that for a longer history. + let bucket = if per_column > 0.0 { per_column } else { interval }; let mut rows = vec![tc::title("network latency monitor", w, &p.head)]; - let live = snapshot.iter().filter(|t| t.down_since.is_none()).count(); rows.push(tc::seg( &[ - (p.dim.as_str(), format!(" {} targets", snapshot.len())), - (p.dim.as_str(), " · ".into()), ( - if live == snapshot.len() { &p.ok } else { &p.bad }, - format!("{} answering", live), + p.dim.as_str(), + format!(" {} targets · {:.1}s interval · ", snapshot.len(), interval), + ), + (p.txt.as_str(), clock_time()), + ( + p.dim.as_str(), + if bucket <= interval { + " · 1 ping/column".to_string() + } else { + format!(" · {} of {}s blocks", how, bucket) + }, + ), + ( + p.grid.as_str(), + " [i]nterval [g]roup [c]olumns [q]uit".into(), ), - (p.dim.as_str(), format!(" every {}s", interval)), ], w - 1, )); rows.push(String::new()); - let name_w = snapshot - .iter() - .map(|t| t.label.chars().count()) - .max() - .unwrap_or(8) - .clamp(8, 24); + // The columns are dropped from the right as the pane narrows rather + // than clipped, because half a number is worse than none. + let wide = w >= 72; + let show_med = w >= 80; + let name_w = 22usize; rows.push(tc::seg( - &[ - (p.dim.as_str(), format!(" {}", tc::pad("TARGET", name_w))), - (p.dim.as_str(), format!("{:>9}", "MEDIAN")), - (p.dim.as_str(), format!("{:>9}", "JITTER")), - (p.dim.as_str(), format!("{:>9}", "WORST")), - (p.dim.as_str(), format!("{:>8}", "LOSS")), - ], + &[( + p.lbl.as_str(), + format!( + " {} {:>7} {:>7}{} {:>7} {:>7} {:>7} {:>6}", + tc::pad("HOST", name_w), + "NOW", + "AVG", + if show_med { " MEDIAN" } else { "" }, + "MIN", + "MAX", + "JITTER", + "LOSS" + ), + )], w - 1, )); for (i, t) in snapshot.iter().enumerate() { - let glyph = SERIES[i % SERIES.len()]; + let st = t.stats(); let hue = &p.hues[i % p.hues.len()]; - let loss = t.loss(); + let loss_c = if st.loss == 0.0 { + &p.ok + } else if st.loss < 5.0 { + &p.warn + } else { + &p.bad + }; rows.push(tc::seg( &[ - (hue.as_str(), format!(" {}", glyph)), - (p.txt.as_str(), tc::pad(&t.label, name_w)), - (p.txt.as_str(), format!("{:>9}", ms(t.median()))), - (p.dim.as_str(), format!("{:>9}", ms(t.jitter()))), - (p.dim.as_str(), format!("{:>9}", ms(t.worst()))), + // The dot rides in the colour rather than the text, so + // it costs no cell - which is how latency.py draws it, + // and the two have to line up column for column when + // they sit side by side. + ( + &format!( + "{}{}", + if t.alive { &p.ok } else { &p.bad }, + if t.alive { '●' } else { '○' } + ), + " ".to_string(), + ), + (hue.as_str(), tc::pad(&t.label, name_w)), + (p.txt.as_str(), format!(" {}", fmt_ms(st.now))), + (p.txt.as_str(), format!(" {}", fmt_ms(st.avg))), ( - if loss > 0.0 { &p.bad } else { &p.dim }, - format!("{:>7.1}%", loss), + p.ok.as_str(), + if show_med { + format!(" {}", fmt_ms(st.med)) + } else { + String::new() + }, ), + (p.dim.as_str(), format!(" {}", fmt_ms(st.min))), + (p.dim.as_str(), format!(" {}", fmt_ms(st.max))), + (p.txt.as_str(), format!(" {}", fmt_ms(st.jit))), + (loss_c.as_str(), format!(" {:>5.1}%", st.loss)), ], w - 1, )); + if wide && !t.samples.is_empty() { + let mut line: Vec<(&str, String)> = vec![(p.dim.as_str(), " ".into())]; + let spark = sparkline(&t.samples, w.saturating_sub(6), &p); + for (colour, text) in &spark { + line.push((colour.as_str(), text.clone())); + } + rows.push(tc::seg(&line, w - 1)); + } } rows.push(String::new()); - let room = h.saturating_sub(rows.len() + 3); - if room >= 5 { - rows.extend(graph(&snapshot, w, room, &p)); + // The log only earns its space on a tall pane: on a short one the + // chart is the thing worth keeping. + let log_h = if h.saturating_sub(rows.len()) > 20 { 7 } else { 0 }; + let gh = h.saturating_sub(rows.len() + log_h + 4).max(4); + let (chart, span) = graph(&snapshot, w, gh, bucket, &how, &p); + let drawn = chart.len(); + rows.extend(chart); + if drawn > 1 { + let gw = w.saturating_sub(9).max(10); + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ".repeat(7)), + (p.grid.as_str(), format!("└{}", "─".repeat(gw))), + ], + w - 1, + )); + let ago = format!("{}s ago", span as i64); + let ago = if ago.chars().count() + 4 > gw { + String::new() + } else { + ago + }; + rows.push(tc::seg( + &[ + (p.dim.as_str(), format!("{:8}{}", "", ago)), + ( + p.dim.as_str(), + " ".repeat(gw.saturating_sub(ago.chars().count() + 3)), + ), + (p.dim.as_str(), "now".into()), + ], + w - 1, + )); } + rows.push(String::new()); - let hints: Vec> = vec![vec![(p.dim.as_str(), "[q]uit".into())]]; - let foot: Vec = tc::pack_hints(&hints, w - 2, " ") - .into_iter() - .map(|l| format!(" {}", l)) - .collect(); - while rows.len() < h.saturating_sub(foot.len()) { - rows.push(String::new()); + if log_h > 0 { + rows.push(tc::seg(&[(p.dim.as_str(), " ── EVENTS ──".into())], w - 1)); + let recent: Vec = match events.lock() { + Ok(g) => g.iter().rev().take(log_h - 1).rev().cloned().collect(), + Err(_) => Vec::new(), + }; + if recent.is_empty() { + rows.push(tc::seg( + &[(p.dim.as_str(), " (no loss or spikes recorded)".into())], + w - 1, + )); + } + for event in &recent { + let kind_c = match event.kind { + "LOSS" | "DOWN" => &p.bad, + "SPIKE" => &p.warn, + _ => &p.ok, + }; + rows.push(tc::seg( + &[ + (p.dim.as_str(), format!(" {} ", event.at)), + (kind_c.as_str(), format!("{:<6}", event.kind)), + (event.hue.as_str(), tc::pad(&event.host, 22)), + (p.dim.as_str(), event.detail.clone()), + ], + w - 1, + )); + } } - rows.extend(foot); + tc::draw(&rows, w, h); std::thread::sleep(Duration::from_millis(300)); } @@ -545,29 +962,39 @@ fn cannot_start(needed: &[String]) { struct Palette { ok: String, + warn: String, bad: String, dim: String, grid: String, txt: String, + lbl: String, head: String, hues: Vec, } fn palette() -> Palette { Palette { - ok: tc::rgb(90, 240, 160), - bad: tc::rgb(255, 100, 110), - dim: tc::rgb(127, 147, 172), - grid: tc::rgb(60, 78, 98), - txt: tc::rgb(225, 235, 245), + ok: tc::rgb(110, 255, 170), + warn: tc::rgb(255, 200, 90), + bad: tc::rgb(255, 95, 105), + dim: tc::rgb(70, 100, 120), + grid: tc::rgb(38, 58, 74), + txt: tc::rgb(215, 235, 250), + lbl: tc::rgb(120, 170, 200), head: tc::rgb(90, 220, 255), + // latency.py's own nine, not the six the other widgets share: the + // traces are told apart by hue alone now that the glyphs are gone, + // so more targets than six needs more than six colours. hues: vec![ - tc::rgb(120, 200, 255), - tc::rgb(150, 230, 180), - tc::rgb(220, 170, 255), - tc::rgb(160, 190, 240), - tc::rgb(200, 220, 150), - tc::rgb(240, 180, 210), + tc::rgb(90, 220, 255), + tc::rgb(255, 170, 80), + tc::rgb(140, 255, 160), + tc::rgb(230, 140, 255), + tc::rgb(255, 110, 130), + tc::rgb(255, 230, 110), + tc::rgb(120, 160, 255), + tc::rgb(255, 140, 200), + tc::rgb(150, 255, 240), ], } } @@ -602,16 +1029,36 @@ mod tests { } #[test] - fn jitter_is_the_middle_of_the_spread_not_the_extremes() { + fn a_spike_belongs_in_max_and_not_in_the_middle() { let mut t = Target::default(); - // Nine steady samples and one wild spike: the spike belongs in - // worst, and must not be allowed to define jitter. + // Nine steady samples and one wild spike. The median and the + // typical round trip are unmoved by it; max is where it shows. for v in [10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 10.0, 400.0] { t.samples.push((0.0, Some(v))); } - assert_eq!(t.median(), Some(10.0)); - assert_eq!(t.jitter(), Some(0.0)); - assert_eq!(t.worst(), Some(400.0)); + let st = t.stats(); + assert_eq!(st.med, Some(10.0)); + assert_eq!(st.max, Some(400.0)); + assert_eq!(st.min, Some(10.0)); + assert_eq!(st.now, Some(400.0)); + } + + #[test] + fn jitter_is_the_gap_between_one_reply_and_the_next() { + let mut t = Target::default(); + // Ten and twenty alternating: every consecutive gap is 10ms, so + // that is the jitter - even though every sample sits 5ms from the + // mean, which is what a deviation would have reported. + for v in [10.0, 20.0, 10.0, 20.0, 10.0] { + t.samples.push((0.0, Some(v))); + } + assert_eq!(t.stats().jit, Some(10.0)); + // A steady link has none, and one sample cannot have any. + let mut steady = Target::default(); + for _ in 0..4 { + steady.samples.push((0.0, Some(30.0))); + } + assert_eq!(steady.stats().jit, Some(0.0)); } #[test] @@ -621,15 +1068,74 @@ mod tests { t.samples.push((0.0, None)); t.samples.push((0.0, Some(12.0))); t.samples.push((0.0, None)); - assert_eq!(t.loss(), 50.0); + assert_eq!(t.stats().loss, 50.0); + // Nothing back at all is total loss, not an absent reading. + let mut silent = Target::default(); + silent.samples.push((0.0, None)); + assert_eq!(silent.stats().loss, 100.0); + assert_eq!(silent.stats().med, None); + } + + #[test] + fn milliseconds_keep_their_column_width() { + // Seven cells whatever the value, or the columns shift under the + // headings as a link speeds up. + for value in [Some(123.4), Some(12.34), Some(1.234), Some(0.21), None] { + assert_eq!(fmt_ms(value).chars().count(), 7, "{:?}", value); + } + assert_eq!(fmt_ms(Some(123.4)), "123.4ms"); + assert_eq!(fmt_ms(Some(12.34)), "12.34ms"); + // Below a millisecond it changes unit rather than losing the value. + assert_eq!(fmt_ms(Some(0.21)), " 210µs"); + assert_eq!(fmt_ms(None), " -- "); } #[test] - fn milliseconds_gain_precision_as_they_shrink() { - assert_eq!(ms(Some(123.4)), "123ms"); - assert_eq!(ms(Some(12.34)), "12.3ms"); - assert_eq!(ms(Some(1.234)), "1.23ms"); - assert_eq!(ms(None), "—"); + fn a_bucket_keeps_the_typical_not_the_extreme() { + let block = [10.0, 10.0, 10.0, 10.0, 400.0]; + // Median by default, because latency is right-skewed and one spike + // in a bucket would drag a mean well above what the link felt like. + assert_eq!(aggregate(&block, "median"), 10.0); + assert_eq!(aggregate(&block, "min"), 10.0); + assert_eq!(aggregate(&block, "max"), 400.0); + assert_eq!(aggregate(&block, "mean"), 88.0); + assert_eq!(aggregate(&block, "p95"), 400.0); + // An even count takes the middle of the two middles. + assert_eq!(aggregate(&[10.0, 20.0], "median"), 15.0); + assert_eq!(aggregate(&[7.0], "mean"), 7.0); + } + + #[test] + fn the_cycling_keys_wrap() { + assert_eq!(cycle(INTERVAL_CHOICES, 0.5), 1.0); + assert_eq!(cycle(INTERVAL_CHOICES, 5.0), 0.2); + // A value that is not one of the choices starts from the first. + assert_eq!(cycle(INTERVAL_CHOICES, 3.3), 0.5); + assert_eq!(cycle(COLUMN_CHOICES, 10.0), 0.0); + } + + #[test] + fn a_gap_in_the_data_is_not_drawn_through() { + // Two readings with a lost bucket between them. Joining across it + // would draw a line where the link was down. + let values = [Some(10.0), None, Some(10.0)]; + let grid = braille_canvas(&values, 1.0, 2.0, 3, 2); + let occupied: Vec = (0..6) + .map(|x| grid.iter().any(|row| row[x / 2] & column_mask(x % 2) != 0)) + .collect(); + // Six dot columns for three cells, and three values, so they sit in + // the last three: a reading, the lost bucket, a reading. + assert!(occupied[3] && occupied[5], "the readings are missing"); + assert!(!occupied[4], "something was drawn across the gap"); + assert!( + !occupied[..3].iter().any(|hit| *hit), + "the empty left of the axis was painted" + ); + } + + /// Every dot bit in one column of a braille cell. + fn column_mask(x: usize) -> u8 { + BRAILLE.iter().fold(0u8, |acc, row| acc | row[x]) } #[test] @@ -643,7 +1149,9 @@ mod tests { fn a_rising_series_climbs_the_canvas() { // Eight samples across four cells - two dots each - from the bottom // of the decade the axis covers to the top of it. - let values: Vec = (0..8).map(|i| 10f64.powf(1.0 + i as f64 / 7.0)).collect(); + let values: Vec> = (0..8) + .map(|i| Some(10f64.powf(1.0 + i as f64 / 7.0))) + .collect(); let grid = braille_canvas(&values, 1.0, 2.0, 4, 4); let highest: Vec = (0..4) .map(|x| { @@ -660,8 +1168,8 @@ mod tests { #[test] fn two_traces_in_one_cell_keep_both_their_dots() { - let top = braille_canvas(&[10.0, 10.0], 0.0, 1.0, 1, 1); - let bottom = braille_canvas(&[1.0, 1.0], 0.0, 1.0, 1, 1); + let top = braille_canvas(&[Some(10.0), Some(10.0)], 0.0, 1.0, 1, 1); + let bottom = braille_canvas(&[Some(1.0), Some(1.0)], 0.0, 1.0, 1, 1); assert!(top[0][0] != 0 && bottom[0][0] != 0); let cells = overlay( &[ diff --git a/rust/widgets/src/bin/latency_help.txt b/rust/widgets/src/bin/latency_help.txt index e533f09..2ccb565 100644 --- a/rust/widgets/src/bin/latency_help.txt +++ b/rust/widgets/src/bin/latency_help.txt @@ -1,20 +1,28 @@ Multi-target latency monitor. -Continuously pings every target, and shows per-target statistics and a -log-scale graph of every target at once. +Continuously pings every target, and shows per-target statistics, a per-target +sparkline, a shared log-scale time graph, and a log of loss/spike events. - latency [-i SECONDS] [HOST...] + latency [-i SECONDS] [-c SECONDS] [host ...] -One ping per target, read line by line as it arrives, so the numbers are what -ping measured rather than anything this timed itself. +Keys while running: i cycles the ping interval (0.2/0.5/1/2/5s, applied to +running pings immediately), g cycles the column aggregation, c cycles seconds +per graph column, q quits. -Jitter is the median absolute deviation, not the standard deviation: a single -400ms spike in a thousand samples is worth knowing about, but it is not what -the link feels like, and a standard deviation would let it dominate. The spike -is in the worst column instead. +-i sets the ping interval. -g picks how samples sharing a column combine +(median, mean, min, max, p95; median by default, because latency is +right-skewed and a mean lets one spike misrepresent the whole block). +-c sets how many seconds each graph column covers; +the default of one column per ping gives the smoothest motion, while a larger +value trades that for a longer visible history. -The graph is log-scale, because targets on one screen can differ by two orders -of magnitude and a linear axis draws the near one as a flat line along the -bottom. +Traffic cost: one 98-byte frame each way per target per interval. At the 1.0s +default with 4 targets that is ~0.8 KB/s (~2.8 MB/hour). -Keys: q quits. +Measures THIS host -> each target. It cannot measure target-to-target legs; +that needs a probe running on the far end. + +The shared graph is drawn on a braille dot canvas rather than one character +per sample, so it holds twice the history and reads as a line rather than a +column of marks. Targets are told apart by colour there; the per-target +sparkline above it is still one character per ping. diff --git a/rust/widgets/src/bin/link_help.txt b/rust/widgets/src/bin/link_help.txt index caff87f..03883cc 100644 --- a/rust/widgets/src/bin/link_help.txt +++ b/rust/widgets/src/bin/link_help.txt @@ -1,17 +1,28 @@ How good the connection is between here and whoever is connected to it. Every other network widget in this repo measures a path it chose - ping these -hosts, watch that tailnet. This one measures the path you are on: the TCP +hosts, watch that tailnet. This one measures the path *you* are on: the TCP socket carrying your session, as the kernel already sees it. Nothing is sent. `ss -tin` reports what the kernel has measured for each established socket - round-trip time and its variance, the best round trip it -has ever seen, retransmitted bytes, the delivery rate it actually achieved. +has ever seen, retransmitted bytes, the delivery rate it actually achieved - +so this widget can describe the link without adding a single packet to it. link [-n SECONDS] +Sessions are every established connection into a port this machine listens on, +which is SSH and anything else that accepts terminals. + w cycles how much time the chart covers - a minute, five, fifteen, an hour. Past a minute there are more samples than columns, so each column becomes the -median of its slice. +median of its slice: a spike is still counted in the worst column and on the +detail screen, but the line itself smooths. Look at a stall on the short +window. + +Keys: up/down select, enter opens one, w changes the span, o toggles idle +sessions, r refreshes, q quits. -Keys: up/down select, w changes the span, o toggles idle sessions, q quits. +The chart is drawn on a braille dot canvas rather than one character per +sample, so it reads as a line rather than a column of marks. Sessions are +told apart by colour, matching the glyph beside each row above. From 02bd35b635f81062efd66122ba09959b62d67ea1 Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sun, 23 Aug 2026 02:38:30 +0800 Subject: [PATCH 022/147] latency: the clock in the header is the machine's, not UTC I hand-rolled a time-of-day formatter to avoid a dependency, made it UTC, and wrote a comment justifying that on the grounds the timestamp is only compared against other lines in the same log. The same function feeds the header, which sits on a wall next to a clock panel showing server time - so on this box it read 18:31 beside a pane saying 02:31, which reads as a broken widget rather than as a different timezone. latency.py has always used local time. chrono is already a workspace dependency, so the reasoning was wrong twice over. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/widgets/src/bin/latency.rs | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/rust/widgets/src/bin/latency.rs b/rust/widgets/src/bin/latency.rs index bfba670..bccf728 100644 --- a/rust/widgets/src/bin/latency.rs +++ b/rust/widgets/src/bin/latency.rs @@ -381,14 +381,13 @@ fn log(events: &Arc>>, hue: &str, host: &str, kind: &'static st } } -/// Wall-clock time of day, without pulling in a date library for it. +/// The time of day, as the machine reckons it. +/// +/// Local rather than UTC: this sits on a wall beside a clock panel showing +/// server time, and a header eight hours out from the pane next to it is +/// read as a broken widget rather than as a different timezone. fn clock_time() -> String { - let secs = now() as i64; - let day = secs.rem_euclid(86_400); - // UTC, because this is only ever compared against the other lines in - // the same log - and a widget that guessed at the local offset would be - // wrong for half the year. - format!("{:02}:{:02}:{:02}", day / 3600, (day % 3600) / 60, day % 60) + chrono::Local::now().format("%H:%M:%S").to_string() } /// Restart every ping so a new interval takes effect at once. From de543517c9abee9a0b0fc0db4b007763d5c22930 Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sun, 23 Aug 2026 03:19:38 +0800 Subject: [PATCH 023/147] herdr-panes: port the board that says who is waiting on you Seventh widget, and the first of the nine that were still Python only. Agents ranked by whether they want a human, the panes running something ranked by what they cost, the idle ones by directory, and Enter focusing whichever is selected - the agent's pane, or the tab holding the process, since a pane has no focus-by-id but a tab tiles its panes. Two things moved into core on the way, both of which common.py owns and this is the third widget to want: heat(), so the same load reads as the same colour in every pane, and cannot_start(), which had been copied into latency and link. A widget that exits with a message loses it - it lives in a pane nobody is watching at the moment it starts - so that screen stays up until somebody presses q. Two things worth naming. The config section is `herdr_panes` with an underscore while the file, the binary and the pane are all hyphenated; reading the hyphenated name compiles, runs, and silently finds nothing, so there is a comment on it. And ago() is this widget's own formatter rather than the span() the others share: between an hour and a day it carries the minutes, because an agent blocked for 3h and one blocked for 3h58m are the same number of hours and a very different amount of ignoring. One difference from the Python, found by a test: mem() returns five characters for a reading and six for an absent one, so a process /proc would not name pushed the workspace column one cell right of every other row. The header allots five, so five it is. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/core/src/lib.rs | 81 ++ rust/widgets/Cargo.toml | 4 + rust/widgets/src/bin/herdr-panes.rs | 981 ++++++++++++++++++++++ rust/widgets/src/bin/herdr-panes_help.txt | 39 + 4 files changed, 1105 insertions(+) create mode 100644 rust/widgets/src/bin/herdr-panes.rs create mode 100644 rust/widgets/src/bin/herdr-panes_help.txt diff --git a/rust/core/src/lib.rs b/rust/core/src/lib.rs index ba12dc3..d231b4e 100644 --- a/rust/core/src/lib.rs +++ b/rust/core/src/lib.rs @@ -324,6 +324,74 @@ fn base64(data: &[u8]) -> String { out } +/// Green through amber to red. +/// +/// Used wherever a fraction is a temperature - CPU, memory, how close a +/// number is to a limit - so the same load reads the same colour whichever +/// widget is showing it. +pub fn heat(frac: f64) -> String { + let frac = frac.clamp(0.0, 1.0); + if frac < 0.5 { + let t = frac / 0.5; + rgb((40.0 + 200.0 * t) as u8, 255, (120.0 - 100.0 * t) as u8) + } else { + let t = (frac - 0.5) / 0.5; + rgb(255, (240.0 - 200.0 * t) as u8, (20.0 + 10.0 * t) as u8) + } +} + +/// Draw the reason a widget cannot run, and hold until q. +/// +/// Exiting with a message loses it: a widget lives in a pane that is not +/// being watched at the moment it starts, and a line printed to a shell +/// that then sits at a prompt is indistinguishable from the widget never +/// having been launched. This stays on screen until somebody reads it. +pub fn cannot_start(name: &str, needed: &[String], why: &[&str], install: &str) { + let bad = rgb(255, 100, 110); + let dim = rgb(127, 147, 172); + let txt = rgb(225, 235, 245); + setup(); + let mut keyboard = Keyboard::new(); + loop { + for key in keyboard.poll() { + if key == "q" || key == "Q" { + keyboard.restore(); + restore_screen(); + return; + } + } + let (w, h) = size(); + let mut rows = vec![title(name, w, &bad), String::new()]; + rows.push(seg( + &[ + (bad.as_str(), " cannot start · ".into()), + (txt.as_str(), format!("needs {}", needed.join(", "))), + ], + w - 1, + )); + rows.push(String::new()); + for line in why { + rows.push(seg(&[(dim.as_str(), format!(" {}", line))], w - 1)); + } + if !install.is_empty() { + rows.push(String::new()); + rows.push(seg( + &[ + (dim.as_str(), " try: ".into()), + (txt.as_str(), install.to_string()), + ], + w - 1, + )); + } + while rows.len() < h - 1 { + rows.push(String::new()); + } + rows.push(seg(&[(dim.as_str(), " [q]uit".into())], w - 1)); + draw(&rows, w, h); + std::thread::sleep(std::time::Duration::from_millis(200)); + } +} + /// Which of these required commands are not on PATH. pub fn missing(programs: &[&str]) -> Vec { let path = std::env::var("PATH").unwrap_or_default(); @@ -477,6 +545,19 @@ pub fn maybe_help(doc: &str) { mod tests { use super::*; + #[test] + fn heat_runs_green_to_red_through_amber() { + // The ends and the middle, since every widget reads the same scale + // and a drift in it would make one pane disagree with the next. + assert_eq!(heat(0.0), rgb(40, 255, 120)); + assert_eq!(heat(0.5), rgb(255, 240, 20)); + assert_eq!(heat(1.0), rgb(255, 40, 30)); + // Out of range is clamped rather than wrapped: a CPU reading over + // 100% on a multicore box must not come back green. + assert_eq!(heat(2.0), heat(1.0)); + assert_eq!(heat(-1.0), heat(0.0)); + } + #[test] fn base64_matches_the_rfc_vectors() { // Hand-rolled, and its output is invisible: the copy notice shows diff --git a/rust/widgets/Cargo.toml b/rust/widgets/Cargo.toml index b384faf..8ac8b98 100644 --- a/rust/widgets/Cargo.toml +++ b/rust/widgets/Cargo.toml @@ -36,3 +36,7 @@ path = "src/bin/link.rs" [[bin]] name = "clocks" path = "src/bin/clocks.rs" + +[[bin]] +name = "herdr-panes" +path = "src/bin/herdr-panes.rs" diff --git a/rust/widgets/src/bin/herdr-panes.rs b/rust/widgets/src/bin/herdr-panes.rs new file mode 100644 index 0000000..36ba82b --- /dev/null +++ b/rust/widgets/src/bin/herdr-panes.rs @@ -0,0 +1,981 @@ +// terminal-toys - small dependency-free terminal widgets +// Copyright (C) 2026 William Li +// +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU Affero General Public License as published +// by the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU Affero General Public License for more details. +// +// You should have received a copy of the GNU Affero General Public License +// along with this program. If not, see . + +//! Everything running in Herdr, across every workspace. +//! +//! A port of herdr-panes.py. A Herdr client rather than a general agent +//! monitor: the inventory and the lifecycle states come from the `herdr` +//! CLI, and any agent kind it recognises appears here with no change to +//! this file. + +use std::collections::HashMap; +use std::sync::{Arc, Condvar, Mutex}; +use std::time::{Duration, SystemTime, UNIX_EPOCH}; + +use toys_core as tc; + +/// Worst first: the states that want a human are the reason to look. +const RANK: &[&str] = &["blocked", "done", "working", "idle", "unknown"]; +const SPINNER: &[char] = &['◐', '◓', '◑', '◒']; + +fn now() -> f64 { + SystemTime::now() + .duration_since(UNIX_EPOCH) + .map(|d| d.as_secs_f64()) + .unwrap_or(0.0) +} + +fn rank_of(state: &str) -> usize { + RANK.iter().position(|s| *s == state).unwrap_or(9) +} + +/// Run a herdr command for its effect; true when it succeeded. +fn herdr_action(args: &[&str]) -> bool { + std::process::Command::new("herdr") + .args(args) + .output() + .map(|out| out.status.success()) + .unwrap_or(false) +} + +/// Run a herdr command and hand back the `result` object it printed. +fn herdr(args: &[&str]) -> Option { + let out = std::process::Command::new("herdr").args(args).output().ok()?; + let text = String::from_utf8_lossy(&out.stdout); + let parsed: serde_json::Value = serde_json::from_str(&text).ok()?; + match parsed.get("result") { + Some(serde_json::Value::Null) | None => None, + Some(value) => Some(value.clone()), + } +} + +/// Keep the end of a path, marking the cut so it does not read as a name. +fn tail_path(path: &str, n: usize) -> String { + let chars: Vec = path.chars().collect(); + if chars.len() <= n || n < 2 { + return path.to_string(); + } + format!("…{}", chars[chars.len() - (n - 1)..].iter().collect::()) +} + +fn base_name(path: &str) -> String { + path.rsplit('/').next().unwrap_or(path).to_string() +} + +/// Readable name for what a pane is running. +/// +/// "python3" or "node" says nothing useful, so prefer the script they were +/// handed; otherwise fall back to the executable's own name. +fn command_label(argv: &[String], name: &str) -> String { + const RUNNERS: &[&str] = &[ + "python", "python3", "node", "ruby", "perl", "bun", "deno", "sh", "bash", "zsh", + ]; + let Some(first) = argv.first() else { + return if name.is_empty() { "?".into() } else { name.into() }; + }; + let head = base_name(first); + let stem = head.split('.').next().unwrap_or(&head); + if RUNNERS.contains(&stem) && argv.len() > 1 { + for token in &argv[1..] { + if !token.starts_with('-') { + return base_name(token); + } + } + } + head +} + +/// (cpu ticks used, resident bytes) for a pid. +fn proc_stats(pid: i32) -> Option<(u64, u64)> { + let text = std::fs::read_to_string(format!("/proc/{}/stat", pid)).ok()?; + // The command is in brackets and may itself contain spaces, so the split + // starts after the last one rather than at the second field. + let rest = text.rsplit_once(')')?.1; + let fields: Vec<&str> = rest.split_whitespace().collect(); + let utime: u64 = fields.get(11)?.parse().ok()?; + let stime: u64 = fields.get(12)?.parse().ok()?; + let rss: u64 = fields.get(21)?.parse().ok()?; + Some((utime + stime, rss * 4096)) +} + +fn clock_ticks() -> f64 { + let hz = unsafe { libc::sysconf(libc::_SC_CLK_TCK) }; + if hz > 0 { + hz as f64 + } else { + 100.0 + } +} + +/// A recognised coding agent, and what its process is costing. +#[derive(Clone, Default)] +struct Agent { + name: String, + pane_id: String, + workspace_id: String, + state: String, + title: String, + cwd: String, + since: f64, + /// False when the state was already in place at the first poll, so the + /// duration is only a lower bound and says so. + exact: bool, + cpu: Option, + rss: Option, +} + +/// A pane with no agent in it: either running something, or at a prompt. +#[derive(Clone, Default)] +struct Panel { + pane_id: String, + tab_id: String, + workspace_id: String, + command: String, + cwd: String, + idle: bool, + cpu: Option, + rss: Option, +} + +#[derive(Default)] +struct State { + agents: Vec, + panels: Vec, + labels: HashMap, + err: String, +} + +/// What each pane's state was when we first saw it, so a duration can be +/// measured rather than guessed. +#[derive(Default)] +struct Seen { + since: HashMap, + cpu: HashMap, + first_poll: bool, +} + +/// Fold a fresh /proc reading into the CPU history and return the percentage. +fn cpu_of(seen: &mut Seen, pid: i32, at: f64, hz: f64) -> (Option, Option) { + let Some((ticks, rss)) = proc_stats(pid) else { + return (None, None); + }; + // A percentage needs two readings; the first visit only records one. + let cpu = match seen.cpu.get(&pid) { + Some((was, when)) if at - when > 0.0 => { + Some((ticks.saturating_sub(*was)) as f64 / hz / (at - when) * 100.0) + } + _ => None, + }; + seen.cpu.insert(pid, (ticks, at)); + (cpu, Some(rss)) +} + +fn text_at(value: &serde_json::Value, key: &str) -> String { + value[key].as_str().unwrap_or("").to_string() +} + +/// The foreground process of a pane, if it is running one. +/// +/// A pane sitting at its shell prompt has nothing to report, and the test +/// for that is that the foreground pid is the shell's own. +fn foreground(pane_id: &str) -> Option<(i32, Vec, String, String)> { + let info = herdr(&["pane", "process-info", "--pane", pane_id])?; + let process = &info["process_info"]; + let front = process["foreground_processes"].as_array()?.first()?.clone(); + let pid = front["pid"].as_i64()? as i32; + let busy = process["shell_pid"].as_i64() != Some(pid as i64); + if !busy { + return None; + } + let argv = front["argv"] + .as_array() + .map(|a| { + a.iter() + .filter_map(|v| v.as_str().map(String::from)) + .collect() + }) + .unwrap_or_default(); + Some((pid, argv, text_at(&front, "name"), text_at(&front, "cwd"))) +} + +fn poll(state: &Arc>, seen: &mut Seen, hz: f64) { + let mut labels = HashMap::new(); + if let Some(res) = herdr(&["workspace", "list"]) { + for w in res["workspaces"].as_array().into_iter().flatten() { + labels.insert(text_at(w, "workspace_id"), text_at(w, "label")); + } + } + let listed = match herdr(&["agent", "list"]) { + Some(res) => res, + None => { + if let Ok(mut guard) = state.lock() { + guard.err = "herdr CLI unavailable (is HERDR_ENV set?)".into(); + } + return; + } + }; + + let at = now(); + let mut agents = Vec::new(); + for entry in listed["agents"].as_array().into_iter().flatten() { + let pane_id = text_at(entry, "pane_id"); + let state_name = match entry["agent_status"].as_str() { + Some(s) if !s.is_empty() => s.to_string(), + _ => "unknown".to_string(), + }; + let was = seen.since.get(&pane_id); + if was.is_none_or(|(had, _, _)| *had != state_name) { + // A state already in place when we started is only a lower + // bound - we did not see it begin. + seen.since + .insert(pane_id.clone(), (state_name.clone(), at, !seen.first_poll)); + } + let (_, began, exact) = seen.since[&pane_id].clone(); + let (cpu, rss) = match foreground(&pane_id) { + Some((pid, _, _, _)) => cpu_of(seen, pid, at, hz), + None => (None, None), + }; + agents.push(Agent { + name: text_at(entry, "agent"), + workspace_id: text_at(entry, "workspace_id"), + title: text_at(entry, "terminal_title_stripped"), + cwd: text_at(entry, "cwd"), + state: state_name, + since: at - began, + exact, + cpu, + rss, + pane_id, + }); + } + agents.sort_by(|a, b| { + rank_of(&a.state) + .cmp(&rank_of(&b.state)) + .then(b.since.total_cmp(&a.since)) + }); + + let mut panels = Vec::new(); + if let Some(listing) = herdr(&["pane", "list"]) { + for pane in listing["panes"].as_array().into_iter().flatten() { + if pane.get("agent").is_some_and(|a| !a.is_null()) { + continue; + } + let pane_id = text_at(pane, "pane_id"); + let front = foreground(&pane_id); + let (cpu, rss) = match &front { + Some((pid, _, _, _)) => cpu_of(seen, *pid, at, hz), + None => (None, None), + }; + let (command, cwd) = match &front { + Some((_, argv, name, cwd)) => ( + command_label(argv, name), + if cwd.is_empty() { text_at(pane, "cwd") } else { cwd.clone() }, + ), + None => (String::new(), text_at(pane, "cwd")), + }; + panels.push(Panel { + tab_id: text_at(pane, "tab_id"), + workspace_id: text_at(pane, "workspace_id"), + idle: front.is_none(), + pane_id, + command, + cwd, + cpu, + rss, + }); + } + } + // Busy first, and the busiest of those first: the point of the section + // is what is costing something. + panels.sort_by(|a, b| { + a.idle + .cmp(&b.idle) + .then(b.cpu.unwrap_or(0.0).total_cmp(&a.cpu.unwrap_or(0.0))) + }); + + if let Ok(mut guard) = state.lock() { + guard.agents = agents; + guard.panels = panels; + guard.labels = labels; + guard.err.clear(); + } + seen.first_poll = false; +} + +/// A duration as this widget says it, which is not how the others do. +/// +/// Between an hour and a day it carries the minutes too: an agent blocked +/// for "3h" and one blocked for "3h58m" are the same number of hours and a +/// very different amount of ignoring. +fn ago(seconds: f64) -> String { + let s = seconds.max(0.0) as i64; + if s < 60 { + format!("{}s", s) + } else if s < 3600 { + format!("{}m", s / 60) + } else if s < 86400 { + format!("{}h{:02}m", s / 3600, s % 3600 / 60) + } else { + format!("{}d", s / 86400) + } +} + +/// Resident memory in five cells, whatever there is to say. +/// +/// herdr-panes.py returns five characters for a reading and six for an +/// absent one, so a process /proc would not name pushes the workspace +/// column one cell right of every other row. The header allots five. +fn mem(bytes: Option) -> String { + let Some(bytes) = bytes else { + return " --".to_string(); + }; + let mut value = bytes as f64; + for unit in ["B", "K", "M", "G"] { + if value < 1024.0 { + return format!("{:>4.0}{}", value, unit); + } + value /= 1024.0; + } + format!("{:>4.1}T", value) +} + +fn percent(cpu: Option) -> String { + match cpu { + Some(v) => format!("{:>4.0}%", v), + None => " -".to_string(), + } +} + +/// Where a row points, so Enter knows what to focus. +#[derive(Clone)] +enum Row { + Agent(Agent), + Process(Panel), +} + +struct Palette { + blocked: String, + done: String, + working: String, + idle: String, + unknown: String, + dim: String, + txt: String, + lbl: String, + accent: String, + proc: String, + idle_c: String, +} + +fn palette() -> Palette { + Palette { + blocked: tc::rgb(255, 105, 115), + done: tc::rgb(90, 240, 160), + working: tc::rgb(255, 200, 90), + idle: tc::rgb(128, 148, 172), + unknown: tc::rgb(150, 150, 165), + dim: tc::rgb(127, 147, 172), + txt: tc::rgb(225, 235, 245), + lbl: tc::rgb(130, 165, 200), + accent: tc::rgb(150, 210, 255), + proc: tc::rgb(170, 190, 215), + idle_c: tc::rgb(122, 138, 160), + } +} + +fn colour_of<'a>(state: &str, p: &'a Palette) -> &'a str { + match state { + "blocked" => &p.blocked, + "done" => &p.done, + "working" => &p.working, + "idle" => &p.idle, + _ => &p.unknown, + } +} + +fn mark_of(state: &str, tick: usize) -> char { + match state { + "blocked" => '⚠', + "done" => '✓', + "working" => SPINNER[tick % SPINNER.len()], + "idle" => '·', + _ => '?', + } +} + +/// The home-relative form of a directory, which is how a person names it. +fn homely(path: &str) -> String { + let home = std::env::var("HOME").unwrap_or_default(); + if home.is_empty() { + return path.to_string(); + } + let projects = format!("{}/projects/", home); + if let Some(rest) = path.strip_prefix(&projects) { + return rest.to_string(); + } + match path.strip_prefix(&home) { + Some(rest) => format!("~{}", rest), + None => path.to_string(), + } +} + +fn main() { + tc::maybe_help(include_str!("herdr-panes_help.txt")); + // The section is spelled with an underscore while everything else about + // this widget is hyphenated. A mismatched key is read as absent rather + // than as an error, so it is worth saying out loud. + let cfg = tc::load_config("herdr_panes"); + let mut refresh = tc::cfg_f64(&cfg, "refresh", 4.0); + let args: Vec = std::env::args().skip(1).collect(); + if args.len() >= 2 && (args[0] == "-n" || args[0] == "--refresh") { + refresh = args[1].parse::().unwrap_or(4.0).max(1.0); + } + + let absent = tc::missing(&["herdr"]); + if !absent.is_empty() { + tc::cannot_start( + "herdr panes", + &absent, + &[ + "This reads a running Herdr session through its own CLI: the", + "workspaces, the panes in them, and which agent is in which.", + "There is no other source for any of it.", + "", + "If Herdr is installed but not on PATH, this widget will find", + "it as soon as the shell can.", + ], + "see https://herdr.dev", + ); + return; + } + + let p = palette(); + let state = Arc::new(Mutex::new(State::default())); + let wake = Arc::new((Mutex::new(false), Condvar::new())); + let poller = Arc::clone(&state); + let poller_wake = Arc::clone(&wake); + std::thread::spawn(move || { + let hz = clock_ticks(); + let mut seen = Seen { + first_poll: true, + ..Default::default() + }; + loop { + // A poller that dies takes its explanation with it, and an empty + // board looks exactly like a Herdr with nothing running in it. + let step = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| { + poll(&poller, &mut seen, hz) + })); + if step.is_err() { + if let Ok(mut guard) = poller.lock() { + guard.err = "poller stopped - see the pane it was started from".into(); + } + return; + } + let (lock, cond) = &*poller_wake; + let mut asked = match lock.lock() { + Ok(g) => g, + Err(_) => return, + }; + if !*asked { + asked = match cond.wait_timeout(asked, Duration::from_secs_f64(refresh)) { + Ok((g, _)) => g, + Err(_) => return, + }; + } + *asked = false; + } + }); + + tc::setup(); + let mut keyboard = tc::Keyboard::new(); + let (mut show_labels, mut show_idle) = (true, true); + let (mut selected, mut tick) = (0usize, 0usize); + let mut note: Option<(String, bool, f64)> = None; + let mut rows_now: Vec = Vec::new(); + + loop { + tick += 1; + for key in keyboard.poll() { + match key.as_str() { + "q" | "Q" => { + keyboard.restore(); + tc::restore_screen(); + return; + } + "r" | "R" => { + let (lock, cond) = &*wake; + if let Ok(mut asked) = lock.lock() { + *asked = true; + cond.notify_all(); + } + } + "w" | "W" => show_labels = !show_labels, + "o" | "O" => { + show_idle = !show_idle; + selected = 0; + } + "up" => selected = selected.saturating_sub(1), + "down" => selected += 1, + "home" => selected = 0, + "end" => selected = rows_now.len().saturating_sub(1), + "enter" | "f" | "F" => { + if let Some(row) = rows_now.get(selected.min(rows_now.len().saturating_sub(1))) + { + let (ok, what, pane) = match row { + Row::Agent(a) => ( + herdr_action(&["agent", "focus", &a.pane_id]), + a.name.clone(), + a.pane_id.clone(), + ), + // A pane has no focus-by-id, but a tab tiles its + // panes, so focusing the tab brings it into view. + Row::Process(n) => ( + herdr_action(&["tab", "focus", &n.tab_id]), + n.command.clone(), + n.pane_id.clone(), + ), + }; + note = Some(( + if ok { + format!("→ focused {} in {}", what, pane) + } else { + format!("! could not focus {}", pane) + }, + ok, + now() + 3.0, + )); + } + } + _ => {} + } + } + + let (w, h) = tc::size(); + let (agents, panels, labels, err) = match state.lock() { + Ok(g) => ( + g.agents.clone(), + g.panels.clone(), + g.labels.clone(), + g.err.clone(), + ), + Err(_) => return, + }; + let running: Vec<&Panel> = panels.iter().filter(|n| !n.idle).collect(); + let resting: Vec<&Panel> = panels.iter().filter(|n| n.idle).collect(); + rows_now = agents + .iter() + .cloned() + .map(Row::Agent) + .chain( + panels + .iter() + .filter(|n| show_idle || !n.idle) + .cloned() + .map(Row::Process), + ) + .collect(); + if !rows_now.is_empty() && selected >= rows_now.len() { + selected = rows_now.len() - 1; + } + if note.as_ref().is_some_and(|(_, _, until)| now() >= *until) { + note = None; + } + + let mut counts: HashMap<&str, usize> = HashMap::new(); + for a in &agents { + *counts.entry(a.state.as_str()).or_insert(0) += 1; + } + let places: std::collections::HashSet<&str> = + agents.iter().map(|a| a.workspace_id.as_str()).collect(); + + let mut rows = vec![tc::title("herdr panes", w, &p.accent)]; + let mut summary = vec![ + ( + p.dim.as_str(), + format!(" {} agent{}", agents.len(), plural(agents.len())), + ), + ( + p.dim.as_str(), + format!(" · {} workspace{}", places.len(), plural(places.len())), + ), + ]; + for state_name in ["blocked", "done", "working", "idle"] { + if let Some(n) = counts.get(state_name) { + summary.push((colour_of(state_name, &p), format!(" {} {}", n, state_name))); + } + } + rows.push(tc::seg(&summary, w - 1)); + if !err.is_empty() { + rows.push(tc::seg(&[(p.blocked.as_str(), format!(" ! {}", err))], w - 1)); + } + + let wants = counts.get("blocked").copied().unwrap_or(0) + + counts.get("done").copied().unwrap_or(0); + rows.push(if wants > 0 { + tc::seg( + &[( + if counts.contains_key("blocked") { + p.blocked.as_str() + } else { + p.done.as_str() + }, + format!(" ▸ {} agent{} waiting for you", wants, plural(wants)), + )], + w - 1, + ) + } else { + tc::seg(&[(p.dim.as_str(), " nothing waiting on you".into())], w - 1) + }); + rows.push(String::new()); + + let wide = w >= 66; + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── AGENTS ── ".into()), + (p.dim.as_str(), format!("{}", agents.len())), + ], + w - 1, + )); + let mut head = format!(" {:<8} {:<8} {:<6} {:<5}", "AGENT", "STATE", "FOR", "CPU"); + if wide { + head += &format!(" {:<5} {:<18}", "MEM", "WORKSPACE"); + } + rows.push(tc::seg(&[(p.dim.as_str(), tc::pad(&head, w - 1))], w - 1)); + + for (i, a) in agents.iter().enumerate() { + if rows.len() >= h.saturating_sub(6) { + break; + } + let here = i == selected; + let colour = colour_of(&a.state, &p); + // Blocked and done keep a tint of their own even unselected: the + // whole point is that they are visible without being looked for. + let loud = a.state == "blocked" || a.state == "done"; + let tint = if here { + tc::bg(38, 56, 76) + } else if a.state == "blocked" { + tc::bg(46, 26, 30) + } else if a.state == "done" { + tc::bg(22, 46, 34) + } else { + String::new() + }; + let c = |colour: &str| format!("{}{}", tint, colour); + let name: String = a.name.chars().take(6).collect(); + let state_cell = if loud { + a.state.to_uppercase() + } else { + a.state.clone() + }; + let heat = match a.cpu { + Some(v) if v > 0.0 => tc::heat((v / 100.0).min(1.0)), + _ => p.dim.clone(), + }; + let mut line = vec![ + ( + c(colour), + format!( + "{}{} {:<6}", + if here { "▸" } else { " " }, + mark_of(&a.state, tick), + name + ), + ), + (c(colour), format!(" {:<8}", state_cell)), + ( + c(&p.dim), + format!(" {:<6}", format!("{}{}", if a.exact { "" } else { "≥" }, ago(a.since))), + ), + (c(&heat), percent(a.cpu)), + ]; + if wide { + let place = if show_labels { + let label = labels.get(&a.workspace_id).cloned().unwrap_or_default(); + if label.is_empty() { a.workspace_id.clone() } else { label } + } else { + a.pane_id.clone() + }; + line.push((c(&p.dim), format!(" {}", mem(a.rss)))); + line.push((c(&p.accent), format!(" {}", tc::pad(&place, 18)))); + } + if loud || here { + line.push((tint.clone(), " ".repeat(w))); + } + let refs: Vec<(&str, String)> = + line.iter().map(|(c, t)| (c.as_str(), t.clone())).collect(); + rows.push(tc::seg(&refs, w - 1)); + if rows.len() < h.saturating_sub(1) { + let body = if loud || here { &p.txt } else { &p.dim }; + rows.push(tc::seg( + &[ + (&c(&p.dim), format!(" {} ", homely(&a.cwd))), + (&c(body), a.title.trim().to_string()), + ( + &tint, + if loud || here { " ".repeat(w) } else { String::new() }, + ), + ], + w - 1, + )); + } + } + if agents.is_empty() && err.is_empty() { + rows.push(tc::seg(&[(p.dim.as_str(), " no agents running".into())], w - 1)); + } + + rows.push(String::new()); + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── PROCESSES ── ".into()), + ( + p.dim.as_str(), + format!( + "{} pane{} running something", + running.len(), + plural(running.len()) + ), + ), + ], + w - 1, + )); + if wide { + rows.push(tc::seg( + &[( + p.dim.as_str(), + tc::pad( + &format!(" {:<20} {:<5} {:<5} {:<18}", "COMMAND", "CPU", "MEM", "WORKSPACE"), + w - 1, + ), + )], + w - 1, + )); + } + for (j, n) in running.iter().enumerate() { + if rows.len() >= h.saturating_sub(2) { + break; + } + let here = agents.len() + j == selected; + let tint = if here { tc::bg(38, 56, 76) } else { String::new() }; + let c = |colour: &str| format!("{}{}", tint, colour); + let heat = match n.cpu { + Some(v) if v > 0.0 => tc::heat((v / 100.0).min(1.0)), + _ => p.dim.clone(), + }; + let mut line = vec![ + (c(&p.proc), format!("{}▪ ", if here { "▸" } else { " " })), + ( + c(&p.txt), + tc::pad(if n.command.is_empty() { "?" } else { &n.command }, 20), + ), + (c(&heat), percent(n.cpu)), + ]; + if wide { + let place = if show_labels { + let label = labels.get(&n.workspace_id).cloned().unwrap_or_default(); + if label.is_empty() { n.workspace_id.clone() } else { label } + } else { + n.pane_id.clone() + }; + line.push((c(&p.dim), format!(" {}", mem(n.rss)))); + line.push((c(&p.accent), format!(" {}", tc::pad(&place, 18)))); + } + if here { + line.push((tint.clone(), " ".repeat(w))); + } + let refs: Vec<(&str, String)> = + line.iter().map(|(c, t)| (c.as_str(), t.clone())).collect(); + rows.push(tc::seg(&refs, w - 1)); + } + if running.is_empty() { + rows.push(tc::seg( + &[(p.dim.as_str(), " every other pane is idle at a prompt".into())], + w - 1, + )); + } + + if show_idle && !resting.is_empty() { + rows.push(String::new()); + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── IDLE ── ".into()), + ( + p.dim.as_str(), + format!("{} pane{} at a prompt", resting.len(), plural(resting.len())), + ), + ], + w - 1, + )); + for (j, n) in resting.iter().enumerate() { + if rows.len() >= h.saturating_sub(2) { + break; + } + let here = agents.len() + running.len() + j == selected; + let tint = if here { tc::bg(38, 56, 76) } else { String::new() }; + let c = |colour: &str| format!("{}{}", tint, colour); + let place = if show_labels { + let label = labels.get(&n.workspace_id).cloned().unwrap_or_default(); + if label.is_empty() { n.workspace_id.clone() } else { label } + } else { + n.pane_id.clone() + }; + let mut line = vec![ + (c(&p.idle_c), format!("{}▫ ", if here { "▸" } else { " " })), + (c(&p.idle_c), tc::pad(&tail_path(&homely(&n.cwd), 26), 27)), + (c(&p.accent), tc::pad(&place, 18)), + ]; + if here { + line.push((tint.clone(), " ".repeat(w))); + } + let refs: Vec<(&str, String)> = + line.iter().map(|(c, t)| (c.as_str(), t.clone())).collect(); + rows.push(tc::seg(&refs, w - 1)); + } + } + + // The footer must always be the last visible line, so the body is + // clamped to the space left for it rather than each section + // budgeting for itself - that drifted, and the footer ended up + // written past the bottom row. + let hints: Vec> = vec![ + vec![(p.accent.as_str(), "↑↓".into()), (p.dim.as_str(), " select".into())], + vec![ + (p.accent.as_str(), "↵".into()), + (p.dim.as_str(), " switch to this pane".into()), + ], + vec![(p.dim.as_str(), "[o]idle".into())], + vec![(p.dim.as_str(), "[w]labels".into())], + vec![(p.dim.as_str(), "[r]efresh".into())], + vec![(p.dim.as_str(), "[q]uit".into())], + ]; + let footer: Vec = tc::pack_hints(&hints, w - 2, " ") + .into_iter() + .map(|l| format!(" {}", l)) + .collect(); + let reserve = footer.len() + 1; // +1 for the note line + rows.truncate(h.saturating_sub(reserve)); + while rows.len() < h.saturating_sub(reserve) { + rows.push(String::new()); + } + rows.push(match note.as_ref() { + Some((text, ok, _)) => tc::seg( + &[( + if *ok { p.done.as_str() } else { p.blocked.as_str() }, + format!(" {}", text), + )], + w - 1, + ), + None => String::new(), + }); + rows.extend(footer); + tc::draw(&rows, w, h); + std::thread::sleep(Duration::from_millis(250)); + } +} + +fn plural(n: usize) -> &'static str { + if n == 1 { + "" + } else { + "s" + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn a_runner_gives_way_to_the_script_it_was_handed() { + // "python3" and "node" say nothing about what a pane is doing. + let argv = |s: &str| -> Vec { + s.split_whitespace().map(String::from).collect() + }; + assert_eq!( + command_label(&argv("/usr/bin/python3 /home/w/toys/netwatch.py"), ""), + "netwatch.py" + ); + // Flags are skipped to reach the script behind them. + assert_eq!( + command_label(&argv("node --inspect /srv/app/server.js"), ""), + "server.js" + ); + // Anything that is not a runner is its own answer. + assert_eq!(command_label(&argv("/usr/bin/htop"), ""), "htop"); + // A runner with nothing after it is still the runner. + assert_eq!(command_label(&argv("bash"), ""), "bash"); + // No argv at all falls back to the name the kernel reports. + assert_eq!(command_label(&[], "cargo"), "cargo"); + assert_eq!(command_label(&[], ""), "?"); + } + + #[test] + fn a_cut_path_says_that_it_was_cut() { + assert_eq!(tail_path("/home/w/projects/toys", 40), "/home/w/projects/toys"); + // The end is kept, because that is the part that names the thing. + assert_eq!(tail_path("/home/w/projects/toys", 10), "…ects/toys"); + assert_eq!(tail_path("/home/w/projects/toys", 10).chars().count(), 10); + } + + #[test] + fn a_duration_carries_minutes_between_an_hour_and_a_day() { + assert_eq!(ago(45.0), "45s"); + assert_eq!(ago(600.0), "10m"); + // Three hours and one minute is not the same as three hours, and an + // agent blocked that long is the reason this widget exists. + assert_eq!(ago(3660.0), "1h01m"); + assert_eq!(ago(14_280.0), "3h58m"); + assert_eq!(ago(90_000.0), "1d"); + assert_eq!(ago(-5.0), "0s"); + } + + #[test] + fn memory_keeps_its_column_width() { + // Five, matching the header - the Python gives six to the absent + // case, which is what this caught. + for value in [Some(0), Some(4096), Some(1_600_000_000), None] { + assert_eq!(mem(value).chars().count(), 5, "{:?}", value); + } + assert_eq!(mem(Some(512)), " 512B"); + assert_eq!(mem(Some(1024 * 1024 * 3)), " 3M"); + assert_eq!(mem(None), " --"); + } + + #[test] + fn the_states_that_want_a_human_sort_first() { + assert!(rank_of("blocked") < rank_of("done")); + assert!(rank_of("done") < rank_of("working")); + assert!(rank_of("working") < rank_of("idle")); + assert!(rank_of("idle") < rank_of("unknown")); + // A state Herdr grows later sorts last rather than crashing. + assert!(rank_of("reticulating") > rank_of("unknown")); + } + + #[test] + fn a_proc_stat_line_gives_up_its_cpu_and_memory() { + // The command sits in brackets and can contain spaces and brackets + // of its own, which is why the fields are counted from the last one. + let line = format!( + "42 (my (odd) proc) S 1 42 42 0 -1 4194304 100 0 0 0 {} {} 0 0 20 0 8 0 900 0 {} 0", + 310, 90, 4096 + ); + let rest = line.rsplit_once(')').unwrap().1; + let fields: Vec<&str> = rest.split_whitespace().collect(); + assert_eq!(fields[11], "310"); + assert_eq!(fields[12], "90"); + assert_eq!(fields[21], "4096"); + } +} diff --git a/rust/widgets/src/bin/herdr-panes_help.txt b/rust/widgets/src/bin/herdr-panes_help.txt new file mode 100644 index 0000000..7017ea5 --- /dev/null +++ b/rust/widgets/src/bin/herdr-panes_help.txt @@ -0,0 +1,39 @@ +Everything running in Herdr, across every workspace. + +Two sections. AGENTS lists recognised coding agents with the lifecycle state +Herdr reports, ordered so the ones wanting a human come first. PROCESSES lists +every other pane that is actually running something — dev servers, monitors, +builds — with what it is running and what it costs. IDLE lists the panes +sitting at a shell prompt, by directory, so they can still be jumped to; +toggle that section with o. + +Enter jumps to whatever is selected: the agent's pane, or the tab holding that +process. + +A Herdr client, not a general agent monitor: the inventory and the lifecycle +states come from `herdr agent list`, the workspace labels from +`herdr workspace list`, and the pid behind each pane from +`herdr pane process-info`. Any agent kind Herdr recognises appears here with +no change to this file. + +On a terminal server hosting many workspaces, agents finish or get stuck in +places you are not currently looking. This lists every agent with the state +Herdr reports, ordered so the ones wanting your attention are at the top: + + blocked waiting on an approval or a question, right now + done finished background work you have not looked at yet + working busy + idle ready for input + unknown an agent is present but Herdr cannot classify it + +Each row also carries the workspace, how long the agent has held its current +state, and the real CPU and memory of its process. A duration is prefixed with +≥ when the state was already in place before this tool started, since then it +is only a lower bound. + + herdr-panes [-n SECONDS] + +Keys: up/down select, Enter (or f) focuses that agent's pane so you jump +straight to whatever needs you, w toggles workspace labels vs pane ids, +r refreshes now, q quits. +Requires HERDR_ENV; it shells out to the `herdr` CLI. From 46f40d41aac8dd50f25a244abd34974999d9aea2 Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sun, 23 Aug 2026 03:26:49 +0800 Subject: [PATCH 024/147] deployments: the first widget here that holds a secret Eighth widget, and the one that decides how the remaining four reach an HTTP API. Through curl, for the same reason every other source in this collection is a subprocess: these already read ss, ping, tailscale and herdr that way, and a TLS stack would be forty dependencies and a megabyte to do what curl does on every machine these run on. The headers go in on curl's standard input, never in its arguments. /proc//cmdline is world-readable, so a token on a command line is a token handed to every user on the box for as long as the request lasts - which would be a strange thing for the widget whose whole design keeps that token out of the source tree. Verified by watching every process that appeared during a poll: three curl invocations caught mid-request, the token in none of their argv. The widget itself is the Python's: teams discovered from the token so deployments are not just personal, the 48-hour activity sparkline coloured by the worst outcome in each bucket, build-time median and p95, and the detail overlay fetched on demand rather than for two hundred deployments nobody asked about. A failed round keeps the last good list and shows the error beside it, because stale rows with a message say more than an empty board. config_token_warning() moves into core alongside the loader, where common.py keeps it: any widget taking a token writes it into the same file, so the check belongs beside the thing that reads it rather than in whichever widget needed it first. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/core/src/lib.rs | 99 ++ rust/widgets/Cargo.toml | 4 + rust/widgets/src/bin/deployments.rs | 1179 +++++++++++++++++++++ rust/widgets/src/bin/deployments_help.txt | 27 + 4 files changed, 1309 insertions(+) create mode 100644 rust/widgets/src/bin/deployments.rs create mode 100644 rust/widgets/src/bin/deployments_help.txt diff --git a/rust/core/src/lib.rs b/rust/core/src/lib.rs index d231b4e..c5b7c30 100644 --- a/rust/core/src/lib.rs +++ b/rust/core/src/lib.rs @@ -392,6 +392,92 @@ pub fn cannot_start(name: &str, needed: &[String], why: &[&str], install: &str) } } +/// Warn when a config file holding a token is readable by others. +/// +/// Any widget that takes a token writes it into this file, so the check +/// belongs beside the loader rather than in whichever widget happened to +/// need it first. +pub fn config_token_warning() -> Option { + use std::os::unix::fs::PermissionsExt; + for path in config_paths() { + if !path.exists() { + continue; + } + let mode = std::fs::metadata(&path).ok()?.permissions().mode() & 0o077; + return if mode != 0 { + Some("config.json is readable by others; chmod 600 it".into()) + } else { + None + }; + } + None +} + +/// One HTTPS GET, returning the body. +/// +/// Through curl rather than an HTTP crate, for the same reason every other +/// source here is a subprocess: this collection reads `ss`, `ping`, +/// `tailscale` and `herdr` the same way, and a TLS stack would be forty +/// dependencies and a megabyte to do what curl already does on every +/// machine these run on. +/// +/// The headers go in on **stdin**, never in the arguments. `/proc// +/// cmdline` is world-readable, so a token on the command line is a token +/// handed to every user on the box for as long as the request lasts - and +/// these widgets exist partly to keep one out of the source tree. +pub fn get(url: &str, headers: &[(&str, &str)], seconds: u64) -> Result { + use std::io::Write; + let mut config = format!( + "--silent\n--show-error\n--fail\n--location\n--max-time {}\n--url {}\n", + seconds, + quoted(url) + ); + for (name, value) in headers { + config.push_str(&format!("--header {}\n", quoted(&format!("{}: {}", name, value)))); + } + let mut child = std::process::Command::new("curl") + .arg("--config") + .arg("-") + .stdin(std::process::Stdio::piped()) + .stdout(std::process::Stdio::piped()) + .stderr(std::process::Stdio::piped()) + .spawn() + .map_err(|e| e.to_string())?; + child + .stdin + .take() + .ok_or("curl would not take its configuration")? + .write_all(config.as_bytes()) + .map_err(|e| e.to_string())?; + let out = child.wait_with_output().map_err(|e| e.to_string())?; + if out.status.success() { + return Ok(String::from_utf8_lossy(&out.stdout).to_string()); + } + // curl's own message, which names the status code for --fail. Whatever + // it says, it must not be allowed to carry the header back out. + let said = String::from_utf8_lossy(&out.stderr).trim().to_string(); + Err(if said.is_empty() { + format!("curl exited {}", out.status.code().unwrap_or(-1)) + } else { + said + }) +} + +/// A value for curl's config format, which takes double quotes and +/// backslash escapes and would otherwise stop at the first space. +fn quoted(value: &str) -> String { + let mut out = String::with_capacity(value.len() + 2); + out.push('"'); + for c in value.chars() { + if c == '"' || c == '\\' { + out.push('\\'); + } + out.push(c); + } + out.push('"'); + out +} + /// Which of these required commands are not on PATH. pub fn missing(programs: &[&str]) -> Vec { let path = std::env::var("PATH").unwrap_or_default(); @@ -545,6 +631,19 @@ pub fn maybe_help(doc: &str) { mod tests { use super::*; + #[test] + fn a_curl_config_value_survives_spaces_and_quotes() { + assert_eq!(quoted("simple"), "\"simple\""); + // A header is "Name: value" and the space is the whole reason this + // exists - unquoted, curl would read the rest as another option. + assert_eq!( + quoted("Authorization: Bearer abc"), + "\"Authorization: Bearer abc\"" + ); + assert_eq!(quoted("a\"b"), "\"a\\\"b\""); + assert_eq!(quoted("a\\b"), "\"a\\\\b\""); + } + #[test] fn heat_runs_green_to_red_through_amber() { // The ends and the middle, since every widget reads the same scale diff --git a/rust/widgets/Cargo.toml b/rust/widgets/Cargo.toml index 8ac8b98..81bd587 100644 --- a/rust/widgets/Cargo.toml +++ b/rust/widgets/Cargo.toml @@ -40,3 +40,7 @@ path = "src/bin/clocks.rs" [[bin]] name = "herdr-panes" path = "src/bin/herdr-panes.rs" + +[[bin]] +name = "deployments" +path = "src/bin/deployments.rs" diff --git a/rust/widgets/src/bin/deployments.rs b/rust/widgets/src/bin/deployments.rs new file mode 100644 index 0000000..43b5cab --- /dev/null +++ b/rust/widgets/src/bin/deployments.rs @@ -0,0 +1,1179 @@ +// terminal-toys - small dependency-free terminal widgets +// Copyright (C) 2026 William Li +// +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU Affero General Public License as published +// by the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU Affero General Public License for more details. +// +// You should have received a copy of the GNU Affero General Public License +// along with this program. If not, see . + +//! Vercel deployments, across every team the token can see. +//! +//! A port of deployments.py. The first widget here to hold a secret: the +//! token comes from the git-ignored config or the environment, never from +//! the source tree, and never reaches a command line. + +use std::collections::{HashMap, HashSet}; +use std::sync::{Arc, Condvar, Mutex}; +use std::time::{Duration, SystemTime, UNIX_EPOCH}; + +use chrono::{Local, TimeZone}; +use toys_core as tc; + +const API: &str = "https://api.vercel.com"; +const FILTERS: &[&str] = &["all", "failed", "production"]; +const SPARK: &[char] = &['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█']; +const SPINNER: &[char] = &['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']; +/// The states that mean something is happening right now. +const LIVE: &[&str] = &["BUILDING", "QUEUED", "INITIALIZING"]; + +fn now() -> f64 { + SystemTime::now() + .duration_since(UNIX_EPOCH) + .map(|d| d.as_secs_f64()) + .unwrap_or(0.0) +} + +/// A Vercel token, and where it came from. +/// +/// Deliberately not the Vercel CLI's session: that expires within hours and +/// only the CLI can refresh it, so a panel reading it goes dark overnight. +/// Create one at Account Settings -> Tokens instead. +fn token(cfg: &serde_json::Value) -> (String, &'static str) { + let from_config = tc::cfg_str(cfg, "token", ""); + if !from_config.is_empty() { + return (from_config, "config"); + } + let name = tc::cfg_str(cfg, "token_env", "VERCEL_TOKEN"); + let name = if name.is_empty() { "VERCEL_TOKEN".into() } else { name }; + match std::env::var(&name) { + Ok(value) if !value.is_empty() => (value, "env"), + _ => (String::new(), "missing"), + } +} + +fn api(path: &str, tok: &str) -> Result { + let url = format!("{}{}", API, path); + let body = tc::get(&url, &[("Authorization", &format!("Bearer {}", tok))], 25)?; + serde_json::from_str(&body).map_err(|e| e.to_string()) +} + +/// Every team the token can see, so deployments are not just personal. +/// +/// An empty list on failure is deliberate: the personal scope still works, +/// and a widget that refused to start because one endpoint was down would +/// be worse than one showing fewer rows. +fn discover_teams(tok: &str) -> Vec { + let Ok(res) = api("/v2/teams", tok) else { + return Vec::new(); + }; + res["teams"] + .as_array() + .into_iter() + .flatten() + .filter_map(|t| t["id"].as_str().map(String::from)) + .collect() +} + +/// Per-deployment detail: why it failed, timings, regions, aliases. +/// +/// The list endpoint carries none of this, so it is fetched when the info +/// view opens rather than for two hundred deployments nobody asked about. +fn fetch_detail(uid: &str, team: &str, tok: &str) -> serde_json::Value { + let mut path = format!("/v13/deployments/{}", uid); + if !team.is_empty() { + path += &format!("?teamId={}", team); + } + match api(&path, tok) { + Ok(value) => value, + Err(e) => serde_json::json!({ "_error": e }), + } +} + +#[derive(Default)] +struct State { + deployments: Vec, + err: String, + fetched: f64, +} + +fn text(value: &serde_json::Value, key: &str) -> String { + value[key].as_str().unwrap_or("").to_string() +} + +fn ms_at(value: &serde_json::Value, key: &str) -> Option { + value[key].as_f64() +} + +/// How long ago, on this widget's own scale. +fn age(ms: Option) -> String { + let Some(ms) = ms else { + return "--".to_string(); + }; + let s = (now() - ms / 1000.0).max(0.0); + if s < 90.0 { + format!("{}s", s as i64) + } else if s < 5400.0 { + format!("{}m", (s / 60.0) as i64) + } else if s < 172_800.0 { + format!("{}h", (s / 3600.0) as i64) + } else { + format!("{}d", (s / 86400.0) as i64) + } +} + +fn dur(seconds: Option) -> String { + let Some(s) = seconds else { + return " -- ".to_string(); + }; + if s < 60.0 { + format!("{:>5.0}s", s) + } else { + format!("{}m{:02}s", (s / 60.0) as i64, (s as i64) % 60) + } +} + +/// How long a build took, or has been taking. +fn build_seconds(d: &serde_json::Value) -> Option { + let building = ms_at(d, "buildingAt")?; + if let Some(ready) = ms_at(d, "ready") { + return Some((ready - building) / 1000.0); + } + if LIVE.contains(&text(d, "state").as_str()) { + return Some(now() - building / 1000.0); + } + None +} + +fn wrap(t: &str, width: usize) -> Vec { + let chars: Vec = t.chars().collect(); + if chars.is_empty() || width == 0 { + return vec![String::new()]; + } + chars + .chunks(width) + .map(|c| c.iter().collect()) + .collect() +} + +fn when(ms: Option) -> String { + let Some(ms) = ms else { + return String::new(); + }; + match Local.timestamp_opt((ms / 1000.0) as i64, 0).single() { + Some(at) => at.format("%Y-%m-%d %H:%M").to_string(), + None => String::new(), + } +} + +/// Everything worth copying out of a deployment. +fn copy_items(dep: &serde_json::Value, detail: Option<&serde_json::Value>) -> Vec<(String, String)> { + let meta = &dep["meta"]; + let mut items = Vec::new(); + let mut push = |label: &str, value: String| { + if !value.is_empty() { + items.push((label.to_string(), value)); + } + }; + push("Deployment dashboard", text(dep, "inspectorUrl")); + let branch_alias = text(meta, "branchAlias"); + if !branch_alias.is_empty() { + push("Branch preview", format!("https://{}", branch_alias)); + } + let url = text(dep, "url"); + if !url.is_empty() { + push("Commit preview", format!("https://{}", url)); + } + let (pr, org, repo) = ( + text(meta, "githubPrId"), + text(meta, "githubOrg"), + text(meta, "githubRepo"), + ); + if !pr.is_empty() && !org.is_empty() && !repo.is_empty() { + push( + "Pull request", + format!("https://github.com/{}/{}/pull/{}", org, repo, pr), + ); + } + push("Commit SHA", text(meta, "githubCommitSha")); + push("Branch name", text(meta, "githubCommitRef")); + if let Some(d) = detail { + push("Error message", text(d, "errorMessage")); + } + items +} + +/// Progressive disclosure: spend extra width on more content, not padding. +/// +/// Under 66 columns only the essentials fit. Above that the commit SHA and +/// branch appear. From 110 the metadata and commit subject share one line, +/// so twice as many deployments are visible in the same height. +struct Columns { + detail: bool, + single: bool, + project: usize, + branch: usize, +} + +fn columns(w: usize) -> Columns { + Columns { + detail: w >= 66, + single: w >= 110, + project: if w < 80 { + 12 + } else if w < 110 { + 16 + } else { + 20 + }, + branch: (w / 5).clamp(12, 34), + } +} + +/// Deployments per time bucket, coloured by the worst outcome in it. +fn activity(deps: &[serde_json::Value], w: usize, hours: f64, p: &Palette) -> (String, usize) { + let cols = w.saturating_sub(2).max(10); + let at = now() * 1000.0; + let span = hours * 3_600_000.0; + let mut buckets: Vec> = vec![Vec::new(); cols]; + for d in deps { + let off = at - ms_at(d, "created").unwrap_or(at); + if (0.0..span).contains(&off) { + let slot = cols - 1 - (off / span * cols as f64) as usize; + buckets[slot.min(cols - 1)].push(d); + } + } + let peak = buckets.iter().map(|b| b.len()).max().unwrap_or(0); + if peak == 0 { + return ( + tc::seg( + &[( + p.dim.as_str(), + format!(" no deployments in the last {}h", hours as i64), + )], + w - 1, + ), + 0, + ); + } + let mut parts: Vec<(&str, String)> = vec![(p.dim.as_str(), " ".into())]; + for bucket in &buckets { + if bucket.is_empty() { + parts.push((p.grid.as_str(), "·".into())); + continue; + } + let states: HashSet = bucket.iter().map(|d| text(d, "state")).collect(); + let colour = if states.contains("ERROR") { + &p.error + } else if LIVE.iter().any(|s| states.contains(*s)) { + &p.build + } else { + &p.ready + }; + let level = ((bucket.len() as f64 / peak as f64) * 7.99) as usize; + parts.push((colour.as_str(), SPARK[level.min(7)].to_string())); + } + (tc::seg(&parts, w - 1), peak) +} + +struct Palette { + ready: String, + build: String, + error: String, + queue: String, + cancel: String, + dim: String, + grid: String, + msg: String, + url: String, + hint: String, + txt: String, + lbl: String, + prod: String, + sha: String, + branch: String, + accent: String, +} + +fn palette() -> Palette { + Palette { + ready: tc::rgb(80, 235, 150), + build: tc::rgb(255, 200, 90), + error: tc::rgb(255, 95, 105), + queue: tc::rgb(120, 160, 220), + cancel: tc::rgb(140, 145, 160), + dim: tc::rgb(127, 147, 172), + grid: tc::rgb(71, 91, 116), + msg: tc::rgb(158, 174, 196), + url: tc::rgb(130, 200, 255), + hint: tc::rgb(126, 148, 173), + txt: tc::rgb(225, 235, 245), + lbl: tc::rgb(130, 165, 200), + prod: tc::rgb(120, 180, 255), + sha: tc::rgb(190, 170, 255), + branch: tc::rgb(150, 210, 255), + accent: tc::rgb(150, 210, 255), + } +} + +fn state_colour<'a>(state: &str, p: &'a Palette) -> &'a str { + match state { + "READY" => &p.ready, + "BUILDING" | "INITIALIZING" => &p.build, + "ERROR" => &p.error, + "QUEUED" => &p.queue, + "CANCELED" => &p.cancel, + _ => &p.dim, + } +} + +/// Title case, which is all the Python's `.title()` is doing to a state. +fn titled(state: &str) -> String { + let mut chars = state.chars(); + match chars.next() { + Some(first) => first.to_uppercase().collect::() + &chars.as_str().to_lowercase(), + None => String::new(), + } +} + +/// One deployment in full: state, timings, why it failed, and what to copy. +fn info_overlay( + dep: &serde_json::Value, + detail: Option<&serde_json::Value>, + w: usize, + h: usize, + note: &str, + p: &Palette, +) -> Vec { + let meta = &dep["meta"]; + let empty = serde_json::Value::Null; + let d = detail.unwrap_or(&empty); + let mut rows = vec![tc::title("deployment", w, &p.prod)]; + + macro_rules! field { + ($label:expr, $value:expr, $colour:expr) => {{ + let value: String = $value; + if !value.is_empty() { + rows.push(tc::seg( + &[ + (p.dim.as_str(), format!(" {:<11}", $label)), + ($colour, value), + ], + w - 1, + )); + } + }}; + } + + let state = text(dep, "state"); + field!("project", text(dep, "name"), p.accent.as_str()); + let step = text(d, "errorStep"); + field!( + "state", + format!( + "{}{}", + titled(&state), + if step.is_empty() { + String::new() + } else { + format!(" ({})", step) + } + ), + state_colour(&state, p) + ); + let production = text(dep, "target") == "production"; + field!( + "target", + if production { "production" } else { "preview" }.to_string(), + if production { p.prod.as_str() } else { p.dim.as_str() } + ); + field!( + "created", + when(ms_at(dep, "created").or_else(|| ms_at(dep, "createdAt"))), + p.txt.as_str() + ); + if let Some(secs) = build_seconds(dep) { + let queued = match (ms_at(dep, "createdAt"), ms_at(dep, "buildingAt")) { + (Some(made), Some(built)) => (built - made) / 1000.0, + _ => 0.0, + }; + field!( + "build", + format!( + "{}{}", + dur(Some(secs)).trim(), + if queued > 0.5 { + format!(" queued {:.0}s", queued) + } else { + String::new() + } + ), + p.txt.as_str() + ); + } + let regions: Vec = d["regions"] + .as_array() + .into_iter() + .flatten() + .filter_map(|r| r.as_str().map(String::from)) + .collect(); + if !regions.is_empty() { + let plan = text(d, "plan"); + field!( + "regions", + format!( + "{}{}", + regions.join(", "), + if plan.is_empty() { + String::new() + } else { + format!(" plan {}", plan) + } + ), + p.txt.as_str() + ); + } + let aliases = d["alias"].as_array().map(|a| a.len()).unwrap_or(0); + if aliases > 0 { + field!("aliases", format!("{} assigned", aliases), p.dim.as_str()); + } + + let (message, code) = (text(d, "errorMessage"), text(d, "errorCode")); + if !message.is_empty() || !code.is_empty() { + rows.push(String::new()); + rows.push(tc::seg(&[(p.lbl.as_str(), " ── WHY IT FAILED ──".into())], w - 1)); + if !code.is_empty() { + rows.push(tc::seg(&[(p.error.as_str(), format!(" {}", code))], w - 1)); + } + for line in wrap(&message, w.saturating_sub(4).max(10)) { + rows.push(tc::seg(&[(p.msg.as_str(), format!(" {}", line))], w - 1)); + } + let link = text(d, "errorLink"); + if !link.is_empty() { + rows.push(tc::seg(&[(p.url.as_str(), format!(" {}", link))], w - 1)); + } + } else if !text(d, "_error").is_empty() { + rows.push(String::new()); + rows.push(tc::seg( + &[( + p.error.as_str(), + format!(" detail unavailable: {}", text(d, "_error")), + )], + w - 1, + )); + } else if d.is_null() { + rows.push(String::new()); + rows.push(tc::seg(&[(p.dim.as_str(), " loading detail…".into())], w - 1)); + } + + let sha = text(meta, "githubCommitSha"); + if !sha.is_empty() { + rows.push(String::new()); + rows.push(tc::seg(&[(p.lbl.as_str(), " ── COMMIT ──".into())], w - 1)); + rows.push(tc::seg( + &[ + (p.sha.as_str(), format!(" {}", &sha[..sha.len().min(7)])), + ( + p.branch.as_str(), + format!(" {}", text(meta, "githubCommitRef")), + ), + ], + w - 1, + )); + let subject = text(meta, "githubCommitMessage"); + let subject = subject.lines().next().unwrap_or(""); + for line in wrap(subject, w.saturating_sub(4).max(10)) { + rows.push(tc::seg(&[(p.msg.as_str(), format!(" {}", line))], w - 1)); + } + let who = match text(meta, "githubCommitAuthorName") { + name if !name.is_empty() => name, + _ => text(meta, "githubCommitAuthorLogin"), + }; + if !who.is_empty() { + rows.push(tc::seg(&[(p.dim.as_str(), format!(" by {}", who))], w - 1)); + } + } + + let pairs = copy_items(dep, detail); + if !pairs.is_empty() { + rows.push(String::new()); + rows.push(tc::seg(&[(p.lbl.as_str(), " ── COPY ──".into())], w - 1)); + for (i, (label, value)) in pairs.iter().enumerate() { + let room = w.saturating_sub(28); + let short = if value.chars().count() <= room { + value.clone() + } else { + format!( + "{}…", + value.chars().take(w.saturating_sub(31)).collect::() + ) + }; + rows.push(tc::seg( + &[ + (p.ready.as_str(), format!(" [{}] ", i + 1)), + (p.txt.as_str(), format!("{:<21} ", label)), + (p.url.as_str(), short), + ], + w - 1, + )); + } + } + + while rows.len() < h.saturating_sub(2) { + rows.push(String::new()); + } + rows.push(tc::seg( + &[( + p.hint.as_str(), + format!(" press 1-{} to copy · esc or i to close", pairs.len()), + )], + w - 1, + )); + rows.push(if note.is_empty() { + String::new() + } else { + tc::seg(&[(p.ready.as_str(), format!(" {}", note))], w - 1) + }); + rows +} + +fn main() { + tc::maybe_help(include_str!("deployments_help.txt")); + let cfg = tc::load_config("deployments"); + let mut refresh = tc::cfg_f64(&cfg, "refresh", 15.0); + let limit = tc::cfg_usize(&cfg, "limit", 100); + let mut teams = tc::cfg_strings(&cfg, "teams", &[]); + let configured: Vec = tc::cfg_strings(&cfg, "projects", &[]); + + let args: Vec = std::env::args().skip(1).collect(); + let mut named: Vec = Vec::new(); + let mut i = 0; + while i < args.len() { + match args[i].as_str() { + "-n" | "--refresh" if i + 1 < args.len() => { + refresh = args[i + 1].parse::().unwrap_or(15.0).max(5.0); + i += 2; + } + "-t" | "--team" if i + 1 < args.len() => { + teams.push(args[i + 1].clone()); + i += 2; + } + other if !other.starts_with('-') => { + named.push(other.to_string()); + i += 1; + } + _ => i += 1, + } + } + let projects: HashSet = if named.is_empty() { + configured.into_iter().collect() + } else { + named.into_iter().collect() + }; + + let absent = tc::missing(&["curl"]); + if !absent.is_empty() { + tc::cannot_start( + "vercel deployments", + &absent, + &[ + "Everything here comes from Vercel's HTTP API, and curl is how", + "this reaches it - the same way the other widgets reach ss,", + "ping and tailscale.", + "", + "The token is passed to curl on its standard input rather than", + "in its arguments, because /proc//cmdline is readable by", + "every user on the machine.", + ], + "apt install curl", + ); + return; + } + + let p = palette(); + let (tok, source) = token(&cfg); + let env_name = { + let name = tc::cfg_str(&cfg, "token_env", "VERCEL_TOKEN"); + if name.is_empty() { "VERCEL_TOKEN".to_string() } else { name } + }; + if !tok.is_empty() && teams.is_empty() { + teams = discover_teams(&tok); + } + + let state = Arc::new(Mutex::new(State::default())); + let wake = Arc::new((Mutex::new(false), Condvar::new())); + let poller = Arc::clone(&state); + let poller_wake = Arc::clone(&wake); + let poll_teams = teams.clone(); + let poll_projects = projects.clone(); + let poll_token = tok.clone(); + let poll_env = env_name.clone(); + std::thread::spawn(move || loop { + if poll_token.is_empty() { + if let Ok(mut guard) = poller.lock() { + guard.err = format!( + "no token: set deployments.token in config.json, or ${}", + poll_env + ); + } + } else { + let mut out: Vec = Vec::new(); + // A file others can read is worth saying out loud, since this + // is the widget that put a token in it. + let mut err = if source == "config" { + tc::config_token_warning().unwrap_or_default() + } else { + String::new() + }; + let scopes: Vec = if poll_teams.is_empty() { + vec![String::new()] + } else { + poll_teams.clone() + }; + for team in &scopes { + let mut path = format!("/v6/deployments?limit={}", limit); + if !team.is_empty() { + path += &format!("&teamId={}", team); + } + match api(&path, &poll_token) { + Ok(res) => { + for d in res["deployments"].as_array().into_iter().flatten() { + let mut d = d.clone(); + // Carried so the detail request knows its scope. + d["_team"] = serde_json::Value::String(team.clone()); + out.push(d); + } + } + Err(said) => { + err = if said.contains("401") || said.contains("403") { + format!("{} (token expired? make a new one)", said) + } else { + said + }; + } + } + } + if !poll_projects.is_empty() { + out.retain(|d| poll_projects.contains(&text(d, "name"))); + } + out.sort_by(|a, b| { + ms_at(b, "created") + .unwrap_or(0.0) + .total_cmp(&ms_at(a, "created").unwrap_or(0.0)) + }); + if let Ok(mut guard) = poller.lock() { + // A failed round keeps the last good list rather than + // blanking the board: stale rows with a message beside them + // say more than an empty screen does. + if !out.is_empty() || err.is_empty() { + guard.deployments = out; + guard.fetched = now(); + } + guard.err = err; + } + } + let (lock, cond) = &*poller_wake; + let mut asked = match lock.lock() { + Ok(g) => g, + Err(_) => return, + }; + if !*asked { + asked = match cond.wait_timeout(asked, Duration::from_secs_f64(refresh)) { + Ok((g, _)) => g, + Err(_) => return, + }; + } + *asked = false; + }); + + tc::setup(); + let mut keyboard = tc::Keyboard::new(); + let details: Arc>> = + Arc::new(Mutex::new(HashMap::new())); + let fetching: Arc>> = Arc::new(Mutex::new(HashSet::new())); + let mut filter = 0usize; + let mut only: Option = None; + let (mut tick, mut selected, mut scroll) = (0usize, 0usize, 0usize); + let mut overlay = false; + let mut note: (String, f64) = (String::new(), 0.0); + let mut visible = 1usize; + let mut shown: Vec = Vec::new(); + + loop { + tick += 1; + for key in keyboard.poll() { + if overlay { + match key.as_str() { + "esc" | "c" | "i" | "q" | "Q" | "enter" => overlay = false, + digit if digit.len() == 1 && digit.chars().all(|c| c.is_ascii_digit()) => { + if let Some(chosen) = shown.get(selected.min(shown.len().saturating_sub(1))) + { + let uid = text(chosen, "uid"); + let held = details.lock().ok().and_then(|g| g.get(&uid).cloned()); + let pairs = copy_items(chosen, held.as_ref()); + let at = digit.parse::().unwrap_or(0); + if at >= 1 && at <= pairs.len() { + let (label, value) = &pairs[at - 1]; + note = ( + if tc::clipboard(value) { + format!("✓ copied {}", label.to_lowercase()) + } else { + "! no clipboard; select the text with the mouse".into() + }, + now() + 3.0, + ); + } + } + } + _ => {} + } + continue; + } + match key.as_str() { + "q" | "Q" => { + keyboard.restore(); + tc::restore_screen(); + return; + } + "r" | "R" => { + let (lock, cond) = &*wake; + if let Ok(mut asked) = lock.lock() { + *asked = true; + cond.notify_all(); + } + } + "f" | "F" => { + filter = (filter + 1) % FILTERS.len(); + selected = 0; + } + "up" => selected = selected.saturating_sub(1), + "down" => selected += 1, + "pgup" => selected = selected.saturating_sub(visible), + "pgdn" => selected += visible, + "home" => selected = 0, + "end" => selected = shown.len().saturating_sub(1), + "c" | "i" | "I" | "enter" => { + if !shown.is_empty() { + overlay = true; + note = (String::new(), 0.0); + } + } + "p" | "P" => { + let names: Vec = { + let guard = match state.lock() { + Ok(g) => g, + Err(_) => return, + }; + let mut seen: Vec = guard + .deployments + .iter() + .map(|d| text(d, "name")) + .filter(|n| !n.is_empty()) + .collect(); + seen.sort(); + seen.dedup(); + seen + }; + // Cycles through every project and back to no filter, + // so the key always has somewhere to go. + only = match &only { + None => names.first().cloned(), + Some(current) => match names.iter().position(|n| n == current) { + Some(at) if at + 1 < names.len() => Some(names[at + 1].clone()), + Some(_) => None, + None => names.first().cloned(), + }, + }; + selected = 0; + } + _ => {} + } + } + + let (w, h) = tc::size(); + let (deps, err, fetched) = match state.lock() { + Ok(g) => (g.deployments.clone(), g.err.clone(), g.fetched), + Err(_) => return, + }; + if !note.0.is_empty() && now() > note.1 { + note = (String::new(), 0.0); + } + shown = deps.clone(); + if let Some(name) = &only { + shown.retain(|d| text(d, "name") == *name); + } + match FILTERS[filter] { + "failed" => shown.retain(|d| { + let s = text(d, "state"); + s == "ERROR" || s == "CANCELED" + }), + "production" => shown.retain(|d| text(d, "target") == "production"), + _ => {} + } + if !shown.is_empty() && selected >= shown.len() { + selected = shown.len() - 1; + } + + if overlay && !shown.is_empty() { + let chosen = shown[selected].clone(); + let uid = text(&chosen, "uid"); + let held = details.lock().ok().and_then(|g| g.get(&uid).cloned()); + if held.is_none() && !uid.is_empty() { + let start = fetching + .lock() + .map(|mut g| g.insert(uid.clone())) + .unwrap_or(false); + if start { + let (details, fetching) = (Arc::clone(&details), Arc::clone(&fetching)); + let (uid, team, tok) = (uid.clone(), text(&chosen, "_team"), tok.clone()); + std::thread::spawn(move || { + let got = fetch_detail(&uid, &team, &tok); + if let Ok(mut g) = details.lock() { + g.insert(uid.clone(), got); + } + if let Ok(mut g) = fetching.lock() { + g.remove(&uid); + } + }); + } + } + let rows = info_overlay(&chosen, held.as_ref(), w, h, ¬e.0, &p); + tc::draw(&rows, w, h); + std::thread::sleep(Duration::from_millis(100)); + continue; + } + + let mut states: HashMap = HashMap::new(); + for d in &deps { + *states.entry(text(d, "state")).or_insert(0) += 1; + } + let seen_projects: HashSet = deps.iter().map(|d| text(d, "name")).collect(); + let live: usize = LIVE + .iter() + .map(|s| states.get(*s).copied().unwrap_or(0)) + .sum(); + + let mut rows = vec![tc::title("vercel deployments", w, &p.prod)]; + let mut head = vec![ + (p.dim.as_str(), format!(" {} deploys", deps.len())), + (p.dim.as_str(), format!(" · {} proj", seen_projects.len())), + ( + p.ready.as_str(), + format!(" {} ready", states.get("READY").copied().unwrap_or(0)), + ), + ]; + if let Some(n) = states.get("ERROR") { + head.push((p.error.as_str(), format!(" {} error", n))); + } + if live > 0 { + head.push(( + p.build.as_str(), + format!(" {} {} building", SPINNER[tick % SPINNER.len()], live), + )); + } + head.push(( + p.dim.as_str(), + format!( + " {} ago", + if fetched > 0.0 { + age(Some(fetched * 1000.0)) + } else { + "--".into() + } + ), + )); + rows.push(tc::seg(&head, w - 1)); + if !err.is_empty() { + rows.push(tc::seg(&[(p.error.as_str(), format!(" ! {}", err))], w - 1)); + } + let mut bits: Vec = Vec::new(); + if FILTERS[filter] != "all" { + bits.push(FILTERS[filter].to_string()); + } + if let Some(name) = &only { + bits.push(name.clone()); + } + if !bits.is_empty() { + rows.push(tc::seg( + &[(p.build.as_str(), format!(" filter: {}", bits.join(" + ")))], + w - 1, + )); + } + rows.push(String::new()); + + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── ACTIVITY ── ".into()), + (p.dim.as_str(), "deploys/hour, last 48h".into()), + ], + w - 1, + )); + let (chart, peak) = activity(&deps, w, 48.0, &p); + rows.push(chart); + if peak > 0 { + rows.push(tc::seg( + &[ + (p.dim.as_str(), " 48h ago".into()), + (p.dim.as_str(), " ".repeat(w.saturating_sub(22).max(1))), + (p.dim.as_str(), format!("peak {}/h", peak)), + ], + w - 1, + )); + } + + let mut durs: Vec = deps.iter().filter_map(build_seconds).collect(); + durs.sort_by(f64::total_cmp); + if !durs.is_empty() { + let med = durs[durs.len() / 2]; + let p95 = durs[(durs.len() - 1).min((durs.len() as f64 * 0.95) as usize)]; + rows.push(String::new()); + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── BUILD TIME ── ".into()), + (p.dim.as_str(), "median ".into()), + (p.txt.as_str(), dur(Some(med))), + (p.dim.as_str(), " p95 ".into()), + (p.txt.as_str(), dur(Some(p95))), + (p.dim.as_str(), " max ".into()), + (p.txt.as_str(), dur(durs.last().copied())), + ], + w - 1, + )); + let recent: Vec = deps + .iter() + .take(w.saturating_sub(2).max(10)) + .filter_map(build_seconds) + .collect::>() + .into_iter() + .rev() + .collect(); + if !recent.is_empty() { + let hi = recent.iter().cloned().fold(0.0f64, f64::max).max(1e-9); + let spark: String = recent + .iter() + .map(|x| SPARK[(((x / hi) * 7.99) as usize).min(7)]) + .collect(); + rows.push(tc::seg(&[(p.ready.as_str(), format!(" {}", spark))], w - 1)); + } + } + rows.push(String::new()); + + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── RECENT ── ".into()), + ( + p.dim.as_str(), + if shown.is_empty() { + String::new() + } else { + format!("{} of {}", selected + 1, shown.len()) + }, + ), + ], + w - 1, + )); + let cols = columns(w); + let per_item = if cols.single { 1 } else { 2 }; + visible = (h.saturating_sub(rows.len() + 1) / per_item).max(1); + scroll = scroll.min(shown.len().saturating_sub(visible)); + if selected < scroll { + scroll = selected; + } else if selected >= scroll + visible { + scroll = selected - visible + 1; + } + for (i, d) in shown.iter().enumerate().skip(scroll).take(visible) { + if rows.len() >= h.saturating_sub(1) { + break; + } + let here = i == selected; + let tint = if here { tc::bg(28, 44, 62) } else { String::new() }; + let meta = &d["meta"]; + let state = text(d, "state"); + let colour = state_colour(&state, &p); + let mark = if LIVE.contains(&state.as_str()) { + SPINNER[tick % SPINNER.len()] + } else if state == "READY" { + '●' + } else if state == "ERROR" { + '✖' + } else { + '○' + }; + let subject = text(meta, "githubCommitMessage"); + let subject = subject.lines().next().unwrap_or("").to_string(); + let c = |colour: &str| format!("{}{}", tint, colour); + let mut line = vec![ + ( + c(colour), + format!( + "{}{} {:<9}", + if here { "▸" } else { " " }, + mark, + titled(&state) + ), + ), + (c(&p.txt), tc::pad(&text(d, "name"), cols.project)), + (c(&p.dim), dur(build_seconds(d))), + (c(&p.dim), format!(" {:>4}", age(ms_at(d, "created")))), + ]; + if text(d, "target") == "production" { + line.push((c(&p.prod), " PROD".into())); + } else if cols.detail { + line.push((c(&p.dim), " prev".into())); + } + if cols.detail { + let sha = text(meta, "githubCommitSha"); + line.push(( + c(&p.sha), + format!(" {}", &sha[..sha.len().min(7)]), + )); + line.push(( + c(&p.branch), + format!(" {}", tc::pad(&text(meta, "githubCommitRef"), cols.branch)), + )); + } + if cols.single { + line.push((c(if here { &p.txt } else { &p.msg }), format!(" {}", subject))); + } + if here { + line.push((tint.clone(), " ".repeat(w))); + } + let refs: Vec<(&str, String)> = + line.iter().map(|(c, t)| (c.as_str(), t.clone())).collect(); + rows.push(tc::seg(&refs, w - 1)); + if !cols.single && rows.len() < h.saturating_sub(1) { + rows.push(tc::seg( + &[ + (&c(if here { &p.txt } else { &p.msg }), format!(" {}", subject)), + (&tint, if here { " ".repeat(w) } else { String::new() }), + ], + w - 1, + )); + } + } + if shown.is_empty() { + rows.push(tc::seg( + &[(p.dim.as_str(), " (nothing matches the current filter)".into())], + w - 1, + )); + } + + let hints: Vec> = vec![ + vec![(p.accent.as_str(), "↑↓".into()), (p.dim.as_str(), " select".into())], + vec![ + (p.accent.as_str(), "↵/[i]".into()), + (p.dim.as_str(), " details".into()), + ], + vec![(p.dim.as_str(), "[f]ilter".into())], + vec![(p.dim.as_str(), "[p]roject".into())], + vec![(p.dim.as_str(), "[r]efresh".into())], + vec![(p.dim.as_str(), "[q]uit".into())], + ]; + let footer: Vec = tc::pack_hints(&hints, w - 2, " ") + .into_iter() + .map(|l| format!(" {}", l)) + .collect(); + rows.truncate(h.saturating_sub(footer.len())); + while rows.len() < h.saturating_sub(footer.len()) { + rows.push(String::new()); + } + rows.extend(footer); + tc::draw(&rows, w, h); + std::thread::sleep(Duration::from_millis(250)); + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn a_token_prefers_the_config_then_the_environment() { + let cfg: serde_json::Value = + serde_json::from_str(r#"{"token": "from-config", "token_env": "NOPE_TOKEN"}"#).unwrap(); + assert_eq!(token(&cfg), ("from-config".to_string(), "config")); + // An empty token in the config is not a token. + let bare: serde_json::Value = serde_json::from_str(r#"{"token": ""}"#).unwrap(); + assert_eq!(token(&bare).1, "missing"); + } + + #[test] + fn a_build_time_covers_the_one_still_running() { + // Finished: the gap between the two stamps. + let done: serde_json::Value = + serde_json::from_str(r#"{"state": "READY", "buildingAt": 1000, "ready": 46000}"#) + .unwrap(); + assert_eq!(build_seconds(&done), Some(45.0)); + // Never started: nothing to report rather than zero. + let queued: serde_json::Value = serde_json::from_str(r#"{"state": "QUEUED"}"#).unwrap(); + assert_eq!(build_seconds(&queued), None); + // Finished but with no start stamp is also nothing, not a huge number. + let odd: serde_json::Value = + serde_json::from_str(r#"{"state": "READY", "ready": 46000}"#).unwrap(); + assert_eq!(build_seconds(&odd), None); + } + + #[test] + fn a_duration_keeps_its_column_width() { + assert_eq!(dur(None), " -- "); + assert_eq!(dur(Some(45.0)), " 45s"); + assert_eq!(dur(Some(45.0)).chars().count(), 6); + assert_eq!(dur(None).chars().count(), 6); + // Past a minute it changes shape, as the Python does. + assert_eq!(dur(Some(125.0)), "2m05s"); + } + + #[test] + fn the_copy_sheet_lists_only_what_exists() { + let dep: serde_json::Value = serde_json::from_str( + r#"{"inspectorUrl": "https://vercel.com/x", "url": "abc.vercel.app", + "meta": {"githubCommitSha": "0123456789", "githubOrg": "o", + "githubRepo": "r", "githubPrId": "7"}}"#, + ) + .unwrap(); + let items = copy_items(&dep, None); + let labels: Vec<&str> = items.iter().map(|(l, _)| l.as_str()).collect(); + assert_eq!( + labels, + vec![ + "Deployment dashboard", + "Commit preview", + "Pull request", + "Commit SHA" + ] + ); + // A pull request needs all three parts, not just the number. + assert_eq!(items[2].1, "https://github.com/o/r/pull/7"); + // No branch alias, so no branch preview - an empty row would be a + // key that copies nothing. + assert!(!labels.contains(&"Branch preview")); + } + + #[test] + fn width_buys_content_rather_than_padding() { + assert!(!columns(60).detail); + assert!(columns(66).detail); + assert!(!columns(100).single); + assert!(columns(110).single); + // The project column grows in steps and the branch scales, but + // neither runs away with a very wide pane. + assert_eq!(columns(70).project, 12); + assert_eq!(columns(200).project, 20); + assert_eq!(columns(200).branch, 34); + assert_eq!(columns(40).branch, 12); + } + + #[test] + fn a_state_reads_as_a_word() { + assert_eq!(titled("READY"), "Ready"); + assert_eq!(titled("INITIALIZING"), "Initializing"); + assert_eq!(titled(""), ""); + } +} diff --git a/rust/widgets/src/bin/deployments_help.txt b/rust/widgets/src/bin/deployments_help.txt new file mode 100644 index 0000000..3478e78 --- /dev/null +++ b/rust/widgets/src/bin/deployments_help.txt @@ -0,0 +1,27 @@ +Vercel deployments, live. + +Shows deployment activity over time, build-duration trend, and the most recent +deployments with their state, project, branch, commit and build time. + + deployments [-n SECONDS] [-t TEAM_ID] [project ...] + +Polls every 15s by default (-n changes it, minimum 5s). One request per team +per poll, so the default is 4 polls/min — modest against the API's limits. + +Keys while running: up/down (also PgUp/PgDn, Home/End) move the selection, +Enter, i or c opens a full detail view for the selected deployment - state and +failure reason, timings, regions, commit, and everything worth copying on +number keys - r refreshes +now, f cycles the filter (all / failed / production), p cycles which project +is shown, q quits. + +Copying uses OSC 52, so the terminal you are sitting at performs it and the +text reaches your local clipboard even over SSH. If your terminal or +multiplexer blocks OSC 52, the sheet still shows each URL in full for mouse +selection. + +Credentials: `deployments.token` in config.json, or $VERCEL_TOKEN. Create one +at Account Settings -> Tokens. The Vercel CLI's own session is deliberately not +used - it expires within hours and only the CLI can refresh it, so anything +reading it goes dark overnight. The token is read locally and never printed. `vercel ls --all --format json` is an equivalent data source +but spawns a Node process per refresh, so this queries the REST API directly. From 7b7aeda59cae20bbf034852c1aad95fe588575ff Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sun, 23 Aug 2026 03:31:33 +0800 Subject: [PATCH 025/147] start: the front door, for a directory that no longer exists start.py reads the folder it sits in and parses each script's docstring. A compiled binary has no folder to read, so the same three things are compiled in from the same files the Python parses at run time: the summary and the paragraph under it from each widget's help text, and the picture from its doc page. Nothing is described twice either way, and a widget still cannot appear here saying something its own file does not. Compiling the doc pages in has a second effect worth having: the menu is a single executable that shows what each widget looks like with no repository anywhere on the machine. Browsing still costs nothing - the preview is a still from the docs rather than the widget itself, because starting one to look at it would ping hosts and spend API quota. matrix is the one entry with no picture. It has no doc page, deliberately - check.py exempts it by name - and it is the one widget that computes nothing, so a still frame of it would carry nothing either. Keyboard gains reclaim(): restore() hands the terminal back and forgets the settings, which is right on the way out and wrong in a launcher, which has to return to cbreak after the widget it started exits. Keystrokes typed while the child held the keyboard are dropped rather than delivered to the menu a moment later. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/core/src/lib.rs | 25 ++ rust/widgets/Cargo.toml | 4 + rust/widgets/src/bin/start.rs | 484 ++++++++++++++++++++++++++++ rust/widgets/src/bin/start_help.txt | 18 ++ 4 files changed, 531 insertions(+) create mode 100644 rust/widgets/src/bin/start.rs create mode 100644 rust/widgets/src/bin/start_help.txt diff --git a/rust/core/src/lib.rs b/rust/core/src/lib.rs index c5b7c30..78b67f4 100644 --- a/rust/core/src/lib.rs +++ b/rust/core/src/lib.rs @@ -534,6 +534,31 @@ impl Keyboard { } } + /// Take the terminal back after handing it to a child. + /// + /// `restore` gives the saved settings back and forgets them, which is + /// right on the way out and wrong in a launcher: the menu has to + /// return to cbreak once the widget it started has finished with the + /// terminal. Anything typed while the child had the keyboard belongs + /// to the child, so what is left of it is dropped rather than + /// delivered to the menu a moment later. + pub fn reclaim(&mut self) { + if self.saved.is_some() || unsafe { libc::isatty(self.fd) } != 1 { + return; + } + let mut saved: libc::termios = unsafe { std::mem::zeroed() }; + if unsafe { libc::tcgetattr(self.fd, &mut saved) } != 0 { + return; + } + let mut raw = saved; + raw.c_lflag &= !(libc::ICANON | libc::ECHO); + raw.c_cc[libc::VMIN] = 0; + raw.c_cc[libc::VTIME] = 0; + unsafe { libc::tcsetattr(self.fd, libc::TCSANOW, &raw) }; + self.saved = Some(saved); + self.buf.clear(); + } + /// Every key waiting, decoded. Empty when nothing has been pressed. pub fn poll(&mut self) -> Vec { if self.saved.is_none() { diff --git a/rust/widgets/Cargo.toml b/rust/widgets/Cargo.toml index 81bd587..ff73d43 100644 --- a/rust/widgets/Cargo.toml +++ b/rust/widgets/Cargo.toml @@ -44,3 +44,7 @@ path = "src/bin/herdr-panes.rs" [[bin]] name = "deployments" path = "src/bin/deployments.rs" + +[[bin]] +name = "start" +path = "src/bin/start.rs" diff --git a/rust/widgets/src/bin/start.rs b/rust/widgets/src/bin/start.rs new file mode 100644 index 0000000..c0f3251 --- /dev/null +++ b/rust/widgets/src/bin/start.rs @@ -0,0 +1,484 @@ +// terminal-toys - small dependency-free terminal widgets +// Copyright (C) 2026 William Li +// +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU Affero General Public License as published +// by the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU Affero General Public License for more details. +// +// You should have received a copy of the GNU Affero General Public License +// along with this program. If not, see . + +//! Every widget here, what it does, and whether it will work on this machine. +//! +//! A port of start.py, which reads the directory it sits in and parses each +//! script's docstring. A compiled binary has no directory to read, so the +//! same three things - the summary, the paragraph under it, and the picture +//! from the doc page - are compiled in from the same files the Python +//! parses at run time. Nothing is described twice either way. + +use std::time::Duration; + +use toys_core as tc; + +/// Each widget's own words, taken from the files that already hold them: +/// the help text every binary answers `--help` with, and the doc page that +/// opens with a picture of it. +struct Widget { + stem: &'static str, + help: &'static str, + doc: &'static str, +} + +const WIDGETS: &[Widget] = &[ + Widget { + stem: "clocks", + help: include_str!("clocks_help.txt"), + doc: include_str!("../../../../docs/clocks.md"), + }, + Widget { + stem: "deployments", + help: include_str!("deployments_help.txt"), + doc: include_str!("../../../../docs/deployments.md"), + }, + Widget { + stem: "herdr-panes", + help: include_str!("herdr-panes_help.txt"), + doc: include_str!("../../../../docs/herdr-panes.md"), + }, + Widget { + stem: "latency", + help: include_str!("latency_help.txt"), + doc: include_str!("../../../../docs/latency.md"), + }, + Widget { + stem: "link", + help: include_str!("link_help.txt"), + doc: include_str!("../../../../docs/link.md"), + }, + Widget { + stem: "matrix", + help: include_str!("matrix_help.txt"), + // The one widget with no doc page, and the only one that computes + // nothing: there is no picture of it that a still frame would carry. + doc: "", + }, + Widget { + stem: "netwatch", + help: include_str!("netwatch_help.txt"), + doc: include_str!("../../../../docs/netwatch.md"), + }, + Widget { + stem: "ports", + help: include_str!("ports_help.txt"), + doc: include_str!("../../../../docs/ports.md"), + }, +]; + +impl Widget { + /// The row: this widget's own first line. + fn summary(&self) -> &'static str { + self.help.lines().next().unwrap_or("") + } + + /// The aside: the paragraph under the summary, which is where each + /// widget explains why it exists. + /// + /// Only that paragraph. What follows is the usage synopsis and the key + /// list, which are for somebody reading --help rather than somebody + /// deciding whether this is the thing they want. + fn about(&self) -> String { + let mut para: Vec<&str> = Vec::new(); + for line in self.help.lines().skip(2) { + if line.starts_with(" ") { + break; // an indented usage block + } + if line.trim().is_empty() { + if !para.is_empty() { + break; + } + continue; + } + para.push(line.trim()); + } + para.join(" ").chars().take(400).collect() + } + + /// The picture from this widget's doc page, if it has one. + /// + /// Every doc opens with a rendering of the widget it describes, kept by + /// whoever wrote it and read by whoever is deciding whether to run the + /// thing. Using that means no second copy of anything - and, more to + /// the point, no widget has to be started to be looked at. + fn sample(&self) -> Vec<&'static str> { + let mut block = Vec::new(); + let mut inside = false; + for line in self.doc.lines() { + if line.starts_with("```") { + if inside { + break; + } + inside = true; + continue; + } + if inside { + block.push(line); + } + } + // Only a block that is actually a picture of the widget: the docs + // also hold shell snippets and JSON, and a config listing is not a + // preview. + match block.first() { + Some(first) if first.starts_with("╺━") => block, + _ => Vec::new(), + } + } +} + +/// Break a paragraph at spaces, for the note under the list. +fn wrap(text: &str, width: usize) -> Vec { + let mut lines = Vec::new(); + let mut rest: Vec = text.trim().chars().collect(); + while !rest.is_empty() && lines.len() < 3 { + if rest.len() <= width { + lines.push(rest.iter().collect()); + break; + } + let cut = rest[..(width + 1).min(rest.len())] + .iter() + .rposition(|c| *c == ' ') + .filter(|c| *c > width / 2) + .unwrap_or(width); + lines.push(rest[..cut].iter().collect()); + rest = rest[cut..].iter().skip_while(|c| **c == ' ').copied().collect(); + } + lines +} + +/// Where the widgets live: beside this binary, whatever it was called from. +fn beside(stem: &str) -> Option { + let here = std::env::current_exe().ok()?; + Some(here.parent()?.join(stem)) +} + +struct Palette { + dim: String, + grid: String, + txt: String, + lbl: String, + accent: String, +} + +fn palette() -> Palette { + Palette { + dim: tc::rgb(127, 147, 172), + grid: tc::rgb(60, 78, 98), + txt: tc::rgb(225, 235, 245), + lbl: tc::rgb(130, 165, 200), + accent: tc::rgb(150, 210, 255), + } +} + +fn rows_for(w: usize, selected: usize, p: &Palette) -> Vec { + let name_w = (w.saturating_sub(58)).clamp(12, 18); + // Every column keeps a space of its own, so a summary that fills its + // width stops short of whatever is beside it rather than running in. + let text_w = ((w - 1).saturating_sub(name_w + 6)).max(8); + WIDGETS + .iter() + .enumerate() + .map(|(i, item)| { + let here = i == selected; + let tint = if here { tc::bg(28, 44, 62) } else { String::new() }; + let c = |colour: &str| format!("{}{}", tint, colour); + let mut line = vec![ + ( + c(if here { &p.accent } else { &p.dim }), + if here { " ▸ ".to_string() } else { " ".to_string() }, + ), + ( + c(if here { &p.txt } else { &p.lbl }), + tc::pad( + &item.stem.chars().take(name_w - 1).collect::(), + name_w, + ), + ), + ( + c(&p.dim), + tc::pad( + &item.summary().chars().take(text_w - 1).collect::(), + text_w, + ), + ), + ]; + if here { + line.push((tint.clone(), " ".repeat(w))); + } + let refs: Vec<(&str, String)> = + line.iter().map(|(c, t)| (c.as_str(), t.clone())).collect(); + tc::seg(&refs, w - 1) + }) + .collect() +} + +/// Hand the terminal over, and take it back when the widget exits. +fn run_widget(keyboard: &mut tc::Keyboard, stem: &str) { + keyboard.restore(); + tc::restore_screen(); + match beside(stem) { + Some(path) => { + match std::process::Command::new(&path).status() { + Ok(_) => {} + Err(e) => { + tc::out(&format!("{}: {}\r\n", path.display(), e)); + tc::flush(); + std::thread::sleep(Duration::from_secs(2)); + } + } + } + None => { + tc::out("cannot find where this binary lives\r\n"); + tc::flush(); + std::thread::sleep(Duration::from_secs(2)); + } + } + // The widget left the terminal however it left it, so take it back + // rather than assuming: cbreak again, cursor away again, screen clear. + keyboard.reclaim(); + tc::out(&format!("{}{}{}", tc::HIDE, tc::CLEAR, tc::HOME)); + tc::flush(); +} + +fn main() { + // A widget name is resolved before --help is looked at, so that + // `start netwatch --help` is netwatch's help, not this one's. Every + // argument after the name belongs to the widget, including that one. + let args: Vec = std::env::args().skip(1).collect(); + if let Some(first) = args.first() { + if !first.starts_with('-') { + let wanted = first.strip_suffix(".py").unwrap_or(first); + let Some(found) = WIDGETS.iter().find(|w| w.stem == wanted) else { + eprintln!( + "no widget called {:?} - try: {}", + first, + WIDGETS + .iter() + .map(|w| w.stem) + .collect::>() + .join(", ") + ); + std::process::exit(2); + }; + let Some(path) = beside(found.stem) else { + eprintln!("cannot find where this binary lives"); + std::process::exit(2); + }; + // Replaced rather than wrapped: the menu is for browsing, not + // something to sit between you and a widget you already named. + let status = std::process::Command::new(&path).args(&args[1..]).status(); + std::process::exit(match status { + Ok(s) => s.code().unwrap_or(0), + Err(e) => { + eprintln!("{}: {}", path.display(), e); + 2 + } + }); + } + } + + tc::maybe_help(include_str!("start_help.txt")); + let p = palette(); + tc::setup(); + let mut keyboard = tc::Keyboard::new(); + let mut selected = 0usize; + + loop { + for key in keyboard.poll() { + match key.as_str() { + "q" | "Q" => { + keyboard.restore(); + tc::restore_screen(); + return; + } + "up" | "k" | "K" => selected = selected.saturating_sub(1), + "down" | "j" | "J" => selected += 1, + "enter" | "right" | "i" | "I" => { + run_widget(&mut keyboard, WIDGETS[selected.min(WIDGETS.len() - 1)].stem) + } + _ => {} + } + } + + let (w, h) = tc::size(); + if selected >= WIDGETS.len() { + selected = WIDGETS.len() - 1; + } + + let mut body = vec![tc::title("terminal toys", w, &p.accent)]; + body.push(tc::seg( + &[( + p.dim.as_str(), + format!(" {} widgets ↵ starts one, q leaves", WIDGETS.len()), + )], + w - 1, + )); + body.push(String::new()); + body.extend(rows_for(w, selected, &p)); + body.push(String::new()); + + // What the highlighted one is for, in its own words - the rest of + // its opening paragraph, which the row has no room for. Not the + // command to run it: that is this screen's job, not the reader's. + let pick = &WIDGETS[selected]; + if h.saturating_sub(body.len()) >= 3 { + body.push(tc::seg( + &[( + p.lbl.as_str(), + format!(" ── {} ── ", pick.stem.to_uppercase()), + )], + w - 1, + )); + let tall = h.saturating_sub(body.len()) >= 12; + let about = wrap(&pick.about(), w.saturating_sub(4)); + for line in about.iter().take(if tall { 1 } else { 3 }) { + body.push(tc::seg(&[(p.dim.as_str(), format!(" {}", line))], w - 1)); + } + } + + // And what it looks like. A picture from the docs rather than the + // widget itself: starting one to look at it would ping hosts, spend + // API quota and read the whole agent transcript tree, and browsing + // a menu should cost nothing at all. Measured against the footer + // that will actually be drawn, rather than a guess at its height. + let hints: Vec> = vec![ + vec![(p.accent.as_str(), "↑↓".into()), (p.dim.as_str(), " select".into())], + vec![(p.accent.as_str(), "↵".into()), (p.dim.as_str(), " launch".into())], + vec![(p.dim.as_str(), "[r]echeck".into())], + vec![(p.dim.as_str(), "[q]uit".into())], + ]; + let foot: Vec = tc::pack_hints(&hints, w - 2, " ") + .into_iter() + .map(|l| format!(" {}", l)) + .collect(); + let room = h.saturating_sub(body.len() + foot.len()); + let shown = pick.sample(); + if !shown.is_empty() && room >= 6 && w >= 44 { + let rule = "─".repeat(w.saturating_sub(15).max(1)); + body.push(tc::seg( + &[ + (p.grid.as_str(), " ┌── ".into()), + (p.dim.as_str(), "example".into()), + (p.grid.as_str(), format!(" {}┐", rule)), + ], + w - 1, + )); + for line in shown.iter().take(room - 1) { + body.push(tc::seg( + &[ + (p.grid.as_str(), " │".into()), + ( + p.dim.as_str(), + line.chars().take(w.saturating_sub(4)).collect::(), + ), + ], + w - 1, + )); + } + } + + while body.len() < h.saturating_sub(foot.len()) { + body.push(String::new()); + } + body.extend(foot); + body.truncate(h); + tc::draw(&body, w, h); + std::thread::sleep(Duration::from_millis(150)); + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn every_widget_describes_itself() { + // The row and the aside both come from the widget's own help text, + // so an empty one here means a help file that lost its opening - + // which is the thing this screen is entirely made of. + for widget in WIDGETS { + assert!( + !widget.summary().trim().is_empty(), + "{} has no summary line", + widget.stem + ); + assert!( + !widget.about().trim().is_empty(), + "{} has no paragraph under its summary", + widget.stem + ); + } + } + + #[test] + fn the_aside_stops_before_the_usage_block() { + // start.py takes the paragraph under the summary and nothing more: + // what follows is the synopsis and the key list, which belong to + // --help rather than to somebody choosing a widget. + for widget in WIDGETS { + let about = widget.about(); + assert!( + !about.contains("Keys:"), + "{} carried its key list into the aside", + widget.stem + ); + assert!(about.chars().count() <= 400, "{} ran long", widget.stem); + } + } + + #[test] + fn a_sample_is_a_picture_of_the_widget() { + // Every doc page opens with a rendering, and the rendering opens + // with the same rule every widget draws across its top. A fenced + // block that does not is a shell snippet or a config listing. + let mut with_pictures = 0; + for widget in WIDGETS { + let sample = widget.sample(); + if sample.is_empty() { + continue; + } + with_pictures += 1; + assert!(sample[0].starts_with("╺━"), "{} is not a preview", widget.stem); + } + assert!( + with_pictures >= WIDGETS.len() - 1, + "only {} of {} widgets have a preview", + with_pictures, + WIDGETS.len() + ); + } + + #[test] + fn a_paragraph_breaks_at_spaces() { + assert_eq!(wrap("one two three", 7), vec!["one two", "three"]); + // A word longer than the line is cut rather than dropped. + assert_eq!(wrap("abcdefghij", 4), vec!["abcd", "efgh", "ij"]); + // Three lines at most: this is a note, not the doc page. + assert_eq!(wrap(&"word ".repeat(60), 10).len(), 3); + assert!(wrap("", 8).is_empty()); + } + + #[test] + fn the_list_is_in_a_settled_order() { + // Alphabetical, as start.py's sorted glob produces - so the row a + // key lands on does not move between builds. + let names: Vec<&str> = WIDGETS.iter().map(|w| w.stem).collect(); + let mut sorted = names.clone(); + sorted.sort(); + assert_eq!(names, sorted); + } +} diff --git a/rust/widgets/src/bin/start_help.txt b/rust/widgets/src/bin/start_help.txt new file mode 100644 index 0000000..644b606 --- /dev/null +++ b/rust/widgets/src/bin/start_help.txt @@ -0,0 +1,18 @@ +Every widget here, what it does, and whether it will work on this machine. + +Thirteen scripts in a directory is a list you have to already know. This is +the front door: pick one and it runs, quit it and you are back here. + + start [WIDGET] [ARGS...] + +Nothing is described twice. The name and the summary are each widget's own +first docstring line, and the note underneath is the paragraph that follows +it - both already maintained, and already checked by check.py, so a widget +cannot appear here saying something its own file does not. + +Nothing is said here about whether a widget will work. A widget that cannot +run says so itself, on its own screen, in its own words - which is where +somebody who has just tried to start it is already looking, and is the only +place that knows what it actually needs. + +Keys: up/down select, enter launches, r rechecks, q quits. From 8caba7bd068296e74048ba0183d299d5e7d1b8d3 Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sun, 23 Aug 2026 03:44:04 +0800 Subject: [PATCH 026/147] linear: how the work is moving, across every team Tenth widget. GraphQL, so core learns POST with a body and the response headers that come with it - a rate limit is only knowable from a header, and a widget polling every two minutes should be able to say how much of its hour it has left. The key rides in on stdin like the Vercel one. The chart primitives common.py shares move into core with it: stacked_bar, meter, vbars, vbars_down, dance, mix and cycle. linear is the first to need them and pr and usage will want the same ones, and the alternative is three copies drifting apart on what a half-filled cell looks like. Two behaviours worth keeping that are easy to lose in a port. Cycles are ranked by what moved in the last six days rather than by deadline, because a cycle nobody has touched in a week is not interesting however close its end date - and an empty one scores zero and sinks without a special case. And when the window key changes what is being counted, the flow chart dances rather than showing the old numbers under a new heading, then eases into the real figures when they land; showing a 14-day count labelled 30d would be a lie told smoothly. Paging is capped at twelve pages per query so one enormous team cannot spin forever, and hitting the cap is reported rather than swallowed: "truncated" beside the count, because a floor presented as a total is the failure this repo cares most about. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/core/src/lib.rs | 343 ++++++- rust/widgets/Cargo.toml | 4 + rust/widgets/src/bin/linear.rs | 1298 ++++++++++++++++++++++++++ rust/widgets/src/bin/linear_help.txt | 20 + 4 files changed, 1661 insertions(+), 4 deletions(-) create mode 100644 rust/widgets/src/bin/linear.rs create mode 100644 rust/widgets/src/bin/linear_help.txt diff --git a/rust/core/src/lib.rs b/rust/core/src/lib.rs index 78b67f4..0375b1a 100644 --- a/rust/core/src/lib.rs +++ b/rust/core/src/lib.rs @@ -463,21 +463,260 @@ pub fn get(url: &str, headers: &[(&str, &str)], seconds: u64) -> Result Result<(String, Vec<(String, String)>), String> { + use std::io::Write; + let mut config = format!( + "--silent\n--show-error\n--request POST\n--dump-header -\n\ + --max-time {}\n--url {}\n--data {}\n", + seconds, + quoted(url), + quoted(body) + ); + for (name, value) in headers { + config.push_str(&format!("--header {}\n", quoted(&format!("{}: {}", name, value)))); + } + let mut child = std::process::Command::new("curl") + .arg("--config") + .arg("-") + .stdin(std::process::Stdio::piped()) + .stdout(std::process::Stdio::piped()) + .stderr(std::process::Stdio::piped()) + .spawn() + .map_err(|e| e.to_string())?; + child + .stdin + .take() + .ok_or("curl would not take its configuration")? + .write_all(config.as_bytes()) + .map_err(|e| e.to_string())?; + let out = child.wait_with_output().map_err(|e| e.to_string())?; + if !out.status.success() { + let said = String::from_utf8_lossy(&out.stderr).trim().to_string(); + return Err(if said.is_empty() { + format!("curl exited {}", out.status.code().unwrap_or(-1)) + } else { + said + }); + } + let text = String::from_utf8_lossy(&out.stdout).to_string(); + let (head, body) = split_response(&text); + let status = head + .first() + .and_then(|line| line.split_whitespace().nth(1)) + .and_then(|code| code.parse::().ok()) + .unwrap_or(0); + let found: Vec<(String, String)> = head + .iter() + .skip(1) + .filter_map(|line| line.split_once(':')) + .map(|(k, v)| (k.trim().to_lowercase(), v.trim().to_string())) + .collect(); + if !(200..300).contains(&status) { + return Err(format!("HTTP {}", status)); + } + Ok((body, found)) +} + +/// Split curl's `--dump-header -` output into its last header block and +/// the body under it. +/// +/// The last block, because a redirect or a `100 Continue` leaves earlier +/// ones in front of it, and the one that describes the response is the one +/// nearest the body. +fn split_response(text: &str) -> (Vec, String) { + let mut head: Vec = Vec::new(); + let mut rest = text; + loop { + let mut lines = Vec::new(); + let mut at = 0usize; + let mut ended = false; + for line in rest.split_inclusive('\n') { + at += line.len(); + let trimmed = line.trim_end_matches(['\r', '\n']); + if trimmed.is_empty() { + ended = true; + break; + } + lines.push(trimmed.to_string()); + } + if !ended || lines.is_empty() || !lines[0].starts_with("HTTP/") { + break; + } + head = lines; + rest = &rest[at..]; + } + (head, rest.to_string()) +} + /// A value for curl's config format, which takes double quotes and -/// backslash escapes and would otherwise stop at the first space. +/// backslash escapes and would otherwise stop at the first space - or, for +/// a GraphQL query, at the end of its first line. fn quoted(value: &str) -> String { let mut out = String::with_capacity(value.len() + 2); out.push('"'); for c in value.chars() { - if c == '"' || c == '\\' { - out.push('\\'); + match c { + '"' | '\\' => { + out.push('\\'); + out.push(c); + } + '\n' => out.push_str("\\n"), + '\r' => out.push_str("\\r"), + '\t' => out.push_str("\\t"), + _ => out.push(c), } - out.push(c); } out.push('"'); out } +/// Proportions as one bar: (fraction, colour) pairs to coloured segments. +/// +/// A bar beats a pie in a character grid - no aliasing, and the eye compares +/// lengths far better than angles. The last segment takes whatever rounding +/// left over, so the bar is always exactly its width. +pub fn stacked_bar(parts: &[(f64, String)], width: usize) -> Vec<(String, String)> { + let mut out = Vec::new(); + let mut used = 0usize; + for (i, (frac, colour)) in parts.iter().enumerate() { + let n = if i + 1 == parts.len() { + width.saturating_sub(used) + } else { + ((frac * width as f64).round() as usize).min(width.saturating_sub(used)) + }; + if n > 0 { + out.push((colour.clone(), "█".repeat(n))); + used += n; + } + } + out +} + +/// A filled fraction of a fixed-width track. +pub fn meter(frac: f64, n: usize) -> String { + let filled = ((frac.clamp(0.0, 1.0) * n as f64).round() as usize).min(n); + format!("{}{}", "█".repeat(filled), "░".repeat(n - filled)) +} + +const EIGHTHS: &[char] = &[' ', '▁', '▂', '▃', '▄', '▅', '▆', '▇', '█']; + +/// Vertical bar chart, one column per value. +/// +/// Each cell resolves an eighth of a row through the partial-block glyphs, +/// so a five-row chart has forty levels rather than five. `hi` fixes the +/// full-scale value so two charts can share a scale and stay comparable. +pub fn vbars(columns: &[(f64, String)], height: usize, hi: f64) -> Vec> { + let hi = if hi > 0.0 { + hi + } else { + columns.iter().map(|(v, _)| *v).fold(0.0, f64::max).max(1.0) + }; + (0..height) + .map(|r| { + let top = hi * (height - r) as f64 / height as f64; + let bottom = hi * (height - r - 1) as f64 / height as f64; + columns + .iter() + .map(|(value, colour)| { + let ch = if *value >= top { + '█' + } else if *value <= bottom { + ' ' + } else { + let step = ((value - bottom) / (top - bottom) * 8.0) as usize; + EIGHTHS[step.clamp(1, 8)] + }; + (colour.clone(), ch.to_string()) + }) + .collect() + }) + .collect() +} + +/// Bar chart hanging downward from a baseline above it. +/// +/// Paired with `vbars` and a shared `hi`, this makes a diverging chart: one +/// series growing up, another down, one column per day. +/// +/// The partial-block glyphs are all bottom-anchored, so a downward bar +/// cannot resolve an eighth of a cell the way `vbars` does - only `▀` +/// exists as a top-anchored partial. Half a cell is ample once peaks are +/// scaled, and the alternative needs the terminal's background painted, +/// which these widgets deliberately never do. +pub fn vbars_down(columns: &[(f64, String)], height: usize, hi: f64) -> Vec> { + let hi = if hi > 0.0 { + hi + } else { + columns.iter().map(|(v, _)| *v).fold(0.0, f64::max).max(1.0) + }; + (0..height) + .map(|r| { + let full = hi * (r + 1) as f64 / height as f64; + let empty = hi * r as f64 / height as f64; + columns + .iter() + .map(|(value, colour)| { + let ch = if *value >= full { + '█' + } else if *value <= empty { + ' ' + } else if (value - empty) / (full - empty) >= 0.5 { + '▀' + } else { + ' ' + }; + (colour.clone(), ch.to_string()) + }) + .collect() + }) + .collect() +} + +/// Column heights in 0..1 bouncing like a level meter, for pending data. +/// +/// Two sine waves of different periods per column, so neighbours move +/// together enough to read as one instrument but never march in lockstep. +/// Deterministic in `tick`, so every frame is reproducible and no random +/// source is needed. +pub fn dance(width: usize, tick: usize, phase: f64) -> Vec { + (0..width) + .map(|i| { + let t = tick as f64; + let i = i as f64; + let a = (t * 0.55 + i * 0.85 + phase).sin(); + let b = (t * 0.31 + i * 0.41 + phase * 1.7).sin(); + (0.5 + 0.33 * a + 0.17 * b).clamp(0.08, 1.0) + }) + .collect() +} + +/// Blend two colours, for fading a placeholder into real data. +pub fn mix(a: (u8, u8, u8), b: (u8, u8, u8), t: f64) -> String { + let t = t.clamp(0.0, 1.0); + let step = |x: u8, y: u8| (x as f64 + (y as f64 - x as f64) * t).round() as u8; + rgb(step(a.0, b.0), step(a.1, b.1), step(a.2, b.2)) +} + +/// The next entry after `current`, wrapping; for a key that cycles. +pub fn cycle(choices: &[T], current: T) -> T { + let at = choices.iter().position(|c| *c == current).unwrap_or(0); + choices[(at + 1) % choices.len()] +} + /// Which of these required commands are not on PATH. pub fn missing(programs: &[&str]) -> Vec { let path = std::env::var("PATH").unwrap_or_default(); @@ -656,6 +895,32 @@ pub fn maybe_help(doc: &str) { mod tests { use super::*; + #[test] + fn a_query_survives_its_own_newlines() { + // A GraphQL query is several lines. Unescaped, curl's config parser + // would read the second one as another option. + assert_eq!(quoted("query {\n issues\n}"), "\"query {\\n issues\\n}\""); + assert_eq!(quoted("a\tb"), "\"a\\tb\""); + } + + #[test] + fn the_headers_that_count_are_the_ones_next_to_the_body() { + // A redirect leaves its own block in front. The response is the one + // nearest the body, and everything before it is history. + let text = "HTTP/2 301\r\nlocation: /x\r\n\r\n\ + HTTP/2 200\r\nX-RateLimit-Requests-Remaining: 2491\r\n\r\n\ + {\"data\": 1}"; + let (head, body) = split_response(text); + assert_eq!(head[0], "HTTP/2 200"); + assert_eq!(body, "{\"data\": 1}"); + // A body containing a blank line of its own is not mistaken for a + // header block, because a block has to open with HTTP/. + let plain = "HTTP/2 200\r\n\r\nline\n\nline"; + let (head, body) = split_response(plain); + assert_eq!(head[0], "HTTP/2 200"); + assert_eq!(body, "line\n\nline"); + } + #[test] fn a_curl_config_value_survives_spaces_and_quotes() { assert_eq!(quoted("simple"), "\"simple\""); @@ -669,6 +934,76 @@ mod tests { assert_eq!(quoted("a\\b"), "\"a\\\\b\""); } + #[test] + fn a_stacked_bar_is_exactly_its_width() { + let hue = |n: u8| rgb(n, n, n); + // Thirds do not divide ten, and the last segment absorbs the + // rounding rather than leaving a gap at the end. + let parts = vec![ + (1.0 / 3.0, hue(1)), + (1.0 / 3.0, hue(2)), + (1.0 / 3.0, hue(3)), + ]; + let drawn: usize = stacked_bar(&parts, 10) + .iter() + .map(|(_, t)| t.chars().count()) + .sum(); + assert_eq!(drawn, 10); + // A part that rounds to nothing takes no segment at all, rather + // than an empty one. + let tiny = vec![(0.001, hue(1)), (0.999, hue(2))]; + assert_eq!(stacked_bar(&tiny, 10).len(), 1); + } + + #[test] + fn a_meter_fills_and_clamps() { + assert_eq!(meter(0.0, 4), "░░░░"); + assert_eq!(meter(0.5, 4), "██░░"); + assert_eq!(meter(1.0, 4), "████"); + // Over and under are clamped: a percentage above 100 must not + // draw a bar wider than its track. + assert_eq!(meter(2.0, 4), "████"); + assert_eq!(meter(-1.0, 4), "░░░░"); + } + + #[test] + fn bars_resolve_eighths_of_a_row() { + let hue = rgb(0, 0, 0); + let columns = vec![(1.0, hue.clone()), (0.5, hue.clone()), (0.0, hue.clone())]; + let rows = vbars(&columns, 1, 1.0); + assert_eq!(rows[0][0].1, "█"); + assert_eq!(rows[0][1].1, "▄"); + assert_eq!(rows[0][2].1, " "); + // Hanging downward there is only one partial glyph, so half a cell + // rounds to it and less than half to nothing. + let down = vbars_down(&columns, 1, 1.0); + assert_eq!(down[0][0].1, "█"); + assert_eq!(down[0][1].1, "▀"); + assert_eq!(down[0][2].1, " "); + } + + #[test] + fn the_placeholder_moves_but_never_leaves_the_track() { + // Every column stays inside the range a bar chart can draw, at + // every tick - a value outside it would render as an empty cell + // and read as data rather than as waiting. + for tick in 0..40 { + for value in dance(12, tick, 0.0) { + assert!((0.08..=1.0).contains(&value), "{} at tick {}", value, tick); + } + } + // Deterministic, so a frame can be reproduced. + assert_eq!(dance(4, 7, 0.0), dance(4, 7, 0.0)); + assert_ne!(dance(4, 7, 0.0), dance(4, 8, 0.0)); + } + + #[test] + fn a_blend_reaches_both_ends() { + assert_eq!(mix((0, 0, 0), (10, 20, 30), 0.0), rgb(0, 0, 0)); + assert_eq!(mix((0, 0, 0), (10, 20, 30), 1.0), rgb(10, 20, 30)); + assert_eq!(mix((0, 0, 0), (10, 20, 30), 0.5), rgb(5, 10, 15)); + } + #[test] fn heat_runs_green_to_red_through_amber() { // The ends and the middle, since every widget reads the same scale diff --git a/rust/widgets/Cargo.toml b/rust/widgets/Cargo.toml index ff73d43..efae7bb 100644 --- a/rust/widgets/Cargo.toml +++ b/rust/widgets/Cargo.toml @@ -48,3 +48,7 @@ path = "src/bin/deployments.rs" [[bin]] name = "start" path = "src/bin/start.rs" + +[[bin]] +name = "linear" +path = "src/bin/linear.rs" diff --git a/rust/widgets/src/bin/linear.rs b/rust/widgets/src/bin/linear.rs new file mode 100644 index 0000000..e3d7976 --- /dev/null +++ b/rust/widgets/src/bin/linear.rs @@ -0,0 +1,1298 @@ +// terminal-toys - small dependency-free terminal widgets +// Copyright (C) 2026 William Li +// +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU Affero General Public License as published +// by the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU Affero General Public License for more details. +// +// You should have received a copy of the GNU Affero General Public License +// along with this program. If not, see . + +//! How the work is moving, across every Linear team. +//! +//! A port of linear.py. Linear has no totalCount on its connections, so +//! anything counted here is walked a page at a time; only the fields the +//! screen actually shows are asked for, because complexity is charged per +//! property and the page count is what costs. + +use std::collections::HashMap; +use std::sync::{Arc, Condvar, Mutex}; +use std::time::{Duration, SystemTime, UNIX_EPOCH}; + +use chrono::{NaiveDateTime, Utc}; +use toys_core as tc; + +const API: &str = "https://api.linear.app/graphql"; +/// Linear's maximum page size. +const PAGE: usize = 250; +/// Pages per query, so one huge team cannot spin forever. +const PAGE_CAP: usize = 12; +const WINDOWS: &[i64] = &[7, 14, 30, 60, 90]; +const SETTLE_FRAMES: usize = 8; +/// Tail of a cycle's history that counts as "lately". +const CHURN_DAYS: usize = 6; +const STATE_ORDER: &[&str] = &["triage", "backlog", "unstarted", "started"]; + +fn now() -> f64 { + SystemTime::now() + .duration_since(UNIX_EPOCH) + .map(|d| d.as_secs_f64()) + .unwrap_or(0.0) +} + +/// A Linear personal API key, from config.json or the environment. +fn token(cfg: &serde_json::Value) -> (String, &'static str) { + let from_config = tc::cfg_str(cfg, "token", ""); + if !from_config.is_empty() { + return (from_config, "config"); + } + let name = tc::cfg_str(cfg, "token_env", "LINEAR_API_KEY"); + let name = if name.is_empty() { "LINEAR_API_KEY".into() } else { name }; + match std::env::var(&name) { + Ok(value) if !value.is_empty() => (value, "env"), + _ => (String::new(), "missing"), + } +} + +/// What the API says is left of this hour's allowance. +#[derive(Clone, Copy, Default)] +struct Quota { + requests: Option, +} + +fn graphql( + query: &str, + tok: &str, + variables: serde_json::Value, + quota: &Arc>, +) -> Result { + let body = serde_json::json!({ "query": query, "variables": variables }).to_string(); + let (text, headers) = tc::post_json( + API, + &[ + ("Authorization", tok), + ("Content-Type", "application/json"), + ("User-Agent", "terminal-toys"), + ], + &body, + 30, + )?; + for (name, value) in &headers { + if name == "x-ratelimit-requests-remaining" { + if let Ok(left) = value.parse() { + if let Ok(mut guard) = quota.lock() { + guard.requests = Some(left); + } + } + } + } + let data: serde_json::Value = serde_json::from_str(&text).map_err(|e| e.to_string())?; + if let Some(first) = data["errors"].as_array().and_then(|a| a.first()) { + return Err(first["message"] + .as_str() + .unwrap_or("") + .chars() + .take(80) + .collect()); + } + Ok(data["data"].clone()) +} + +/// Follow pageInfo to the end, or to PAGE_CAP, and return every node. +/// +/// The bool says the cap was hit, so the screen can mark the count as a +/// floor rather than reporting a truncated total as a total. +fn pages( + tok: &str, + query: &str, + path: &[&str], + variables: &serde_json::Value, + quota: &Arc>, +) -> Result<(Vec, bool), String> { + let mut out = Vec::new(); + let mut cursor = serde_json::Value::Null; + for _ in 0..PAGE_CAP { + let mut v = variables.clone(); + v["after"] = cursor.clone(); + let mut conn = graphql(query, tok, v, quota)?; + for step in path { + conn = conn[*step].clone(); + } + for node in conn["nodes"].as_array().into_iter().flatten() { + out.push(node.clone()); + } + if !conn["pageInfo"]["hasNextPage"].as_bool().unwrap_or(false) { + return Ok((out, false)); + } + cursor = conn["pageInfo"]["endCursor"].clone(); + } + Ok((out, true)) +} + +fn open_query() -> String { + format!( + r#" +query($after: String) {{ + issues(first: {}, after: $after, + filter: {{ state: {{ type: {{ nin: ["completed", "canceled", + "duplicate"] }} }} }}) {{ + nodes {{ identifier estimate startedAt createdAt + state {{ type }} team {{ key }} }} + pageInfo {{ hasNextPage endCursor }} + }} +}}"#, + PAGE + ) +} + +fn created_query() -> String { + format!( + r#" +query($after: String, $since: DateTimeOrDuration!) {{ + issues(first: {}, after: $after, filter: {{ createdAt: {{ gte: $since }} }}) {{ + nodes {{ createdAt team {{ key }} }} + pageInfo {{ hasNextPage endCursor }} + }} +}}"#, + PAGE + ) +} + +fn done_query() -> String { + format!( + r#" +query($after: String, $since: DateTimeOrDuration!) {{ + issues(first: {}, after: $after, filter: {{ completedAt: {{ gte: $since }} }}) {{ + nodes {{ identifier completedAt startedAt createdAt team {{ key }} }} + pageInfo {{ hasNextPage endCursor }} + }} +}}"#, + PAGE + ) +} + +const CYCLES_QUERY: &str = r#" +{ + cycles(first: 50, filter: { isActive: { eq: true } }) { + nodes { + name number startsAt endsAt progress + issueCountHistory completedIssueCountHistory + scopeHistory completedScopeHistory + team { key name } + } + pageInfo { hasNextPage endCursor } + } +}"#; + +const TEAMS_QUERY: &str = r#" +{ teams(first: 100) { nodes { key name } pageInfo { hasNextPage } } }"#; + +fn text(value: &serde_json::Value, key: &str) -> String { + value[key].as_str().unwrap_or("").to_string() +} + +/// The calendar day of an ISO timestamp, as Linear returns them. +fn day(ts: &str) -> String { + ts.chars().take(10).collect() +} + +fn parse(ts: &str) -> Option { + if ts.len() < 19 { + return None; + } + NaiveDateTime::parse_from_str(&ts[..19], "%Y-%m-%dT%H:%M:%S").ok() +} + +fn hours_since(from: Option, to: Option) -> Option { + let (from, to) = (from?, to?); + Some((to - from).num_seconds() as f64 / 3600.0) +} + +fn ago(t: f64) -> String { + if t <= 0.0 { + return "--".into(); + } + let s = (now() - t) as i64; + if s < 60 { + format!("{}s", s) + } else if s < 3600 { + format!("{}m", s / 60) + } else { + format!("{}h", s / 3600) + } +} + +/// A span at whatever unit keeps it readable. +/// +/// Rolls over to years because these figures reach them: an issue open for +/// "1021.6d" is arithmetic, one open for "2.8y" is a decision. +fn dur(hours: Option) -> String { + let Some(h) = hours else { + return "--".into(); + }; + if h < 1.0 { + return format!("{}m", ((h * 60.0) as i64).max(1)); + } + if h < 48.0 { + return format!("{:.1}h", h); + } + let days = h / 24.0; + if days < 365.0 { + format!("{:.1}d", days) + } else { + format!("{:.1}y", days / 365.0) + } +} + +fn median(xs: &[f64]) -> Option { + if xs.is_empty() { + return None; + } + let mut s = xs.to_vec(); + s.sort_by(f64::total_cmp); + let n = s.len(); + Some(if n % 2 == 1 { + s[n / 2] + } else { + (s[n / 2 - 1] + s[n / 2]) / 2.0 + }) +} + +/// An issue worth going and looking at: how long, and which one. +type Extreme = Option<(f64, String)>; + +#[derive(Default)] +struct State { + teams: Vec<(String, String)>, + states: HashMap, + by_team: HashMap>, + cycles: Vec, + created: HashMap, + completed: HashMap, + lead: Vec, + cycle_time: Vec, + quickest: Extreme, + slowest: Extreme, + oldest_open: Extreme, + oldest_wip: Extreme, + /// Which window the counters describe, which is not always the window + /// the keys have asked for. + window: i64, + truncated: bool, + err: String, + fetched: f64, +} + +#[allow(clippy::too_many_arguments)] +fn one_pass( + tok: &str, + source: &str, + days: i64, + keep: &[String], + exclude: &[String], + state: &Arc>, + quota: &Arc>, +) -> Result<(), String> { + let wanted = |key: &str| -> bool { + if !keep.is_empty() { + keep.iter().any(|k| k == key) + } else { + !exclude.iter().any(|k| k == key) + } + }; + let since = (Utc::now() - chrono::Duration::days(days - 1)) + .format("%Y-%m-%dT00:00:00.000Z") + .to_string(); + + let teams_res = graphql(TEAMS_QUERY, tok, serde_json::json!({}), quota)?; + let teams: Vec<(String, String)> = teams_res["teams"]["nodes"] + .as_array() + .into_iter() + .flatten() + .map(|t| (text(t, "key"), text(t, "name"))) + .filter(|(key, _)| wanted(key)) + .collect(); + let keys: Vec = teams.iter().map(|(k, _)| k.clone()).collect(); + if let Ok(mut guard) = state.lock() { + guard.teams = teams.clone(); + } + + // What is outstanding right now, at any age. + let (rows, capped) = pages(tok, &open_query(), &["issues"], &serde_json::json!({}), quota)?; + let mut states: HashMap = HashMap::new(); + let mut by_team: HashMap> = HashMap::new(); + let at = Utc::now().naive_utc(); + let (mut oldest_open, mut oldest_wip): (Extreme, Extreme) = (None, None); + for it in &rows { + let key = text(&it["team"], "key"); + if !keys.contains(&key) { + continue; + } + let st = text(&it["state"], "type"); + if !STATE_ORDER.contains(&st.as_str()) { + continue; + } + *states.entry(st.clone()).or_insert(0) += 1; + let slot = by_team.entry(key).or_default(); + *slot.entry(st.clone()).or_insert(0) += 1; + *slot.entry("open".into()).or_insert(0) += 1; + let ident = text(it, "identifier"); + if let Some(age) = hours_since(parse(&text(it, "createdAt")), Some(at)) { + if oldest_open.as_ref().is_none_or(|(had, _)| age > *had) { + oldest_open = Some((age, ident.clone())); + } + } + if st == "started" { + if let Some(age) = hours_since(parse(&text(it, "startedAt")), Some(at)) { + if oldest_wip.as_ref().is_none_or(|(had, _)| age > *had) { + oldest_wip = Some((age, ident)); + } + } + } + } + + // The running cycles, each already carrying its own burndown. + let cycles_res = graphql(CYCLES_QUERY, tok, serde_json::json!({}), quota)?; + let cycles: Vec = cycles_res["cycles"]["nodes"] + .as_array() + .into_iter() + .flatten() + .filter(|c| keys.contains(&text(&c["team"], "key"))) + .cloned() + .collect(); + + // Arrivals and departures over the window. + let vars = serde_json::json!({ "since": since }); + let (made, cap2) = pages(tok, &created_query(), &["issues"], &vars, quota)?; + let (done, cap3) = pages(tok, &done_query(), &["issues"], &vars, quota)?; + let mut created: HashMap = HashMap::new(); + let mut completed: HashMap = HashMap::new(); + let (mut lead, mut ctime): (Vec, Vec) = (Vec::new(), Vec::new()); + let (mut quickest, mut slowest): (Extreme, Extreme) = (None, None); + for it in &made { + if keys.contains(&text(&it["team"], "key")) { + *created.entry(day(&text(it, "createdAt"))).or_insert(0) += 1; + } + } + for it in &done { + if !keys.contains(&text(&it["team"], "key")) { + continue; + } + *completed.entry(day(&text(it, "completedAt"))).or_insert(0) += 1; + let fin = parse(&text(it, "completedAt")); + let ident = text(it, "identifier"); + if let Some(hrs) = hours_since(parse(&text(it, "createdAt")), fin) { + lead.push(hrs); + if quickest.as_ref().is_none_or(|(had, _)| hrs < *had) { + quickest = Some((hrs, ident.clone())); + } + if slowest.as_ref().is_none_or(|(had, _)| hrs > *had) { + slowest = Some((hrs, ident)); + } + } + if let Some(hrs) = hours_since(parse(&text(it, "startedAt")), fin) { + ctime.push(hrs); + } + } + for (key, slot) in by_team.iter_mut() { + let n = done + .iter() + .filter(|it| text(&it["team"], "key") == *key) + .count(); + slot.insert("done".into(), n); + } + + if let Ok(mut guard) = state.lock() { + guard.states = states; + guard.by_team = by_team; + guard.cycles = cycles; + guard.created = created; + guard.completed = completed; + guard.lead = lead; + guard.cycle_time = ctime; + guard.quickest = quickest; + guard.slowest = slowest; + guard.oldest_open = oldest_open; + guard.oldest_wip = oldest_wip; + guard.window = days; + guard.truncated = capped || cap2 || cap3; + guard.fetched = now(); + guard.err = if source == "config" { + tc::config_token_warning().unwrap_or_default() + } else { + String::new() + }; + } + Ok(()) +} + +struct Palette { + ok: String, + warn: String, + bad: String, + dim: String, + grid: String, + txt: String, + lbl: String, + accent: String, + new: String, +} + +const GHOST: (u8, u8, u8) = (96, 106, 124); +const NEW_RGB: (u8, u8, u8) = (180, 160, 255); +const OK_RGB: (u8, u8, u8) = (90, 240, 160); + +fn palette() -> Palette { + Palette { + ok: tc::rgb(90, 240, 160), + warn: tc::rgb(255, 200, 90), + bad: tc::rgb(255, 100, 110), + dim: tc::rgb(127, 147, 172), + grid: tc::rgb(60, 78, 98), + txt: tc::rgb(225, 235, 245), + lbl: tc::rgb(130, 165, 200), + accent: tc::rgb(150, 210, 255), + new: tc::rgb(180, 160, 255), + } +} + +fn state_colour<'a>(state: &str, p: &'a Palette) -> &'a str { + match state { + "triage" => &p.bad, + "backlog" => &p.dim, + "unstarted" => &p.accent, + _ => &p.warn, + } +} + +fn state_label(state: &str) -> &'static str { + match state { + "triage" => "triage", + "backlog" => "backlog", + "unstarted" => "todo", + _ => "in progress", + } +} + +/// How much a cycle has moved lately, for ranking. +/// +/// The burndown arrays already say where the action is: day-over-day +/// movement in completed scope and in scope itself, summed over the tail. +/// A cycle nothing has touched in a week is not interesting however close +/// its deadline, and an empty one scores zero and sinks without a special +/// case. Deadline breaks ties. +fn churn(c: &serde_json::Value) -> (f64, i64) { + let mut moved = 0.0; + for series in ["completedScopeHistory", "scopeHistory"] { + let all: Vec = c[series] + .as_array() + .into_iter() + .flatten() + .filter_map(|v| v.as_f64()) + .collect(); + let tail = &all[all.len().saturating_sub(CHURN_DAYS)..]; + moved += tail.windows(2).map(|w| (w[1] - w[0]).abs()).sum::(); + } + let left = match parse(&text(c, "endsAt")) { + Some(ends) => (ends - Utc::now().naive_utc()).num_days(), + None => 999, + }; + (-moved, left) +} + +fn last_of(c: &serde_json::Value, key: &str) -> f64 { + c[key] + .as_array() + .and_then(|a| a.last()) + .and_then(|v| v.as_f64()) + .unwrap_or(0.0) +} + +fn first_of(c: &serde_json::Value, key: &str) -> f64 { + c[key] + .as_array() + .and_then(|a| a.first()) + .and_then(|v| v.as_f64()) + .unwrap_or(0.0) +} + +/// A number as the Python's %g writes it: no trailing zeros on a whole one. +fn tidy(v: f64) -> String { + if v.fract().abs() < 1e-9 { + format!("{}", v as i64) + } else { + format!("{}", v) + } +} + +fn main() { + tc::maybe_help(include_str!("linear_help.txt")); + let cfg = tc::load_config("linear"); + let mut refresh = tc::cfg_f64(&cfg, "refresh", 120.0); + let exclude: Vec = tc::cfg_strings(&cfg, "exclude_teams", &[]); + let start_window = tc::cfg_f64(&cfg, "window_days", 14.0) as i64; + + let args: Vec = std::env::args().skip(1).collect(); + let mut keep: Vec = Vec::new(); + let mut i = 0; + while i < args.len() { + match args[i].as_str() { + "-n" | "--refresh" if i + 1 < args.len() => { + refresh = args[i + 1].parse().unwrap_or(120.0); + i += 2; + } + other if !other.starts_with('-') => { + keep.push(other.to_uppercase()); + i += 1; + } + _ => i += 1, + } + } + + let absent = tc::missing(&["curl"]); + if !absent.is_empty() { + tc::cannot_start( + "linear ops", + &absent, + &[ + "Everything here comes from Linear's GraphQL API, and curl is", + "how this reaches it - the same way the other widgets reach", + "ss, ping and tailscale.", + "", + "The key is passed to curl on its standard input rather than", + "in its arguments, because /proc//cmdline is readable by", + "every user on the machine.", + ], + "apt install curl", + ); + return; + } + + let p = palette(); + let state = Arc::new(Mutex::new(State { + window: start_window, + ..Default::default() + })); + let quota = Arc::new(Mutex::new(Quota::default())); + let days = Arc::new(Mutex::new(start_window)); + let wake = Arc::new((Mutex::new(false), Condvar::new())); + + let (tok, source) = token(&cfg); + let env_name = { + let name = tc::cfg_str(&cfg, "token_env", "LINEAR_API_KEY"); + if name.is_empty() { "LINEAR_API_KEY".to_string() } else { name } + }; + let poller = Arc::clone(&state); + let poller_wake = Arc::clone(&wake); + let poller_days = Arc::clone(&days); + let poller_quota = Arc::clone("a); + std::thread::spawn(move || loop { + if tok.is_empty() { + if let Ok(mut guard) = poller.lock() { + guard.err = format!( + "no key: set linear.token in config.json or ${}", + env_name + ); + } + } else { + let want = poller_days.lock().map(|g| *g).unwrap_or(14); + if let Err(said) = one_pass( + &tok, + source, + want, + &keep, + &exclude, + &poller, + &poller_quota, + ) { + if let Ok(mut guard) = poller.lock() { + guard.err = said; + } + } + } + let (lock, cond) = &*poller_wake; + let mut asked = match lock.lock() { + Ok(g) => g, + Err(_) => return, + }; + if !*asked { + asked = match cond.wait_timeout(asked, Duration::from_secs_f64(refresh)) { + Ok((g, _)) => g, + Err(_) => return, + }; + } + *asked = false; + }); + + tc::setup(); + let mut keyboard = tc::Keyboard::new(); + // Two sections scroll, so the arrows need to know which one they are + // in. Tab moves the focus; the focused heading says so. + let (cycles_pane, teams_pane) = (0usize, 1usize); + let mut focus = cycles_pane; + let mut sel = [0usize, 0usize]; + let mut tick = 0usize; + let mut settle_t = 0usize; + let mut settle_from: Option<(Vec, Vec)> = None; + + loop { + tick += 1; + for key in keyboard.poll() { + match key.as_str() { + "q" | "Q" => { + keyboard.restore(); + tc::restore_screen(); + return; + } + "r" | "R" => { + let (lock, cond) = &*wake; + if let Ok(mut asked) = lock.lock() { + *asked = true; + cond.notify_all(); + } + } + "w" | "W" => { + if let Ok(mut want) = days.lock() { + *want = tc::cycle(WINDOWS, *want); + } + let (lock, cond) = &*wake; + if let Ok(mut asked) = lock.lock() { + *asked = true; + cond.notify_all(); + } + } + "tab" => focus = if focus == cycles_pane { teams_pane } else { cycles_pane }, + "up" => sel[focus] = sel[focus].saturating_sub(1), + "down" => sel[focus] += 1, + _ => {} + } + } + + let (w, h) = tc::size(); + let want = days.lock().map(|g| *g).unwrap_or(14); + let s = match state.lock() { + Ok(g) => g, + Err(_) => return, + }; + // The counters describe the window they were fetched for, which is + // not the one the key has just asked for. + let stale = s.window != want; + let left = quota.lock().map(|g| g.requests).unwrap_or(None); + + let mut rows = vec![tc::title("linear ops", w, &p.new)]; + let mut head = vec![ + ( + p.dim.as_str(), + format!(" {} team{}", s.teams.len(), if s.teams.len() == 1 { "" } else { "s" }), + ), + (p.dim.as_str(), format!(" updated {} ago", ago(s.fetched))), + ]; + if let Some(left) = left { + head.push(( + if left > 500 { p.ok.as_str() } else { p.warn.as_str() }, + format!(" {} req left/hr", left), + )); + } + rows.push(tc::seg(&head, w - 1)); + if !s.err.is_empty() { + rows.push(tc::seg(&[(p.bad.as_str(), format!(" ! {}", s.err))], w - 1)); + } + if s.teams.is_empty() { + rows.push(tc::seg(&[(p.dim.as_str(), " collecting…".into())], w - 1)); + drop(s); + while rows.len() < h.saturating_sub(1) { + rows.push(String::new()); + } + tc::draw(&rows, w, h); + std::thread::sleep(Duration::from_millis(400)); + continue; + } + + // How long work takes, across every team. It leads the board: it is + // the one figure that says whether the machine is getting faster or + // slower, and it is an aggregate rather than any one team's - which + // the heading has to say, or it reads as whichever team is selected + // below. + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── HOW LONG ── ".into()), + (p.dim.as_str(), "all teams · ".into()), + ( + p.dim.as_str(), + if stale { + "counting…".to_string() + } else { + format!("median of {} completed in {}d", s.lead.len(), want) + }, + ), + ], + w - 1, + )); + let extreme = |label: &str, pair: &Extreme, colour: &str| -> (String, String, String) { + if stale { + return (label.into(), "···".into(), p.dim.clone()); + } + match pair { + None => (label.into(), "--".into(), p.dim.clone()), + Some((hours, ident)) => ( + label.into(), + format!("{} {}", if ident.is_empty() { "?" } else { ident }, dur(Some(*hours))), + colour.to_string(), + ), + } + }; + let dimmed = |value: Option| -> (String, String) { + if stale { + ("···".into(), p.dim.clone()) + } else { + (dur(value), p.txt.clone()) + } + }; + let (lead_txt, lead_c) = dimmed(median(&s.lead)); + let (cycle_txt, cycle_c) = dimmed(median(&s.cycle_time)); + let cells: Vec<(String, String, String)> = vec![ + ("lead (created→completed)".into(), lead_txt, lead_c), + ("cycle (started→completed)".into(), cycle_txt, cycle_c), + extreme("quickest", &s.quickest, &p.ok), + extreme("slowest", &s.slowest, &p.warn), + extreme("oldest open", &s.oldest_open, &p.bad), + extreme("oldest in progress", &s.oldest_wip, &p.warn), + ]; + let label_w = cells.iter().map(|c| c.0.chars().count()).max().unwrap_or(8); + // Two columns only when a value still gets room for the longest + // thing it holds - an identifier and a duration. Cells are a fixed + // width so a long value cannot push the next column out of line. + let ncols = if (w - 2) / 2 >= label_w + 3 + 15 { 2 } else { 1 }; + let cw = (w - 2) / ncols; + let val_w = cw.saturating_sub(label_w + 3).max(6); + for chunk in cells.chunks(ncols) { + let mut line: Vec<(&str, String)> = vec![(tc::RST, " ".into())]; + for (label, value, colour) in chunk { + line.push((p.dim.as_str(), format!(" {} ", tc::pad(label, label_w)))); + line.push((colour.as_str(), tc::pad(value, val_w))); + } + rows.push(tc::seg(&line, w - 1)); + } + rows.push(String::new()); + + let total_open: usize = STATE_ORDER + .iter() + .map(|st| s.states.get(*st).copied().unwrap_or(0)) + .sum(); + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── OPEN ── ".into()), + (p.new.as_str(), format!("{}", total_open)), + (p.dim.as_str(), " issues open".into()), + (p.dim.as_str(), " (any age)".into()), + ( + p.warn.as_str(), + if s.truncated { " truncated".into() } else { String::new() }, + ), + ], + w - 1, + )); + if total_open > 0 { + let parts: Vec<(f64, String)> = STATE_ORDER + .iter() + .filter_map(|st| { + let n = s.states.get(*st).copied().unwrap_or(0); + if n == 0 { + return None; + } + Some((n as f64 / total_open as f64, state_colour(st, &p).to_string())) + }) + .collect(); + let bar = tc::stacked_bar(&parts, w.saturating_sub(3).max(10)); + let mut line: Vec<(&str, String)> = vec![(tc::RST, " ".into())]; + for (colour, txt) in &bar { + line.push((colour.as_str(), txt.clone())); + } + rows.push(tc::seg(&line, w - 1)); + let mut key: Vec<(&str, String)> = vec![(tc::RST, " ".into())]; + for st in STATE_ORDER { + let n = s.states.get(*st).copied().unwrap_or(0); + if n == 0 { + continue; + } + key.push((state_colour(st, &p), "▇ ".into())); + key.push((p.txt.as_str(), state_label(st).into())); + key.push(( + p.dim.as_str(), + format!(" {} ({:.0}%) ", n, 100.0 * n as f64 / total_open as f64), + )); + } + rows.push(tc::seg(&key, w - 1)); + } + + rows.push(String::new()); + let mut ranked_cycles = s.cycles.clone(); + ranked_cycles.sort_by(|a, b| { + let (am, al) = churn(a); + let (bm, bl) = churn(b); + am.total_cmp(&bm).then(al.cmp(&bl)) + }); + if !ranked_cycles.is_empty() { + sel[cycles_pane] = sel[cycles_pane].min(ranked_cycles.len() - 1); + } + let shown = ((h.saturating_sub(rows.len())) / 4).clamp(2, 6); + let cfirst = if ranked_cycles.len() > shown { + sel[cycles_pane] + .saturating_sub(shown / 2) + .min(ranked_cycles.len() - shown) + } else { + 0 + }; + let here_now = focus == cycles_pane; + rows.push(tc::seg( + &[ + ( + if here_now { p.accent.as_str() } else { p.lbl.as_str() }, + " ── ACTIVE CYCLES ── ".into(), + ), + (p.dim.as_str(), format!("{} running", s.cycles.len())), + ( + if here_now { p.accent.as_str() } else { p.dim.as_str() }, + if ranked_cycles.len() > shown { + format!( + " {}{}-{} of {}", + if here_now { "↑↓ " } else { "" }, + cfirst + 1, + (cfirst + shown).min(ranked_cycles.len()), + ranked_cycles.len() + ) + } else { + String::new() + }, + ), + ], + w - 1, + )); + if s.cycles.is_empty() { + rows.push(tc::seg( + &[(p.dim.as_str(), " no cycle is running in any team".into())], + w - 1, + )); + } + for (ci, c) in ranked_cycles.iter().enumerate().skip(cfirst).take(shown) { + let scope = last_of(c, "scopeHistory"); + let done = last_of(c, "completedScopeHistory"); + let opened_at = first_of(c, "scopeHistory"); + let left_days = parse(&text(c, "endsAt")) + .map(|ends| (ends - Utc::now().naive_utc()).num_days()); + let frac = if scope > 0.0 { done / scope } else { 0.0 }; + let name = format!( + "{} {}", + match text(&c["team"], "key") { + k if k.is_empty() => "?".to_string(), + k => k, + }, + match text(c, "name") { + n if n.is_empty() => format!("Cycle {}", tidy(c["number"].as_f64().unwrap_or(0.0))), + n => n, + } + ); + let on = focus == cycles_pane && ci == sel[cycles_pane]; + let tint = if on { tc::bg(38, 56, 76) } else { String::new() }; + let c_of = |colour: &str| format!("{}{}", tint, colour); + let hot = tc::heat(frac); + let mut line = vec![ + ( + c_of(if on { &p.accent } else { &p.txt }), + format!("{}{}", if on { "▸" } else { " " }, tc::pad(&name, 18)), + ), + ( + c_of(&hot), + tc::meter(frac, (w.saturating_sub(54)).clamp(8, 28)), + ), + ( + c_of(if scope > 0.0 { &hot } else { &p.dim }), + format!( + " {:>3}", + if scope > 0.0 { + format!("{:.0}%", frac * 100.0) + } else { + "--".into() + } + ), + ), + ( + c_of(&p.dim), + if scope > 0.0 { + format!(" {}/{} pts", tidy(done), tidy(scope)) + } else { + " nothing scoped".into() + }, + ), + ]; + if let Some(days_left) = left_days { + line.push(( + c_of(if days_left <= 2 { &p.warn } else { &p.dim }), + format!(" {}d left", days_left), + )); + } + // Scope added after the cycle opened is the number that explains + // a cycle working hard and still slipping. + if scope > opened_at { + line.push((c_of(&p.bad), format!(" +{} added", tidy(scope - opened_at)))); + } + if on { + line.push((tint.clone(), " ".repeat(w))); + } + let refs: Vec<(&str, String)> = + line.iter().map(|(c, t)| (c.as_str(), t.clone())).collect(); + rows.push(tc::seg(&refs, w - 1)); + } + + // Arrivals against departures. + let today = Utc::now().date_naive(); + let mut days_list: Vec = (0..want) + .rev() + .map(|n| (today - chrono::Duration::days(n)).format("%Y-%m-%d").to_string()) + .collect(); + let avail = w.saturating_sub(3).max(10); + if days_list.len() > avail { + days_list = days_list[days_list.len() - avail..].to_vec(); + } + let slot = (avail / days_list.len()).max(1); + let gap = if slot >= 3 { 1 } else { 0 }; + let barw = slot - gap; + let spread = |per_day: &[f64]| -> Vec { + let mut cols = Vec::new(); + for (n, v) in per_day.iter().enumerate() { + cols.extend(std::iter::repeat_n(*v, barw)); + if gap > 0 && n + 1 < per_day.len() { + cols.extend(std::iter::repeat_n(0.0, gap)); + } + } + cols + }; + let made_day: Vec = days_list + .iter() + .map(|d| s.created.get(d).copied().unwrap_or(0) as f64) + .collect(); + let done_day: Vec = days_list + .iter() + .map(|d| s.completed.get(d).copied().unwrap_or(0) as f64) + .collect(); + let (up, down) = (spread(&made_day), spread(&done_day)); + let chart_cols = up.len(); + let span_hi = up + .iter() + .chain(down.iter()) + .cloned() + .fold(0.0f64, f64::max) + .max(1.0); + rows.push(String::new()); + if stale { + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── ISSUE FLOW ── ".into()), + (p.dim.as_str(), format!("counting {}d…", want)), + ], + w - 1, + )); + } else { + let span = if days_list.len() < want as usize { + format!("{}d of {}d", days_list.len(), want) + } else { + format!("{}d", days_list.len()) + }; + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── ISSUE FLOW ── ".into()), + (p.dim.as_str(), format!("{} · ", span)), + ( + p.new.as_str(), + format!("▲ {} created", made_day.iter().sum::() as i64), + ), + (p.dim.as_str(), " · ".into()), + ( + p.ok.as_str(), + format!("▼ {} completed", done_day.iter().sum::() as i64), + ), + (p.dim.as_str(), format!(" peak {}/day", span_hi as i64)), + ], + w - 1, + )); + } + // While the counters are for a window nobody asked for, the chart + // dances rather than showing a number that is not the answer; when + // the real one lands it eases in from where the dance left off. + let (hu, hd, cu, cd) = if stale { + let hu = spread(&tc::dance(days_list.len(), tick, 0.0)); + let hd = spread(&tc::dance(days_list.len(), tick, 2.1)); + settle_from = Some((hu.clone(), hd.clone())); + settle_t = 0; + ( + hu, + hd, + tc::mix(GHOST, NEW_RGB, 0.45), + tc::mix(GHOST, OK_RGB, 0.45), + ) + } else { + let real_u: Vec = up.iter().map(|v| v / span_hi).collect(); + let real_d: Vec = down.iter().map(|v| v / span_hi).collect(); + match &settle_from { + Some((fu, fd)) if settle_t < SETTLE_FRAMES && fu.len() == chart_cols => { + settle_t += 1; + let q = settle_t as f64 / SETTLE_FRAMES as f64; + let q = q * q * (3.0 - 2.0 * q); + ( + fu.iter().zip(&real_u).map(|(a, b)| a + (b - a) * q).collect(), + fd.iter().zip(&real_d).map(|(a, b)| a + (b - a) * q).collect(), + tc::mix(GHOST, NEW_RGB, 0.45 + 0.55 * q), + tc::mix(GHOST, OK_RGB, 0.45 + 0.55 * q), + ) + } + _ => (real_u, real_d, p.new.clone(), p.ok.clone()), + } + }; + for line in tc::vbars( + &hu.iter().map(|v| (*v, cu.clone())).collect::>(), + 3, + 1.0, + ) { + let mut parts: Vec<(&str, String)> = vec![(tc::RST, " ".into())]; + for (colour, ch) in &line { + parts.push((colour.as_str(), ch.clone())); + } + rows.push(tc::seg(&parts, w - 1)); + } + rows.push(tc::seg( + &[(tc::RST, " ".into()), (p.grid.as_str(), "─".repeat(chart_cols))], + w - 1, + )); + for line in tc::vbars_down( + &hd.iter().map(|v| (*v, cd.clone())).collect::>(), + 3, + 1.0, + ) { + let mut parts: Vec<(&str, String)> = vec![(tc::RST, " ".into())]; + for (colour, ch) in &line { + parts.push((colour.as_str(), ch.clone())); + } + rows.push(tc::seg(&parts, w - 1)); + } + let left_lbl = format!("{}d ago", days_list.len()); + rows.push(tc::seg( + &[ + (p.dim.as_str(), format!(" {}", left_lbl)), + ( + p.dim.as_str(), + " ".repeat(chart_cols.saturating_sub(left_lbl.chars().count() + 5).max(1)), + ), + (p.dim.as_str(), "today".into()), + ], + w - 1, + )); + + rows.push(String::new()); + let mut ranked = s.teams.clone(); + ranked.sort_by(|a, b| { + let open = |k: &String| { + s.by_team + .get(k) + .and_then(|c| c.get("open")) + .copied() + .unwrap_or(0) + }; + open(&b.0).cmp(&open(&a.0)).then(a.0.cmp(&b.0)) + }); + if !ranked.is_empty() { + sel[teams_pane] = sel[teams_pane].min(ranked.len() - 1); + } + let room = h.saturating_sub(5 + rows.len()).max(1); + let first = if ranked.len() > room { + sel[teams_pane].saturating_sub(room / 2).min(ranked.len() - room) + } else { + 0 + }; + let on_teams = focus == teams_pane; + rows.push(tc::seg( + &[ + ( + if on_teams { p.accent.as_str() } else { p.lbl.as_str() }, + " ── BY TEAM ──".into(), + ), + ( + if on_teams { p.accent.as_str() } else { p.dim.as_str() }, + if ranked.len() > room { + format!( + " {}{}-{} of {}", + if on_teams { "↑↓ " } else { "" }, + first + 1, + (first + room).min(ranked.len()), + ranked.len() + ) + } else { + String::new() + }, + ), + ], + w - 1, + )); + rows.push(tc::seg( + &[( + p.dim.as_str(), + tc::pad( + &format!( + " {:<22}{:>6}{:>7}{:>8}{:>8}", + "TEAM", + "OPEN", + "TRIAGE", + "DOING", + format!("DONE{}D", want) + ), + w - 1, + ), + )], + w - 1, + )); + for (i, (key, name)) in ranked.iter().enumerate().skip(first).take(room) { + let empty = HashMap::new(); + let c = s.by_team.get(key).unwrap_or(&empty); + let count = |k: &str| c.get(k).copied().unwrap_or(0); + let here = on_teams && i == sel[teams_pane]; + let tint = if here { tc::bg(38, 56, 76) } else { String::new() }; + let c_of = |colour: &str| format!("{}{}", tint, colour); + let mut line = vec![ + ( + c_of(if here { &p.accent } else { &p.txt }), + format!( + "{}{}", + if here { "▸" } else { " " }, + tc::pad(&format!("{} {}", key, name), 22) + ), + ), + (c_of(&p.new), format!("{:>6}", count("open"))), + ( + c_of(if count("triage") > 0 { &p.bad } else { &p.dim }), + format!("{:>7}", count("triage")), + ), + ( + c_of(if count("started") > 0 { &p.warn } else { &p.dim }), + format!("{:>8}", count("started")), + ), + ( + c_of(if count("done") > 0 { &p.ok } else { &p.dim }), + format!("{:>8}", count("done")), + ), + ]; + if here { + line.push((tint.clone(), " ".repeat(w))); + } + let refs: Vec<(&str, String)> = + line.iter().map(|(c, t)| (c.as_str(), t.clone())).collect(); + rows.push(tc::seg(&refs, w - 1)); + } + drop(s); + + let hints: Vec> = vec![ + vec![(p.accent.as_str(), "↑↓".into()), (p.dim.as_str(), " scroll".into())], + vec![(p.dim.as_str(), "[tab] section".into())], + vec![(p.dim.as_str(), "[w]indow".into())], + vec![(p.dim.as_str(), "[r]efresh".into())], + vec![(p.dim.as_str(), "[q]uit".into())], + ]; + let footer: Vec = tc::pack_hints(&hints, w - 2, " ") + .into_iter() + .map(|l| format!(" {}", l)) + .collect(); + rows.truncate(h.saturating_sub(footer.len())); + while rows.len() < h.saturating_sub(footer.len()) { + rows.push(String::new()); + } + rows.extend(footer); + tc::draw(&rows, w, h); + std::thread::sleep(Duration::from_millis(300)); + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn a_span_changes_unit_before_it_stops_meaning_anything() { + assert_eq!(dur(None), "--"); + assert_eq!(dur(Some(0.5)), "30m"); + assert_eq!(dur(Some(3.25)), "3.2h"); + assert_eq!(dur(Some(72.0)), "3.0d"); + // An issue open for 1021.6d is arithmetic; 2.8y is a decision. + assert_eq!(dur(Some(24.0 * 365.0 * 2.8)), "2.8y"); + // Never zero: something that took forty seconds took a minute, not + // no time at all. + assert_eq!(dur(Some(0.001)), "1m"); + } + + #[test] + fn a_median_takes_the_middle_of_an_even_count() { + assert_eq!(median(&[]), None); + assert_eq!(median(&[5.0]), Some(5.0)); + assert_eq!(median(&[1.0, 3.0]), Some(2.0)); + assert_eq!(median(&[3.0, 1.0, 2.0]), Some(2.0)); + } + + #[test] + fn a_timestamp_gives_up_its_day_and_its_instant() { + assert_eq!(day("2026-08-23T04:15:00.000Z"), "2026-08-23"); + assert_eq!(day(""), ""); + let at = parse("2026-08-23T04:15:00.000Z").expect("a Linear timestamp"); + assert_eq!(at.date().to_string(), "2026-08-23"); + // Anything shorter than a whole instant is not one. + assert!(parse("2026-08-23").is_none()); + assert!(parse("").is_none()); + } + + #[test] + fn a_cycle_is_ranked_by_what_moved_lately() { + let busy: serde_json::Value = serde_json::from_str( + r#"{"scopeHistory": [10,10,10,10,10,20], + "completedScopeHistory": [0,1,2,3,4,5], "endsAt": ""}"#, + ) + .unwrap(); + let quiet: serde_json::Value = serde_json::from_str( + r#"{"scopeHistory": [10,10,10,10,10,10], + "completedScopeHistory": [5,5,5,5,5,5], "endsAt": ""}"#, + ) + .unwrap(); + // Movement is negated so the busiest sorts first. + assert!(churn(&busy).0 < churn(&quiet).0); + // A cycle nothing has touched scores nothing at all, whatever its + // deadline - which is how an empty one sinks without a special case. + assert_eq!(churn(&quiet).0, 0.0); + let empty: serde_json::Value = serde_json::from_str(r#"{"endsAt": ""}"#).unwrap(); + assert_eq!(churn(&empty).0, 0.0); + } + + #[test] + fn a_whole_number_of_points_loses_its_decimal() { + assert_eq!(tidy(8.0), "8"); + assert_eq!(tidy(8.5), "8.5"); + assert_eq!(tidy(0.0), "0"); + } + + #[test] + fn a_key_decides_which_teams_are_counted() { + // Named teams win outright; otherwise the excluded ones are dropped + // and everything else is in. + let wanted = |keep: &[&str], exclude: &[&str], key: &str| -> bool { + if !keep.is_empty() { + keep.contains(&key) + } else { + !exclude.contains(&key) + } + }; + assert!(wanted(&["TOY"], &["OPS"], "TOY")); + assert!(!wanted(&["TOY"], &[], "OPS")); + assert!(wanted(&[], &["OPS"], "TOY")); + assert!(!wanted(&[], &["OPS"], "OPS")); + } +} diff --git a/rust/widgets/src/bin/linear_help.txt b/rust/widgets/src/bin/linear_help.txt new file mode 100644 index 0000000..d423609 --- /dev/null +++ b/rust/widgets/src/bin/linear_help.txt @@ -0,0 +1,20 @@ +Linear delivery metrics across every team in the workspace. + +What is outstanding, what the running cycles look like, and whether issues are +being closed faster than they arrive. + + linear [-n SECONDS] [team-key ...] + +Team keys are the prefixes on issue identifiers - XFY, SYS and so on. With +none given every team is included, minus anything in `linear.exclude_teams`. + +Triage is counted apart from the backlog throughout. An auto-filed intake +queue and a groomed backlog are different populations, and adding them +together produces a number that means nothing. + +Credentials: `linear.token` in config.json, or $LINEAR_API_KEY. A personal API +key from Settings - Security & access - Personal API keys. The API is called +directly, so no CLI is required. + +Keys: up/down select a team, r refreshes now, w cycles the window +(7/14/30/60/90 days), q quits. From 50ea5a749993310c0875339009c0067ca396eac6 Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sun, 23 Aug 2026 03:49:04 +0800 Subject: [PATCH 027/147] start: list linear, and stop advertising a key that cannot exist Two defects in the launcher, both mine and both shipped. linear was ported after the menu, so the menu listed eight of the nine binaries and would have kept doing that for every widget after it. start.py globs its directory, so a widget appears there by existing; here the list is compiled in, and a widget that ships with no way to find it is a real failure. There is now a test that reads the cargo manifest and asserts every [[bin]] except the launcher is on the menu, so forgetting one is a build failure rather than something somebody has to notice. And the footer advertised [r]echeck while the key matched nothing - exactly the defect the help-text commit existed to fix, reintroduced three commits later. start.py rescans its directory on r; there is no directory here, so there is nothing a recheck could find. The hint is gone, and the help says why rather than silently dropping a line the Python has. Found by running the key-table comparison over the four newest widgets, which is the tool that found the first four half-ported ones. herdr-panes, deployments and linear came back clean. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/widgets/src/bin/start.rs | 43 ++++++++++++++++++++++++++++- rust/widgets/src/bin/start_help.txt | 6 +++- 2 files changed, 47 insertions(+), 2 deletions(-) diff --git a/rust/widgets/src/bin/start.rs b/rust/widgets/src/bin/start.rs index c0f3251..1a541c0 100644 --- a/rust/widgets/src/bin/start.rs +++ b/rust/widgets/src/bin/start.rs @@ -56,6 +56,11 @@ const WIDGETS: &[Widget] = &[ help: include_str!("latency_help.txt"), doc: include_str!("../../../../docs/latency.md"), }, + Widget { + stem: "linear", + help: include_str!("linear_help.txt"), + doc: include_str!("../../../../docs/linear.md"), + }, Widget { stem: "link", help: include_str!("link_help.txt"), @@ -358,7 +363,6 @@ fn main() { let hints: Vec> = vec![ vec![(p.accent.as_str(), "↑↓".into()), (p.dim.as_str(), " select".into())], vec![(p.accent.as_str(), "↵".into()), (p.dim.as_str(), " launch".into())], - vec![(p.dim.as_str(), "[r]echeck".into())], vec![(p.dim.as_str(), "[q]uit".into())], ]; let foot: Vec = tc::pack_hints(&hints, w - 2, " ") @@ -405,6 +409,43 @@ fn main() { mod tests { use super::*; + #[test] + fn every_binary_is_on_the_menu() { + // start.py globs the directory, so a new widget appears by existing. + // Here the list is compiled in, and the failure mode is a widget + // that ships without a way to find it - which linear did, for one + // commit. The manifest is the thing that knows what was built. + let manifest = include_str!("../../Cargo.toml"); + let mut built: Vec<&str> = Vec::new(); + let mut in_bin = false; + for line in manifest.lines() { + let line = line.trim(); + if line.starts_with('[') { + in_bin = line == "[[bin]]"; + continue; + } + if in_bin { + if let Some(rest) = line.strip_prefix("name = \"") { + if let Some(name) = rest.strip_suffix('"') { + built.push(name); + } + } + } + } + assert!(built.len() > 1, "no binaries found in the manifest"); + for name in built { + // The menu does not list itself. + if name == "start" { + continue; + } + assert!( + WIDGETS.iter().any(|w| w.stem == name), + "{} is built but is not on the menu", + name + ); + } + } + #[test] fn every_widget_describes_itself() { // The row and the aside both come from the widget's own help text, diff --git a/rust/widgets/src/bin/start_help.txt b/rust/widgets/src/bin/start_help.txt index 644b606..484cffc 100644 --- a/rust/widgets/src/bin/start_help.txt +++ b/rust/widgets/src/bin/start_help.txt @@ -15,4 +15,8 @@ run says so itself, on its own screen, in its own words - which is where somebody who has just tried to start it is already looking, and is the only place that knows what it actually needs. -Keys: up/down select, enter launches, r rechecks, q quits. +Keys: up/down select, enter launches, q quits. + +start.py rescans its directory on r. This one has no directory to +rescan - the list is compiled in - so there is no recheck key here, +and none is advertised. From 1d9d78422f4136d05148afc42b410602a1d845dd Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sun, 23 Aug 2026 04:01:15 +0800 Subject: [PATCH 028/147] pr: the board, and a day that pr.py has never been counting Eleventh widget. The union of several GitHub searches, because search has no OR; each PR remembers which sources found it, so narrowing to one is instant and costs no request. The detail view opens in stages with a spinner on the one in flight, and reconstructs a stack from branch names when GitHub has no native one - which is a tree rather than a line, so it draws the connectors properly. While comparing it against the running Python I found a real bug in pr.py, and the numbers are not small. OPENED / DAY buckets by `date.today()` - the local calendar day - while every createdAt the API returns is a UTC date. On this UTC+8 box the two are a day apart, so the window reserves a bucket for local-today that cannot fill until midnight UTC, and drops the oldest real day off the other end. Measured against the live data just now: 51 open PRs, and the local window counts 40 of them where the UTC window counts 50. The day it gains, 2026-08-23, holds 0 PRs. The day it loses, 2026-07-24, holds 10. The peak reads 7/day instead of 10. So this port buckets by UTC, and the two will disagree by design until pr.py is fixed. That is the right way round: a chart headed "last 30d" that silently covers 29 usable days is exactly the failure this repo cares most about. linear.py has the same line and the same problem; the linear port already buckets by UTC, so it is already on the right side of it. The token check was re-run against this widget: two curl invocations caught mid-request, the token in neither argv. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/core/src/lib.rs | 36 + rust/widgets/Cargo.toml | 4 + rust/widgets/src/bin/pr.rs | 2083 ++++++++++++++++++++++++++++++ rust/widgets/src/bin/pr_help.txt | 17 + rust/widgets/src/bin/start.rs | 5 + 5 files changed, 2145 insertions(+) create mode 100644 rust/widgets/src/bin/pr.rs create mode 100644 rust/widgets/src/bin/pr_help.txt diff --git a/rust/core/src/lib.rs b/rust/core/src/lib.rs index 0375b1a..c6b0693 100644 --- a/rust/core/src/lib.rs +++ b/rust/core/src/lib.rs @@ -717,6 +717,27 @@ pub fn cycle(choices: &[T], current: T) -> T { choices[(at + 1) % choices.len()] } +/// A placeholder bar with a highlight sweeping across it. +/// +/// For values that are being refetched: showing the previous number while a +/// new one is in flight states something false, and blanking the row makes +/// the layout jump. A shimmering grey bar says "pending" without either. +pub fn skeleton(width: usize, tick: usize, span: usize) -> Vec<(String, String)> { + let period = width + span * 2; + let centre = (tick % period) as f64 - span as f64; + let mut out: Vec<(String, String)> = Vec::new(); + for i in 0..width { + let near = (1.0 - (i as f64 - centre).abs() / span as f64).max(0.0); + let level = (58.0 + near * 118.0) as u8; + let colour = rgb(level, level, level.saturating_add(8)); + match out.last_mut() { + Some((had, run)) if *had == colour => run.push('█'), + _ => out.push((colour, "█".to_string())), + } + } + out +} + /// Which of these required commands are not on PATH. pub fn missing(programs: &[&str]) -> Vec { let path = std::env::var("PATH").unwrap_or_default(); @@ -997,6 +1018,21 @@ mod tests { assert_ne!(dance(4, 7, 0.0), dance(4, 8, 0.0)); } + #[test] + fn the_shimmer_covers_its_width_and_moves() { + let drawn = |tick: usize| -> String { + skeleton(20, tick, 7).iter().map(|(_, t)| t.clone()).collect() + }; + // Always exactly its width, whatever the phase: the row it stands + // in for has a fixed size. + for tick in 0..40 { + assert_eq!(drawn(tick).chars().count(), 20, "at tick {}", tick); + } + // And the highlight actually travels, or it is just a grey bar. + let runs = |tick: usize| skeleton(20, tick, 7).len(); + assert!((0..40).map(runs).collect::>().len() > 1); + } + #[test] fn a_blend_reaches_both_ends() { assert_eq!(mix((0, 0, 0), (10, 20, 30), 0.0), rgb(0, 0, 0)); diff --git a/rust/widgets/Cargo.toml b/rust/widgets/Cargo.toml index efae7bb..3dab38b 100644 --- a/rust/widgets/Cargo.toml +++ b/rust/widgets/Cargo.toml @@ -52,3 +52,7 @@ path = "src/bin/start.rs" [[bin]] name = "linear" path = "src/bin/linear.rs" + +[[bin]] +name = "pr" +path = "src/bin/pr.rs" diff --git a/rust/widgets/src/bin/pr.rs b/rust/widgets/src/bin/pr.rs new file mode 100644 index 0000000..3c60fde --- /dev/null +++ b/rust/widgets/src/bin/pr.rs @@ -0,0 +1,2083 @@ +// terminal-toys - small dependency-free terminal widgets +// Copyright (C) 2026 William Li +// +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU Affero General Public License as published +// by the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU Affero General Public License for more details. +// +// You should have received a copy of the GNU Affero General Public License +// along with this program. If not, see . + +//! Every open pull request you can see, and what is holding each one up. +//! +//! A port of pr.py. GitHub's search has no OR, so anything that is a union +//! of conditions is several searches merged; each source remembers which +//! PRs it found, so narrowing to one costs no request. + +use std::collections::{HashMap, HashSet}; +use std::sync::{Arc, Condvar, Mutex}; +use std::time::{Duration, SystemTime, UNIX_EPOCH}; + +use chrono::{NaiveDateTime, Utc}; +use toys_core as tc; + +const API: &str = "https://api.github.com/graphql"; +const SORTS: &[&str] = &["updated", "created"]; +const SPINNER: &[char] = &['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']; +const SPARK: &[char] = &['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█']; +/// Width of the opened-per-day chart. +const OPENED_DAYS: i64 = 30; + +fn now() -> f64 { + SystemTime::now() + .duration_since(UNIX_EPOCH) + .map(|d| d.as_secs_f64()) + .unwrap_or(0.0) +} + +/// The GitHub token, shared with github.py rather than duplicated. +fn token(pr_cfg: &serde_json::Value, gh_cfg: &serde_json::Value) -> (String, &'static str) { + for cfg in [pr_cfg, gh_cfg] { + let value = tc::cfg_str(cfg, "token", ""); + if !value.is_empty() { + return (value, "config"); + } + } + let name = tc::cfg_str(pr_cfg, "token_env", "GITHUB_TOKEN"); + let name = if name.is_empty() { "GITHUB_TOKEN".into() } else { name }; + match std::env::var(&name) { + Ok(value) if !value.is_empty() => (value, "env"), + _ => (String::new(), "missing"), + } +} + +#[derive(Clone, Copy, Default)] +struct Rate { + remaining: Option, +} + +fn graphql( + query: &str, + tok: &str, + variables: serde_json::Value, +) -> Result { + let body = serde_json::json!({ "query": query, "variables": variables }).to_string(); + let (out, _headers) = tc::post_json( + API, + &[ + ("Authorization", &format!("Bearer {}", tok)), + ("Content-Type", "application/json"), + ("User-Agent", "terminal-toys"), + ], + &body, + 45, + )?; + let data: serde_json::Value = serde_json::from_str(&out).map_err(|e| e.to_string())?; + if let Some(first) = data["errors"].as_array().and_then(|a| a.first()) { + return Err(first["message"] + .as_str() + .unwrap_or("") + .chars() + .take(100) + .collect()); + } + Ok(data["data"].clone()) +} + +const PR_FIELDS: &str = " + number title url isDraft createdAt updatedAt + additions deletions changedFiles + author { login } + repository { nameWithOwner } + headRefName baseRefName reviewDecision mergeable + stackEntry { position stack { number size } } + commits(last: 1) { nodes { commit { statusCheckRollup { state } } } }"; + +/// One request, one aliased search per source. +/// +/// The ceiling is on result nodes rather than field complexity: three +/// searches of 100 return HTTP 502 with or without the check rollup, three +/// of 50 do not. So the page size is per source and deliberately modest. +fn list_query(queries: &[String], limit: usize) -> String { + let mut parts = vec!["rateLimit { remaining }".to_string()]; + for (i, q) in queries.iter().enumerate() { + parts.push(format!( + "s{}: search(query: {}, type: ISSUE, first: {}) {{ issueCount nodes {{ ... on PullRequest {{ {} }} }} }}", + i, + serde_json::Value::String(q.clone()), + limit, + PR_FIELDS + )); + } + format!("{{ {} }}", parts.join(" ")) +} + +const DETAIL_QUERY: &str = r#" +query($owner: String!, $name: String!, $number: Int!) { + repository(owner: $owner, name: $name) { + pullRequest(number: $number) { + number title url state isDraft createdAt updatedAt + additions deletions changedFiles + author { login } headRefName baseRefName + mergeable mergeStateStatus reviewDecision + commitCount: commits { totalCount } + stack { number size baseRefName + entries(first: 40) { nodes { position pullRequest { + number title isDraft reviewDecision mergeable + additions deletions author { login } headRefName } } } } + reviewThreads(first: 60) { nodes { isResolved } } + reviews(last: 20) { nodes { author { login } state submittedAt } } + reviewRequests(first: 12) { nodes { requestedReviewer { + ... on User { login } ... on Team { name } } } } + commits(last: 1) { nodes { commit { statusCheckRollup { + state contexts(first: 25) { nodes { + ... on CheckRun { name conclusion status startedAt completedAt } + ... on StatusContext { context state } } } } } } } + } + } +}"#; + +/// Every open PR in one repository, for reconstructing a stack that was not +/// made with `gh stack` - the API's own stack field is authoritative when +/// it is there, and null everywhere else. +const REPO_PRS_QUERY: &str = r#" +query($owner: String!, $name: String!) { + repository(owner: $owner, name: $name) { + pullRequests(states: OPEN, first: 100) { + nodes { number title isDraft headRefName baseRefName + additions deletions author { login } + reviewDecision mergeable } + } + } +}"#; + +fn text(value: &serde_json::Value, key: &str) -> String { + value[key].as_str().unwrap_or("").to_string() +} + +fn number(value: &serde_json::Value, key: &str) -> i64 { + value[key].as_i64().unwrap_or(0) +} + +fn parse(ts: &str) -> Option { + if ts.len() < 19 { + return None; + } + NaiveDateTime::parse_from_str(&ts[..19], "%Y-%m-%dT%H:%M:%S").ok() +} + +fn hours_since(ts: &str) -> Option { + let when = parse(ts)?; + Some((Utc::now().naive_utc() - when).num_seconds() as f64 / 3600.0) +} + +fn ago(ts: &str) -> String { + let Some(hours) = hours_since(ts) else { + return "--".into(); + }; + let s = hours * 3600.0; + if s < 3600.0 { + format!("{}m", ((s / 60.0) as i64).max(1)) + } else if s < 86400.0 { + format!("{}h", (s / 3600.0) as i64) + } else if s < 86400.0 * 365.0 { + format!("{}d", (s / 86400.0) as i64) + } else { + format!("{:.1}y", s / (86400.0 * 365.0)) + } +} + +fn span(hours: Option) -> String { + let Some(h) = hours else { + return "--".into(); + }; + if h < 48.0 { + return format!("{}h", h as i64); + } + let days = h / 24.0; + if days < 365.0 { + format!("{}d", days as i64) + } else { + format!("{:.1}y", days / 365.0) + } +} + +fn rollup(pr: &serde_json::Value) -> String { + pr["commits"]["nodes"] + .as_array() + .and_then(|a| a.first()) + .map(|n| text(&n["commit"]["statusCheckRollup"], "state")) + .unwrap_or_default() +} + +/// Approved, green, no conflict, not a draft - the actionable count. +/// +/// Everything else on this board describes work in flight; this is the one +/// number that says something can be done right now. +fn ready_to_merge(pr: &serde_json::Value) -> bool { + let checks = rollup(pr); + text(pr, "reviewDecision") == "APPROVED" + && (checks == "SUCCESS" || checks.is_empty()) + && text(pr, "mergeable") != "CONFLICTING" + && !pr["isDraft"].as_bool().unwrap_or(false) +} + +/// The chain this PR belongs to, reconstructed from branch names. +/// +/// A PR whose base branch is another open PR's head branch is sitting on +/// top of it. That inference produces a tree rather than a line, so each PR +/// keeps its list of children. +type Chain = (Option, HashMap, HashMap>); + +fn stack_of(number: i64, repo_prs: &[serde_json::Value]) -> Chain { + let mut by_head: HashMap = HashMap::new(); + for other in repo_prs { + by_head.insert(text(other, "headRefName"), self::number(other, "number")); + } + let mut parent: HashMap = HashMap::new(); + let mut kids: HashMap> = HashMap::new(); + for other in repo_prs { + let mine = self::number(other, "number"); + if let Some(up) = by_head.get(&text(other, "baseRefName")) { + if *up != mine { + parent.insert(mine, *up); + kids.entry(*up).or_default().push(mine); + } + } + } + if !parent.contains_key(&number) && !kids.contains_key(&number) { + return (None, HashMap::new(), HashMap::new()); + } + let mut root = number; + let mut seen: HashSet = HashSet::new(); + while let Some(up) = parent.get(&root) { + if !seen.insert(root) { + break; + } + root = *up; + } + (Some(root), parent, kids) +} + +/// A row of the stack map: connector, the PR, whether it is the open one, +/// and its position when GitHub gave one. +type StackRow = (String, serde_json::Value, bool, Option); + +/// What the open is actually doing, so the wait can show real work. +#[derive(Clone)] +struct Stage { + label: String, + done: bool, + t0: f64, + took: f64, +} + +#[derive(Default)] +struct State { + viewer: String, + orgs: Vec, + prs: Vec, + total: usize, + query: String, + detail: Option, + stack_rows: Vec, + want: Option<(String, String, i64)>, + loading: bool, + target: String, + stages: Vec, + err: String, + fetched: f64, +} + +impl State { + fn stage(&mut self, label: &str, done: bool) -> f64 { + if let Some(st) = self.stages.iter_mut().find(|s| s.label == label) { + st.done = done; + st.took = now() - st.t0; + return st.t0; + } + let t0 = now(); + self.stages.push(Stage { + label: label.to_string(), + done, + t0, + took: 0.0, + }); + t0 + } +} + +/// Each configured source, with `@mine` expanded and args appended. +/// +/// Repeated qualifiers of the same kind are OR'd by GitHub, so one search +/// covers every org and your own account at once; relationships that reach +/// outside them - authored, assigned - need their own. +fn searches( + sources: &[(String, String)], + viewer: &str, + orgs: &[String], + extra: &[String], +) -> Vec<(String, String)> { + let mut mine: Vec = orgs.iter().map(|o| format!("org:{}", o)).collect(); + if !viewer.is_empty() { + mine.push(format!("user:{}", viewer)); + } + let mine = mine.join(" "); + sources + .iter() + .map(|(name, q)| { + let mut parts = vec![q.replace("@mine", &mine)]; + parts.extend(extra.iter().cloned()); + (name.clone(), parts.join(" ")) + }) + .collect() +} + +fn fetch_detail( + tok: &str, + want: &(String, String, i64), + state: &Arc>, +) -> Result<(), String> { + let (owner, name, num) = want; + let t0 = state + .lock() + .map(|mut g| g.stage("pull request, checks, reviews", false)) + .unwrap_or(0.0); + let d = graphql( + DETAIL_QUERY, + tok, + serde_json::json!({ "owner": owner, "name": name, "number": num }), + )?; + if let Ok(mut g) = state.lock() { + g.stage("pull request, checks, reviews", true); + let _ = t0; + } + let pr = d["repository"]["pullRequest"].clone(); + let mut rows: Vec = Vec::new(); + if !pr.is_null() { + let native = &pr["stack"]; + if !native.is_null() { + if let Ok(mut g) = state.lock() { + g.stage("stack, from GitHub", true); + } + // GitHub hands the order over directly, position 1 nearest the + // base. A native stack is a line, not a tree, so it draws flat - + // eleven levels of indentation would be unreadable and would + // imply a branching that is not there. + let mut entries: Vec = native["entries"]["nodes"] + .as_array() + .cloned() + .unwrap_or_default(); + entries.sort_by_key(|e| number(e, "position")); + let last = entries.len().saturating_sub(1); + for (i, e) in entries.iter().enumerate() { + let child = e["pullRequest"].clone(); + let twig = if i == last { "└─ " } else { "├─ " }; + let is_here = number(&child, "number") == *num; + let position = e["position"].as_i64(); + rows.push((twig.to_string(), child, is_here, position)); + } + } else { + if let Ok(mut g) = state.lock() { + g.stage("stack, from open branches", false); + } + let repo = graphql( + REPO_PRS_QUERY, + tok, + serde_json::json!({ "owner": owner, "name": name }), + )?; + if let Ok(mut g) = state.lock() { + g.stage("stack, from open branches", true); + } + let others: Vec = repo["repository"]["pullRequests"]["nodes"] + .as_array() + .cloned() + .unwrap_or_default(); + let (root, _parent, kids) = stack_of(*num, &others); + if let Some(root) = root { + let by_num: HashMap = + others.iter().map(|o| (number(o, "number"), o)).collect(); + // An inferred stack really is a tree - one PR can have two + // others branched off it - so the connectors are drawn + // properly rather than indenting by depth alone. + let mut stack = vec![(root, String::new(), true)]; + while let Some((num_at, prefix, last)) = stack.pop() { + if let Some(node) = by_num.get(&num_at) { + rows.push(( + format!("{}{}", prefix, if last { "└─ " } else { "├─ " }), + (*node).clone(), + num_at == *num, + None, + )); + } + let mut children = kids.get(&num_at).cloned().unwrap_or_default(); + children.sort_unstable(); + let below = format!("{}{}", prefix, if last { " " } else { "│ " }); + for (i, kid) in children.iter().enumerate().rev() { + stack.push((*kid, below.clone(), i + 1 == children.len())); + } + } + } + } + } + if let Ok(mut g) = state.lock() { + g.detail = if pr.is_null() { None } else { Some(pr) }; + g.stack_rows = rows; + g.loading = false; + } + Ok(()) +} + +fn fetch_list( + tok: &str, + source: &str, + sources: &[(String, String)], + extra: &[String], + limit: usize, + state: &Arc>, + rate: &Arc>, +) -> Result<(), String> { + let need_viewer = state.lock().map(|g| g.viewer.is_empty()).unwrap_or(true); + if need_viewer { + let who = graphql( + "{ viewer { login organizations(first:20) { nodes { login } } } }", + tok, + serde_json::json!({}), + )?; + if let Ok(mut g) = state.lock() { + g.viewer = text(&who["viewer"], "login"); + g.orgs = who["viewer"]["organizations"]["nodes"] + .as_array() + .into_iter() + .flatten() + .map(|o| text(o, "login")) + .collect(); + } + } + let (viewer, orgs) = state + .lock() + .map(|g| (g.viewer.clone(), g.orgs.clone())) + .unwrap_or_default(); + let pairs = searches(sources, &viewer, &orgs, extra); + let queries: Vec = pairs.iter().map(|(_, q)| q.clone()).collect(); + let d = graphql(&list_query(&queries, limit), tok, serde_json::json!({}))?; + if let Some(left) = d["rateLimit"]["remaining"].as_i64() { + if let Ok(mut g) = rate.lock() { + g.remaining = Some(left); + } + } + // Pool the sources, remembering which found each PR and noting when a + // source filled its page, so a truncated union is not read as a total. + let mut pool: HashMap = HashMap::new(); + let mut order: Vec = Vec::new(); + for (i, (name, _)) in pairs.iter().enumerate() { + let block = &d[format!("s{}", i)]; + let got: Vec<&serde_json::Value> = block["nodes"] + .as_array() + .into_iter() + .flatten() + .filter(|n| !n.is_null()) + .collect(); + for n in got { + let url = text(n, "url"); + let entry = pool.entry(url.clone()).or_insert_with(|| { + order.push(url.clone()); + let mut copy = n.clone(); + copy["sources"] = serde_json::Value::Array(Vec::new()); + copy + }); + if let Some(list) = entry["sources"].as_array_mut() { + list.push(serde_json::Value::String(name.clone())); + } + } + } + let nodes: Vec = order + .into_iter() + .filter_map(|url| pool.remove(&url)) + .collect(); + if let Ok(mut g) = state.lock() { + g.query = pairs + .iter() + .map(|(n, _)| n.clone()) + .collect::>() + .join(", "); + g.total = nodes.len(); + g.prs = nodes; + g.fetched = now(); + g.err = if source == "config" { + tc::config_token_warning().unwrap_or_default() + } else { + String::new() + }; + } + Ok(()) +} + +struct Palette { + ok: String, + warn: String, + bad: String, + dim: String, + grid: String, + txt: String, + lbl: String, + accent: String, + pr: String, +} + +fn palette() -> Palette { + Palette { + ok: tc::rgb(90, 240, 160), + warn: tc::rgb(255, 200, 90), + bad: tc::rgb(255, 100, 110), + dim: tc::rgb(127, 147, 172), + grid: tc::rgb(60, 78, 98), + txt: tc::rgb(225, 235, 245), + lbl: tc::rgb(130, 165, 200), + accent: tc::rgb(150, 210, 255), + pr: tc::rgb(180, 160, 255), + } +} + +fn review_label<'a>(decision: &str, p: &'a Palette) -> (&'static str, &'a str) { + match decision { + "APPROVED" => ("approved", &p.ok), + "CHANGES_REQUESTED" => ("changes", &p.bad), + "REVIEW_REQUIRED" => ("needs review", &p.warn), + _ => ("—", &p.dim), + } +} + +fn check_label<'a>(state: &str, p: &'a Palette) -> (&'static str, &'a str) { + match state { + "SUCCESS" => ("pass", &p.ok), + "FAILURE" | "ERROR" => ("FAIL", &p.bad), + "PENDING" => ("running", &p.warn), + "EXPECTED" => ("waiting", &p.dim), + _ => ("—", &p.dim), + } +} + +fn merge_label<'a>(state: &str, p: &'a Palette) -> (&'static str, &'a str) { + match state { + "CLEAN" => ("ready", &p.ok), + "DIRTY" => ("CONFLICT", &p.bad), + "BLOCKED" => ("blocked", &p.warn), + "BEHIND" => ("behind", &p.warn), + "UNSTABLE" => ("checks failing", &p.warn), + "HAS_HOOKS" | "UNKNOWN" => ("checking", &p.dim), + _ => ("—", &p.dim), + } +} + +fn matches(pr: &serde_json::Value, needle: &str) -> bool { + if needle.is_empty() { + return true; + } + let hay = [ + number(pr, "number").to_string(), + text(pr, "title"), + text(&pr["author"], "login"), + text(&pr["repository"], "nameWithOwner"), + text(pr, "headRefName"), + text(pr, "baseRefName"), + ] + .join(" ") + .to_lowercase(); + hay.contains(&needle.to_lowercase()) +} + +fn sort_prs(prs: &[serde_json::Value], field: &str, newest_first: bool) -> Vec { + let key = if field == "updated" { "updatedAt" } else { "createdAt" }; + let mut out = prs.to_vec(); + out.sort_by(|a, b| { + let (x, y) = (text(a, key), text(b, key)); + if newest_first { y.cmp(&x) } else { x.cmp(&y) } + }); + out +} + +fn main() { + tc::maybe_help(include_str!("pr_help.txt")); + let cfg = tc::load_config("pr"); + let gh = tc::load_config("github"); + let mut refresh = tc::cfg_f64(&cfg, "refresh", 60.0); + let limit = tc::cfg_usize(&cfg, "limit", 50); + // GitHub search has no OR, so anything that is a union of conditions has + // to be several searches merged. + let sources: Vec<(String, String)> = match cfg.get("sources").and_then(|v| v.as_object()) { + Some(map) => map + .iter() + .map(|(k, v)| (k.clone(), v.as_str().unwrap_or("").to_string())) + .collect(), + None => vec![ + ("orgs".into(), "is:open is:pr @mine".into()), + ("authored".into(), "is:open is:pr author:@me".into()), + ("assigned".into(), "is:open is:pr assignee:@me".into()), + ], + }; + + let args: Vec = std::env::args().skip(1).collect(); + let mut extra: Vec = Vec::new(); + let mut i = 0; + while i < args.len() { + match args[i].as_str() { + "-n" | "--refresh" if i + 1 < args.len() => { + refresh = args[i + 1].parse().unwrap_or(60.0); + i += 2; + } + other if !other.starts_with('-') => { + extra.push(other.to_string()); + i += 1; + } + _ => i += 1, + } + } + + let absent = tc::missing(&["curl"]); + if !absent.is_empty() { + tc::cannot_start( + "pr watch", + &absent, + &[ + "Everything here comes from GitHub's GraphQL API, and curl is", + "how this reaches it - the same way the other widgets reach", + "ss, ping and tailscale.", + "", + "The token is passed to curl on its standard input rather than", + "in its arguments, because /proc//cmdline is readable by", + "every user on the machine.", + ], + "apt install curl", + ); + return; + } + + let p = palette(); + let state = Arc::new(Mutex::new(State::default())); + let rate = Arc::new(Mutex::new(Rate::default())); + let wake = Arc::new((Mutex::new(false), Condvar::new())); + let (tok, source) = token(&cfg, &gh); + + let poller = Arc::clone(&state); + let poller_wake = Arc::clone(&wake); + let poller_rate = Arc::clone(&rate); + let poll_tok = tok.clone(); + let poll_sources = sources.clone(); + let poll_extra = extra.clone(); + std::thread::spawn(move || loop { + if poll_tok.is_empty() { + if let Ok(mut g) = poller.lock() { + g.err = "no token: set github.token in config.json or $GITHUB_TOKEN".into(); + } + } else { + let want = poller.lock().ok().and_then(|g| { + let have = g.detail.as_ref().map(|d| number(d, "number")); + match &g.want { + Some(w) if Some(w.2) != have => Some(w.clone()), + _ => None, + } + }); + let mut failed = None; + if let Some(want) = want { + if let Err(said) = fetch_detail(&poll_tok, &want, &poller) { + failed = Some(said); + } + } + if failed.is_none() { + if let Err(said) = fetch_list( + &poll_tok, + source, + &poll_sources, + &poll_extra, + limit, + &poller, + &poller_rate, + ) { + failed = Some(said); + } + } + if let Some(said) = failed { + if let Ok(mut g) = poller.lock() { + g.err = said; + g.loading = false; + } + } + } + let (lock, cond) = &*poller_wake; + let mut asked = match lock.lock() { + Ok(g) => g, + Err(_) => return, + }; + if !*asked { + asked = match cond.wait_timeout(asked, Duration::from_secs_f64(refresh)) { + Ok((g, _)) => g, + Err(_) => return, + }; + } + *asked = false; + }); + + tc::setup(); + let mut keyboard = tc::Keyboard::new(); + let (mut selected, mut tick, mut stack_sel) = (0usize, 0usize, 0usize); + let mut sort_at = 0usize; + let mut newest_first = true; + let (mut needle, mut typing) = (String::new(), false); + let mut show_stats = true; + let mut copied: (String, f64) = (String::new(), 0.0); + let mut source_filter = "all".to_string(); + let filter_names: Vec = std::iter::once("all".to_string()) + .chain(sources.iter().map(|(n, _)| n.clone())) + .collect(); + + let nudge = |wake: &Arc<(Mutex, Condvar)>| { + let (lock, cond) = &**wake; + if let Ok(mut asked) = lock.lock() { + *asked = true; + cond.notify_all(); + } + }; + + loop { + tick += 1; + let (prs, total, detail, stack_rows, loading, err, fetched, stages, target) = + match state.lock() { + Ok(g) => ( + g.prs.clone(), + g.total, + g.detail.clone(), + g.stack_rows.clone(), + g.loading, + g.err.clone(), + g.fetched, + g.stages.clone(), + g.target.clone(), + ), + Err(_) => return, + }; + let shown: Vec = sort_prs(&prs, SORTS[sort_at], newest_first) + .into_iter() + .filter(|pr| matches(pr, &needle)) + .filter(|pr| { + source_filter == "all" + || pr["sources"] + .as_array() + .into_iter() + .flatten() + .any(|s| s.as_str() == Some(source_filter.as_str())) + }) + .collect(); + + for key in keyboard.poll() { + if typing { + // While filtering, keys are text - only escape and enter are + // navigation, or the filter could never contain "q". + match key.as_str() { + "esc" => { + needle.clear(); + typing = false; + } + "enter" => typing = false, + "backspace" => { + needle.pop(); + } + other if other.chars().count() == 1 => needle.push_str(other), + _ => {} + } + continue; + } + match key.as_str() { + "q" | "Q" => { + keyboard.restore(); + tc::restore_screen(); + return; + } + "/" => typing = true, + "esc" => { + if detail.is_some() || loading { + if let Ok(mut g) = state.lock() { + g.want = None; + g.detail = None; + g.stack_rows.clear(); + g.loading = false; + g.stages.clear(); + } + stack_sel = 0; + } else { + needle.clear(); + } + } + "enter" => { + if let Some(open) = &detail { + if !stack_rows.is_empty() { + // Walk the stack from inside it: the row under + // the cursor becomes the PR on screen. + let node = &stack_rows[stack_sel.min(stack_rows.len() - 1)].1; + let url = text(open, "url"); + let parts: Vec<&str> = url.split('/').collect(); + if parts.len() >= 5 && number(node, "number") != number(open, "number") + { + if let Ok(mut g) = state.lock() { + g.want = Some(( + parts[3].to_string(), + parts[4].to_string(), + number(node, "number"), + )); + g.detail = None; + g.stack_rows.clear(); + g.loading = true; + g.target = + format!("{}/{} #{}", parts[3], parts[4], number(node, "number")); + g.stages.clear(); + } + stack_sel = 0; + nudge(&wake); + } + } + } else if !shown.is_empty() && !loading { + let pick = &shown[selected.min(shown.len() - 1)]; + let full = text(&pick["repository"], "nameWithOwner"); + if let Some((owner, name)) = full.split_once('/') { + if let Ok(mut g) = state.lock() { + g.want = + Some((owner.into(), name.into(), number(pick, "number"))); + g.detail = None; + g.stack_rows.clear(); + g.loading = true; + g.target = format!("{} #{}", full, number(pick, "number")); + g.stages.clear(); + } + nudge(&wake); + } + } + } + "c" | "C" => { + // The URL of whatever is on screen: the open PR in the + // dashboard, the highlighted row in the list. + let url = match &detail { + Some(d) => text(d, "url"), + None => shown + .get(selected.min(shown.len().saturating_sub(1))) + .map(|pr| text(pr, "url")) + .unwrap_or_default(), + }; + if !url.is_empty() { + copied = ( + if tc::clipboard(&url) { + url + } else { + format!("no clipboard: {}", url) + }, + now(), + ); + } + } + "r" | "R" => nudge(&wake), + "f" | "F" => { + // Every PR remembers which sources found it, so + // narrowing to one is instant and costs no request. + let at = filter_names + .iter() + .position(|n| *n == source_filter) + .unwrap_or(0); + source_filter = filter_names[(at + 1) % filter_names.len()].clone(); + } + "s" | "S" => sort_at = (sort_at + 1) % SORTS.len(), + "o" | "O" => newest_first = !newest_first, + "t" | "T" => show_stats = !show_stats, + "up" => { + if detail.is_some() { + stack_sel = stack_sel.saturating_sub(1); + } else { + selected = selected.saturating_sub(1); + } + } + "down" => { + if detail.is_some() { + stack_sel += 1; + } else { + selected += 1; + } + } + _ => {} + } + } + + let (w, h) = tc::size(); + let mut rows = vec![tc::title("pr watch", w, &p.pr)]; + let mut head = vec![ + (p.dim.as_str(), format!(" {} of {}", shown.len(), total)), + ( + p.dim.as_str(), + if !needle.is_empty() || source_filter != "all" { + " shown".to_string() + } else { + " open".to_string() + }, + ), + ( + p.dim.as_str(), + format!( + " updated {} ago", + if fetched > 0.0 { + let s = now() - fetched; + if s < 3600.0 { + format!("{}m", ((s / 60.0) as i64).max(1)) + } else { + format!("{}h", (s / 3600.0) as i64) + } + } else { + "--".into() + } + ), + ), + ]; + if let Some(left) = rate.lock().map(|g| g.remaining).unwrap_or(None) { + head.push((p.dim.as_str(), format!(" {} api", left))); + } + if !copied.0.is_empty() && now() - copied.1 < 4.0 { + head.push((p.ok.as_str(), " copied ".into())); + head.push(( + p.dim.as_str(), + copied.0.chars().take(w.saturating_sub(46).max(10)).collect(), + )); + } + rows.push(tc::seg(&head, w - 1)); + if !err.is_empty() { + rows.push(tc::seg(&[(p.bad.as_str(), format!(" ! {}", err))], w - 1)); + } + + let hints: Vec> = if detail.is_some() || loading { + let mut stack_sel_clamped = stack_sel; + if !stack_rows.is_empty() { + stack_sel_clamped = stack_sel.min(stack_rows.len() - 1); + stack_sel = stack_sel_clamped; + } + let top = rows.len(); + rows.extend(detail_view( + detail.as_ref(), + &stack_rows, + stack_sel_clamped, + loading, + w, + h, + tick, + &stages, + &target, + top, + &p, + )); + let mut hints: Vec> = Vec::new(); + if !stack_rows.is_empty() { + hints.push(vec![ + (p.accent.as_str(), "↑↓".into()), + (p.dim.as_str(), " stack".into()), + ]); + hints.push(vec![(p.dim.as_str(), "[↵] open it".into())]); + } + hints.push(vec![(p.dim.as_str(), "[c]opy url".into())]); + hints.push(vec![(p.dim.as_str(), "[esc] back".into())]); + hints.push(vec![(p.dim.as_str(), "[r]efresh".into())]); + hints.push(vec![(p.dim.as_str(), "[q]uit".into())]); + hints + } else { + if !shown.is_empty() && selected >= shown.len() { + selected = shown.len() - 1; + } + // The stats cost eight rows; below thirty they would leave the + // list too short to be a list, so they stand down without asking. + if show_stats && h >= 30 { + // Every open PR, not `shown`: the filter is a search of the + // board, not a redefinition of it. + rows.extend(stats_view( + &sort_prs(&prs, SORTS[sort_at], newest_first), + w, + &p, + )); + } + let top = rows.len(); + rows.extend(list_view( + &shown, + selected, + SORTS[sort_at], + newest_first, + &needle, + w, + h, + fetched == 0.0, + &source_filter, + top, + &p, + )); + vec![ + vec![(p.accent.as_str(), "↑↓".into()), (p.dim.as_str(), " select".into())], + vec![(p.dim.as_str(), "[↵] open".into())], + vec![(p.dim.as_str(), "[/]filter".into())], + vec![(p.dim.as_str(), format!("[s]ort {}", SORTS[sort_at]))], + vec![( + p.dim.as_str(), + format!("[o]rder {}", if newest_first { "newest" } else { "oldest" }), + )], + vec![(p.dim.as_str(), format!("[f]rom {}", source_filter))], + vec![( + p.dim.as_str(), + format!("[t]stats {}", if show_stats { "on" } else { "off" }), + )], + vec![(p.dim.as_str(), "[c]opy url".into())], + vec![(p.dim.as_str(), "[r]efresh".into())], + vec![(p.dim.as_str(), "[q]uit".into())], + ] + }; + let hints = if typing { + vec![ + vec![(p.accent.as_str(), format!("/{}▌", needle))], + vec![(p.dim.as_str(), "[↵] keep".into())], + vec![(p.dim.as_str(), "[esc] clear".into())], + ] + } else { + hints + }; + let footer: Vec = tc::pack_hints(&hints, w - 2, " ") + .into_iter() + .map(|l| format!(" {}", l)) + .collect(); + rows.truncate(h.saturating_sub(footer.len())); + while rows.len() < h.saturating_sub(footer.len()) { + rows.push(String::new()); + } + rows.extend(footer); + tc::draw(&rows, w, h); + std::thread::sleep(Duration::from_millis(300)); + } +} + +/// Shape and age of every open PR, whatever the list is filtered to. +/// +/// Deliberately not the filtered set. Typing in the filter is a search, and +/// a search should not move the backlog it is searching: watching the age +/// median and the state bar lurch on every keystroke made them unreadable +/// and, worse, made them look like statements about the whole board when +/// they described three matching rows. +fn stats_view(prs: &[serde_json::Value], w: usize, p: &Palette) -> Vec { + let mut rows = vec![String::new()]; + if prs.is_empty() { + return rows; + } + let n = prs.len(); + let mut review: HashMap<&str, usize> = HashMap::new(); + let mut checks: HashMap<&str, usize> = HashMap::new(); + let (mut drafts, mut conflicts, mut ready) = (0usize, 0usize, 0usize); + for pr in prs { + let decision = text(pr, "reviewDecision"); + let slot = match decision.as_str() { + "APPROVED" => "APPROVED", + "CHANGES_REQUESTED" => "CHANGES_REQUESTED", + "REVIEW_REQUIRED" => "REVIEW_REQUIRED", + _ => "", + }; + *review.entry(slot).or_insert(0) += 1; + let state = rollup(pr); + let slot = match state.as_str() { + "SUCCESS" => "SUCCESS", + "FAILURE" => "FAILURE", + "PENDING" => "PENDING", + _ => "other", + }; + *checks.entry(slot).or_insert(0) += 1; + if pr["isDraft"].as_bool().unwrap_or(false) { + drafts += 1; + } + if text(pr, "mergeable") == "CONFLICTING" { + conflicts += 1; + } + if ready_to_merge(pr) { + ready += 1; + } + } + + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── STATE ── ".into()), + (p.txt.as_str(), format!("{}", n)), + (p.dim.as_str(), " open · ".into()), + (p.dim.as_str(), format!("{} draft", drafts)), + (p.dim.as_str(), " · ".into()), + ( + if conflicts > 0 { p.bad.as_str() } else { p.dim.as_str() }, + format!("{} conflicting", conflicts), + ), + (p.dim.as_str(), " · ".into()), + ( + if ready > 0 { p.ok.as_str() } else { p.dim.as_str() }, + format!("{} ready to merge", ready), + ), + ], + w - 1, + )); + let order: Vec<(&str, &str)> = vec![ + ("APPROVED", p.ok.as_str()), + ("CHANGES_REQUESTED", p.bad.as_str()), + ("REVIEW_REQUIRED", p.warn.as_str()), + ("", p.dim.as_str()), + ]; + let parts: Vec<(f64, String)> = order + .iter() + .filter_map(|(k, c)| { + let got = review.get(k).copied().unwrap_or(0); + if got == 0 { + return None; + } + Some((got as f64 / n as f64, c.to_string())) + }) + .collect(); + let bar = tc::stacked_bar(&parts, w.saturating_sub(3).max(10)); + let mut line: Vec<(&str, String)> = vec![(tc::RST, " ".into())]; + for (colour, txt) in &bar { + line.push((colour.as_str(), txt.clone())); + } + rows.push(tc::seg(&line, w - 1)); + let mut key: Vec<(&str, String)> = vec![(tc::RST, " ".into())]; + for (k, colour) in &order { + let got = review.get(k).copied().unwrap_or(0); + if got == 0 { + continue; + } + key.push((colour, "▇ ".into())); + key.push((p.txt.as_str(), review_label(k, p).0.into())); + key.push((p.dim.as_str(), format!(" {} ", got))); + } + for (k, colour, label) in [ + ("SUCCESS", p.ok.as_str(), "checks pass"), + ("FAILURE", p.bad.as_str(), "checks FAIL"), + ("PENDING", p.warn.as_str(), "running"), + ] { + let got = checks.get(k).copied().unwrap_or(0); + if got == 0 { + continue; + } + key.push((colour, "· ".into())); + key.push((p.txt.as_str(), label.into())); + key.push((p.dim.as_str(), format!(" {} ", got))); + } + rows.push(tc::seg(&key, w - 1)); + + let mut ages: Vec<(f64, &serde_json::Value)> = prs + .iter() + .filter_map(|pr| hours_since(&text(pr, "createdAt")).map(|h| (h, pr))) + .collect(); + ages.sort_by(|a, b| a.0.total_cmp(&b.0)); + let idles: Vec<(f64, &serde_json::Value)> = prs + .iter() + .filter_map(|pr| hours_since(&text(pr, "updatedAt")).map(|h| (h, pr))) + .collect(); + + // When the open ones arrived. + let today = Utc::now().date_naive(); + let days: Vec = (0..OPENED_DAYS) + .rev() + .map(|k| (today - chrono::Duration::days(k)).format("%Y-%m-%d").to_string()) + .collect(); + let mut per_day: HashMap<&String, usize> = days.iter().map(|d| (d, 0)).collect(); + let mut inside = 0usize; + for pr in prs { + let key: String = text(pr, "createdAt").chars().take(10).collect(); + if let Some(slot) = days.iter().find(|d| **d == key) { + *per_day.get_mut(slot).unwrap() += 1; + inside += 1; + } + } + let avail = w.saturating_sub(3).max(10); + let slot = (avail / days.len()).max(1); + let gap = if slot >= 3 { 1 } else { 0 }; + let barw = slot - gap; + let mut cols: Vec<(f64, String)> = Vec::new(); + for (i, d) in days.iter().enumerate() { + let value = per_day.get(d).copied().unwrap_or(0) as f64; + cols.extend(std::iter::repeat_n((value, p.pr.clone()), barw)); + if gap > 0 && i + 1 < days.len() { + cols.extend(std::iter::repeat_n((0.0, p.pr.clone()), gap)); + } + } + let peak = per_day.values().copied().max().unwrap_or(0); + rows.push(String::new()); + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── OPENED / DAY ── ".into()), + (p.dim.as_str(), format!("last {}d · ", OPENED_DAYS)), + (p.txt.as_str(), format!("{}", inside)), + (p.dim.as_str(), format!(" of {} still open · ", n)), + (p.dim.as_str(), format!("peak {}/day", peak)), + ], + w - 1, + )); + if peak > 0 { + for line in tc::vbars(&cols, 3, 0.0) { + let mut parts: Vec<(&str, String)> = vec![(tc::RST, " ".into())]; + for (colour, ch) in &line { + parts.push((colour.as_str(), ch.clone())); + } + rows.push(tc::seg(&parts, w - 1)); + } + rows.push(tc::seg( + &[(tc::RST, " ".into()), (p.grid.as_str(), "─".repeat(cols.len()))], + w - 1, + )); + let left = format!("{}d ago", OPENED_DAYS); + rows.push(tc::seg( + &[ + (p.dim.as_str(), format!(" {}", left)), + ( + p.dim.as_str(), + " ".repeat(cols.len().saturating_sub(left.len() + 5).max(1)), + ), + (p.dim.as_str(), "today".into()), + ], + w - 1, + )); + } else { + rows.push(tc::seg( + &[( + p.dim.as_str(), + format!( + " none of the open PRs were opened in the last {}d", + OPENED_DAYS + ), + )], + w - 1, + )); + } + + let at = |pairs: &[(f64, &serde_json::Value)], frac: f64| -> Option { + if pairs.is_empty() { + return None; + } + let mut vals: Vec = pairs.iter().map(|x| x.0).collect(); + vals.sort_by(f64::total_cmp); + Some(vals[((vals.len() as f64 * frac) as usize).min(vals.len() - 1)]) + }; + rows.push(String::new()); + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── AGE ── ".into()), + (p.dim.as_str(), "median ".into()), + (p.txt.as_str(), span(at(&ages, 0.5))), + (p.dim.as_str(), " p95 ".into()), + (p.txt.as_str(), span(at(&ages, 0.95))), + (p.dim.as_str(), " max ".into()), + (p.warn.as_str(), span(at(&ages, 1.0))), + (p.dim.as_str(), " idle median ".into()), + (p.txt.as_str(), span(at(&idles, 0.5))), + ], + w - 1, + )); + if !ages.is_empty() { + // One bar per open PR, youngest left to oldest right - the x axis is + // rank, not time. It fills the pane and carries a baseline and end + // labels, because a sparkline that stops in the middle of the screen + // gives no way to tell where the chart ends and the blank begins. + let room = w.saturating_sub(3).max(10); + let drawn: &[(f64, &serde_json::Value)] = if ages.len() > room { + &ages[ages.len() - room..] + } else { + &ages + }; + // Spread the remainder across the leftmost bars so the chart reaches + // the right edge exactly: stopping short of it left no way to tell a + // finished chart from a truncated one. + let (slot, extra) = if drawn.len() >= room { + (1, 0) + } else { + (room / drawn.len(), room % drawn.len()) + }; + let hi = drawn.iter().map(|x| x.0).fold(0.0f64, f64::max).max(1.0); + let mut bars = String::new(); + for (i, (hours, _)) in drawn.iter().enumerate() { + let wide_bar = slot + usize::from(i < extra); + let level = ((hours / hi) * 7.99) as usize; + for _ in 0..wide_bar { + bars.push(SPARK[level.min(7)]); + } + } + let count = bars.chars().count(); + rows.push(tc::seg( + &[(tc::RST, " ".into()), (&tc::heat(0.4), bars)], + w - 1, + )); + rows.push(tc::seg( + &[(tc::RST, " ".into()), (p.grid.as_str(), "─".repeat(count))], + w - 1, + )); + let left = format!("youngest {}", span(Some(drawn[0].0))); + let right = format!("oldest {}", span(Some(drawn[drawn.len() - 1].0))); + let note = if drawn.len() < ages.len() { + format!("{} of {} PRs", drawn.len(), ages.len()) + } else { + format!("{} PRs", drawn.len()) + }; + let mid = count + .saturating_sub(left.len() + right.len() + note.len() + 2) + .max(1); + rows.push(tc::seg( + &[ + (p.dim.as_str(), format!(" {}", left)), + (p.dim.as_str(), " ".repeat(mid / 2)), + (p.grid.as_str(), note), + (p.dim.as_str(), " ".repeat(mid - mid / 2 + 2)), + (p.dim.as_str(), right), + ], + w - 1, + )); + } + if let Some(fattest) = prs.iter().max_by_key(|p| number(p, "additions") + number(p, "deletions")) + { + let worst = |pairs: &[(f64, &serde_json::Value)]| -> String { + match pairs.iter().max_by(|a, b| a.0.total_cmp(&b.0)) { + Some((hours, pr)) => { + format!("#{} {}", number(pr, "number"), span(Some(*hours))) + } + None => "--".into(), + } + }; + rows.push(tc::seg( + &[ + (p.dim.as_str(), " oldest ".into()), + (p.warn.as_str(), tc::pad(&worst(&ages), 12)), + (p.dim.as_str(), " untouched longest ".into()), + (p.warn.as_str(), tc::pad(&worst(&idles), 12)), + (p.dim.as_str(), " biggest ".into()), + ( + p.txt.as_str(), + format!( + "#{} +{}/-{}", + number(fattest, "number"), + number(fattest, "additions"), + number(fattest, "deletions") + ), + ), + ], + w - 1, + )); + } + rows +} + +#[allow(clippy::too_many_arguments)] +fn list_view( + prs: &[serde_json::Value], + selected: usize, + sort_field: &str, + newest_first: bool, + needle: &str, + w: usize, + h: usize, + waiting: bool, + source_filter: &str, + top: usize, + p: &Palette, +) -> Vec { + let mut rows = vec![String::new()]; + let arrow = if newest_first { "↓" } else { "↑" }; + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── OPEN PRs ── ".into()), + (p.dim.as_str(), format!("by {} {}", sort_field, arrow)), + ( + p.dim.as_str(), + if source_filter != "all" { + format!(" from {}", source_filter) + } else { + String::new() + }, + ), + ( + p.accent.as_str(), + if needle.is_empty() { + String::new() + } else { + format!(" /{}", needle) + }, + ), + ], + w - 1, + )); + if prs.is_empty() { + // "collecting" is only true before the first fetch: an empty filter + // or an empty source is a result, not a wait. + let why = if !needle.is_empty() { + format!(" nothing matches /{}", needle) + } else if source_filter != "all" { + format!(" no open PRs from {}", source_filter) + } else if waiting { + " collecting…".to_string() + } else { + " no open PRs".to_string() + }; + rows.push(tc::seg(&[(p.dim.as_str(), why)], w - 1)); + return rows; + } + + // Columns are budgeted rather than guessed: the fixed ones are summed + // and the title takes exactly what is left, so nothing runs off the + // right edge or into its neighbour. + let wide = w >= 96; + let repo_w = if wide { 18 } else { 0 }; + let size_w = if wide { 12 } else { 0 }; + let fixed = 8 + repo_w + 13 + 8 + 6 + size_w; + let title_w = (w - 1).saturating_sub(fixed).max(16); + let mut head = format!(" {:<7}", "PR"); + if repo_w > 0 { + head += &format!("{:13}{:>8}{:>6}", + "TITLE", + "REVIEW", + "CHECKS", + when_label, + width = title_w + ); + if size_w > 0 { + head += &format!("{:>width$}", "SIZE", width = size_w); + } + rows.push(tc::seg(&[(p.dim.as_str(), tc::pad(&head, w - 1))], w - 1)); + + // `top` is what was drawn above this view. Without it the window is + // sized as though the list began at the top of the screen, so it renders + // far more rows than are visible, the caller truncates the overflow, and + // the selection scrolls off the bottom while `first` is still 0. + let room = h.saturating_sub(top + rows.len() + 3).max(1); + let first = if prs.len() > room { + selected.saturating_sub(room / 2).min(prs.len() - room) + } else { + 0 + }; + for (i, pr) in prs.iter().enumerate().skip(first).take(room) { + let here = i == selected; + let tint = if here { tc::bg(38, 56, 76) } else { String::new() }; + let c = |colour: &str| format!("{}{}", tint, colour); + let (rlabel, rcol) = review_label(&text(pr, "reviewDecision"), p); + let (clabel, ccol) = check_label(&rollup(pr), p); + let stacked = !pr["stackEntry"].is_null(); + let mut line = vec![( + c(if here { &p.accent } else { &p.pr }), + format!( + "{}{}", + if here { "▸" } else { " " }, + tc::pad(&format!("#{}", number(pr, "number")), 7) + ), + )]; + if repo_w > 0 { + // Clipped one short of the column so it never touches the title. + let full = text(&pr["repository"], "nameWithOwner"); + let repo = full.rsplit('/').next().unwrap_or("").to_string(); + line.push(( + c(&p.dim), + tc::pad( + &repo.chars().take(repo_w - 1).collect::(), + repo_w, + ), + )); + } + let mut name = format!( + "{}{}", + if stacked { "⣿ " } else { "" }, + text(pr, "title") + ); + if pr["isDraft"].as_bool().unwrap_or(false) { + name = format!("draft · {}", name); + } + line.push(( + c(&p.txt), + tc::pad( + &name.chars().take(title_w - 1).collect::(), + title_w, + ), + )); + line.push((c(rcol), format!("{:>13}", rlabel))); + line.push((c(ccol), format!("{:>8}", clabel))); + line.push(( + c(&p.dim), + format!( + "{:>6}", + ago(&text( + pr, + if sort_field == "created" { "createdAt" } else { "updatedAt" } + )) + ), + )); + if size_w > 0 { + line.push(( + c(&p.dim), + format!( + "{:>width$}", + format!("+{}/-{}", number(pr, "additions"), number(pr, "deletions")), + width = size_w + ), + )); + } + if here { + line.push((tint.clone(), " ".repeat(w))); + } + let refs: Vec<(&str, String)> = line.iter().map(|(c, t)| (c.as_str(), t.clone())).collect(); + rows.push(tc::seg(&refs, w - 1)); + } + rows +} + +#[allow(clippy::too_many_arguments)] +fn detail_view( + pr: Option<&serde_json::Value>, + stack_rows: &[StackRow], + stack_sel: usize, + loading: bool, + w: usize, + h: usize, + tick: usize, + stages: &[Stage], + target: &str, + top: usize, + p: &Palette, +) -> Vec { + let mut rows = vec![String::new()]; + let Some(pr) = pr.filter(|_| !loading) else { + // A shimmer says "wait" and nothing else. The open really does run + // in stages, so show them: a spinner on the one in flight, a tick + // and a duration on the ones behind it. Honest, and it reads like a + // machine doing something rather than a placeholder. + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── OPENING ── ".into()), + (p.accent.as_str(), target.to_string()), + ], + w - 1, + )); + rows.push(String::new()); + let spin = SPINNER[tick % SPINNER.len()]; + for st in stages { + rows.push(tc::seg( + &[ + ( + if st.done { p.ok.as_str() } else { p.accent.as_str() }, + format!(" {} ", if st.done { '✓' } else { spin }), + ), + ( + if st.done { p.txt.as_str() } else { p.dim.as_str() }, + tc::pad(&st.label, w.saturating_sub(22).max(20)), + ), + ( + p.dim.as_str(), + format!( + "{:>6}", + if st.took > 0.0 { + format!("{:.1}s", st.took) + } else { + String::new() + } + ), + ), + ], + w - 1, + )); + } + if stages.is_empty() { + rows.push(tc::seg( + &[ + (p.accent.as_str(), format!(" {} ", spin)), + (p.dim.as_str(), "connecting".into()), + ], + w - 1, + )); + } + rows.push(String::new()); + // One sweeping line rather than four fat bars of shimmer. + let shimmer = tc::skeleton(w.saturating_sub(6).max(10), tick * 2, 7); + let mut line: Vec<(&str, String)> = vec![(tc::RST, " ".into())]; + for (colour, txt) in &shimmer { + line.push((colour.as_str(), txt.clone())); + } + rows.push(tc::seg(&line, w - 1)); + return rows; + }; + + let draft = if pr["isDraft"].as_bool().unwrap_or(false) { + " · draft" + } else { + "" + }; + rows.push(tc::seg( + &[ + (p.pr.as_str(), format!(" #{} ", number(pr, "number"))), + ( + p.txt.as_str(), + text(pr, "title") + .chars() + .take(w.saturating_sub(24).max(10)) + .collect::(), + ), + (p.dim.as_str(), draft.into()), + ], + w - 1, + )); + rows.push(tc::seg( + &[ + (p.dim.as_str(), " ".into()), + ( + p.dim.as_str(), + match text(&pr["author"], "login") { + s if s.is_empty() => "?".into(), + s => s, + }, + ), + (p.dim.as_str(), " ".into()), + (p.accent.as_str(), text(pr, "headRefName")), + (p.dim.as_str(), " → ".into()), + (p.accent.as_str(), text(pr, "baseRefName")), + ], + w - 1, + )); + + let (rlabel, rcol) = review_label(&text(pr, "reviewDecision"), p); + let (mlabel, mcol) = merge_label(&text(pr, "mergeStateStatus"), p); + let unresolved = pr["reviewThreads"]["nodes"] + .as_array() + .into_iter() + .flatten() + .filter(|t| !t["isResolved"].as_bool().unwrap_or(false)) + .count(); + rows.push(String::new()); + let cells: Vec<(String, String, &str)> = vec![ + ("review".into(), rlabel.into(), rcol), + ("merge".into(), mlabel.into(), mcol), + ( + "unresolved threads".into(), + unresolved.to_string(), + if unresolved > 0 { p.bad.as_str() } else { p.ok.as_str() }, + ), + ( + "size".into(), + format!( + "+{}/-{} in {} files", + number(pr, "additions"), + number(pr, "deletions"), + number(pr, "changedFiles") + ), + p.txt.as_str(), + ), + ( + "commits".into(), + number(&pr["commitCount"], "totalCount").to_string(), + p.txt.as_str(), + ), + ( + "opened / updated".into(), + format!( + "{} ago / {} ago", + ago(&text(pr, "createdAt")), + ago(&text(pr, "updatedAt")) + ), + p.txt.as_str(), + ), + ]; + let label_w = cells.iter().map(|c| c.0.len()).max().unwrap_or(8); + let ncols = if (w - 2) / 2 >= label_w + 3 + 18 { 2 } else { 1 }; + let cw = (w - 2) / ncols; + let val_w = cw.saturating_sub(label_w + 3).max(6); + for chunk in cells.chunks(ncols) { + let mut line: Vec<(&str, String)> = vec![(tc::RST, " ".into())]; + for (label, value, colour) in chunk { + line.push((p.dim.as_str(), format!(" {} ", tc::pad(label, label_w)))); + line.push((colour, tc::pad(value, val_w))); + } + rows.push(tc::seg(&line, w - 1)); + } + + // Who has looked at it. The last state per person wins: someone who + // requested changes and later approved has approved, and showing both + // would misreport the gate. + let mut latest: HashMap = HashMap::new(); + for r in pr["reviews"]["nodes"].as_array().into_iter().flatten() { + let who = text(&r["author"], "login"); + if !who.is_empty() { + latest.insert(who, text(r, "state")); + } + } + let mut pending: Vec = Vec::new(); + for n in pr["reviewRequests"]["nodes"].as_array().into_iter().flatten() { + let who = &n["requestedReviewer"]; + let name = match text(who, "login") { + s if !s.is_empty() => s, + _ => text(who, "name"), + }; + if !name.is_empty() && !latest.contains_key(&name) { + pending.push(name); + } + } + let pick = |state: &str| -> Vec { + let mut out: Vec = latest + .iter() + .filter(|(_, v)| *v == state) + .map(|(k, _)| k.clone()) + .collect(); + out.sort(); + out + }; + let groups: Vec<(&str, &str, Vec)> = vec![ + ("approved", p.ok.as_str(), pick("APPROVED")), + ("changes requested", p.bad.as_str(), pick("CHANGES_REQUESTED")), + ("commented", p.dim.as_str(), pick("COMMENTED")), + ("awaiting", p.warn.as_str(), { + pending.sort(); + pending.clone() + }), + ]; + rows.push(String::new()); + let live: Vec<&(&str, &str, Vec)> = groups.iter().filter(|g| !g.2.is_empty()).collect(); + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── REVIEWERS ── ".into()), + ( + p.dim.as_str(), + if live.is_empty() { + "nobody has been asked".to_string() + } else { + live.iter() + .map(|g| format!("{} {}", g.2.len(), g.0)) + .collect::>() + .join(" · ") + }, + ), + ], + w - 1, + )); + for (label, colour, who) in &live { + rows.push(tc::seg( + &[ + (p.dim.as_str(), format!(" {}", tc::pad(label, 18))), + ( + colour, + who.join(", ") + .chars() + .take(w.saturating_sub(24).max(10)) + .collect::(), + ), + ], + w - 1, + )); + } + + let roll = pr["commits"]["nodes"] + .as_array() + .and_then(|a| a.first()) + .map(|n| n["commit"]["statusCheckRollup"].clone()) + .unwrap_or(serde_json::Value::Null); + rows.push(String::new()); + if roll.is_null() { + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── CHECKS ── ".into()), + (p.dim.as_str(), "none on the last commit".into()), + ], + w - 1, + )); + } else { + let (state, scol) = check_label(&text(&roll, "state"), p); + let ctx: Vec<&serde_json::Value> = roll["contexts"]["nodes"] + .as_array() + .into_iter() + .flatten() + .filter(|c| !c.is_null()) + .collect(); + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── CHECKS ── ".into()), + (scol, state.into()), + (p.dim.as_str(), format!(" {} total", ctx.len())), + ], + w - 1, + )); + let verdict_of = |c: &serde_json::Value| -> String { + for key in ["conclusion", "state", "status"] { + let v = text(c, key); + if !v.is_empty() { + return v; + } + } + String::new() + }; + let is_bad = |c: &serde_json::Value| -> bool { + let v = verdict_of(c); + !matches!(v.as_str(), "SUCCESS" | "NEUTRAL" | "SKIPPED" | "") + }; + // Failures first: a green wall of passing checks is not why anyone + // opens this view. + let ordered: Vec<&&serde_json::Value> = ctx + .iter() + .filter(|c| is_bad(c)) + .chain(ctx.iter().filter(|c| !is_bad(c))) + .collect(); + for c in ordered.into_iter().take(8) { + let name = match text(c, "name") { + s if !s.is_empty() => s, + _ => match text(c, "context") { + s if !s.is_empty() => s, + _ => "?".into(), + }, + }; + let verdict = verdict_of(c); + let (lab, col) = check_label(&verdict, p); + let lab = if lab == "—" && !verdict.is_empty() { + verdict.to_lowercase() + } else { + lab.to_string() + }; + let took = match ( + parse(&text(c, "startedAt")), + parse(&text(c, "completedAt")), + ) { + (Some(a), Some(b)) => format!("{}s", (b - a).num_seconds()), + _ => String::new(), + }; + rows.push(tc::seg( + &[ + (p.dim.as_str(), " ".into()), + (p.txt.as_str(), tc::pad(&name, w.saturating_sub(30).max(12))), + (col, format!("{:>10}", lab)), + (p.dim.as_str(), format!("{:>8}", took)), + ], + w - 1, + )); + } + } + + if !stack_rows.is_empty() { + let native = !pr["stack"].is_null(); + rows.push(String::new()); + // The stack scrolls: eleven-deep stacks exist, and a pane that has + // already spent its height on checks cannot show them all. + let room = h.saturating_sub(top + rows.len() + 4).max(3); + let first = if stack_rows.len() > room { + stack_sel.saturating_sub(room / 2).min(stack_rows.len() - room) + } else { + 0 + }; + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── STACK ── ".into()), + ( + p.dim.as_str(), + format!( + "{} pull requests · {}", + stack_rows.len(), + if native { "from GitHub" } else { "inferred from branches" } + ), + ), + ( + p.accent.as_str(), + if stack_rows.len() > room { + format!( + " ↑↓ {}-{} of {}", + first + 1, + (first + room).min(stack_rows.len()), + stack_rows.len() + ) + } else { + String::new() + }, + ), + ], + w - 1, + )); + rows.push(tc::seg( + &[ + (p.dim.as_str(), " merge bottom-up: ".into()), + (p.txt.as_str(), "the one nearest the base branch first".into()), + (p.dim.as_str(), " ▸ cursor · ● on screen".into()), + ], + w - 1, + )); + let base = if native { + text(&pr["stack"], "baseRefName") + } else { + text(pr, "baseRefName") + }; + rows.push(tc::seg( + &[ + (p.dim.as_str(), " ".into()), + ( + p.accent.as_str(), + if base.is_empty() { "trunk".into() } else { base }, + ), + ], + w - 1, + )); + for (idx, (twig, node, is_here, position)) in + stack_rows.iter().enumerate().skip(first).take(room) + { + let (lab, col) = review_label(&text(node, "reviewDecision"), p); + let (mlab, mcol) = match text(node, "mergeable").as_str() { + "CONFLICTING" => ("CONFLICT", p.bad.as_str()), + "MERGEABLE" => ("ok", p.ok.as_str()), + _ => ("…", p.dim.as_str()), + }; + let on_cursor = idx == stack_sel; + let tint = if on_cursor { tc::bg(38, 56, 76) } else { String::new() }; + let c = |colour: &str| format!("{}{}", tint, colour); + let mut name = text(node, "title"); + if let Some(pos) = position { + name = format!("{}. {}", pos, name); + } + // Two gutter marks, because they answer different questions: ▸ + // is where the cursor is, ● is the PR actually on screen. One + // symbol plus a colour could not say both. + let gutter = format!( + "{}{}", + if on_cursor { "▸" } else { " " }, + if *is_here { "●" } else { " " } + ); + let name_w = w + .saturating_sub(34 + twig.chars().count()) + .max(10); + let mut line = vec![ + (c(if on_cursor { &p.accent } else { &p.dim }), gutter), + (c(&p.dim), twig.clone()), + ( + c(if on_cursor { &p.accent } else { &p.pr }), + format!("#{:<5} ", number(node, "number")), + ), + ( + c(if *is_here || on_cursor { &p.txt } else { &p.dim }), + tc::pad(&name.chars().take(name_w).collect::(), name_w), + ), + (c(col), format!("{:>13}", lab)), + (c(mcol), format!("{:>10}", mlab)), + ]; + if on_cursor { + line.push((tint.clone(), " ".repeat(w))); + } + let refs: Vec<(&str, String)> = + line.iter().map(|(c, t)| (c.as_str(), t.clone())).collect(); + rows.push(tc::seg(&refs, w - 1)); + } + } + rows +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn ready_means_nothing_is_left_to_do() { + let pr = |json: &str| -> serde_json::Value { serde_json::from_str(json).unwrap() }; + let green = pr(r#"{"reviewDecision": "APPROVED", "mergeable": "MERGEABLE", + "commits": {"nodes": [{"commit": {"statusCheckRollup": {"state": "SUCCESS"}}}]}}"#); + assert!(ready_to_merge(&green)); + // A repo with no CI at all still counts: no checks is not a failing + // check, and holding those back would empty the one actionable + // number on the board. + let no_ci = pr(r#"{"reviewDecision": "APPROVED", "mergeable": "MERGEABLE"}"#); + assert!(ready_to_merge(&no_ci)); + // Every one of the four gates on its own is enough to hold it. + assert!(!ready_to_merge(&pr( + r#"{"reviewDecision": "REVIEW_REQUIRED", "mergeable": "MERGEABLE"}"# + ))); + assert!(!ready_to_merge(&pr( + r#"{"reviewDecision": "APPROVED", "mergeable": "CONFLICTING"}"# + ))); + assert!(!ready_to_merge(&pr( + r#"{"reviewDecision": "APPROVED", "isDraft": true}"# + ))); + assert!(!ready_to_merge(&pr( + r#"{"reviewDecision": "APPROVED", + "commits": {"nodes": [{"commit": {"statusCheckRollup": {"state": "FAILURE"}}}]}}"# + ))); + } + + #[test] + fn a_stack_is_inferred_from_where_the_branches_sit() { + // main <- a <- b, and c also on a: a tree rather than a line. + let prs: Vec = serde_json::from_str( + r#"[{"number": 1, "headRefName": "a", "baseRefName": "main"}, + {"number": 2, "headRefName": "b", "baseRefName": "a"}, + {"number": 3, "headRefName": "c", "baseRefName": "a"}]"#, + ) + .unwrap(); + let (root, parent, kids) = stack_of(2, &prs); + assert_eq!(root, Some(1)); + assert_eq!(parent.get(&2), Some(&1)); + let mut branched = kids.get(&1).cloned().unwrap_or_default(); + branched.sort_unstable(); + assert_eq!(branched, vec![2, 3]); + // A PR that neither sits on another nor carries one has no stack, + // rather than a stack of itself. + let lone: Vec = serde_json::from_str( + r#"[{"number": 9, "headRefName": "x", "baseRefName": "main"}]"#, + ) + .unwrap(); + assert_eq!(stack_of(9, &lone).0, None); + } + + #[test] + fn a_cycle_of_branches_does_not_hang_the_walk() { + // Two PRs each based on the other's branch. It should not happen, + // and the walk must still finish. + let prs: Vec = serde_json::from_str( + r#"[{"number": 1, "headRefName": "a", "baseRefName": "b"}, + {"number": 2, "headRefName": "b", "baseRefName": "a"}]"#, + ) + .unwrap(); + let (root, _, _) = stack_of(1, &prs); + assert!(root.is_some()); + } + + #[test] + fn mine_expands_to_every_org_plus_the_account() { + let sources = vec![ + ("orgs".to_string(), "is:open is:pr @mine".to_string()), + ("authored".to_string(), "is:open is:pr author:@me".to_string()), + ]; + let out = searches(&sources, "wiiiimm", &["acme".into(), "beta".into()], &[]); + assert_eq!(out[0].1, "is:open is:pr org:acme org:beta user:wiiiimm"); + // A source that does not mention @mine is left alone. + assert_eq!(out[1].1, "is:open is:pr author:@me"); + // Extra arguments are appended to every source. + let with = searches(&sources, "w", &[], &["repo:x/y".into()]); + assert!(with[1].1.ends_with("repo:x/y")); + } + + #[test] + fn the_filter_looks_at_everything_on_the_row() { + let pr: serde_json::Value = serde_json::from_str( + r#"{"number": 42, "title": "Fix the thing", + "author": {"login": "wiiiimm"}, + "repository": {"nameWithOwner": "acme/widgets"}, + "headRefName": "fix/thing", "baseRefName": "main"}"#, + ) + .unwrap(); + for needle in ["42", "thing", "WIIIIMM", "widgets", "fix/", "main"] { + assert!(matches(&pr, needle), "{} did not match", needle); + } + assert!(!matches(&pr, "nonsense")); + // No filter matches everything, rather than nothing. + assert!(matches(&pr, "")); + } + + #[test] + fn a_span_rolls_over_before_it_stops_reading() { + assert_eq!(span(None), "--"); + assert_eq!(span(Some(5.0)), "5h"); + assert_eq!(span(Some(72.0)), "3d"); + assert_eq!(span(Some(24.0 * 400.0)), "1.1y"); + } +} diff --git a/rust/widgets/src/bin/pr_help.txt b/rust/widgets/src/bin/pr_help.txt new file mode 100644 index 0000000..a14b680 --- /dev/null +++ b/rust/widgets/src/bin/pr_help.txt @@ -0,0 +1,17 @@ +Watch the pull requests you have to follow up on. + +A list of open PRs, and a dashboard for whichever one is selected: checks, +reviews, mergeability, and - when the PR belongs to a stack - the stack it +sits in and the order that stack has to merge in. + + pr [-n SECONDS] [search terms ...] + +Extra arguments are appended to the search, so `pr.py org:acme` narrows to one +organisation and `pr.py author:@me` to your own. With none given it uses +`pr.query` from config, which defaults to everything you are involved in. + +Credentials: reuses `github.token` from config.json, or $GITHUB_TOKEN. A +classic token with `repo` and `read:org`, the same one github.py uses. + +Keys: up/down select, enter opens a PR, esc goes back, / filters, s cycles the +sort, o reverses it, r refreshes, q quits. diff --git a/rust/widgets/src/bin/start.rs b/rust/widgets/src/bin/start.rs index 1a541c0..0b18df0 100644 --- a/rust/widgets/src/bin/start.rs +++ b/rust/widgets/src/bin/start.rs @@ -83,6 +83,11 @@ const WIDGETS: &[Widget] = &[ help: include_str!("ports_help.txt"), doc: include_str!("../../../../docs/ports.md"), }, + Widget { + stem: "pr", + help: include_str!("pr_help.txt"), + doc: include_str!("../../../../docs/pr.md"), + }, ]; impl Widget { From daef40be811558713a656b511c8d1a5a9475c847 Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sun, 23 Aug 2026 04:11:24 +0800 Subject: [PATCH 029/147] github: throughput across every account, counted rather than sampled Twelfth widget. Every figure comes from an aliased search's issueCount rather than from reading nodes, because a search connection returns at most 100 nodes a page - a busy fortnight lost everything past the hundredth record, and the merged series sorted by update time, so those hundred were not even the hundredth most recent. A count is exact at any volume and an aliased request costs one rate-limit point however many searches are packed into it. Two things carried over that are easy to lose. The day cache: a past day cannot change, so only days never seen before plus the trailing two cost a request - widening the window buys only the days it adds, and narrowing is free. And the two-phase pass: aggregates for every account first, so the headline is live in seconds, then the per-day counts, which can cost fifty requests on a cold 90-day window and would otherwise hold the whole board grey for minutes. Rows carry the window they were fetched for, so a half-updated board shows one account's real numbers beside another's shimmer rather than summing two windows together. The scope warning is the part worth having: a classic token without `repo` still searches happily and just returns public results, so every number comes back smaller with nothing to say it did. That is worse than an error, so it is named. A fine-grained token sends no scope header at all, and the check says nothing rather than guessing. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/widgets/Cargo.toml | 4 + rust/widgets/src/bin/github.rs | 1426 ++++++++++++++++++++++++++ rust/widgets/src/bin/github_help.txt | 25 + rust/widgets/src/bin/start.rs | 5 + 4 files changed, 1460 insertions(+) create mode 100644 rust/widgets/src/bin/github.rs create mode 100644 rust/widgets/src/bin/github_help.txt diff --git a/rust/widgets/Cargo.toml b/rust/widgets/Cargo.toml index 3dab38b..dee84a9 100644 --- a/rust/widgets/Cargo.toml +++ b/rust/widgets/Cargo.toml @@ -56,3 +56,7 @@ path = "src/bin/linear.rs" [[bin]] name = "pr" path = "src/bin/pr.rs" + +[[bin]] +name = "github" +path = "src/bin/github.rs" diff --git a/rust/widgets/src/bin/github.rs b/rust/widgets/src/bin/github.rs new file mode 100644 index 0000000..473d443 --- /dev/null +++ b/rust/widgets/src/bin/github.rs @@ -0,0 +1,1426 @@ +// terminal-toys - small dependency-free terminal widgets +// Copyright (C) 2026 William Li +// +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU Affero General Public License as published +// by the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU Affero General Public License for more details. +// +// You should have received a copy of the GNU Affero General Public License +// along with this program. If not, see . + +//! Pull request throughput across every account you can see. +//! +//! A port of github.py. Counted with aliased searches rather than by +//! reading nodes: a search connection returns at most 100 nodes a page, so +//! a busy fortnight lost everything past the hundredth record, while an +//! issueCount is exact at any volume and costs one rate-limit point per +//! request however many are packed into it. + +use std::collections::HashMap; +use std::sync::{Arc, Condvar, Mutex}; +use std::time::{Duration, SystemTime, UNIX_EPOCH}; + +use chrono::{Duration as Days, NaiveDate, Utc}; +use toys_core as tc; + +const API: &str = "https://api.github.com/graphql"; +const WINDOWS: &[i64] = &[7, 14, 30, 60, 90]; +/// A full year, like the calendar on github.com. +const CONTRIB_WEEKS: i64 = 52; +/// Two searches a day; the alias ceiling sits between 60 and 90. +const DAY_CHUNK: usize = 20; +/// Trailing days to always refetch: today is still running, and the search +/// index lags a little behind a merge. +const FRESH_DAYS: usize = 2; +const SETTLE_FRAMES: usize = 8; +const SPARK: &[char] = &['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█']; +const WEEKDAYS: &[&str] = &["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"]; +const GHOST: (u8, u8, u8) = (96, 106, 124); +const PR_RGB: (u8, u8, u8) = (180, 160, 255); +const OK_RGB: (u8, u8, u8) = (90, 240, 160); + +fn now() -> f64 { + SystemTime::now() + .duration_since(UNIX_EPOCH) + .map(|d| d.as_secs_f64()) + .unwrap_or(0.0) +} + +/// A GitHub token from config.json or the environment. +/// +/// Deliberately not shelled out to the `gh` CLI: this widget talks to the +/// API directly and should not require another program to be installed, +/// logged in and current just to read a number. +fn token(cfg: &serde_json::Value) -> (String, &'static str) { + let from_config = tc::cfg_str(cfg, "token", ""); + if !from_config.is_empty() { + return (from_config, "config"); + } + let name = tc::cfg_str(cfg, "token_env", "GITHUB_TOKEN"); + let name = if name.is_empty() { "GITHUB_TOKEN".into() } else { name }; + match std::env::var(&name) { + Ok(value) if !value.is_empty() => (value, "env"), + _ => (String::new(), "missing"), + } +} + +/// What the token is allowed to see, read off the response headers. +#[derive(Default, Clone)] +struct Scopes { + seen: bool, + have: Vec, +} + +fn graphql( + query: &str, + tok: &str, + scopes: &Arc>, +) -> Result { + let body = serde_json::json!({ "query": query }).to_string(); + let (text, headers) = tc::post_json( + API, + &[ + ("Authorization", &format!("Bearer {}", tok)), + ("Content-Type", "application/json"), + ("User-Agent", "terminal-toys"), + ], + &body, + 30, + )?; + for (name, value) in &headers { + // Absent on fine-grained tokens, which is itself information: a + // header that never arrives means the check cannot be made. + if name == "x-oauth-scopes" { + if let Ok(mut g) = scopes.lock() { + g.seen = true; + g.have = value + .split(',') + .map(|s| s.trim().to_string()) + .filter(|s| !s.is_empty()) + .collect(); + } + } + } + serde_json::from_str(&text).map_err(|e| e.to_string()) +} + +/// Flag a token that will undercount rather than fail. +/// +/// A classic token without `repo` still searches happily - it just returns +/// public results only, so every figure comes back smaller with nothing to +/// say it did. Without `read:org` the account list comes back short the +/// same way. Both are worse than an error, so name them. +fn scope_warning(scopes: &Scopes) -> String { + if !scopes.seen { + return String::new(); + } + let missing: Vec<&str> = ["repo", "read:org"] + .into_iter() + .filter(|want| !scopes.have.iter().any(|had| had == want)) + .collect(); + if missing.is_empty() { + return String::new(); + } + let why = if missing.contains(&"repo") { + "private repos are not counted" + } else { + "orgs cannot be discovered" + }; + format!("token lacks {} - {}", missing.join(" and "), why) +} + +/// The search qualifier that limits results to a single account. +fn scope_of(acc: &str, viewer: &str) -> String { + if acc == "@me" { + format!("user:{}", viewer) + } else { + format!("org:{}", acc) + } +} + +/// Exact per-day PR counts for one account. +fn build_day_query(q: &str, dates: &[String]) -> String { + let mut parts = vec!["{".to_string()]; + for (n, day) in dates.iter().enumerate() { + parts.push(format!( + "\n m{n}: search(query:\"{q} is:pr is:merged merged:{d}\", type:ISSUE) {{ issueCount }}\ + \n c{n}: search(query:\"{q} is:pr created:{d}\", type:ISSUE) {{ issueCount }}", + n = n, + q = q, + d = day + )); + } + parts.push("\n}".into()); + parts.join("") +} + +/// Metrics for one account in one request. +/// +/// Six aliased searches per account keeps each request within GitHub's +/// complexity limit - asking for seven accounts at once returned HTTP 502 - +/// while still being far fewer round trips than one query per metric. +fn build_query(acc: &str, days: i64, viewer: &str) -> String { + // N days *ending today*, so this spans exactly the dates the per-day + // charts plot - `days` rather than `days - 1` would cover one day more + // and quietly disagree with the chart drawn directly beneath it. + let since = (today() - Days::days(days - 1)).format("%Y-%m-%d").to_string(); + let q = scope_of(acc, viewer); + format!( + r#"{{ + o0_open: search(query:"{q} is:pr is:open", type:ISSUE) {{ issueCount }} + o0_draft: search(query:"{q} is:pr is:open draft:true", type:ISSUE) {{ issueCount }} + o0_review: search(query:"{q} is:pr is:open review:required", type:ISSUE) {{ issueCount }} + o0_merged: search(query:"{q} is:pr is:merged merged:>={s}", type:ISSUE) {{ issueCount }} + o0_dropped: search(query:"{q} is:pr is:unmerged is:closed closed:>={s}", type:ISSUE) {{ issueCount }} + o0_issues: search(query:"{q} is:issue is:open", type:ISSUE) {{ issueCount }} + rateLimit {{ remaining limit }} +}}"#, + q = q, + s = since + ) +} + +/// GitHub's own contribution calendar - the green squares. +/// +/// contributionsCollection is per-viewer rather than per-org, so this is +/// your activity across everything, which is what the calendar means on +/// github.com. +fn contribution_query(weeks: i64) -> String { + let since = (Utc::now() - Days::weeks(weeks)) + .format("%Y-%m-%dT%H:%M:%SZ") + .to_string(); + format!( + r#"{{ viewer {{ contributionsCollection(from:"{}") {{ + contributionCalendar {{ totalContributions + weeks {{ contributionDays {{ date contributionCount weekday }} }} }} }} }} }}"#, + since + ) +} + +/// The calendar day this machine is having, which is what a chart headed +/// "today" has to agree with. +fn today() -> NaiveDate { + chrono::Local::now().date_naive() +} + +fn count_at(d: &serde_json::Value, key: &str) -> i64 { + d[key]["issueCount"].as_i64().unwrap_or(0) +} + +/// One account's row, and the two per-day series behind its chart. +#[derive(Clone, Default)] +struct Account { + key: String, + account: String, + is_me: bool, + /// Which window these figures cover, so a half-updated board cannot sum + /// two windows together. + window: i64, + open: i64, + draft: i64, + review: i64, + issues: i64, + merged: i64, + dropped: i64, + rate: Option, + hist: HashMap, + opened_hist: HashMap, + hist_window: Option, +} + +#[derive(Default)] +struct State { + stats: Vec, + accounts: Vec, + rate: Option<(i64, i64)>, + calendar: Option, + err: String, + fetched: f64, + days: i64, + /// Set by [r]: drop the day cache and refetch even past days. + bust: bool, +} + +fn ago(t: f64) -> String { + if t <= 0.0 { + return "--".into(); + } + let s = now() - t; + if s < 90.0 { + format!("{}s", s as i64) + } else if s < 5400.0 { + format!("{}m", (s / 60.0) as i64) + } else { + format!("{}h", (s / 3600.0) as i64) + } +} + +/// Streaks and totals behind the contribution calendar. +/// +/// A streak is consecutive days carrying at least one contribution, counted +/// the way github.com does it: a day that has scored nothing *so far* does +/// not break the current streak, because it is not over yet. +struct CalendarStats { + today: i64, + current: i64, + longest: i64, + active: usize, + span: usize, + busiest: (String, i64), + weekday: (&'static str, i64), +} + +fn calendar_stats(weeks: &serde_json::Value) -> Option { + let mut days: Vec<(String, i64, usize)> = weeks + .as_array()? + .iter() + .flat_map(|wk| wk["contributionDays"].as_array().into_iter().flatten()) + .map(|d| { + ( + d["date"].as_str().unwrap_or("").to_string(), + d["contributionCount"].as_i64().unwrap_or(0), + d["weekday"].as_u64().unwrap_or(0) as usize, + ) + }) + .collect(); + if days.is_empty() { + return None; + } + days.sort(); + let today_key = today().format("%Y-%m-%d").to_string(); + + let (mut longest, mut run) = (0i64, 0i64); + for (_, count, _) in &days { + run = if *count > 0 { run + 1 } else { 0 }; + longest = longest.max(run); + } + + let mut done: Vec<&(String, i64, usize)> = + days.iter().filter(|(d, _, _)| *d <= today_key).collect(); + if done.last().is_some_and(|(_, c, _)| *c == 0) { + done.pop(); // today is still in progress + } + let mut current = 0i64; + for (_, count, _) in done.iter().rev() { + if *count == 0 { + break; + } + current += 1; + } + + let mut per_weekday: HashMap = HashMap::new(); + for (_, count, wd) in &days { + *per_weekday.entry(*wd).or_insert(0) += count; + } + let top_wd = per_weekday + .iter() + .max_by_key(|(wd, n)| (**n, std::cmp::Reverse(**wd))) + .map(|(wd, _)| *wd) + .unwrap_or(0); + let busiest = days + .iter() + .max_by_key(|(_, c, _)| *c) + .map(|(d, c, _)| (d.clone(), *c)) + .unwrap_or_default(); + Some(CalendarStats { + today: days + .iter() + .find(|(d, _, _)| *d == today_key) + .map(|(_, c, _)| *c) + .unwrap_or(0), + current, + longest, + active: days.iter().filter(|(_, c, _)| *c > 0).count(), + span: days.len(), + busiest, + weekday: ( + WEEKDAYS[top_wd.min(6)], + per_weekday.get(&top_wd).copied().unwrap_or(0), + ), + }) +} + +/// The calendar as seven rows of one cell per week. +fn heatmap(weeks: &serde_json::Value, w: usize) -> (Vec, i64, i64) { + const LEVELS: &[char] = &[' ', '░', '▒', '▓', '█']; + let all: Vec<&serde_json::Value> = weeks.as_array().map(|a| a.iter().collect()).unwrap_or_default(); + let counts: Vec = all + .iter() + .flat_map(|wk| wk["contributionDays"].as_array().into_iter().flatten()) + .map(|d| d["contributionCount"].as_i64().unwrap_or(0)) + .collect(); + let peak = counts.iter().copied().max().unwrap_or(0); + let total: i64 = counts.iter().sum(); + let cols = all.len().min(w.saturating_sub(8)).max(4).min(all.len().max(4)); + let shown = &all[all.len().saturating_sub(cols)..]; + let mut grid = vec![vec![' '; shown.len()]; 7]; + for (x, wk) in shown.iter().enumerate() { + for d in wk["contributionDays"].as_array().into_iter().flatten() { + let n = d["contributionCount"].as_i64().unwrap_or(0); + let wd = (d["weekday"].as_u64().unwrap_or(0) as usize).min(6); + let level = if n == 0 { + 0 + } else { + (1 + (n as f64 / peak.max(1) as f64 * 3.99) as usize).min(4) + }; + grid[wd][x] = LEVELS[level]; + } + } + ( + grid.into_iter().map(|row| row.into_iter().collect()).collect(), + peak, + total, + ) +} + +struct Palette { + ok: String, + warn: String, + bad: String, + dim: String, + grid: String, + txt: String, + lbl: String, + accent: String, + pr: String, +} + +fn palette() -> Palette { + Palette { + ok: tc::rgb(90, 240, 160), + warn: tc::rgb(255, 200, 90), + bad: tc::rgb(255, 100, 110), + dim: tc::rgb(127, 147, 172), + grid: tc::rgb(60, 78, 98), + txt: tc::rgb(225, 235, 245), + lbl: tc::rgb(130, 165, 200), + accent: tc::rgb(150, 210, 255), + pr: tc::rgb(180, 160, 255), + } +} + +#[allow(clippy::too_many_arguments)] +fn one_pass( + tok: &str, + source: &str, + viewer: &mut String, + day_cache: &mut HashMap>, + state: &Arc>, + scopes: &Arc>, +) -> Result<(), String> { + if viewer.is_empty() { + let who = graphql("{ viewer { login } }", tok, scopes)?; + *viewer = who["data"]["viewer"]["login"] + .as_str() + .unwrap_or("") + .to_string(); + } + let mut accounts = state.lock().map(|g| g.accounts.clone()).unwrap_or_default(); + if accounts.is_empty() { + // Every org you belong to, plus your own account. + let d = graphql( + "{ viewer { login organizations(first:20) { nodes { login } } } }", + tok, + scopes, + )?; + accounts = d["data"]["viewer"]["organizations"]["nodes"] + .as_array() + .into_iter() + .flatten() + .map(|o| o["login"].as_str().unwrap_or("").to_string()) + .filter(|s| !s.is_empty()) + .collect(); + accounts.push("@me".into()); + if let Ok(mut g) = state.lock() { + g.accounts = accounts.clone(); + } + } + + // The calendar is best-effort: it is decoration beside the counts, and a + // fine-grained token that cannot read it should not blank the board. + if let Ok(cal) = graphql(&contribution_query(CONTRIB_WEEKS), tok, scopes) { + let found = cal["data"]["viewer"]["contributionsCollection"]["contributionCalendar"].clone(); + if !found.is_null() { + if let Ok(mut g) = state.lock() { + g.calendar = Some(found); + } + } + } + + let (days_now, bust) = match state.lock() { + Ok(mut g) => { + let out = (g.days, g.bust); + g.bust = false; + out + } + Err(_) => return Err("state lock poisoned".into()), + }; + // Start the pass from what is already on screen, keyed by account, so + // rows are replaced in place as each lands instead of the table + // emptying and refilling every pass. + let mut by_acc: HashMap = state + .lock() + .map(|g| g.stats.iter().map(|a| (a.key.clone(), a.clone())).collect()) + .unwrap_or_default(); + let base = today(); + let dates: Vec = (0..days_now) + .rev() + .map(|k| (base - Days::days(k)).format("%Y-%m-%d").to_string()) + .collect(); + let keep_from = (base - Days::days(WINDOWS[WINDOWS.len() - 1] - 1)) + .format("%Y-%m-%d") + .to_string(); + let mut failed: Vec = Vec::new(); + let mut rate: Option<(i64, i64)> = None; + + // Aggregates first, for every account, before any per-day work. One + // request each, so the headline is live in seconds; the day charts below + // can cost fifty requests on a cold 90d window and would otherwise hold + // the whole board grey for minutes. + for acc in &accounts { + let data = match graphql(&build_query(acc, days_now, viewer), tok, scopes) { + Ok(d) => d, + Err(e) => { + failed.push(format!("{} ({})", acc, e.chars().take(20).collect::())); + continue; + } + }; + if let Some(first) = data["errors"].as_array().and_then(|a| a.first()) { + failed.push(format!( + "{} ({})", + acc, + first["message"].as_str().unwrap_or("").chars().take(50).collect::() + )); + continue; + } + let d = &data["data"]; + if let Some(limit) = d["rateLimit"]["limit"].as_i64() { + rate = Some((d["rateLimit"]["remaining"].as_i64().unwrap_or(0), limit)); + } + let (merged, dropped) = (count_at(d, "o0_merged"), count_at(d, "o0_dropped")); + let prev = by_acc.get(acc).cloned().unwrap_or_default(); + by_acc.insert( + acc.clone(), + Account { + key: acc.clone(), + account: if acc == "@me" { viewer.clone() } else { acc.clone() }, + is_me: acc == "@me", + window: days_now, + open: count_at(d, "o0_open"), + draft: count_at(d, "o0_draft"), + review: count_at(d, "o0_review"), + issues: count_at(d, "o0_issues"), + merged, + dropped, + rate: if merged + dropped > 0 { + Some(100.0 * merged as f64 / (merged + dropped) as f64) + } else { + None + }, + hist: prev.hist, + opened_hist: prev.opened_hist, + hist_window: prev.hist_window, + }, + ); + publish(state, &accounts, &by_acc, rate); + } + + // Then the per-day counts. A past day cannot change - a PR merged on the + // 3rd stays merged on the 3rd - so only days never seen before, plus the + // trailing few, cost a request. Widening the window therefore buys only + // the days it adds; narrowing is free. + for acc in &accounts { + if !by_acc.contains_key(acc) { + continue; + } + let cache = day_cache.entry(acc.clone()).or_default(); + if bust { + cache.clear(); + } + let fresh: Vec<&String> = dates.iter().rev().take(FRESH_DAYS).collect(); + let want: Vec = dates + .iter() + .filter(|x| !cache.contains_key(*x) || fresh.contains(x)) + .cloned() + .collect(); + for chunk in want.chunks(DAY_CHUNK) { + let dd = match graphql(&build_day_query(&scope_of(acc, viewer), chunk), tok, scopes) { + Ok(d) => d["data"].clone(), + Err(_) => continue, + }; + for (n, day) in chunk.iter().enumerate() { + cache.insert( + day.clone(), + ( + count_at(&dd, &format!("m{}", n)), + count_at(&dd, &format!("c{}", n)), + ), + ); + } + } + cache.retain(|day, _| *day >= keep_from); // older than any window + if !dates.iter().all(|x| cache.contains_key(x)) { + continue; // a chunk failed; leave it + } + if let Some(row) = by_acc.get_mut(acc) { + row.hist = dates.iter().map(|x| (x.clone(), cache[x].0)).collect(); + row.opened_hist = dates.iter().map(|x| (x.clone(), cache[x].1)).collect(); + row.hist_window = Some(days_now); + } + publish(state, &accounts, &by_acc, rate); + } + + if let Ok(mut g) = state.lock() { + // With nothing else to report, surface a token sitting in a file + // other users on the box can read. + g.err = if !failed.is_empty() { + format!("could not read: {}", failed.join(", ")) + } else { + let warn = scopes.lock().map(|s| scope_warning(&s)).unwrap_or_default(); + if !warn.is_empty() { + warn + } else if source == "config" { + tc::config_token_warning().unwrap_or_default() + } else { + String::new() + } + }; + } + Ok(()) +} + +fn publish( + state: &Arc>, + accounts: &[String], + by_acc: &HashMap, + rate: Option<(i64, i64)>, +) { + if let Ok(mut g) = state.lock() { + g.stats = accounts + .iter() + .filter_map(|a| by_acc.get(a).cloned()) + .collect(); + if rate.is_some() { + g.rate = rate; + } + g.fetched = now(); + } +} + +fn main() { + tc::maybe_help(include_str!("github_help.txt")); + let cfg = tc::load_config("github"); + let mut refresh = tc::cfg_f64(&cfg, "refresh", 120.0); + let configured: Vec = tc::cfg_strings(&cfg, "accounts", &[]); + let start_window = tc::cfg_f64(&cfg, "window_days", 7.0) as i64; + + let args: Vec = std::env::args().skip(1).collect(); + let mut named: Vec = Vec::new(); + let mut i = 0; + while i < args.len() { + match args[i].as_str() { + "-n" | "--refresh" if i + 1 < args.len() => { + refresh = args[i + 1].parse::().unwrap_or(120.0).max(30.0); + i += 2; + } + other if !other.starts_with('-') => { + named.push(other.to_string()); + i += 1; + } + _ => i += 1, + } + } + + let absent = tc::missing(&["curl"]); + if !absent.is_empty() { + tc::cannot_start( + "github ops", + &absent, + &[ + "Everything here comes from GitHub's GraphQL API, and curl is", + "how this reaches it - the same way the other widgets reach", + "ss, ping and tailscale.", + "", + "The token is passed to curl on its standard input rather than", + "in its arguments, because /proc//cmdline is readable by", + "every user on the machine.", + ], + "apt install curl", + ); + return; + } + + let p = palette(); + let state = Arc::new(Mutex::new(State { + accounts: if named.is_empty() { configured } else { named }, + days: start_window, + ..Default::default() + })); + let scopes = Arc::new(Mutex::new(Scopes::default())); + let wake = Arc::new((Mutex::new(false), Condvar::new())); + let (tok, source) = token(&cfg); + let env_name = { + let name = tc::cfg_str(&cfg, "token_env", "GITHUB_TOKEN"); + if name.is_empty() { "GITHUB_TOKEN".to_string() } else { name } + }; + + let poller = Arc::clone(&state); + let poller_wake = Arc::clone(&wake); + let poller_scopes = Arc::clone(&scopes); + std::thread::spawn(move || { + let mut viewer = String::new(); + let mut day_cache: HashMap> = HashMap::new(); + loop { + if tok.is_empty() { + if let Ok(mut g) = poller.lock() { + g.err = format!( + "no token: set github.token in config.json or ${} (needs repo + read:org)", + env_name + ); + } + } else if let Err(said) = one_pass( + &tok, + source, + &mut viewer, + &mut day_cache, + &poller, + &poller_scopes, + ) { + if let Ok(mut g) = poller.lock() { + g.err = said; + } + } + let (lock, cond) = &*poller_wake; + let mut asked = match lock.lock() { + Ok(g) => g, + Err(_) => return, + }; + if !*asked { + asked = match cond.wait_timeout(asked, Duration::from_secs_f64(refresh)) { + Ok((g, _)) => g, + Err(_) => return, + }; + } + *asked = false; + } + }); + + tc::setup(); + let mut keyboard = tc::Keyboard::new(); + let (mut selected, mut tick) = (0usize, 0usize); + let mut settle_t = 0usize; + let mut settle_from: Option<(Vec, Vec)> = None; + + loop { + tick += 1; + for key in keyboard.poll() { + match key.as_str() { + "q" | "Q" => { + keyboard.restore(); + tc::restore_screen(); + return; + } + "r" | "R" => { + // A manual refresh re-reads even past days. + if let Ok(mut g) = state.lock() { + g.bust = true; + } + let (lock, cond) = &*wake; + if let Ok(mut asked) = lock.lock() { + *asked = true; + cond.notify_all(); + } + } + "w" | "W" => { + if let Ok(mut g) = state.lock() { + g.days = tc::cycle(WINDOWS, g.days); + } + let (lock, cond) = &*wake; + if let Ok(mut asked) = lock.lock() { + *asked = true; + cond.notify_all(); + } + } + "up" => selected = selected.saturating_sub(1), + "down" => selected += 1, + _ => {} + } + } + + let (w, h) = tc::size(); + let (mut stats, rate, err, fetched, calendar, want) = match state.lock() { + Ok(g) => ( + g.stats.clone(), + g.rate, + g.err.clone(), + g.fetched, + g.calendar.clone(), + g.days, + ), + Err(_) => return, + }; + // Busiest first: open PRs decide it, and merged-in-window breaks ties + // so an idle backlog ranks below an account of the same size that is + // actually moving. Name last, to keep the order steady frame to frame. + stats.sort_by(|a, b| { + b.open + .cmp(&a.open) + .then(b.merged.cmp(&a.merged)) + .then(a.account.to_lowercase().cmp(&b.account.to_lowercase())) + }); + // Windowed figures are stale until every account has reported for the + // window now selected. The charts are tracked apart from the headline + // because their data costs far more requests and lands well after it. + let stale = stats.is_empty() || stats.iter().any(|x| x.window != want); + let chart_stale = stats.is_empty() || stats.iter().any(|x| x.hist_window != Some(want)); + if !stats.is_empty() && selected >= stats.len() { + selected = stats.len() - 1; + } + + let mut rows = vec![tc::title("github ops", w, &p.pr)]; + let mut head = vec![ + ( + p.dim.as_str(), + format!( + " {} account{}", + stats.len(), + if stats.len() == 1 { "" } else { "s" } + ), + ), + (p.dim.as_str(), format!(" updated {} ago", ago(fetched))), + ]; + if let Some((left, limit)) = rate { + head.push(( + if left > 1000 { p.ok.as_str() } else { p.warn.as_str() }, + format!(" {}/{} api", left, limit), + )); + } + rows.push(tc::seg(&head, w - 1)); + if !err.is_empty() { + rows.push(tc::seg(&[(p.bad.as_str(), format!(" ! {}", err))], w - 1)); + } + if stats.is_empty() { + rows.push(tc::seg(&[(p.dim.as_str(), " collecting…".into())], w - 1)); + tc::draw(&rows, w, h); + std::thread::sleep(Duration::from_millis(400)); + continue; + } + + let sum = |f: fn(&Account) -> i64| -> i64 { stats.iter().map(f).sum() }; + let (open, draft, review, issues, merged, dropped) = ( + sum(|a| a.open), + sum(|a| a.draft), + sum(|a| a.review), + sum(|a| a.issues), + sum(|a| a.merged), + sum(|a| a.dropped), + ); + let rate_pct = if merged + dropped > 0 { + Some(100.0 * merged as f64 / (merged + dropped) as f64) + } else { + None + }; + // What is outstanding right now leads the board: it is the question + // asked most often, and the only section that is not windowed. + if open > 0 { + let ready = (open - draft - review).max(0); + let legend: Vec<(&str, i64, &str)> = [ + ("awaiting review", review, p.warn.as_str()), + ("ready to merge", ready, p.ok.as_str()), + ("draft", draft, p.dim.as_str()), + ] + .into_iter() + .filter(|x| x.1 > 0) + .collect(); + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── OPEN PR STATE ── ".into()), + (p.pr.as_str(), format!("{}", open)), + (p.dim.as_str(), " PRs · ".into()), + (p.warn.as_str(), format!("{}", issues)), + (p.dim.as_str(), " issues open (any age)".into()), + ], + w - 1, + )); + let parts: Vec<(f64, String)> = legend + .iter() + .map(|(_, n, c)| (*n as f64 / open as f64, c.to_string())) + .collect(); + let bar = tc::stacked_bar(&parts, w.saturating_sub(3).max(10)); + let mut line: Vec<(&str, String)> = vec![(tc::RST, " ".into())]; + for (colour, txt) in &bar { + line.push((colour.as_str(), txt.clone())); + } + rows.push(tc::seg(&line, w - 1)); + let mut key: Vec<(&str, String)> = vec![(tc::RST, " ".into())]; + for (label, count, colour) in &legend { + key.push((colour, "▇ ".into())); + key.push((p.txt.as_str(), (*label).into())); + key.push(( + p.dim.as_str(), + format!(" {} ({:.0}%) ", count, 100.0 * *count as f64 / open as f64), + )); + } + rows.push(tc::seg(&key, w - 1)); + } + + rows.push(String::new()); + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── MERGE RATE ── ".into()), + (p.dim.as_str(), format!("last {} days", want)), + ], + w - 1, + )); + let bar_w = w.saturating_sub(34).max(10); + if stale { + let shimmer = tc::skeleton(bar_w, tick, 7); + let mut line: Vec<(&str, String)> = vec![(p.dim.as_str(), format!(" {:<5}", "···"))]; + for (colour, txt) in &shimmer { + line.push((colour.as_str(), txt.clone())); + } + line.push((p.dim.as_str(), format!(" loading {}d…", want))); + rows.push(tc::seg(&line, w - 1)); + } else { + let hot = match rate_pct { + Some(v) => tc::heat(v / 100.0), + None => p.dim.clone(), + }; + rows.push(tc::seg( + &[ + ( + hot.as_str(), + format!( + " {:<5}", + match rate_pct { + Some(v) => format!("{:.0}%", v), + None => "--".into(), + } + ), + ), + (hot.as_str(), tc::meter(rate_pct.unwrap_or(0.0) / 100.0, bar_w)), + (p.ok.as_str(), format!(" {} merged", merged)), + (p.dim.as_str(), " / ".into()), + (p.bad.as_str(), format!("{} dropped", dropped)), + ], + w - 1, + )); + } + + let mut merged_all: HashMap = HashMap::new(); + let mut opened_all: HashMap = HashMap::new(); + for st in &stats { + if st.hist_window != Some(want) { + continue; // covers a different window; adding it lies + } + for (day, n) in &st.hist { + *merged_all.entry(day.clone()).or_insert(0) += n; + } + for (day, n) in &st.opened_hist { + *opened_all.entry(day.clone()).or_insert(0) += n; + } + } + let base = today(); + let mut days: Vec = (0..want) + .rev() + .map(|n| (base - Days::days(n)).format("%Y-%m-%d").to_string()) + .collect(); + // The chart always fills the pane. Where there is room to spare a day + // takes several columns; where there is not, the oldest days are + // cropped rather than the whole chart squeezed into a corner. + let avail = w.saturating_sub(3).max(10); + if days.len() > avail { + days = days[days.len() - avail..].to_vec(); + } + let slot = (avail / days.len()).max(1); + let gap = if slot >= 3 { 1 } else { 0 }; + let barw = slot - gap; + let spread = |per_day: &[f64]| -> Vec { + let mut cols = Vec::new(); + for (n, v) in per_day.iter().enumerate() { + cols.extend(std::iter::repeat_n(*v, barw)); + if gap > 0 && n + 1 < per_day.len() { + cols.extend(std::iter::repeat_n(0.0, gap)); + } + } + cols + }; + let opened_day: Vec = days + .iter() + .map(|d| opened_all.get(d).copied().unwrap_or(0) as f64) + .collect(); + let merged_day: Vec = days + .iter() + .map(|d| merged_all.get(d).copied().unwrap_or(0) as f64) + .collect(); + let (up, down) = (spread(&opened_day), spread(&merged_day)); + let chart_cols = up.len(); + // One scale both ways, or the comparison lies. + let span_hi = up + .iter() + .chain(down.iter()) + .cloned() + .fold(0.0f64, f64::max) + .max(1.0); + rows.push(String::new()); + if chart_stale { + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── PR FLOW ── ".into()), + (p.dim.as_str(), format!("counting {}d…", want)), + ], + w - 1, + )); + } else { + // Totals come from the days themselves: a day spans several + // columns now, so summing the columns would multiply by bar width. + let span = if days.len() < want as usize { + format!("{}d of {}d", days.len(), want) + } else { + format!("{}d", days.len()) + }; + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── PR FLOW ── ".into()), + (p.dim.as_str(), format!("{} · ", span)), + ( + p.pr.as_str(), + format!("▲ {} opened", opened_day.iter().sum::() as i64), + ), + (p.dim.as_str(), " · ".into()), + ( + p.ok.as_str(), + format!("▼ {} merged", merged_day.iter().sum::() as i64), + ), + (p.dim.as_str(), format!(" peak {}/day", span_hi as i64)), + ], + w - 1, + )); + } + // While the figures are still arriving the bars bounce like a level + // meter in pale versions of their own colours, then settle onto the + // real values rather than cutting to them. Three rows each side, + // always - trimming the unused half would make the chart change + // height at the end of the animation, which is exactly when it + // should be still. + let (hu, hd, cu, cd) = if chart_stale { + // Dance per day, then widen: bouncing each column on its own + // would show a twelve-column day as twelve separate thin bars. + let hu = spread(&tc::dance(days.len(), tick, 0.0)); + let hd = spread(&tc::dance(days.len(), tick, 2.1)); + settle_from = Some((hu.clone(), hd.clone())); + settle_t = 0; + ( + hu, + hd, + tc::mix(GHOST, PR_RGB, 0.45), + tc::mix(GHOST, OK_RGB, 0.45), + ) + } else { + let real_u: Vec = up.iter().map(|v| v / span_hi).collect(); + let real_d: Vec = down.iter().map(|v| v / span_hi).collect(); + match &settle_from { + Some((fu, fd)) if settle_t < SETTLE_FRAMES && fu.len() == chart_cols => { + settle_t += 1; + let q = settle_t as f64 / SETTLE_FRAMES as f64; + let q = q * q * (3.0 - 2.0 * q); // ease in and out + ( + fu.iter().zip(&real_u).map(|(a, b)| a + (b - a) * q).collect(), + fd.iter().zip(&real_d).map(|(a, b)| a + (b - a) * q).collect(), + tc::mix(GHOST, PR_RGB, 0.45 + 0.55 * q), + tc::mix(GHOST, OK_RGB, 0.45 + 0.55 * q), + ) + } + _ => (real_u, real_d, p.pr.clone(), p.ok.clone()), + } + }; + for line in tc::vbars(&hu.iter().map(|v| (*v, cu.clone())).collect::>(), 3, 1.0) { + let mut parts: Vec<(&str, String)> = vec![(tc::RST, " ".into())]; + for (colour, ch) in &line { + parts.push((colour.as_str(), ch.clone())); + } + rows.push(tc::seg(&parts, w - 1)); + } + // An explicit baseline: without it the two series abut and the eye + // cannot tell which row the bars grow from. + rows.push(tc::seg( + &[(tc::RST, " ".into()), (p.grid.as_str(), "─".repeat(chart_cols))], + w - 1, + )); + for line in tc::vbars_down(&hd.iter().map(|v| (*v, cd.clone())).collect::>(), 3, 1.0) + { + let mut parts: Vec<(&str, String)> = vec![(tc::RST, " ".into())]; + for (colour, ch) in &line { + parts.push((colour.as_str(), ch.clone())); + } + rows.push(tc::seg(&parts, w - 1)); + } + let left = format!("{}d ago", days.len()); + rows.push(tc::seg( + &[ + (p.dim.as_str(), format!(" {}", left)), + ( + p.dim.as_str(), + " ".repeat(chart_cols.saturating_sub(left.len() + 5).max(1)), + ), + (p.dim.as_str(), "today".into()), + ], + w - 1, + )); + rows.push(String::new()); + + // The account table earns the remaining height; the calendar keeps + // its place only where the pane is tall enough for both. + if let Some(cal) = calendar.as_ref().filter(|_| h > 38) { + let (grid, peak, total) = heatmap(&cal["weeks"], w); + let total_c = cal["totalContributions"].as_i64().unwrap_or(total); + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── CONTRIBUTIONS ── ".into()), + ( + p.dim.as_str(), + format!("{} in {} weeks, peak {}/day", total_c, CONTRIB_WEEKS, peak), + ), + ], + w - 1, + )); + for (r, line) in grid.iter().enumerate() { + // Rows are GitHub's own weekday index, where 0 is Sunday, so + // the labels come off the same constant rather than a + // hand-written tuple. Written Monday-first they sat one row + // early and put today under yesterday's name. + let label = if r == 1 || r == 3 || r == 5 { WEEKDAYS[r] } else { "" }; + rows.push(tc::seg( + &[ + (p.dim.as_str(), format!(" {:<4}", label)), + (p.ok.as_str(), line.clone()), + ], + w - 1, + )); + } + if let Some(cs) = calendar_stats(&cal["weeks"]) { + let cells: Vec<(String, String, &str)> = vec![ + ( + "current streak".into(), + format!("{} days", cs.current), + if cs.current > 0 { p.ok.as_str() } else { p.dim.as_str() }, + ), + ("longest streak".into(), format!("{} days", cs.longest), p.txt.as_str()), + ( + "today".into(), + format!("{}", cs.today), + if cs.today > 0 { p.ok.as_str() } else { p.dim.as_str() }, + ), + ( + "active days".into(), + format!( + "{} of {} ({:.0}%)", + cs.active, + cs.span, + 100.0 * cs.active as f64 / cs.span as f64 + ), + p.txt.as_str(), + ), + ( + "busiest".into(), + format!("{} ({})", cs.busiest.0, cs.busiest.1), + p.txt.as_str(), + ), + ( + "most on".into(), + format!("{} ({})", cs.weekday.0, cs.weekday.1), + p.txt.as_str(), + ), + ]; + // As many columns as the width honestly allows, never fewer + // than one - the labels are what make these readable. + let ncols = if w >= 86 { + 3 + } else if w >= 58 { + 2 + } else { + 1 + }; + let cw = (w - 2) / ncols; + for chunk in cells.chunks(ncols) { + let mut line: Vec<(&str, String)> = vec![(tc::RST, " ".into())]; + for (label, value, colour) in chunk { + let used = label.len() + 1 + value.len(); + line.push((p.dim.as_str(), format!("{} ", label))); + line.push((colour, value.clone())); + line.push((tc::RST, " ".repeat(cw.saturating_sub(used).max(2)))); + } + rows.push(tc::seg(&line, w - 1)); + } + } + rows.push(String::new()); + } + + // Scroll rather than truncate: the selection has to stay on screen, + // or the arrows move something invisible. + let room = h.saturating_sub(5 + rows.len()).max(1); + let first = if stats.len() > room { + selected.saturating_sub(room / 2).min(stats.len() - room) + } else { + 0 + }; + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── BY ACCOUNT ──".into()), + ( + p.dim.as_str(), + if stats.len() > room { + format!( + " {}-{} of {}", + first + 1, + (first + room).min(stats.len()), + stats.len() + ) + } else { + String::new() + }, + ), + ], + w - 1, + )); + let wide = w >= 62; + let bar_cols = w.saturating_sub(64).max(4); + // No separators between these fields: the row emits its widths + // back-to-back, so a space here drifts the header one column per + // field. MRG takes seven, since "MRG60D" is six characters and would + // sit flush against REVW in every window but the seven-day one. + let mut head = format!( + " {:<20}{:>5}{:>5}{:>7}{:>6}", + "ACCOUNT", + "OPEN", + "REVW", + format!("MRG{}D", want), + "RATE" + ); + let spark_days: Vec = (0..(want as usize).min(bar_cols) as i64) + .rev() + .map(|n| (base - Days::days(n)).format("%Y-%m-%d").to_string()) + .collect(); + if wide { + head += &format!("{:>7}", "ISSUES"); + // Each row is scaled to its own busiest day, so say what the + // reader may do with it - read the shape - rather than naming + // the mechanism. Pick the longest label that fits rather than + // clipping one: a truncated hint is worse than a shorter one. + let label = [ + "MERGED/DAY · SHAPE ONLY, NOT TO SCALE", + "MERGED/DAY · SHAPE ONLY", + "MERGED/DAY (shape)", + "MERGED/DAY", + "", + ] + .into_iter() + .find(|l| l.len() <= bar_cols) + .unwrap_or(""); + if !label.is_empty() { + head += &format!(" {}", label); + } + } + rows.push(tc::seg(&[(p.dim.as_str(), tc::pad(&head, w - 1))], w - 1)); + for (i, s) in stats.iter().enumerate().skip(first).take(room) { + let here = i == selected; + let tint = if here { tc::bg(38, 56, 76) } else { String::new() }; + let c = |colour: &str| format!("{}{}", tint, colour); + // This row's own staleness: accounts land one at a time, so an + // account already refetched for the new window shows real numbers + // while the ones behind it still shimmer. + let old = s.window != want; + let hot = match s.rate { + Some(r) if !old => tc::heat(r / 100.0), + _ => p.dim.clone(), + }; + let mut line = vec![ + ( + c(if here { &p.accent } else { &p.txt }), + format!( + "{}{}", + if here { "▸" } else { " " }, + tc::pad( + &format!("{}{}", s.account, if s.is_me { " (you)" } else { "" }), + 20 + ) + ), + ), + (c(&p.pr), format!("{:>5}", s.open)), + ( + c(if s.review > 0 { &p.warn } else { &p.dim }), + format!("{:>5}", s.review), + ), + ( + c(if old { &p.dim } else { &p.ok }), + format!("{:>7}", if old { "···".to_string() } else { s.merged.to_string() }), + ), + ( + c(&hot), + format!( + "{:>6}", + if old { + "···".to_string() + } else { + match s.rate { + Some(r) => format!("{:.0}%", r), + None => "--".into(), + } + } + ), + ), + ]; + if wide { + line.push((c(&p.dim), format!("{:>7}", s.issues))); + // Each account's own merged-per-day. The columns carry + // totals but no shape, and a fortnight of nothing ending in + // a spike reads very differently from a steady trickle. + if s.hist_window != Some(want) { + line.push((c(&p.grid), format!(" {}", "·".repeat(spark_days.len())))); + } else { + let top = s.hist.values().copied().max().unwrap_or(0); + let mut marks = String::new(); + for d in &spark_days { + let v = s.hist.get(d).copied().unwrap_or(0); + marks.push(if v > 0 && top > 0 { + SPARK[(((v as f64 / top as f64) * 7.99) as usize).min(7)] + } else { + ' ' + }); + } + line.push((c(&p.ok), format!(" {}", marks))); + } + } + if here { + line.push((tint.clone(), " ".repeat(w))); + } + let refs: Vec<(&str, String)> = + line.iter().map(|(c, t)| (c.as_str(), t.clone())).collect(); + rows.push(tc::seg(&refs, w - 1)); + } + + let hints: Vec> = vec![ + vec![(p.accent.as_str(), "↑↓".into()), (p.dim.as_str(), " account".into())], + vec![(p.dim.as_str(), "[w]indow".into())], + vec![(p.dim.as_str(), "[r]efresh".into())], + vec![(p.dim.as_str(), "[q]uit".into())], + ]; + let footer: Vec = tc::pack_hints(&hints, w - 2, " ") + .into_iter() + .map(|l| format!(" {}", l)) + .collect(); + rows.truncate(h.saturating_sub(footer.len())); + while rows.len() < h.saturating_sub(footer.len()) { + rows.push(String::new()); + } + rows.extend(footer); + tc::draw(&rows, w, h); + std::thread::sleep(Duration::from_millis(300)); + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn a_token_that_will_undercount_says_so() { + // A classic token missing `repo` still searches - it just silently + // returns public results only, which is worse than an error. + let short = Scopes { + seen: true, + have: vec!["read:org".into()], + }; + assert!(scope_warning(&short).contains("private repos are not counted")); + let no_org = Scopes { + seen: true, + have: vec!["repo".into()], + }; + assert!(scope_warning(&no_org).contains("orgs cannot be discovered")); + let full = Scopes { + seen: true, + have: vec!["repo".into(), "read:org".into(), "gist".into()], + }; + assert_eq!(scope_warning(&full), ""); + // A fine-grained token sends no scope header at all, so there is + // nothing to check and nothing to claim. + assert_eq!(scope_warning(&Scopes::default()), ""); + } + + #[test] + fn an_account_scopes_its_own_search() { + assert_eq!(scope_of("acme", "wiiiimm"), "org:acme"); + // @me is the viewer, resolved once rather than sent literally. + assert_eq!(scope_of("@me", "wiiiimm"), "user:wiiiimm"); + } + + #[test] + fn the_window_ends_today_and_spans_exactly_its_days() { + // `days - 1` back from today, because the chart under it plots N + // days *including* today - one more would quietly disagree with it. + let q = build_query("acme", 7, "w"); + let since = (today() - Days::days(6)).format("%Y-%m-%d").to_string(); + assert!(q.contains(&format!("merged:>={}", since)), "{}", q); + assert!(q.contains("org:acme is:pr is:open")); + assert!(q.contains("rateLimit")); + } + + #[test] + fn a_day_query_asks_for_counts_not_records() { + // A search connection returns at most 100 nodes a page, so a busy + // fortnight lost everything past the hundredth record. issueCount is + // exact at any volume. + let dates = vec!["2026-08-01".to_string(), "2026-08-02".to_string()]; + let q = build_day_query("org:acme", &dates); + assert_eq!(q.matches("issueCount").count(), 4); + assert!(q.contains("m0:") && q.contains("c0:")); + assert!(q.contains("m1:") && q.contains("c1:")); + assert!(!q.contains("nodes")); + } + + #[test] + fn a_streak_is_not_broken_by_a_day_still_running() { + // Sunday through Saturday, with today scoring nothing yet. + let weeks: serde_json::Value = serde_json::from_str(&format!( + r#"[{{"contributionDays": [ + {{"date": "{}", "contributionCount": 3, "weekday": 0}}, + {{"date": "{}", "contributionCount": 5, "weekday": 1}}, + {{"date": "{}", "contributionCount": 0, "weekday": 2}}]}}]"#, + (today() - Days::days(2)).format("%Y-%m-%d"), + (today() - Days::days(1)).format("%Y-%m-%d"), + today().format("%Y-%m-%d"), + )) + .unwrap(); + let cs = calendar_stats(&weeks).expect("a calendar"); + // Two days behind it, and today's zero does not end the run. + assert_eq!(cs.current, 2); + assert_eq!(cs.longest, 2); + assert_eq!(cs.today, 0); + assert_eq!(cs.active, 2); + assert_eq!(cs.busiest.1, 5); + } + + #[test] + fn the_heatmap_is_seven_rows_whatever_the_data() { + let weeks: serde_json::Value = serde_json::from_str( + r#"[{"contributionDays": [ + {"date": "2026-08-16", "contributionCount": 0, "weekday": 0}, + {"date": "2026-08-17", "contributionCount": 9, "weekday": 1}]}]"#, + ) + .unwrap(); + let (grid, peak, total) = heatmap(&weeks, 80); + assert_eq!(grid.len(), 7); + assert_eq!(peak, 9); + assert_eq!(total, 9); + // Nothing on a day is a blank cell, not the lowest shade - the + // difference between "quiet" and "none" is the whole point. + assert_eq!(grid[0].chars().next(), Some(' ')); + assert_eq!(grid[1].chars().next(), Some('█')); + } +} diff --git a/rust/widgets/src/bin/github_help.txt b/rust/widgets/src/bin/github_help.txt new file mode 100644 index 0000000..204b3b0 --- /dev/null +++ b/rust/widgets/src/bin/github_help.txt @@ -0,0 +1,25 @@ +GitHub delivery metrics across every org and account you can see. + +Open pull requests, how many are actually merging, review backlog and issue +counts - for one org, several, or your personal account alongside them. + + github [-n SECONDS] [account ...] + +Accounts are org logins, or @me for your own. With none given it uses +`github.accounts` from config, and failing that every org you belong to plus +your personal account. + +Open counts - PRs, issues, drafts, review backlog - are point-in-time totals of +whatever is open right now, at any age. Everything else - the merge rate, the +per-day charts and the per-account merged/rate columns - covers the merge +window, which is the N days ending today. + +Credentials: `github.token` in config.json, or $GITHUB_TOKEN. It must be a +*classic* token: a fine-grained one is limited to a single resource owner, so +it cannot span the orgs this board exists to compare. Two scopes - `repo` so search sees private +repositories, and `read:org` to enumerate your orgs. Missing either one does +not fail, it silently undercounts, so the granted scopes are checked and named. +The API is called directly, so the `gh` CLI is not required. + +Keys: up/down select an account, r refreshes now, w cycles the window +(7/14/30/60/90 days), q quits. diff --git a/rust/widgets/src/bin/start.rs b/rust/widgets/src/bin/start.rs index 0b18df0..214453e 100644 --- a/rust/widgets/src/bin/start.rs +++ b/rust/widgets/src/bin/start.rs @@ -46,6 +46,11 @@ const WIDGETS: &[Widget] = &[ help: include_str!("deployments_help.txt"), doc: include_str!("../../../../docs/deployments.md"), }, + Widget { + stem: "github", + help: include_str!("github_help.txt"), + doc: include_str!("../../../../docs/github.md"), + }, Widget { stem: "herdr-panes", help: include_str!("herdr-panes_help.txt"), From 84bc76817476438bc5baa5cafd988c4818f87bf2 Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sun, 23 Aug 2026 04:18:55 +0800 Subject: [PATCH 030/147] tailnet: who is online, and how you are actually reaching them Thirteenth widget, and the last before usage. Everything comes from the local tailscaled through its own CLI - nothing here is sent anywhere, and the DERP region names come from the local map rather than a geolocation service, which is the whole reason the info view can name a peer's city. The PATH column is the point. `tailscale status` will happily tell you a peer is online while every packet to it round-trips through a relay in another continent, and the two cases look identical unless you go looking. Direct and relayed are separate counts here, and the relay is named. Three pieces of judgement carried over intact. Peer names come from the first MagicDNS label rather than HostName, because iPads, Chromecasts and Pixels all report "localhost" and two Apple TVs report the same name. Private addresses are ranked so a real LAN address beats a docker bridge - an address inside a subnet the peer advertises wins outright, then 192.168, then 10.x, and 172.16-31 last. And PrimaryRoutes is filtered of 0.0.0.0/0 before any of that, or an exit node's route would match every address and defeat the ranking entirely. One ping process at a time, following the selection: probing two dozen peers continuously would be two dozen ping processes for data nobody is looking at. History is kept per peer, so coming back to one still shows its earlier samples. The running ping is signalled when the selection moves rather than left to finish into a history nobody will read. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/widgets/Cargo.toml | 4 + rust/widgets/src/bin/start.rs | 5 + rust/widgets/src/bin/tailnet.rs | 1585 +++++++++++++++++++++++++ rust/widgets/src/bin/tailnet_help.txt | 40 + 4 files changed, 1634 insertions(+) create mode 100644 rust/widgets/src/bin/tailnet.rs create mode 100644 rust/widgets/src/bin/tailnet_help.txt diff --git a/rust/widgets/Cargo.toml b/rust/widgets/Cargo.toml index dee84a9..d121337 100644 --- a/rust/widgets/Cargo.toml +++ b/rust/widgets/Cargo.toml @@ -60,3 +60,7 @@ path = "src/bin/pr.rs" [[bin]] name = "github" path = "src/bin/github.rs" + +[[bin]] +name = "tailnet" +path = "src/bin/tailnet.rs" diff --git a/rust/widgets/src/bin/start.rs b/rust/widgets/src/bin/start.rs index 214453e..175f391 100644 --- a/rust/widgets/src/bin/start.rs +++ b/rust/widgets/src/bin/start.rs @@ -93,6 +93,11 @@ const WIDGETS: &[Widget] = &[ help: include_str!("pr_help.txt"), doc: include_str!("../../../../docs/pr.md"), }, + Widget { + stem: "tailnet", + help: include_str!("tailnet_help.txt"), + doc: include_str!("../../../../docs/tailnet.md"), + }, ]; impl Widget { diff --git a/rust/widgets/src/bin/tailnet.rs b/rust/widgets/src/bin/tailnet.rs new file mode 100644 index 0000000..bdd9e9a --- /dev/null +++ b/rust/widgets/src/bin/tailnet.rs @@ -0,0 +1,1585 @@ +// terminal-toys - small dependency-free terminal widgets +// Copyright (C) 2026 William Li +// +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU Affero General Public License as published +// by the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU Affero General Public License for more details. +// +// You should have received a copy of the GNU Affero General Public License +// along with this program. If not, see . + +//! Tailscale network: who is online, and how you are reaching them. +//! +//! A port of tailnet.py. The column that matters is PATH: a peer is either +//! DIRECT, meaning NAT traversal succeeded, or relayed through a named DERP +//! region, meaning every packet round-trips through Tailscale's own +//! infrastructure - a difference `tailscale status` does not show unless +//! you go looking for it. + +use std::collections::HashMap; +use std::io::{BufRead, BufReader}; +use std::sync::{Arc, Condvar, Mutex}; +use std::time::{Duration, SystemTime, UNIX_EPOCH}; + +use chrono::{Local, NaiveDateTime, TimeZone}; +use toys_core as tc; + +const SPARK: &[char] = &['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█']; +/// Cycled at runtime with n, the same way the latency monitor's i key does. +const REFRESH_CHOICES: &[f64] = &[1.0, 2.0, 5.0, 10.0, 30.0]; + +fn now() -> f64 { + SystemTime::now() + .duration_since(UNIX_EPOCH) + .map(|d| d.as_secs_f64()) + .unwrap_or(0.0) +} + +fn run(args: &[&str]) -> String { + match std::process::Command::new(args[0]).args(&args[1..]).output() { + Ok(out) if out.status.success() => String::from_utf8_lossy(&out.stdout).to_string(), + _ => String::new(), + } +} + +fn text(value: &serde_json::Value, key: &str) -> String { + value[key].as_str().unwrap_or("").to_string() +} + +fn bytes_at(value: &serde_json::Value, key: &str) -> u64 { + value[key].as_u64().unwrap_or(0) +} + +/// Seconds since tailscaled started. +/// +/// Its byte counters live in memory and reset with it, so RX/TX cover this +/// window rather than all time - a peer reading 0B may just predate a +/// restart. +fn daemon_uptime() -> Option { + let hz = { + let n = unsafe { libc::sysconf(libc::_SC_CLK_TCK) }; + if n > 0 { n as f64 } else { 100.0 } + }; + for entry in std::fs::read_dir("/proc").ok()? { + let entry = entry.ok()?; + let name = entry.file_name().to_string_lossy().to_string(); + if !name.chars().all(|c| c.is_ascii_digit()) { + continue; + } + let comm = std::fs::read_to_string(format!("/proc/{}/comm", name)).unwrap_or_default(); + if comm.trim() != "tailscaled" { + continue; + } + let stat = std::fs::read_to_string(format!("/proc/{}/stat", name)).ok()?; + let rest = stat.rsplit_once(')')?.1; + let started: f64 = rest.split_whitespace().nth(19)?.parse().ok()?; + let uptime = std::fs::read_to_string("/proc/uptime").ok()?; + let up: f64 = uptime.split_whitespace().next()?.parse().ok()?; + return Some(up - started / hz); + } + None +} + +/// Tailnet-unique display name. +/// +/// HostName is whatever the device calls itself and is frequently useless: +/// iPads, Chromecasts and Pixels all report "localhost", and two Apple TVs +/// report the same "apple-tv". The first label of the MagicDNS name is +/// unique across the tailnet and matches what the admin console shows. +fn peer_name(peer: &serde_json::Value) -> String { + let dns = text(peer, "DNSName"); + let dns = dns.trim_end_matches('.'); + if !dns.is_empty() { + return dns.split('.').next().unwrap_or(dns).to_string(); + } + match text(peer, "HostName") { + s if s.is_empty() => "?".into(), + s => s, + } +} + +/// public | private | tailscale | other, from the address alone. +fn classify(ip: &str) -> &'static str { + let ip = ip.split('%').next().unwrap_or(ip); + if ip.contains(':') { + return if ip.to_lowercase().starts_with("fd7a:") { + "tailscale" + } else { + "other" + }; + } + let parts: Vec<&str> = ip.split('.').collect(); + let (a, b) = match ( + parts.first().and_then(|x| x.parse::().ok()), + parts.get(1).and_then(|x| x.parse::().ok()), + ) { + (Some(a), Some(b)) => (a, b), + _ => return "other", + }; + if a == 100 && (64..=127).contains(&b) { + return "tailscale"; // the CGNAT range Tailscale itself uses + } + if a == 10 || (a == 172 && (16..=31).contains(&b)) || (a == 192 && b == 168) { + return "private"; + } + if (a == 169 && b == 254) || a == 127 { + return "other"; + } + "public" +} + +/// Is an IPv4 address inside a CIDR block? +fn in_network(ip: &str, cidr: &str) -> bool { + let Some((net, bits)) = cidr.split_once('/') else { + return false; + }; + if net.contains(':') { + return false; + } + let Ok(bits) = bits.parse::() else { + return false; + }; + if bits > 32 { + return false; + } + let to_int = |a: &str| -> Option { + let parts: Vec = a.split('.').filter_map(|o| o.parse().ok()).collect(); + if parts.len() != 4 || parts.iter().any(|o| *o > 255) { + return None; + } + Some(parts.iter().enumerate().map(|(i, o)| o << (24 - 8 * i)).sum()) + }; + let mask = if bits == 0 { 0 } else { u32::MAX << (32 - bits) }; + match (to_int(ip), to_int(net)) { + (Some(a), Some(b)) => (a & mask) == (b & mask), + _ => false, + } +} + +/// Lower is better. Prefers a real LAN address over a virtual bridge. +/// +/// A peer often exposes several private endpoints, and docker0 (172.17.0.1) +/// or a k8s bridge is not the address anyone wants to copy. An address +/// inside a subnet the peer advertises is almost certainly its real LAN one. +fn lan_rank(ip: &str, routes: &[String]) -> u8 { + if routes.iter().any(|r| in_network(ip, r)) { + return 0; + } + let parts: Vec = ip.split('.').filter_map(|x| x.parse().ok()).collect(); + match (parts.first(), parts.get(1)) { + (Some(192), Some(168)) => 1, + (Some(10), _) => 2, + _ => 3, // 172.16-31: usually docker or another virtual bridge + } +} + +/// Peer LAN and public endpoints from the netmap, which needs root. +/// +/// Optional enrichment: `tailscale status` does not carry peer endpoints, so +/// without this the panel simply offers fewer addresses to copy. `sudo -n` +/// so it fails instantly rather than prompting when sudo wants a password. +fn endpoints_by_peer() -> HashMap> { + let mut found = HashMap::new(); + let text_out = run(&["sudo", "-n", "tailscale", "debug", "netmap"]); + let data: serde_json::Value = match serde_json::from_str(&text_out) { + Ok(d) => d, + Err(_) => return found, + }; + for peer in data["Peers"].as_array().into_iter().flatten() { + let name = text(peer, "Name").trim_end_matches('.').to_string(); + if name.is_empty() { + continue; + } + found.insert( + name, + peer["Endpoints"] + .as_array() + .into_iter() + .flatten() + .filter_map(|e| e.as_str()) + .map(|e| e.rsplit_once(':').map(|(h, _)| h).unwrap_or(e).to_string()) + .collect(), + ); + } + found +} + +/// DERP region code to city, from the local map. +/// +/// A peer's home region is the Tailscale POP nearest to it, so this gives a +/// location hint without sending anyone's address to a geolocation service. +fn derp_regions() -> HashMap { + let mut out = HashMap::new(); + let text_out = run(&["tailscale", "debug", "derp-map"]); + let data: serde_json::Value = match serde_json::from_str(&text_out) { + Ok(d) => d, + Err(_) => return out, + }; + for region in data["Regions"].as_object().into_iter().flatten().map(|(_, v)| v) { + let code = text(region, "RegionCode"); + if !code.is_empty() { + let city = text(region, "RegionName"); + out.insert(code.clone(), if city.is_empty() { code } else { city }); + } + } + out +} + +fn spark(values: &[f64], n: usize, peak: f64) -> String { + let vals = &values[values.len().saturating_sub(n)..]; + if vals.is_empty() { + return String::new(); + } + let hi = if peak > 0.0 { + peak + } else { + vals.iter().cloned().fold(0.0f64, f64::max) + }; + if hi <= 0.0 { + return "·".repeat(vals.len()); + } + vals.iter() + .map(|v| SPARK[(((v / hi) * 7.99) as usize).min(7)]) + .collect() +} + +fn ago(s: f64) -> String { + let s = s.max(0.0) as i64; + if s < 3600 { + format!("{}m ago", s / 60) + } else if s < 172_800 { + format!("{}h ago", s / 3600) + } else { + format!("{}d ago", s / 86400) + } +} + +/// A byte count in exactly five cells, so columns stay aligned. +fn human(n: u64) -> String { + let mut v = n as f64; + for unit in ["B", "K", "M", "G", "T"] { + if v < 1024.0 { + let body = if v >= 10.0 || unit == "B" { + format!("{:.0}{}", v, unit) + } else { + format!("{:.1}{}", v, unit) + }; + return format!("{:>5}", body); + } + v /= 1024.0; + } + format!("{:>5}", format!("{:.0}P", v)) +} + +/// A per-second byte rate in six cells. +fn rate(v: f64) -> String { + format!("{:>5}/s", human(v as u64).trim()) +} + +fn parse_iso(iso: &str) -> Option { + if iso.len() < 19 || iso.starts_with("0001-01-01") { + return None; + } + NaiveDateTime::parse_from_str(&iso[..19], "%Y-%m-%dT%H:%M:%S").ok() +} + +/// The age of an ISO-8601 timestamp, coarsely. +fn seen(iso: &str) -> String { + let Some(at) = parse_iso(iso) else { + return " -".into(); + }; + let s = (chrono::Utc::now().naive_utc() - at).num_seconds().max(0); + if s < 90 { + "now".into() + } else if s < 5400 { + format!("{}m", s / 60) + } else if s < 172_800 { + format!("{}h", s / 3600) + } else { + format!("{}d", s / 86400) + } +} + +/// ISO-8601 to a readable local time, or nothing when unset. +fn stamp(iso: &str) -> String { + let Some(at) = parse_iso(iso) else { + return String::new(); + }; + match Local.from_utc_datetime(&at).format("%Y-%m-%d %H:%M").to_string() { + s => s, + } +} + +/// The addresses worth copying for a peer, as (label, value) pairs. +fn addresses(peer: &serde_json::Value, eps: &HashMap>) -> Vec<(String, String)> { + let mut out = Vec::new(); + let ips: Vec = peer["TailscaleIPs"] + .as_array() + .into_iter() + .flatten() + .filter_map(|i| i.as_str().map(String::from)) + .collect(); + let v4: Vec<&String> = ips.iter().filter(|i| !i.contains(':')).collect(); + let v6: Vec<&String> = ips.iter().filter(|i| i.contains(':')).collect(); + if let Some(first) = v4.first() { + out.push(("Tailscale IP".into(), (*first).clone())); + } + let dns = text(peer, "DNSName").trim_end_matches('.').to_string(); + if !dns.is_empty() { + out.push(("MagicDNS name".into(), dns.clone())); + } + + let (mut pub_ips, mut priv_ips): (Vec, Vec) = (Vec::new(), Vec::new()); + let cur = text(peer, "CurAddr"); + let cur = cur.rsplit_once(':').map(|(h, _)| h).unwrap_or(&cur).to_string(); + if !cur.is_empty() && classify(&cur) == "public" { + pub_ips.push(cur); + } + for ip in eps.get(&dns).into_iter().flatten() { + match classify(ip) { + "public" if !pub_ips.contains(ip) => pub_ips.push(ip.clone()), + "private" if !priv_ips.contains(ip) => priv_ips.push(ip.clone()), + _ => {} + } + } + // PrimaryRoutes only: AllowedIPs also carries 0.0.0.0/0 for exit nodes, + // which would match every address and defeat the ranking entirely. + let routes = primary_routes(peer); + priv_ips.sort_by_key(|i| lan_rank(i, &routes)); + if let Some(first) = pub_ips.first() { + out.push(("Public IP".into(), first.clone())); + } + if let Some(first) = priv_ips.first() { + out.push(("Private IP (LAN)".into(), first.clone())); + if let Some(second) = priv_ips.get(1) { + out.push(("Other private IP".into(), second.clone())); + } + } + if let Some(first) = v6.first() { + out.push(("Tailscale IPv6".into(), (*first).clone())); + } + out +} + +fn primary_routes(peer: &serde_json::Value) -> Vec { + peer["PrimaryRoutes"] + .as_array() + .into_iter() + .flatten() + .filter_map(|r| r.as_str()) + .filter(|r| *r != "0.0.0.0/0" && *r != "::/0") + .map(String::from) + .collect() +} + +/// Pings whichever peer is selected, keeping per-peer history. +/// +/// Probing every peer continuously would mean two dozen ping processes for +/// data nobody is looking at, so exactly one runs at a time and follows the +/// selection. History is kept per peer, so returning to one still shows its +/// earlier samples. +#[derive(Default)] +struct Prober { + samples: HashMap>>, + want: Option<(String, String)>, + pid: Option, +} + +fn rtt_of(line: &str) -> Option { + let at = line.find("time=")? + 5; + let rest = &line[at..]; + let end = rest + .find(|c: char| !c.is_ascii_digit() && c != '.') + .unwrap_or(rest.len()); + rest[..end].parse().ok() +} + +fn prober_loop(shared: Arc>) { + loop { + let target = shared.lock().ok().and_then(|g| g.want.clone()); + let Some((machine, ip)) = target else { + std::thread::sleep(Duration::from_millis(400)); + continue; + }; + let child = std::process::Command::new("ping") + .args(["-n", "-O", "-i", "1", &ip]) + .stdout(std::process::Stdio::piped()) + .stderr(std::process::Stdio::null()) + .spawn(); + let mut child = match child { + Ok(c) => c, + Err(_) => { + std::thread::sleep(Duration::from_secs(2)); + continue; + } + }; + if let Ok(mut g) = shared.lock() { + g.pid = Some(child.id() as i32); + } + if let Some(stdout) = child.stdout.take() { + for line in BufReader::new(stdout).lines().map_while(Result::ok) { + let mut g = match shared.lock() { + Ok(g) => g, + Err(_) => return, + }; + // The selection moved on; this ping is for a peer nobody is + // looking at any more. + if g.want.as_ref().map(|w| w.0.clone()) != Some(machine.clone()) { + break; + } + let hist = g.samples.entry(machine.clone()).or_default(); + if let Some(rtt) = rtt_of(&line) { + hist.push(Some(rtt)); + } else if line.contains("no answer yet") || line.contains("Unreachable") { + hist.push(None); + } + if hist.len() > 120 { + let drop = hist.len() - 120; + hist.drain(..drop); + } + } + } + let _ = child.kill(); + let _ = child.wait(); + if let Ok(mut g) = shared.lock() { + g.pid = None; + } + } +} + +fn watch(shared: &Arc>, machine: &str, ip: Option) { + let kill = { + let Ok(mut g) = shared.lock() else { return }; + if g.want.as_ref().is_some_and(|w| w.0 == machine) { + return; + } + g.want = ip.map(|ip| (machine.to_string(), ip)); + g.pid.take() + }; + // The running ping belongs to the peer that was selected a moment ago, + // so it is stopped rather than left to finish into a history nobody + // will read. + if let Some(pid) = kill { + unsafe { libc::kill(pid, libc::SIGTERM) }; + } +} + +#[derive(Default)] +struct State { + data: Option, + endpoints: HashMap>, + err: String, + rates: HashMap>, + counters: HashMap, + endpoints_at: f64, +} + +/// Turn cumulative byte counters into per-second rates. +fn sample_rates(state: &mut State, data: &serde_json::Value, history: usize) { + let at = now(); + for peer in data["Peer"].as_object().into_iter().flatten().map(|(_, v)| v) { + let key = peer_name(peer); + let (rx, tx) = (bytes_at(peer, "RxBytes"), bytes_at(peer, "TxBytes")); + let prev = state.counters.insert(key.clone(), (rx, tx, at)); + let Some((was_rx, was_tx, when)) = prev else { + continue; + }; + let dt = at - when; + if dt <= 0.0 { + continue; + } + // A tailscaled restart zeroes the counters; report no traffic rather + // than a large negative spike. + let drx = rx.saturating_sub(was_rx) as f64 / dt; + let dtx = tx.saturating_sub(was_tx) as f64 / dt; + let hist = state.rates.entry(key).or_default(); + hist.push((drx, dtx)); + if hist.len() > history { + let drop = hist.len() - history; + hist.drain(..drop); + } + } +} + +struct Palette { + online: String, + offline: String, + direct: String, + relay: String, + dim: String, + txt: String, + lbl: String, + accent: String, + route: String, + exit: String, +} + +fn palette() -> Palette { + Palette { + online: tc::rgb(90, 240, 160), + offline: tc::rgb(120, 130, 150), + direct: tc::rgb(90, 240, 160), + relay: tc::rgb(255, 190, 90), + dim: tc::rgb(127, 147, 172), + txt: tc::rgb(225, 235, 245), + lbl: tc::rgb(130, 165, 200), + accent: tc::rgb(120, 200, 255), + route: tc::rgb(200, 160, 255), + exit: tc::rgb(255, 140, 200), + } +} + +/// Live throughput for peers that are actually moving data. +fn activity_rows( + rates: &HashMap>, + w: usize, + limit: usize, + p: &Palette, +) -> Vec { + let mut active: Vec<(f64, &String, &Vec<(f64, f64)>)> = rates + .iter() + .filter_map(|(name, hist)| { + if hist.is_empty() { + return None; + } + let recent = &hist[hist.len().saturating_sub(30)..]; + let peak = recent.iter().map(|(r, t)| r + t).fold(0.0f64, f64::max); + // Ignore keepalives: a tailnet is never entirely silent. + if peak < 64.0 { + return None; + } + Some((peak, name, hist)) + }) + .collect(); + active.sort_by(|a, b| b.0.total_cmp(&a.0)); + if active.is_empty() { + return vec![tc::seg( + &[(p.dim.as_str(), " no peer traffic in the last few minutes".into())], + w - 1, + )]; + } + let sw = (w.saturating_sub(42)).clamp(8, 28); + let peak = active[0].0; + active + .iter() + .take(limit) + .map(|(_, name, hist)| { + let rx: Vec = hist.iter().map(|(r, _)| *r).collect(); + let tx: Vec = hist.iter().map(|(_, t)| *t).collect(); + tc::seg( + &[ + ( + p.txt.as_str(), + format!( + " {}", + tc::pad(&name.chars().take(18).collect::(), 19) + ), + ), + (p.online.as_str(), format!("↓{}", spark(&rx, sw, peak))), + (p.relay.as_str(), format!(" ↑{}", spark(&tx, sw, peak))), + ( + p.dim.as_str(), + format!( + " {} {}", + rate(*rx.last().unwrap_or(&0.0)), + rate(*tx.last().unwrap_or(&0.0)) + ), + ), + ], + w - 1, + ) + }) + .collect() +} + +fn main() { + tc::maybe_help(include_str!("tailnet_help.txt")); + let cfg = tc::load_config("tailnet"); + let mut refresh = tc::cfg_f64(&cfg, "refresh", 2.0); + let history = tc::cfg_usize(&cfg, "history", 180); + let args: Vec = std::env::args().skip(1).collect(); + if args.len() >= 2 && (args[0] == "-n" || args[0] == "--refresh") { + refresh = args[1].parse::().unwrap_or(2.0).max(1.0); + } + + let absent = tc::missing(&["tailscale"]); + if !absent.is_empty() { + tc::cannot_start( + "tailnet", + &absent, + &[ + "Everything here comes from the local tailscaled through its", + "own CLI: who is online, whether each peer is direct or", + "relayed, and the byte counters the WireGuard engine keeps.", + "", + "There is no other source for any of it, and nothing here is", + "sent anywhere - the DERP region names come from the local", + "map rather than from a geolocation service.", + ], + "see https://tailscale.com/download", + ); + return; + } + + let p = palette(); + let state = Arc::new(Mutex::new(State::default())); + let prober = Arc::new(Mutex::new(Prober::default())); + let wake = Arc::new((Mutex::new(false), Condvar::new())); + let refresh_now = Arc::new(Mutex::new(refresh)); + + let poller = Arc::clone(&state); + let poller_wake = Arc::clone(&wake); + let poller_refresh = Arc::clone(&refresh_now); + std::thread::spawn(move || loop { + let out = run(&["tailscale", "status", "--json"]); + let parsed: Option = serde_json::from_str(&out).ok(); + // The netmap needs sudo and changes slowly, so it is asked for far + // less often than the status is. + let want_eps = poller + .lock() + .map(|g| now() - g.endpoints_at > 60.0) + .unwrap_or(false); + let eps = if want_eps { Some(endpoints_by_peer()) } else { None }; + if let Ok(mut g) = poller.lock() { + match &parsed { + None => g.err = "tailscale CLI unavailable or not logged in".into(), + Some(d) => { + g.err.clear(); + sample_rates(&mut g, d, history); + g.data = Some(d.clone()); + } + } + if let Some(eps) = eps { + if !eps.is_empty() { + g.endpoints = eps; + } + g.endpoints_at = now(); + } + } + let wait = poller_refresh.lock().map(|g| *g).unwrap_or(2.0); + let (lock, cond) = &*poller_wake; + let mut asked = match lock.lock() { + Ok(g) => g, + Err(_) => return, + }; + if !*asked { + asked = match cond.wait_timeout(asked, Duration::from_secs_f64(wait)) { + Ok((g, _)) => g, + Err(_) => return, + }; + } + *asked = false; + }); + + let probing = Arc::clone(&prober); + std::thread::spawn(move || prober_loop(probing)); + + tc::setup(); + let mut keyboard = tc::Keyboard::new(); + let (mut hide_offline, mut show_graph) = (false, true); + let (mut selected, mut scroll, mut visible) = (0usize, 0usize, 1usize); + // None, "copy" or "info". + let mut view: Option<&'static str> = None; + let mut note: (String, f64) = (String::new(), 0.0); + let mut listed: Vec = Vec::new(); + let derp = derp_regions(); + + let nudge = |wake: &Arc<(Mutex, Condvar)>| { + let (lock, cond) = &**wake; + if let Ok(mut asked) = lock.lock() { + *asked = true; + cond.notify_all(); + } + }; + + loop { + let (data, eps_now, err, rates) = match state.lock() { + Ok(g) => (g.data.clone(), g.endpoints.clone(), g.err.clone(), g.rates.clone()), + Err(_) => return, + }; + + for key in keyboard.poll() { + if view.is_some() { + match key.as_str() { + "esc" | "q" | "Q" => view = None, + "i" | "I" | "enter" => { + view = if view != Some("info") { Some("info") } else { None } + } + "c" | "C" => view = if view != Some("copy") { Some("copy") } else { None }, + digit + if view == Some("copy") + && digit.len() == 1 + && digit.chars().all(|c| c.is_ascii_digit()) + && !listed.is_empty() => + { + let pairs = + addresses(&listed[selected.min(listed.len() - 1)], &eps_now); + let at = digit.parse::().unwrap_or(0); + if at >= 1 && at <= pairs.len() { + let (label, value) = &pairs[at - 1]; + note = ( + if tc::clipboard(value) { + format!("✓ copied {}", label.to_lowercase()) + } else { + "! no clipboard; select the text with the mouse".into() + }, + now() + 3.0, + ); + } + } + _ => {} + } + continue; + } + match key.as_str() { + "q" | "Q" => { + keyboard.restore(); + tc::restore_screen(); + return; + } + "r" | "R" => nudge(&wake), + "o" | "O" => { + hide_offline = !hide_offline; + selected = 0; + } + "g" | "G" => show_graph = !show_graph, + "n" | "N" => { + if let Ok(mut g) = refresh_now.lock() { + *g = tc::cycle(REFRESH_CHOICES, *g); + } + nudge(&wake); // apply the new interval immediately + } + "up" => selected = selected.saturating_sub(1), + "down" => selected += 1, + "pgup" => selected = selected.saturating_sub(visible), + "pgdn" => selected += visible, + "home" => selected = 0, + "end" => selected = listed.len().saturating_sub(1), + "c" | "C" => { + if !listed.is_empty() { + view = Some("copy"); + note = (String::new(), 0.0); + } + } + "i" | "I" | "enter" => { + if !listed.is_empty() { + view = Some("info"); + } + } + _ => {} + } + } + + let (w, h) = tc::size(); + let interval = refresh_now.lock().map(|g| *g).unwrap_or(2.0); + if !note.0.is_empty() && now() > note.1 { + note = (String::new(), 0.0); + } + let mut rows = vec![tc::title("tailnet", w, &p.accent)]; + let Some(data) = data else { + rows.push(tc::seg( + &[( + p.relay.as_str(), + format!(" {}", if err.is_empty() { "connecting…" } else { &err }), + )], + w - 1, + )); + tc::draw(&rows, w, h); + std::thread::sleep(Duration::from_millis(400)); + continue; + }; + + let me = data["Self"].clone(); + let peers: Vec = data["Peer"] + .as_object() + .into_iter() + .flatten() + .map(|(_, v)| v.clone()) + .collect(); + let online: Vec<&serde_json::Value> = peers + .iter() + .filter(|x| x["Online"].as_bool().unwrap_or(false)) + .collect(); + let direct = online.iter().filter(|x| !text(x, "CurAddr").is_empty()).count(); + let routers: Vec<&serde_json::Value> = peers + .iter() + .filter(|x| !primary_routes(x).is_empty()) + .collect(); + let exits: Vec<&serde_json::Value> = peers + .iter() + .filter(|x| x["ExitNode"].as_bool().unwrap_or(false)) + .collect(); + + let my_name = text(&me, "DNSName"); + rows.push(tc::seg( + &[ + ( + p.txt.as_str(), + format!( + " {}", + my_name.trim_end_matches('.').split('.').next().unwrap_or("") + ), + ), + ( + p.dim.as_str(), + format!( + " {}", + me["TailscaleIPs"][0].as_str().unwrap_or("?") + ), + ), + (p.dim.as_str(), format!(" {}", text(&data, "MagicDNSSuffix"))), + ], + w - 1, + )); + rows.push(tc::seg( + &[ + (p.online.as_str(), format!(" {} online", online.len())), + (p.dim.as_str(), format!(" / {} peers", peers.len())), + (p.direct.as_str(), format!(" {} direct", direct)), + ( + p.relay.as_str(), + format!(" {} relayed", online.len() - direct), + ), + (p.dim.as_str(), format!(" every {}s", interval)), + ], + w - 1, + )); + rows.push(tc::seg( + &[ + (p.route.as_str(), format!(" {} advertising routes", routers.len())), + ( + p.exit.as_str(), + format!( + " exit node: {}", + match exits.first() { + Some(x) => peer_name(x), + None => "none".into(), + } + ), + ), + ], + w - 1, + )); + rows.push(String::new()); + + if let (Some(which), false) = (view, listed.is_empty()) { + let chosen = listed[selected.min(listed.len() - 1)].clone(); + let body = if which == "info" { + let users: HashMap = data["User"] + .as_object() + .into_iter() + .flatten() + .map(|(k, v)| (k.clone(), v.clone())) + .collect(); + let latency = prober + .lock() + .ok() + .and_then(|g| g.samples.get(&peer_name(&chosen)).cloned()) + .unwrap_or_default(); + info_overlay(&chosen, &eps_now, &users, w, h, &rates, &latency, &derp, &p) + } else { + copy_overlay(&chosen, &eps_now, w, h, ¬e.0, &p) + }; + tc::draw(&body, w, h); + std::thread::sleep(Duration::from_millis(100)); + continue; + } + + if show_graph { + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── LIVE THROUGHPUT ── ".into()), + (p.dim.as_str(), "peers moving data".into()), + ], + w - 1, + )); + rows.extend(activity_rows(&rates, w, 4, &p)); + rows.push(String::new()); + } + + let wide = w >= 62; + // Machine names are long; spend spare width on them, not padding. + let namew = if wide { + (w.saturating_sub(45)).clamp(16, 32) + } else { + w.saturating_sub(22).max(12) + }; + let mut head = format!(" {} {:<8} {:<7}", tc::pad("MACHINE", namew + 1), "OS", "PATH"); + if wide { + head += &format!(" {:>5} {:>5} {:>5}", "RX", "TX", "SEEN"); + } + rows.push(tc::seg(&[(p.lbl.as_str(), tc::pad(&head, w - 1))], w - 1)); + if wide { + let span = daemon_uptime(); + rows.push(tc::seg( + &[( + p.dim.as_str(), + format!( + " rx/tx = this host ↔ peer, since tailscaled started{}", + match span { + Some(s) => format!(" {}", ago(s)), + None => String::new(), + } + ), + )], + w - 1, + )); + } + + if let Some(sel_peer) = listed.get(selected.min(listed.len().saturating_sub(1))) { + let ip4 = sel_peer["TailscaleIPs"] + .as_array() + .into_iter() + .flatten() + .filter_map(|i| i.as_str()) + .find(|i| !i.contains(':')) + .map(String::from); + // Nothing is learned by pinging ourselves, and the round trip + // would read as a suspiciously good link. + let live = sel_peer["Online"].as_bool().unwrap_or(false) + && !sel_peer["_self"].as_bool().unwrap_or(false); + watch( + &prober, + &peer_name(sel_peer), + if live { ip4 } else { None }, + ); + } + + let mut sorted = peers.clone(); + sorted.sort_by_key(|x| { + ( + !x["Online"].as_bool().unwrap_or(false), + text(x, "CurAddr").is_empty(), + std::cmp::Reverse(bytes_at(x, "RxBytes") + bytes_at(x, "TxBytes")), + ) + }); + listed = sorted + .into_iter() + .filter(|x| !(hide_offline && !x["Online"].as_bool().unwrap_or(false))) + .collect(); + // This machine belongs in the list of machines - it was only ever in + // the header - but never in the counts above it: "3 direct, 2 + // relayed" describes connections out of here, and there is no + // connection from here to here. It pins to the top rather than + // sorting by traffic, because where you are is not a ranking. + if !me.is_null() { + let mut mine = me.clone(); + mine["_self"] = serde_json::Value::Bool(true); + listed.insert(0, mine); + } + if !listed.is_empty() && selected >= listed.len() { + selected = listed.len() - 1; + } + visible = h.saturating_sub(rows.len() + 2).max(1); + if selected < scroll { + scroll = selected; + } else if selected >= scroll + visible { + scroll = selected - visible + 1; + } + scroll = scroll.min(listed.len().saturating_sub(visible)); + + for (idx, peer) in listed.iter().enumerate().skip(scroll).take(visible) { + if rows.len() >= h.saturating_sub(2) { + break; + } + let mine = peer["_self"].as_bool().unwrap_or(false); + let up = mine || peer["Online"].as_bool().unwrap_or(false); + let here = idx == selected; + let tint = if here { tc::bg(28, 44, 62) } else { String::new() }; + let c = |colour: &str| format!("{}{}", tint, colour); + let path_direct = !text(peer, "CurAddr").is_empty(); + // "this" rather than DIRECT or a relay name: the path column + // answers how the traffic gets there, and for this machine it + // does not go anywhere. + let path = if mine { + "this".to_string() + } else if path_direct { + "DIRECT".to_string() + } else { + match text(peer, "Relay") { + s if s.is_empty() => "?".into(), + s => s, + } + }; + let name = peer_name(peer); + let mut line = vec![ + ( + c(if mine { + &p.accent + } else if up { + &p.online + } else { + &p.offline + }), + format!( + "{}{} ", + if here { "▸" } else { " " }, + if mine { '◆' } else if up { '●' } else { '○' } + ), + ), + ( + c(if up { &p.txt } else { &p.offline }), + tc::pad(&name.chars().take(namew - 1).collect::(), namew), + ), + ( + c(&p.dim), + format!("{:<8}", text(peer, "OS").chars().take(8).collect::()), + ), + ( + c(if mine { + &p.accent + } else if path_direct { + &p.direct + } else { + &p.relay + }), + format!("{:<7}", if up { path.as_str() } else { "-" }), + ), + ]; + if wide { + line.push(( + c(&p.dim), + format!( + " {} {}", + human(bytes_at(peer, "RxBytes")), + human(bytes_at(peer, "TxBytes")) + ), + )); + line.push(( + c(&p.dim), + format!( + " {:>5}", + if up { "now".to_string() } else { seen(&text(peer, "LastSeen")) } + ), + )); + } + if !primary_routes(peer).is_empty() { + line.push((c(&p.route), " ⇄".into())); + } + if here { + line.push((tint.clone(), " ".repeat(w))); + } + let refs: Vec<(&str, String)> = + line.iter().map(|(c, t)| (c.as_str(), t.clone())).collect(); + rows.push(tc::seg(&refs, w - 1)); + } + + while rows.len() < h.saturating_sub(2) { + rows.push(String::new()); + } + if let Some(first) = routers.first() { + let rts = primary_routes(first); + rows.push(tc::seg( + &[ + (p.route.as_str(), " ⇄ ".into()), + (p.dim.as_str(), format!("{} routes ", text(first, "HostName"))), + (p.txt.as_str(), rts.iter().take(2).cloned().collect::>().join(", ")), + ( + p.dim.as_str(), + if rts.len() > 2 { + format!(" +{} more", rts.len() - 2) + } else { + String::new() + }, + ), + ], + w - 1, + )); + } + let hints: Vec> = vec![ + vec![(p.accent.as_str(), "↑↓".into()), (p.dim.as_str(), " select".into())], + vec![(p.dim.as_str(), "↵/[i]nfo".into())], + vec![(p.dim.as_str(), "[c]opy".into())], + vec![(p.dim.as_str(), "[g]raph".into())], + vec![(p.dim.as_str(), "[o]ffline".into())], + vec![(p.dim.as_str(), format!("[n]={}s", interval))], + vec![(p.dim.as_str(), "[r]efresh".into())], + vec![(p.dim.as_str(), "[q]uit".into())], + ]; + for line in tc::pack_hints(&hints, w - 2, " ") { + rows.push(format!(" {}", line)); + } + tc::draw(&rows, w, h); + std::thread::sleep(Duration::from_millis(300)); + } +} + +/// Everything known about one machine, including every address. +#[allow(clippy::too_many_arguments)] +fn info_overlay( + peer: &serde_json::Value, + eps: &HashMap>, + users: &HashMap, + w: usize, + h: usize, + rates: &HashMap>, + latency: &[Option], + derp: &HashMap, + p: &Palette, +) -> Vec { + let mut rows = vec![tc::title("machine info", w, &p.accent)]; + let dns = text(peer, "DNSName").trim_end_matches('.').to_string(); + let owner = users + .get(&peer["UserID"].as_i64().unwrap_or(0).to_string()) + .map(|u| text(u, "LoginName")) + .unwrap_or_default(); + + macro_rules! field { + ($label:expr, $value:expr, $colour:expr) => {{ + let value: String = $value; + if !value.is_empty() { + rows.push(tc::seg( + &[ + (p.dim.as_str(), format!(" {:<13}", $label)), + ($colour, value), + ], + w - 1, + )); + } + }}; + } + + field!("machine", peer_name(peer), p.accent.as_str()); + field!("dns name", dns.clone(), p.txt.as_str()); + let hostname = text(peer, "HostName"); + if hostname != peer_name(peer) && !hostname.is_empty() { + field!( + "hostname", + format!("{} (self-reported)", hostname), + p.dim.as_str() + ); + } + field!("os", text(peer, "OS"), p.txt.as_str()); + let region = text(peer, "Relay"); + if !region.is_empty() { + field!( + "region", + match derp.get(®ion) { + Some(city) => format!("{} — {}", region, city), + None => region.clone(), + }, + p.route.as_str() + ); + } + field!("owner", owner, p.txt.as_str()); + field!( + "tags", + peer["Tags"] + .as_array() + .into_iter() + .flatten() + .filter_map(|t| t.as_str()) + .collect::>() + .join(", "), + p.route.as_str() + ); + rows.push(String::new()); + + let up = peer["Online"].as_bool().unwrap_or(false); + field!( + "status", + if up { "online" } else { "offline" }.to_string(), + if up { p.online.as_str() } else { p.offline.as_str() } + ); + let cur = text(peer, "CurAddr"); + if !cur.is_empty() { + field!("path", format!("DIRECT via {}", cur), p.direct.as_str()); + } else { + let relay = match region.as_str() { + "" => "?".to_string(), + s => s.to_string(), + }; + let city = derp.get(&relay).cloned().unwrap_or_default(); + field!( + "path", + format!( + "relayed through DERP {}{}", + relay, + if city.is_empty() { String::new() } else { format!(" ({})", city) } + ), + p.relay.as_str() + ); + } + field!( + "rx / tx", + format!( + "{} / {}", + human(bytes_at(peer, "RxBytes")).trim(), + human(bytes_at(peer, "TxBytes")).trim() + ), + p.txt.as_str() + ); + field!("handshake", stamp(&text(peer, "LastHandshake")), p.txt.as_str()); + let last = stamp(&text(peer, "LastSeen")); + field!( + "last seen", + if last.is_empty() { + if up { "connected".to_string() } else { "-".to_string() } + } else { + last + }, + p.txt.as_str() + ); + field!("added", stamp(&text(peer, "Created")), p.txt.as_str()); + rows.push(String::new()); + + rows.push(tc::seg(&[(p.lbl.as_str(), " addresses".into())], w - 1)); + for ip in peer["TailscaleIPs"].as_array().into_iter().flatten() { + field!( + " tailscale", + ip.as_str().unwrap_or("").to_string(), + p.accent.as_str() + ); + } + let (mut pub_ips, mut priv_ips, mut other) = (Vec::new(), Vec::new(), Vec::new()); + let cur_host = cur.rsplit_once(':').map(|(h, _)| h).unwrap_or(&cur).to_string(); + if !cur_host.is_empty() { + pub_ips.push(cur_host); + } + for ip in eps.get(&dns).into_iter().flatten() { + let bucket = match classify(ip) { + "public" => &mut pub_ips, + "private" => &mut priv_ips, + _ => &mut other, + }; + if !bucket.contains(ip) { + bucket.push(ip.clone()); + } + } + let routes = primary_routes(peer); + priv_ips.sort_by_key(|i| lan_rank(i, &routes)); + for ip in &pub_ips { + field!(" public", ip.clone(), p.txt.as_str()); + } + for ip in &priv_ips { + let tag = if routes.iter().any(|r| in_network(ip, r)) { + " (in advertised subnet)" + } else { + "" + }; + field!(" private", format!("{}{}", ip, tag), p.txt.as_str()); + } + for ip in &other { + field!(" other", ip.clone(), p.dim.as_str()); + } + if eps.is_empty() { + rows.push(tc::seg( + &[( + p.dim.as_str(), + " endpoints need sudo; only the current path is shown".into(), + )], + w - 1, + )); + } + + if !routes.is_empty() { + rows.push(String::new()); + rows.push(tc::seg(&[(p.lbl.as_str(), " advertises".into())], w - 1)); + for r in routes.iter().take(6) { + rows.push(tc::seg(&[(p.route.as_str(), format!(" {}", r))], w - 1)); + } + if routes.len() > 6 { + rows.push(tc::seg( + &[(p.dim.as_str(), format!(" +{} more", routes.len() - 6))], + w - 1, + )); + } + } + + let pings: Vec = latency.iter().filter_map(|x| *x).collect(); + if !latency.is_empty() { + rows.push(String::new()); + let loss = 100.0 * (latency.len() - pings.len()) as f64 / latency.len() as f64; + if !pings.is_empty() { + let mut ordered = pings.clone(); + ordered.sort_by(f64::total_cmp); + let jit = if pings.len() > 1 { + pings.windows(2).map(|x| (x[1] - x[0]).abs()).sum::() + / (pings.len() - 1) as f64 + } else { + 0.0 + }; + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " latency ".into()), + ( + p.dim.as_str(), + format!("(icmp over tailscale, {} samples)", latency.len()), + ), + ], + w - 1, + )); + rows.push(tc::seg( + &[ + (p.dim.as_str(), " now ".into()), + (p.txt.as_str(), format!("{:>7.2}ms", pings[pings.len() - 1])), + (p.dim.as_str(), " avg ".into()), + ( + p.txt.as_str(), + format!("{:>7.2}ms", pings.iter().sum::() / pings.len() as f64), + ), + (p.dim.as_str(), " med ".into()), + (p.txt.as_str(), format!("{:>7.2}ms", ordered[ordered.len() / 2])), + ], + w - 1, + )); + rows.push(tc::seg( + &[ + (p.dim.as_str(), " min ".into()), + (p.txt.as_str(), format!("{:>7.2}ms", ordered[0])), + (p.dim.as_str(), " max ".into()), + (p.txt.as_str(), format!("{:>7.2}ms", ordered[ordered.len() - 1])), + (p.dim.as_str(), " jit ".into()), + (p.txt.as_str(), format!("{:>7.2}ms", jit)), + ], + w - 1, + )); + rows.push(tc::seg( + &[ + (p.dim.as_str(), " loss".into()), + ( + if loss == 0.0 { p.online.as_str() } else { p.relay.as_str() }, + format!("{:>7.1}%", loss), + ), + ], + w - 1, + )); + let (lo, hi) = (ordered[0], ordered[ordered.len() - 1]); + let span = if hi > lo { hi - lo } else { 1.0 }; + let sw = w.saturating_sub(8).max(10); + let mut marks: Vec<(&str, String)> = vec![(p.dim.as_str(), " ".into())]; + for v in latency.iter().rev().take(sw).rev() { + match v { + None => marks.push((p.relay.as_str(), "×".into())), + Some(v) => marks.push(( + p.online.as_str(), + SPARK[((((v - lo) / span) * 7.99) as usize).min(7)].to_string(), + )), + } + } + rows.push(tc::seg(&marks, w - 1)); + } else { + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " latency ".into()), + (p.relay.as_str(), "no replies".into()), + ], + w - 1, + )); + } + } else if up { + rows.push(String::new()); + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " latency ".into()), + (p.dim.as_str(), "probing…".into()), + ], + w - 1, + )); + } + + if let Some(hist) = rates.get(&peer_name(peer)).filter(|h| !h.is_empty()) { + rows.push(String::new()); + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " throughput ".into()), + ( + p.dim.as_str(), + format!("(last {} samples)", hist.len().min(60)), + ), + ], + w - 1, + )); + let rx: Vec = hist.iter().map(|(r, _)| *r).collect(); + let tx: Vec = hist.iter().map(|(_, t)| *t).collect(); + let peak = rx + .iter() + .chain(tx.iter()) + .cloned() + .fold(0.0f64, f64::max) + .max(1.0); + let sw = w.saturating_sub(22).max(10); + rows.push(tc::seg( + &[ + (p.dim.as_str(), " down ".into()), + (p.online.as_str(), spark(&rx, sw, peak)), + (p.dim.as_str(), format!(" {}", rate(*rx.last().unwrap_or(&0.0)))), + ], + w - 1, + )); + rows.push(tc::seg( + &[ + (p.dim.as_str(), " up ".into()), + (p.relay.as_str(), spark(&tx, sw, peak)), + (p.dim.as_str(), format!(" {}", rate(*tx.last().unwrap_or(&0.0)))), + ], + w - 1, + )); + rows.push(tc::seg( + &[(p.dim.as_str(), format!(" peak {}", rate(peak)))], + w - 1, + )); + } + + if peer["ExitNodeOption"].as_bool().unwrap_or(false) { + rows.push(String::new()); + rows.push(tc::seg( + &[(p.exit.as_str(), " offers itself as an exit node".into())], + w - 1, + )); + } + + while rows.len() < h.saturating_sub(1) { + rows.push(String::new()); + } + rows.push(tc::seg( + &[(p.dim.as_str(), " [c]opy addresses · esc, ↵ or i to close".into())], + w - 1, + )); + rows +} + +fn copy_overlay( + peer: &serde_json::Value, + eps: &HashMap>, + w: usize, + h: usize, + note: &str, + p: &Palette, +) -> Vec { + let pairs = addresses(peer, eps); + let mut rows = vec![tc::title("copy address", w, &p.accent)]; + rows.push(tc::seg( + &[ + (p.accent.as_str(), format!(" {}", peer_name(peer))), + ( + p.dim.as_str(), + format!(" {}", text(peer, "DNSName").trim_end_matches('.')), + ), + ], + w - 1, + )); + rows.push(String::new()); + if pairs.is_empty() { + rows.push(tc::seg( + &[(p.dim.as_str(), " no addresses known for this machine".into())], + w - 1, + )); + } + for (i, (label, value)) in pairs.iter().enumerate() { + rows.push(tc::seg( + &[ + (p.online.as_str(), format!(" [{}] ", i + 1)), + (p.txt.as_str(), format!("{:<18} ", label)), + (p.accent.as_str(), value.clone()), + ], + w - 1, + )); + } + while rows.len() < h.saturating_sub(2) { + rows.push(String::new()); + } + rows.push(tc::seg( + &[( + p.dim.as_str(), + format!( + " press 1-{} to copy · esc or c to close", + pairs.len().max(1) + ), + )], + w - 1, + )); + rows.push(if note.is_empty() { + String::new() + } else { + tc::seg(&[(p.online.as_str(), format!(" {}", note))], w - 1) + }); + rows +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn a_name_comes_from_magicdns_not_the_device() { + // Two iPads both call themselves "localhost"; the MagicDNS label is + // unique across the tailnet and matches the admin console. + let peer: serde_json::Value = + serde_json::from_str(r#"{"DNSName": "pi-2-bne.tail1234.ts.net.", "HostName": "localhost"}"#) + .unwrap(); + assert_eq!(peer_name(&peer), "pi-2-bne"); + // Only when there is no DNS name does the device get to say. + let bare: serde_json::Value = serde_json::from_str(r#"{"HostName": "kitchen-pi"}"#).unwrap(); + assert_eq!(peer_name(&bare), "kitchen-pi"); + assert_eq!(peer_name(&serde_json::json!({})), "?"); + } + + #[test] + fn an_address_is_classified_from_itself() { + // 100.64/10 is the CGNAT range Tailscale uses, not a public address. + assert_eq!(classify("100.64.0.1"), "tailscale"); + assert_eq!(classify("100.127.255.254"), "tailscale"); + assert_eq!(classify("100.63.0.1"), "public"); + assert_eq!(classify("100.128.0.1"), "public"); + assert_eq!(classify("fd7a:115c:a1e0::1"), "tailscale"); + assert_eq!(classify("10.0.0.5"), "private"); + assert_eq!(classify("172.17.0.1"), "private"); + assert_eq!(classify("192.168.1.4"), "private"); + assert_eq!(classify("203.0.113.9"), "public"); + assert_eq!(classify("169.254.1.1"), "other"); + assert_eq!(classify("127.0.0.1"), "other"); + // A zone index does not change what an address is. + assert_eq!(classify("fe80::1%eth0"), "other"); + } + + #[test] + fn a_cidr_contains_what_it_should() { + assert!(in_network("192.168.1.50", "192.168.1.0/24")); + assert!(!in_network("192.168.2.50", "192.168.1.0/24")); + assert!(in_network("10.4.5.6", "10.0.0.0/8")); + // A v6 route cannot contain a v4 address, and a bare address is not + // a network. + assert!(!in_network("10.4.5.6", "fd7a::/48")); + assert!(!in_network("10.4.5.6", "10.0.0.0")); + } + + #[test] + fn a_real_lan_address_beats_a_docker_bridge() { + let routes = vec!["192.168.7.0/24".to_string()]; + // Inside an advertised subnet wins outright. + assert_eq!(lan_rank("192.168.7.20", &routes), 0); + // Then 192.168, then 10, and docker's 172.17 last. + assert!(lan_rank("192.168.9.1", &routes) < lan_rank("10.1.2.3", &routes)); + assert!(lan_rank("10.1.2.3", &routes) < lan_rank("172.17.0.1", &routes)); + } + + #[test] + fn an_exit_node_route_does_not_defeat_the_ranking() { + // AllowedIPs carries 0.0.0.0/0 for an exit node, which would match + // every address; PrimaryRoutes is filtered so it cannot. + let peer: serde_json::Value = + serde_json::from_str(r#"{"PrimaryRoutes": ["0.0.0.0/0", "::/0", "192.168.7.0/24"]}"#) + .unwrap(); + assert_eq!(primary_routes(&peer), vec!["192.168.7.0/24"]); + } + + #[test] + fn a_byte_count_is_always_five_cells() { + // Up to petabytes, which is well past anything a WireGuard counter + // reaches before tailscaled restarts. Beyond that the number itself + // is wider than the column, and so is the Python's. + for n in [0u64, 9, 10, 1023, 1024, 15_000, 3_000_000_000, 900_000_000_000_000] { + assert_eq!(human(n).chars().count(), 5, "{}", n); + } + assert_eq!(human(0), " 0B"); + assert_eq!(human(1536), " 1.5K"); + assert_eq!(human(15_360), " 15K"); + } +} diff --git a/rust/widgets/src/bin/tailnet_help.txt b/rust/widgets/src/bin/tailnet_help.txt new file mode 100644 index 0000000..31caf21 --- /dev/null +++ b/rust/widgets/src/bin/tailnet_help.txt @@ -0,0 +1,40 @@ +Tailscale network: who is online, and how you are reaching them. + +RX and TX are traffic between *this* host and that peer, counted by the local +WireGuard engine — not the peer's own totals. They reset when tailscaled +restarts, so they cover that window rather than all time. + +The column that matters is PATH. A peer is either DIRECT, meaning NAT traversal +succeeded and traffic goes peer-to-peer, or it is relayed through a named DERP +region, meaning every packet round-trips through Tailscale's infrastructure. +Relayed peers can be dramatically slower and the difference is invisible in +`tailscale status` output unless you look for it. + +Peers advertising subnet routes are flagged, since those only reach you if this +node runs with --accept-routes. + +The info view names each peer's home DERP region — the Tailscale POP nearest to +it — as a location hint. That comes from the local DERP map, so no address is +ever sent to a geolocation service. + + tailnet [-n SECONDS] + +A live throughput section graphs peers currently moving data (toggle with g), +and the info view carries the same graph for the selected machine plus ICMP +latency over the tunnel — current, average, median, min, max, jitter, loss and +a sparkline — measured the same way the latency monitor does. Only the selected +peer is probed, so this costs one ping process regardless of tailnet size. + +n cycles the poll interval while running (1/2/5/10/30s), the same way the +latency monitor's i key does; the graph resolution follows it. -n sets the +starting value, and `tailnet.refresh` in config.json sets the default. + +Keys: up/down select a peer, Enter or i opens a full machine info view (every address, +routes, tags, owner, handshake times), c or Enter opens a copy sheet offering its +Tailscale IP, MagicDNS name, public IP and LAN IP, r refreshes now, o hides +offline peers, q quits. Copying uses OSC 52, so it reaches the clipboard of +the machine you are typing at even over SSH. + +Needs the `tailscale` CLI. Peer LAN addresses come from `tailscale debug +netmap`, which needs root; it is attempted with `sudo -n` and simply omitted +when that would prompt, so nothing here requires privilege. From 1fff3ab2b14cc9b230daee1cc253efc09cf67ee1 Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sun, 23 Aug 2026 08:37:55 +0800 Subject: [PATCH 031/147] usage: the shared half, and Claude usage.py is six agent readers in one widget, and this is the framework plus the first of them. What is here works against real data; what is not here says so on its own tab, which is the same rule the Python applies to an agent that publishes nothing - a plausible zero is worse than an empty tab. The shared half is most of the substance and all of the arithmetic. The rate card, with the list prices carried as published facts and the date they were copied on carried onto the screen with them, because they go stale in silence. Longest-match model lookup, so claude-opus-4 does not shadow claude-opus-4-8. The models with no published price named explicitly, so prefix matching cannot hand one its family's rate - a number nobody published is the one thing this widget must never show. The paced bar, whose notch is where an even burn would have reached, because 71% spent with three weeks left and 71% with three days left are the same percentage and the same red. The four-step calendar, its streaks counted over the range rather than over the days the file happens to list. And pct_text, which keeps two decimals below 1% because a real 0.03% and an empty section have to be tellable apart. Claude reads its transcripts rather than the stats cache for money: the cache has one total per model per day, and input, output and the two cache durations differ in price by up to fifty times, so a total cannot be costed. Records are keyed by uuid because resuming or forking a session replays history into the new transcript - summed raw that inflated one model by 29% against Claude Code's own figures. 774MB across 468 files, cached on mtime and size so each is parsed once. The quota matches the running Python exactly: session 11% +1%, overall 49% +43%, Fable 6.0% +86%. rusqlite is in for the three vendors that keep their history in SQLite - Cursor, Copilot and Antigravity - which was the decision that unblocked this. Bundled, so the binary still runs where sqlite is not installed. LTO drops it from the other thirteen: matrix and ports are byte-identical in size. Codex, Grok, Cursor, Copilot and Antigravity have no reader here yet. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/Cargo.lock | 118 ++ rust/core/src/lib.rs | 37 + rust/widgets/Cargo.toml | 10 + rust/widgets/src/bin/start.rs | 5 + rust/widgets/src/bin/usage.rs | 1758 +++++++++++++++++++++++++ rust/widgets/src/bin/usage/vendors.rs | 1225 +++++++++++++++++ rust/widgets/src/bin/usage_help.txt | 18 + 7 files changed, 3171 insertions(+) create mode 100644 rust/widgets/src/bin/usage.rs create mode 100644 rust/widgets/src/bin/usage/vendors.rs create mode 100644 rust/widgets/src/bin/usage_help.txt diff --git a/rust/Cargo.lock b/rust/Cargo.lock index 1c2b57d..f52c325 100644 --- a/rust/Cargo.lock +++ b/rust/Cargo.lock @@ -2,6 +2,18 @@ # It is not intended for manual editing. version = 4 +[[package]] +name = "ahash" +version = "0.8.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5a15f179cd60c4584b8a8c596927aadc462e27f2ca70c04e0071964a73ba7a75" +dependencies = [ + "cfg-if", + "once_cell", + "version_check", + "zerocopy", +] + [[package]] name = "android_system_properties" version = "0.1.6" @@ -17,6 +29,12 @@ version = "1.5.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53" +[[package]] +name = "bitflags" +version = "2.13.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b588b76d00fde79687d7646a9b5bdf3cc0f655e0bbd080335a95d7e96f3587da" + [[package]] name = "bumpalo" version = "3.20.3" @@ -66,6 +84,18 @@ version = "0.8.7" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b" +[[package]] +name = "fallible-iterator" +version = "0.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2acce4a10f12dc2fb14a218589d4f1f62ef011b2d0cc4b3cb1bba8e94da14649" + +[[package]] +name = "fallible-streaming-iterator" +version = "0.1.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7360491ce676a36bf9bb3c56c1aa791658183a54d2744120f27285738d90465a" + [[package]] name = "find-msvc-tools" version = "0.1.11" @@ -96,6 +126,24 @@ dependencies = [ "slab", ] +[[package]] +name = "hashbrown" +version = "0.14.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e5274423e17b7c9fc20b6e7e208532f9b19825d82dfd615708b70edd83df41f1" +dependencies = [ + "ahash", +] + +[[package]] +name = "hashlink" +version = "0.9.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6ba4ff7128dee98c7dc9794b6a411377e1404dba1c97deb8d1a55297bd25d8af" +dependencies = [ + "hashbrown", +] + [[package]] name = "iana-time-zone" version = "0.1.65" @@ -143,6 +191,17 @@ version = "0.2.189" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2" +[[package]] +name = "libsqlite3-sys" +version = "0.30.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2e99fb7a497b1e3339bc746195567ed8d3e24945ecd636e3619d20b9de9e9149" +dependencies = [ + "cc", + "pkg-config", + "vcpkg", +] + [[package]] name = "log" version = "0.4.34" @@ -194,6 +253,12 @@ version = "0.2.17" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd" +[[package]] +name = "pkg-config" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f6b464fbc74e149a392436b17d523f769e057cb6877f6a5c4618bc6f11800548" + [[package]] name = "proc-macro2" version = "1.0.107" @@ -212,6 +277,20 @@ dependencies = [ "proc-macro2", ] +[[package]] +name = "rusqlite" +version = "0.32.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7753b721174eb8ff87a9a0e799e2d7bc3749323e773db92e0984debb00019d6e" +dependencies = [ + "bitflags", + "fallible-iterator", + "fallible-streaming-iterator", + "hashlink", + "libsqlite3-sys", + "smallvec", +] + [[package]] name = "rustversion" version = "1.0.23" @@ -278,6 +357,12 @@ version = "0.4.12" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5" +[[package]] +name = "smallvec" +version = "1.15.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8ed6a63f02c8539c91a8685a86f4099661ba3da017932f6ebbea6de3f0fa7c90" + [[package]] name = "syn" version = "2.0.119" @@ -317,6 +402,7 @@ dependencies = [ "chrono", "chrono-tz", "libc", + "rusqlite", "serde_json", "toys-core", ] @@ -327,6 +413,18 @@ version = "1.0.24" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75" +[[package]] +name = "vcpkg" +version = "0.2.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "accd4ea62f7bb7a82fe23066fb0957d48ef677f6eeb8215f372f52e48bb32426" + +[[package]] +name = "version_check" +version = "0.9.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a" + [[package]] name = "wasm-bindgen" version = "0.2.127" @@ -431,6 +529,26 @@ dependencies = [ "windows-link", ] +[[package]] +name = "zerocopy" +version = "0.8.56" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "556764e583adb45a9f8d413c2a147fa7e8d821e48e12b14fd560b607998b75eb" +dependencies = [ + "zerocopy-derive", +] + +[[package]] +name = "zerocopy-derive" +version = "0.8.56" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f2ab42fc20575779bd240faa45f94a74256f755c0fa9e89f0ede20d91d0cdfc1" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + [[package]] name = "zmij" version = "1.0.23" diff --git a/rust/core/src/lib.rs b/rust/core/src/lib.rs index c6b0693..d154fba 100644 --- a/rust/core/src/lib.rs +++ b/rust/core/src/lib.rs @@ -738,6 +738,28 @@ pub fn skeleton(width: usize, tick: usize, span: usize) -> Vec<(String, String)> out } +/// Cell widths for `count` bars that fill `room` columns exactly. +/// +/// The remainder goes to the leftmost bars rather than being dropped on the +/// floor by integer division: stopping short of the right edge leaves no way +/// to tell a finished chart from a truncated one. Twenty-eight days across +/// fifty-nine columns is two cells each and three columns wasted, which +/// reads as a chart that gave up. +pub fn spread(count: usize, room: usize) -> Vec { + if count == 0 { + return Vec::new(); + } + if count >= room { + // One cell each and the caller decides what to drop: silently + // returning fewer widths than bars would lose data without saying so. + return vec![1; count]; + } + let (slot, extra) = (room / count, room % count); + (0..count) + .map(|i| slot + usize::from(i < extra)) + .collect() +} + /// Which of these required commands are not on PATH. pub fn missing(programs: &[&str]) -> Vec { let path = std::env::var("PATH").unwrap_or_default(); @@ -1033,6 +1055,21 @@ mod tests { assert!((0..40).map(runs).collect::>().len() > 1); } + #[test] + fn spread_fills_its_room_exactly() { + // Twenty-eight days across fifty-nine columns: the three left over + // go to the leftmost bars rather than leaving the chart short. + let widths = spread(28, 59); + assert_eq!(widths.len(), 28); + assert_eq!(widths.iter().sum::(), 59); + assert_eq!(widths[0], 3); + assert_eq!(widths[27], 2); + // More bars than columns is one cell each, and the caller decides + // what to drop - returning fewer widths would lose data silently. + assert_eq!(spread(10, 4), vec![1; 10]); + assert!(spread(0, 10).is_empty()); + } + #[test] fn a_blend_reaches_both_ends() { assert_eq!(mix((0, 0, 0), (10, 20, 30), 0.0), rgb(0, 0, 0)); diff --git a/rust/widgets/Cargo.toml b/rust/widgets/Cargo.toml index d121337..1f81da7 100644 --- a/rust/widgets/Cargo.toml +++ b/rust/widgets/Cargo.toml @@ -12,6 +12,12 @@ serde_json = "1" # nothing at run time because LTO drops what no binary reaches. chrono = { version = "0.4", default-features = false, features = ["clock", "std"] } chrono-tz = "0.10" +# usage reads three of its six agent vendors out of SQLite files, which is +# what Cursor, Copilot and Antigravity each keep their history in. Python +# has sqlite3 in its standard library; this is the equivalent, bundled so +# that the binary still runs on a machine with no sqlite installed - the +# single executable being the point of the port. +rusqlite = { version = "0.32", features = ["bundled"] } [[bin]] name = "ports" @@ -64,3 +70,7 @@ path = "src/bin/github.rs" [[bin]] name = "tailnet" path = "src/bin/tailnet.rs" + +[[bin]] +name = "usage" +path = "src/bin/usage.rs" diff --git a/rust/widgets/src/bin/start.rs b/rust/widgets/src/bin/start.rs index 175f391..b9f8d83 100644 --- a/rust/widgets/src/bin/start.rs +++ b/rust/widgets/src/bin/start.rs @@ -98,6 +98,11 @@ const WIDGETS: &[Widget] = &[ help: include_str!("tailnet_help.txt"), doc: include_str!("../../../../docs/tailnet.md"), }, + Widget { + stem: "usage", + help: include_str!("usage_help.txt"), + doc: include_str!("../../../../docs/usage.md"), + }, ]; impl Widget { diff --git a/rust/widgets/src/bin/usage.rs b/rust/widgets/src/bin/usage.rs new file mode 100644 index 0000000..2cef942 --- /dev/null +++ b/rust/widgets/src/bin/usage.rs @@ -0,0 +1,1758 @@ +// terminal-toys - small dependency-free terminal widgets +// Copyright (C) 2026 William Li +// +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU Affero General Public License as published +// by the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU Affero General Public License for more details. +// +// You should have received a copy of the GNU Affero General Public License +// along with this program. If not, see . + +//! How much the coding agents on this machine have been used. +//! +//! A port of usage.py. One tab per agent, because they do not agree on what +//! usage even means: one counts tokens, another counts lines it wrote, and +//! several publish nothing at all outside their own session. An agent that +//! exposes nothing says so rather than showing a plausible zero. + +use std::collections::HashMap; +use std::sync::{Arc, Condvar, Mutex}; +use std::time::{Duration, SystemTime, UNIX_EPOCH}; + +use chrono::{Datelike, Duration as Days, NaiveDate, TimeZone, Utc}; +use toys_core as tc; + +/// The priced kinds, in the order every rate card lists them. +const RATE_KINDS: &[&str] = &[ + "input", + "output", + "cache_read", + "cache_write", + "cache_write_1h", +]; + +const LIST_RATES_AS_OF: &str = "Aug 2026"; +/// Models known to have no published price: prefix matching would otherwise +/// hand gpt-5.3-codex-spark its family's rate, and Spark is explicitly not +/// on the API. Naming them makes them report as unpriced rather than as a +/// number nobody published. +const NO_PUBLISHED_PRICE: &[&str] = &["gpt-5.3-codex-spark", "codex-auto-review"]; + +/// Published list prices, US$ per million tokens, from the vendors' own +/// pricing pages on the date above. They are shipped because they are +/// published facts with a citable source, not a guess - but they go stale +/// silently, so the date is carried onto the screen with them and config +/// overrides any line. +/// +/// Cache writes come in two durations at different prices, and the +/// transcripts record which was taken per iteration, so both are carried +/// and neither is assumed. OpenAI does not charge for cache writes, so +/// those entries are absent rather than zero. +const LIST_RATES: &[(&str, &[(&str, f64)])] = &[ + ("gpt-5.6-sol", &[("input", 5.0), ("output", 30.0), ("cache_read", 0.50)]), + ("gpt-5.6-terra", &[("input", 2.0), ("output", 12.0), ("cache_read", 0.20)]), + ("gpt-5.6-luna", &[("input", 0.20), ("output", 1.20), ("cache_read", 0.02)]), + ("gpt-5.5-pro", &[("input", 30.0), ("output", 180.0)]), + ("gpt-5.5", &[("input", 5.0), ("output", 30.0), ("cache_read", 0.50)]), + ("gpt-5.4-mini", &[("input", 0.75), ("output", 4.50), ("cache_read", 0.075)]), + ("gpt-5.4-nano", &[("input", 0.20), ("output", 1.25), ("cache_read", 0.02)]), + ("gpt-5.4-pro", &[("input", 30.0), ("output", 180.0)]), + ("gpt-5.4", &[("input", 2.50), ("output", 15.0), ("cache_read", 0.25)]), + ("gpt-5.3-codex", &[("input", 1.75), ("output", 14.0), ("cache_read", 0.175)]), + ("gpt-5.2-pro", &[("input", 21.0), ("output", 168.0)]), + ("gpt-5.2", &[("input", 1.75), ("output", 14.0), ("cache_read", 0.175)]), + ("gpt-5.1", &[("input", 1.25), ("output", 10.0), ("cache_read", 0.125)]), + ("gpt-5-mini", &[("input", 0.25), ("output", 2.0), ("cache_read", 0.025)]), + ("gpt-5-nano", &[("input", 0.05), ("output", 0.40), ("cache_read", 0.005)]), + ("gpt-5-pro", &[("input", 15.0), ("output", 120.0)]), + ("gpt-5", &[("input", 1.25), ("output", 10.0), ("cache_read", 0.125)]), + ( + "claude-fable-5", + &[("input", 10.0), ("output", 50.0), ("cache_write", 12.50), ("cache_read", 1.0), ("cache_write_1h", 20.0)], + ), + ( + "claude-mythos-5", + &[("input", 10.0), ("output", 50.0), ("cache_write", 12.50), ("cache_read", 1.0), ("cache_write_1h", 20.0)], + ), + ( + "claude-opus-5", + &[("input", 5.0), ("output", 25.0), ("cache_write", 6.25), ("cache_read", 0.50), ("cache_write_1h", 10.0)], + ), + ( + "claude-opus-4-8", + &[("input", 5.0), ("output", 25.0), ("cache_write", 6.25), ("cache_read", 0.50), ("cache_write_1h", 10.0)], + ), + ( + "claude-opus-4-7", + &[("input", 5.0), ("output", 25.0), ("cache_write", 6.25), ("cache_read", 0.50), ("cache_write_1h", 10.0)], + ), + ( + "claude-opus-4-6", + &[("input", 5.0), ("output", 25.0), ("cache_write", 6.25), ("cache_read", 0.50), ("cache_write_1h", 10.0)], + ), + ( + "claude-opus-4-5", + &[("input", 5.0), ("output", 25.0), ("cache_write", 6.25), ("cache_read", 0.50), ("cache_write_1h", 10.0)], + ), + ( + "claude-opus-4-1", + &[("input", 15.0), ("output", 75.0), ("cache_write", 18.75), ("cache_read", 1.50), ("cache_write_1h", 30.0)], + ), + ( + "claude-sonnet-5", + &[("input", 2.0), ("output", 10.0), ("cache_write", 2.50), ("cache_read", 0.20), ("cache_write_1h", 4.0)], + ), + ( + "claude-sonnet-4-6", + &[("input", 3.0), ("output", 15.0), ("cache_write", 3.75), ("cache_read", 0.30), ("cache_write_1h", 6.0)], + ), + ( + "claude-sonnet-4-5", + &[("input", 3.0), ("output", 15.0), ("cache_write", 3.75), ("cache_read", 0.30), ("cache_write_1h", 6.0)], + ), + ( + "claude-haiku-4-5", + &[("input", 1.0), ("output", 5.0), ("cache_write", 1.25), ("cache_read", 0.10), ("cache_write_1h", 2.0)], + ), + ( + "claude-haiku-3-5", + &[("input", 0.80), ("output", 4.0), ("cache_write", 1.0), ("cache_read", 0.08), ("cache_write_1h", 1.6)], + ), +]; + +/// One hue, four steps, the way /stats and the contribution calendar do it. +/// heat() runs green to amber to red, which reads as a change of *kind* +/// rather than of amount - wrong for "more of the same thing". +const HEAT_STEPS: [(u8, u8, u8); 4] = [(74, 52, 46), (140, 78, 58), (196, 100, 66), (240, 132, 84)]; +// Carried with Claude's because they are the Python's own four-step ramps +// and the vendors that use them are the next thing to be ported. Kept here +// rather than reinvented later, where the numbers would drift. +#[allow(dead_code)] +const CODEX_STEPS: [(u8, u8, u8); 4] = + [(66, 72, 82), (122, 130, 144), (182, 190, 202), (240, 244, 250)]; +#[allow(dead_code)] +const GROK_STEPS: [(u8, u8, u8); 4] = [(44, 62, 88), (62, 104, 156), (86, 150, 210), (120, 196, 250)]; +#[allow(dead_code)] +const CURSOR_STEPS: [(u8, u8, u8); 4] = + [(48, 74, 66), (72, 124, 104), (100, 172, 142), (140, 220, 184)]; + +/// One hue per provider. Each is the colour that agent's own tab already +/// uses, so the same agent looks the same wherever you meet it. Copilot and +/// Antigravity have no calendar to borrow from and get their own, chosen to +/// sit clear of the amber and red this widget reserves for trouble. +fn agent_hue(name: &str) -> Option<(u8, u8, u8)> { + Some(match name { + "claude" => (240, 132, 84), + "codex" => (206, 214, 228), + "cursor" => (126, 208, 176), + "grok" => (120, 196, 250), + "copilot" => (186, 166, 255), + "antigravity" => (232, 158, 200), + _ => return None, + }) +} + +#[allow(dead_code)] +fn agent_steps(name: &str) -> [(u8, u8, u8); 4] { + match name { + "codex" => CODEX_STEPS, + "grok" => GROK_STEPS, + "cursor" => CURSOR_STEPS, + _ => HEAT_STEPS, + } +} + +const SPINNER: &[char] = &['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']; +const SUMMARY_TAB: &str = "+"; +const ORDER: &[&str] = &["claude", "codex", "cursor", "grok", "copilot", "antigravity"]; +const MONTHS: &[&str] = &[ + "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec", +]; + +/// Below this much of a window, a pace figure is noise. +const PACE_FLOOR: f64 = 3.0; +/// The five-hour session and the seven-day total, which the response names +/// in its own top-level keys rather than in limits[]. +const CLAUDE_WINDOW_SECS: &[(&str, f64)] = &[("session", 5.0 * 3600.0), ("weekly", 7.0 * 86400.0)]; + +fn now() -> f64 { + SystemTime::now() + .duration_since(UNIX_EPOCH) + .map(|d| d.as_secs_f64()) + .unwrap_or(0.0) +} + +fn home() -> String { + std::env::var("HOME").unwrap_or_default() +} + +fn under_home(rest: &str) -> String { + format!("{}/{}", home(), rest) +} + +fn text(value: &serde_json::Value, key: &str) -> String { + value[key].as_str().unwrap_or("").to_string() +} + +fn num(value: &serde_json::Value, key: &str) -> f64 { + value[key].as_f64().unwrap_or(0.0) +} + +/// A duration in milliseconds as days, hours and minutes. +fn span_ms(ms: f64) -> String { + let s = (ms / 1000.0) as i64; + let (d, rest) = (s / 86400, s % 86400); + let (h, rest) = (rest / 3600, rest % 3600); + let m = rest / 60; + if d > 0 { + format!("{}d {}h {}m", d, h, m) + } else if h > 0 { + format!("{}h {}m", h, m) + } else if m > 0 { + // A couple of seconds of generation is not "0m". + format!("{}m", m) + } else { + format!("{:.1}s", ms / 1000.0) + } +} + +/// Token counts run to billions; nobody reads eleven digits. +fn big_num(n: f64) -> String { + for (unit, size) in [("B", 1e9), ("M", 1e6), ("k", 1e3)] { + if n.abs() >= size { + return format!("{:.1}{}", n / size, unit); + } + } + format!("{}", n as i64) +} + +fn ago(when: f64) -> String { + if when <= 0.0 { + return "never".into(); + } + let s = now() - when; + if s < 60.0 { + format!("{}s", s as i64) + } else if s < 3600.0 { + format!("{}m", (s / 60.0) as i64) + } else if s < 86400.0 { + format!("{}h", (s / 3600.0) as i64) + } else if s < 365.0 * 86400.0 { + format!("{}d", (s / 86400.0) as i64) + } else { + // A subscription can be years old, and "890d" is not a span anyone + // reads. + format!("{:.1}y", s / (365.0 * 86400.0)) + } +} + +/// ISO-8601 to epoch seconds. +/// +/// These APIs mix a trailing Z with +00:00 in the same response, and Go +/// writes nanoseconds where the parsers take three or six digits. +fn iso_epoch(s: &str) -> Option { + if s.is_empty() { + return None; + } + let s = s.trim_end_matches('Z'); + // Trim any sub-second field to microseconds, whatever it arrived as. + let cleaned = match s.find('.') { + Some(dot) => { + let tail = &s[dot + 1..]; + let digits: String = tail.chars().take_while(|c| c.is_ascii_digit()).collect(); + let rest = &tail[digits.len()..]; + format!("{}.{}{}", &s[..dot], &digits[..digits.len().min(6)], rest) + } + None => s.to_string(), + }; + for fmt in [ + "%Y-%m-%dT%H:%M:%S%.f%:z", + "%Y-%m-%dT%H:%M:%S%:z", + "%Y-%m-%dT%H:%M:%S%.f", + "%Y-%m-%dT%H:%M:%S", + ] { + if let Ok(at) = chrono::DateTime::parse_from_str(&cleaned, fmt) { + return Some(at.timestamp() as f64 + at.timestamp_subsec_millis() as f64 / 1000.0); + } + if let Ok(at) = chrono::NaiveDateTime::parse_from_str(&cleaned, fmt) { + return Some(Utc.from_utc_datetime(&at).timestamp() as f64); + } + } + None +} + +/// A date, kept in the zone it arrived in. +/// +/// assigned_date carries the account's own offset. Converting it to this +/// machine's zone can move it a day - 3 Jun at 12:10 -07:00 is 4 Jun in UTC - +/// and then the pane disagrees with what the vendor shows for the same seat. +fn iso_day(s: &str) -> String { + let s = s.trim_end_matches('Z'); + for fmt in ["%Y-%m-%dT%H:%M:%S%.f%:z", "%Y-%m-%dT%H:%M:%S%:z"] { + if let Ok(at) = chrono::DateTime::parse_from_str(s, fmt) { + return format!("{} {} {}", at.day(), MONTHS[at.month0() as usize], at.year()); + } + } + for fmt in ["%Y-%m-%dT%H:%M:%S%.f", "%Y-%m-%dT%H:%M:%S", "%Y-%m-%d"] { + if let Ok(at) = chrono::NaiveDateTime::parse_from_str(s, fmt) { + return format!("{} {} {}", at.day(), MONTHS[at.month0() as usize], at.year()); + } + if let Ok(at) = NaiveDate::parse_from_str(s, fmt) { + return format!("{} {} {}", at.day(), MONTHS[at.month0() as usize], at.year()); + } + } + String::new() +} + +fn left_span(secs: f64) -> String { + let s = secs as i64; + let (d, rest) = (s / 86400, s % 86400); + let (h, rest) = (rest / 3600, rest % 3600); + if d > 0 { + format!("{}d {}h", d, h) + } else if h > 0 { + format!("{}h {}m", h, rest / 60) + } else { + format!("{}m", rest / 60) + } +} + +/// How far ahead of the clock a quota is, as a signed percentage. +/// +/// The share of the window already gone minus the share of the allowance +/// already spent. Positive is headroom; negative means this runs out before +/// the window does. Below PACE_FLOOR of a window it is not shown at all, +/// because ten minutes into a week every number looks like a catastrophe or +/// a triumph. +fn lead(pct_used: f64, window_secs: Option, reset_ts: Option) -> Option { + let (window, reset) = (window_secs?, reset_ts?); + if window <= 0.0 { + return None; + } + let gone = window - (reset - now()); + if gone <= 0.0 || gone > window { + return None; + } + let elapsed = 100.0 * gone / window; + if elapsed < PACE_FLOOR { + return None; + } + Some(elapsed - pct_used) +} + +/// A percentage with enough precision to prove it is not a placeholder. +/// +/// Every Antigravity lane rounded to "0%" - which is what an empty section +/// looks like - while one was genuinely 0.4% spent and another 0.03%. A real +/// small number and no number at all have to be tellable apart. +fn pct_text(pct: f64) -> String { + if pct <= 0.0 { + " 0%".into() + } else if pct < 1.0 { + format!("{:5.2}%", pct) + } else if pct < 10.0 { + format!("{:5.1}%", pct) + } else { + format!("{:5.0}%", pct) + } +} + +/// How much of a window has gone, from its length and its reset. +fn elapsed_of(secs: Option, reset: Option) -> Option { + let (secs, reset) = (secs?, reset?); + if secs <= 0.0 { + return None; + } + let left = reset - now(); + if left <= 0.0 || left > secs { + return None; + } + Some((secs - left) / secs) +} + +/// The dark end of every agent ramp. The two stops above it are measured, +/// not picked: 0.51 keeps the dimmest filled cell at 3:1 against the +/// background for the darkest agent hue, and 0.34 leaves the empty track at +/// least as visible as the flat grid it replaces. +const BAR_FLOOR: (u8, u8, u8) = (30, 38, 52); + +fn blend(hue: (u8, u8, u8), t: f64) -> (u8, u8, u8) { + let step = |a: u8, b: u8| (a as f64 + (b as f64 - a as f64) * t).round() as u8; + ( + step(BAR_FLOOR.0, hue.0), + step(BAR_FLOOR.1, hue.1), + step(BAR_FLOOR.2, hue.2), + ) +} + +/// A tint of an agent's colour, t running dark to full. +/// +/// Not `shade` - that name is taken by the calendars' four-step ramp, and +/// two functions of the same name meant the heatmaps drew with this one. +fn tint(hue: (u8, u8, u8), t: f64) -> String { + let (r, g, b) = blend(hue, t); + tc::rgb(r, g, b) +} + +/// Which of the four steps a day falls in. +fn shade(frac: f64, steps: [(u8, u8, u8); 4]) -> String { + let at = ((frac * 3.999) as usize).min(3); + let (r, g, b) = steps[at]; + tc::rgb(r, g, b) +} + +struct Palette { + ok: String, + warn: String, + bad: String, + dim: String, + grid: String, + txt: String, + lbl: String, + accent: String, + agent: String, + empty_cell: String, + /// The notch is white on its own dark cell rather than a bare + /// foreground colour: plain white manages 1.2:1 against a full bar, so + /// it disappears exactly where it matters. + pace_mark: String, + /// Default background again, and only that. + nobg: String, +} + +fn palette() -> Palette { + Palette { + ok: tc::rgb(90, 240, 160), + warn: tc::rgb(255, 200, 90), + bad: tc::rgb(255, 100, 110), + dim: tc::rgb(127, 147, 172), + grid: tc::rgb(60, 78, 98), + txt: tc::rgb(225, 235, 245), + lbl: tc::rgb(130, 165, 200), + accent: tc::rgb(150, 210, 255), + agent: tc::rgb(180, 160, 255), + empty_cell: tc::rgb(58, 66, 80), + pace_mark: format!("{}{}", tc::bg(10, 12, 18), tc::rgb(238, 244, 252)), + nobg: tc::NOBG.to_string(), + } +} + +/// What colour a quota's percentage is written in. +/// +/// The agent's own colour, so the number matches the bar it sits beside. +/// Red is the one exception, at 90% spent, because nearly empty is trouble +/// whatever the pace. Behind-the-clock deliberately does not colour this: +/// the pace cell beside it is already amber for exactly that, and a number +/// and its own explanation both turning yellow reads as two problems. +fn pct_colour(pct: f64, hue: Option<(u8, u8, u8)>, p: &Palette) -> String { + if pct >= 90.0 { + return p.bad.clone(); + } + match hue { + Some((r, g, b)) => tc::rgb(r, g, b), + None => tc::heat(pct / 100.0), + } +} + +/// The signed cushion, coloured by whether it is one. +fn pace_cell(value: Option, p: &Palette) -> (String, String) { + match value { + None => (p.dim.clone(), String::new()), + Some(v) => ( + if v >= 0.0 { p.ok.clone() } else { p.warn.clone() }, + format!(" {:+.0}%", v), + ), + } +} + +/// A quota bar with a mark where an even burn would have reached by now. +/// +/// The percentage alone cannot separate a lane 71% spent with three weeks +/// left from one 71% spent with three days left, and colour alone cannot +/// either - both are the same red. The mark is the window's own progress, +/// so a fill short of it is spending slower than the clock. +fn paced_bar( + used: f64, + elapsed: Option, + room: usize, + hue: Option<(u8, u8, u8)>, + p: &Palette, +) -> Vec<(String, String)> { + let bar = tc::meter(used, room); + let filled = bar.chars().filter(|c| *c == '█').count(); + let at = elapsed.map(|e| ((e * room as f64).round() as usize).min(room.saturating_sub(1))); + let mut parts: Vec<(String, String)> = Vec::new(); + for (i, ch) in bar.chars().enumerate() { + let (colour, glyph) = if Some(i) == at { + // One colour for the mark on every bar. It is a reference line - + // where an even burn would have reached - and a line that + // changes colour looks like it has a state of its own, when the + // state being reported is the fill's position relative to it. + (p.pace_mark.clone(), '┃') + } else if i < filled { + // Filled cells run dark to full across the fill, so the bar is + // recognisably its agent's colour and still reads as a quantity + // without counting cells. + let t = 0.51 + 0.49 * (i as f64 / filled.saturating_sub(1).max(1) as f64); + ( + format!( + "{}{}", + p.nobg, + match hue { + Some(hue) => tint(hue, t), + None => tc::heat(used), + } + ), + ch, + ) + } else { + ( + format!( + "{}{}", + p.nobg, + match hue { + Some(hue) => tint(hue, 0.34), + None => p.grid.clone(), + } + ), + ch, + ) + }; + match parts.last_mut() { + Some((had, run)) if *had == colour => run.push(glyph), + _ => parts.push((colour, glyph.to_string())), + } + } + // The mark is the one thing here that sets a background, so the run ends + // by putting it back. Without this the dark cell bled through everything + // drawn after it on the row. + parts.push((p.nobg.clone(), String::new())); + parts +} + +/// Plain text flowed to a width. Clipping a sentence loses its end. +fn wrap_text(t: &str, budget: usize) -> Vec { + let mut lines = Vec::new(); + let mut line = String::new(); + for word in t.split_whitespace() { + if !line.is_empty() && line.chars().count() + 1 + word.chars().count() > budget { + lines.push(std::mem::take(&mut line)); + line.push_str(word); + } else if line.is_empty() { + line.push_str(word); + } else { + line.push(' '); + line.push_str(word); + } + } + if !line.is_empty() { + lines.push(line); + } + if lines.is_empty() { + vec![String::new()] + } else { + lines + } +} + +/// A labelled value flowed onto as many lines as it needs. +/// +/// Only text can be wrapped. A bar chart broken across two lines is not a +/// bar chart, which is why those adapt to the width instead. The +/// continuation lines sit under the value rather than under the label. +fn wrap_pair(key: &str, value: &str, label_w: usize, w: usize) -> Vec<(String, String)> { + let budget = (w.saturating_sub(label_w + 5)).max(8); + let mut lines: Vec = Vec::new(); + let mut line = String::new(); + for word in value.split_whitespace() { + let mut word = word.to_string(); + if !line.is_empty() && line.chars().count() + 1 + word.chars().count() > budget { + lines.push(std::mem::take(&mut line)); + } + // A single word longer than the column is split rather than allowed + // to run off; an enterprise sku is one word and still has to fit. + while word.chars().count() > budget { + lines.push(word.chars().take(budget).collect()); + word = word.chars().skip(budget).collect(); + } + if line.is_empty() { + line = word; + } else { + line.push(' '); + line.push_str(&word); + } + } + if !line.is_empty() { + lines.push(line); + } + lines + .into_iter() + .enumerate() + .map(|(i, part)| (if i == 0 { key.to_string() } else { String::new() }, part)) + .collect() +} + +/// What to run to make each agent start recording. An empty tab that only +/// says "nothing here" leaves the reader to guess whether it is broken. +fn run_hint(name: &str) -> &'static str { + match name { + "claude" => "claude", + "codex" => "codex", + "cursor" => "cursor-agent", + "grok" => "grok", + "copilot" => "copilot", + _ => "", + } +} + +/// The empty state: what is missing, and the one command that fixes it. +fn no_local(what: &str, run: &str, w: usize, p: &Palette) -> Vec { + let mut rows: Vec = wrap_text(what, w.saturating_sub(4).max(20)) + .into_iter() + .map(|line| tc::seg(&[(p.dim.as_str(), format!(" {}", line))], w - 1)) + .collect(); + if !run.is_empty() { + rows.push(tc::seg( + &[ + (p.dim.as_str(), " run ".into()), + (p.accent.as_str(), run.to_string()), + (p.dim.as_str(), " here and this fills in".into()), + ], + w - 1, + )); + } + rows +} + +/// A rate card: US$ per million tokens, by priced kind. +type Rate = HashMap; + +/// The rate for a model, and where it came from. +/// +/// Config wins outright, then the published list prices. Keyed by model +/// rather than by agent, because a model has one list price wherever it +/// ran. Longest matching name wins, so claude-opus-4 does not shadow +/// claude-opus-4-8, and a "*" entry catches anything left over. +fn rate_for(model: &str, configured: &HashMap) -> (Option, &'static str) { + if NO_PUBLISHED_PRICE.contains(&model) && !configured.contains_key(model) { + return (None, ""); + } + if let Some(rate) = configured.get(model) { + return (Some(rate.clone()), "config"); + } + let mut best: Option<(usize, Rate)> = None; + for (key, rate) in configured { + if key != "*" && model.contains(key.as_str()) { + let len = key.chars().count(); + if best.as_ref().is_none_or(|(had, _)| len > *had) { + best = Some((len, rate.clone())); + } + } + } + if let Some((_, rate)) = best { + return (Some(rate), "config"); + } + if let Some(rate) = configured.get("*") { + return (Some(rate.clone()), "config"); + } + let to_rate = |entries: &[(&str, f64)]| -> Rate { + entries.iter().map(|(k, v)| (k.to_string(), *v)).collect() + }; + for (key, entries) in LIST_RATES { + if *key == model { + return (Some(to_rate(entries)), "list"); + } + } + let mut best: Option<(usize, Rate)> = None; + for (key, entries) in LIST_RATES { + if model.contains(key) { + let len = key.chars().count(); + if best.as_ref().is_none_or(|(had, _)| len > *had) { + best = Some((len, to_rate(entries))); + } + } + } + match best { + Some((_, rate)) => (Some(rate), "list"), + None => (None, ""), + } +} + +/// Token counts by priced kind. +type Tokens = HashMap; + +fn cost_of(tokens: &Tokens, rate: &Rate) -> f64 { + RATE_KINDS + .iter() + .map(|kind| { + tokens.get(*kind).copied().unwrap_or(0.0) / 1e6 + * rate.get(*kind).copied().unwrap_or(0.0) + }) + .sum() +} + +fn empty_tokens() -> Tokens { + RATE_KINDS.iter().map(|k| (k.to_string(), 0.0)).collect() +} + +fn total_tokens(t: &Tokens) -> f64 { + RATE_KINDS + .iter() + .map(|k| t.get(*k).copied().unwrap_or(0.0)) + .sum() +} + +/// One costed window: its label, what it cost, how many tokens, and the +/// models under it. +type Window = (String, f64, f64, Vec<(String, f64)>); + +/// The metered section: one row per window, each with its models under it. +/// +/// Two windows - today and thirty days - because a month's total says what +/// an agent costs and today says whether that is still true. A single +/// all-time figure answered neither question. +#[allow(clippy::too_many_arguments)] +fn metered_block( + where_: &str, + windows: &[Window], + w: usize, + extras: &[(String, Option, String)], + note: &str, + scope: &str, + caveat: &str, + p: &Palette, +) -> Vec { + // Windows are kept even when empty, as long as something is. A zero + // today against a busy month is the answer to "have I used this today". + if !windows.iter().any(|x| x.1 > 0.0 || x.2 > 0.0) { + return Vec::new(); + } + // Scope first, because it is the thing most easily got wrong: this + // section sits under a QUOTA labelled "account-wide", and a local figure + // beside it reads as the same scope unless it says otherwise. + let mut rows = vec![tc::seg( + &[ + (p.lbl.as_str(), " ── METERED ── ".into()), + ( + p.txt.as_str(), + if scope.is_empty() { String::new() } else { format!("{} · ", scope) }, + ), + (p.dim.as_str(), format!("at {}", where_)), + ( + p.dim.as_str(), + if note.is_empty() { String::new() } else { format!(" {}", note) }, + ), + ], + w - 1, + )]; + if !caveat.is_empty() { + for line in wrap_text(caveat, w.saturating_sub(4).max(20)) { + rows.push(tc::seg(&[(p.dim.as_str(), format!(" {}", line))], w - 1)); + } + } + let extras: Vec<&(String, Option, String)> = + extras.iter().filter(|x| x.1.is_some()).collect(); + let label_w = windows + .iter() + .map(|x| x.0.chars().count()) + .chain(extras.iter().map(|x| x.0.chars().count())) + .max() + .unwrap_or(6); + for (label, cost, tokens, models) in windows { + rows.push(tc::seg( + &[ + (p.txt.as_str(), format!(" {} ", tc::pad(label, label_w))), + (p.agent.as_str(), tc::pad(&format!("${:.2}", cost), 11)), + (p.dim.as_str(), format!("{} tokens", big_num(*tokens))), + ], + w - 1, + )); + let top: Vec<&(String, f64)> = models.iter().take(5).collect(); + let name_w = top.iter().map(|(m, _)| m.chars().count()).max().unwrap_or(0); + for (model, model_cost) in &top { + rows.push(tc::seg( + &[ + (p.dim.as_str(), format!(" {} ", " ".repeat(label_w))), + (p.dim.as_str(), format!("{} ", tc::pad(model, name_w))), + (p.txt.as_str(), format!("${:.2}", model_cost)), + ], + w - 1, + )); + } + if models.len() > top.len() { + rows.push(tc::seg( + &[ + (p.dim.as_str(), format!(" {} ", " ".repeat(label_w))), + (p.dim.as_str(), format!("+{} more", models.len() - top.len())), + ], + w - 1, + )); + } + } + // Summary rows below the windows rather than in the header, which had + // grown long enough to clip the moment a scope word joined it. + for (label, value, colour) in extras { + rows.push(tc::seg( + &[ + (p.dim.as_str(), format!(" {} ", tc::pad(label, label_w))), + (colour.as_str(), format!("${:.2}", value.unwrap_or(0.0))), + ], + w - 1, + )); + } + rows.push(String::new()); + rows +} + +/// Cost a set of windows against the rate card. +/// +/// Only models with a rate are counted and the unpriced ones are named, so +/// a half-filled card cannot read as a total. +#[allow(clippy::too_many_arguments)] +fn metered_rows( + windows: &[(String, Vec<(String, Tokens)>)], + w: usize, + note: &str, + agent: &str, + scope: &str, + caveat: &str, + cfg: &Config, + p: &Palette, +) -> Vec { + let mut origins: Vec<&'static str> = Vec::new(); + let mut missing: Vec = Vec::new(); + let mut built: Vec = Vec::new(); + for (label, entries) in windows { + let (mut cost, mut tokens) = (0.0, 0.0); + let mut models: Vec<(String, f64)> = Vec::new(); + for (model, counts) in entries { + if total_tokens(counts) <= 0.0 { + continue; + } + let (rate, origin) = rate_for(model, &cfg.rates); + tokens += total_tokens(counts); + let Some(rate) = rate else { + if !missing.contains(model) { + missing.push(model.clone()); + } + continue; + }; + let this = cost_of(counts, &rate); + cost += this; + if !origins.contains(&origin) { + origins.push(origin); + } + models.push((model.clone(), this)); + } + models.sort_by(|a, b| b.1.total_cmp(&a.1)); + built.push((label.clone(), cost, tokens, models)); + } + if !built.iter().any(|x| x.1 > 0.0) { + if cfg.rates.is_empty() { + let mut rows = vec![tc::seg( + &[ + (p.lbl.as_str(), " ── METERED ── ".into()), + (p.dim.as_str(), "no published rates for these models".into()), + ], + w - 1, + )]; + rows.extend(no_local( + "Set usage.rates in config.json - US$ per million tokens, keyed by model.", + "", + w, + p, + )); + rows.push(String::new()); + return rows; + } + return Vec::new(); + } + // Where the prices came from belongs on screen: a list price is a dated + // fact that goes stale in silence, and a configured one is the reader's + // own assertion. Neither should be mistaken for the other. + let where_ = if origins == ["config"] { + "your configured rates".to_string() + } else if origins == ["list"] { + format!("list prices · {}", LIST_RATES_AS_OF) + } else { + format!("list prices · {}, some configured", LIST_RATES_AS_OF) + }; + // A month's list cost against what the month actually cost you. Shown + // only when the plan price is configured, because it is the one figure + // in this section that no machine here knows. + let month = built.iter().find(|x| x.0 == "30 days").map(|x| x.1); + let saves = match (cfg.plan_cost.get(agent), month) { + (Some(paid), Some(month)) => Some(month - paid), + _ => None, + }; + let mut rows = metered_block( + &where_, + &built, + w, + &[("the plan saves".to_string(), saves, p.ok.clone())], + note, + scope, + caveat, + p, + ); + if !missing.is_empty() && !rows.is_empty() { + missing.sort(); + let at = rows.len() - 1; + rows.insert( + at, + tc::seg( + &[ + ( + p.warn.as_str(), + format!( + " {} model{} unpriced: ", + missing.len(), + if missing.len() == 1 { "" } else { "s" } + ), + ), + ( + p.dim.as_str(), + missing.iter().take(3).cloned().collect::>().join(", "), + ), + ], + w - 1, + ), + ); + } + rows +} + +/// A subscription block: what the plan is, then the facts about it. +/// +/// Shared by four tabs so the same question is answered in the same shape +/// wherever you are on the wall - a percentage means little without the +/// subscription it is a percentage of. +fn plan_rows( + headline: &str, + pairs: &[(String, String)], + w: usize, + note: &str, + wrapped: Option<(&str, &[String])>, + caveat: &str, + p: &Palette, +) -> Vec { + let mut rows = vec![tc::seg( + &[ + (p.lbl.as_str(), " ── SUBSCRIPTION ── ".into()), + ( + p.txt.as_str(), + if headline.is_empty() { "unknown".into() } else { headline.to_string() }, + ), + ( + p.dim.as_str(), + if note.is_empty() { String::new() } else { format!(" {}", note) }, + ), + ], + w - 1, + )]; + if !caveat.is_empty() { + for line in wrap_text(caveat, w.saturating_sub(4).max(20)) { + rows.push(tc::seg(&[(p.dim.as_str(), format!(" {}", line))], w - 1)); + } + } + let label_w = pairs + .iter() + .map(|(k, _)| k.chars().count()) + .chain(wrapped.iter().map(|(k, _)| k.chars().count())) + .max() + .unwrap_or(0); + for (key, value) in pairs { + for (lab, part) in wrap_pair(key, value, label_w, w) { + rows.push(tc::seg( + &[ + (p.dim.as_str(), format!(" {} ", tc::pad(&lab, label_w))), + (p.txt.as_str(), part), + ], + w - 1, + )); + } + } + if let Some((label, names)) = wrapped { + if !names.is_empty() { + // Wrapped rather than clipped: a truncated list reads as a + // shorter one, and only the first line takes the label. + let budget = w.saturating_sub(label_w + 6).max(10); + let mut lines: Vec> = Vec::new(); + let mut line: Vec = Vec::new(); + for name in names { + let mut trial = line.clone(); + trial.push(name.clone()); + if !line.is_empty() && trial.join(" · ").chars().count() > budget { + lines.push(std::mem::take(&mut line)); + } + line.push(name.clone()); + } + if !line.is_empty() { + lines.push(line); + } + for (i, part) in lines.iter().enumerate() { + rows.push(tc::seg( + &[ + ( + p.dim.as_str(), + format!(" {} ", tc::pad(if i == 0 { label } else { "" }, label_w)), + ), + (p.ok.as_str(), part.join(" · ")), + ], + w - 1, + )); + } + } + } + rows +} + +/// Append a section with exactly one blank line before it. +/// +/// The separator is owned here rather than by callers who each end +/// differently - some finish on a blank line and would otherwise leave two, +/// and plain concatenation leaves none at all. +fn add_section(mut rows: Vec, block: Vec) -> Vec { + if block.is_empty() { + return rows; + } + while rows.last().is_some_and(|x| x.is_empty()) { + rows.pop(); + } + rows.push(String::new()); + rows.extend(block); + rows +} + +/// Tokens per day, drawn the way Claude Code's own /stats draws it. +/// +/// Weekday rows with only Mon, Wed and Fri labelled; one cell per day; +/// months named across the top; solid blocks in four steps of a single hue, +/// and a dim dot for a day the file has no entry for. +struct Calendar { + rows: Vec>, + best: Option, + active: usize, + span: usize, + longest: usize, + current: usize, +} + +fn day_calendar( + totals: &HashMap, + w: usize, + steps: [(u8, u8, u8); 4], + weeks: Option, + p: &Palette, +) -> Option { + if totals.is_empty() { + return None; + } + let peak = totals.values().cloned().fold(0.0f64, f64::max).max(1.0); + let best = totals + .iter() + .max_by(|a, b| a.1.total_cmp(b.1)) + .map(|(d, _)| *d); + let last = *totals.keys().max()?; + let first = *totals.keys().min()?; + // A caller with a bounded window says so, rather than having its month + // of data stretched across a year of empty dots. + let fit = weeks.unwrap_or(w.saturating_sub(7)).clamp(4, w.saturating_sub(7).max(4)); + let end_week = last - Days::days(last.weekday().num_days_from_monday() as i64); + let starts: Vec = (0..fit) + .rev() + .map(|i| end_week - Days::days(7 * i as i64)) + .collect(); + + // Month names sit over the week their month starts in, three characters + // wide like /stats - a single initial is not a label, it is a hint. A + // month label needs three clear cells; without checking where the last + // one ended, a short month writes over its neighbour. + let mut strip = vec![' '; starts.len()]; + let (mut seen, mut wrote_to): (Option, i64) = (None, -1); + for (x, wk) in starts.iter().enumerate() { + if Some(wk.month()) != seen && x as i64 > wrote_to && x + 3 <= strip.len() { + seen = Some(wk.month()); + for (k, ch) in MONTHS[wk.month0() as usize].chars().enumerate() { + strip[x + k] = ch; + } + wrote_to = x as i64 + 3; + } + } + let mut rows: Vec> = vec![vec![( + p.dim.clone(), + format!(" {}", strip.iter().collect::()), + )]]; + for i in 0..7 { + let label = match i { + 0 => "Mon", + 2 => "Wed", + 4 => "Fri", + _ => "", + }; + let mut line = vec![(p.dim.clone(), format!(" {:<4}", label))]; + for wk in &starts { + let day = *wk + Days::days(i); + match totals.get(&day) { + None => line.push((p.empty_cell.clone(), "·".into())), + Some(n) => line.push((shade((n / peak).sqrt(), steps), "█".into())), + } + } + rows.push(line); + } + + // Active out of days in the range, not out of days the file happens to + // list - otherwise every day is active by construction. + let span = (last - first).num_days() as usize + 1; + let active = totals.values().filter(|v| **v > 0.0).count(); + let (mut run, mut longest) = (0usize, 0usize); + for i in 0..span { + let day = first + Days::days(i as i64); + run = if totals.get(&day).is_some_and(|v| *v > 0.0) { run + 1 } else { 0 }; + longest = longest.max(run); + } + let mut current = 0usize; + for i in 0..span { + let day = last - Days::days(i as i64); + if !totals.get(&day).is_some_and(|v| *v > 0.0) { + break; + } + current += 1; + } + Some(Calendar { + rows, + best, + active, + span, + longest, + current, + }) +} + +/// Settings, read once, so no widget-wide mutable globals are needed. +#[derive(Default)] +struct Config { + agents: Vec, + exclude_agents: Vec, + rates: HashMap, + plan_cost: HashMap, + refresh: f64, +} + +fn read_config() -> Config { + let raw = tc::load_config("usage"); + let table = |key: &str| -> HashMap { + raw[key] + .as_object() + .into_iter() + .flatten() + .map(|(model, entry)| { + let rate: Rate = entry + .as_object() + .into_iter() + .flatten() + .filter_map(|(k, v)| v.as_f64().map(|v| (k.clone(), v))) + .collect(); + (model.clone(), rate) + }) + .collect() + }; + Config { + agents: tc::cfg_strings(&raw, "agents", &[]), + exclude_agents: tc::cfg_strings(&raw, "exclude_agents", &[]), + rates: table("rates"), + plan_cost: raw["plan_cost"] + .as_object() + .into_iter() + .flatten() + .filter_map(|(k, v)| v.as_f64().map(|v| (k.clone(), v))) + .collect(), + refresh: tc::cfg_f64(&raw, "refresh", 30.0), + } +} + +/// What we know how to read, and how to tell it is here. +/// +/// An agent counts as present if its CLI is on PATH *or* it has left state +/// behind: an uninstalled agent whose history is still on disk is worth +/// showing, and a CLI installed under a different name would otherwise +/// vanish. +fn agent_spec(name: &str) -> (&'static str, Vec<&'static str>, Vec) { + match name { + "claude" => ( + "Claude Code", + vec!["claude"], + vec![under_home(".claude/stats-cache.json")], + ), + "codex" => ("OpenAI Codex", vec!["codex"], vec![under_home(".codex/sessions")]), + "cursor" => ( + "Cursor", + vec!["cursor-agent", "cursor"], + vec![under_home(".cursor/ai-tracking/ai-code-tracking.db")], + ), + "grok" => ("Grok", vec!["grok"], vec![under_home(".grok")]), + "copilot" => ( + "GitHub Copilot", + vec!["copilot"], + vec![under_home(".copilot/session-store.db"), under_home(".copilot/config.json")], + ), + // No binary on PATH to look for: the CLI is launched by the IDE and + // its server is fetched per run, so the state directory is the only + // proof it is here - which is why detection takes paths as well. + "antigravity" => ( + "Antigravity", + vec!["antigravity"], + vec![under_home(".gemini/antigravity-cli")], + ), + other => (Box::leak(other.to_string().into_boxed_str()), vec![], vec![]), + } +} + +#[derive(Clone, Default)] +struct Presence { + present: bool, +} + +fn detect_agents() -> HashMap { + ORDER + .iter() + .map(|name| { + let (_, bins, paths) = agent_spec(name); + let has_bin = bins.iter().any(|b| tc::missing(&[b]).is_empty()); + let has_data = paths.iter().any(|p| std::path::Path::new(p).exists()); + ( + name.to_string(), + Presence { + present: has_bin || has_data, + }, + ) + }) + .collect() +} + +/// The tabs to draw. +/// +/// Empty `agents` discovers every agent this machine actually has. Naming +/// them instead fixes both the set and the order, whether or not they are +/// installed - if you listed it, you want the tab. Falls back to everything +/// known if the result would be empty, because a widget with no tabs +/// teaches nothing and the likeliest cause is a typo. +fn visible_agents(found: &HashMap, cfg: &Config) -> Vec { + let known: Vec<&str> = ORDER.to_vec(); + let named: Vec = cfg + .agents + .iter() + .filter(|n| known.contains(&n.as_str())) + .cloned() + .collect(); + let chosen: Vec = if named.is_empty() { + ORDER + .iter() + .filter(|n| found.get(**n).is_some_and(|x| x.present)) + .map(|n| n.to_string()) + .collect() + } else { + named + }; + let shown: Vec = chosen + .into_iter() + .filter(|n| !cfg.exclude_agents.contains(n)) + .collect(); + // The summary leads and is never discovered or excluded: it is not an + // agent, it is the view across whichever agents there turn out to be. + let mut out = vec![SUMMARY_TAB.to_string()]; + if shown.is_empty() { + out.extend(ORDER.iter().map(|n| n.to_string())); + } else { + out.extend(shown); + } + out +} + +/// Names in the config that match no agent we know how to read. +fn config_complaints(cfg: &Config) -> String { + let mut bad: Vec = cfg + .agents + .iter() + .chain(cfg.exclude_agents.iter()) + .filter(|n| !ORDER.contains(&n.as_str())) + .cloned() + .collect(); + if bad.is_empty() { + return String::new(); + } + bad.sort(); + bad.dedup(); + format!( + "unknown agent in config: {} (known: {})", + bad.join(", "), + ORDER.join(", ") + ) +} + +fn tab_bar( + active: &str, + installed: &HashMap, + tabs: &[String], + w: usize, + p: &Palette, +) -> String { + // Brackets as well as the tint: which tab is open must not depend on a + // background colour surviving. A dot marks an agent that is installed. + let mut parts: Vec<(String, String)> = vec![(tc::RST.to_string(), " ".into())]; + for name in tabs { + let here = name == active; + let have = installed.get(name).is_some_and(|x| x.present); + parts.push(( + if here { + format!("{}{}", tc::bg(38, 56, 76), p.accent) + } else { + p.dim.clone() + }, + if here { + format!("[{}]", name.to_uppercase()) + } else { + format!(" {} ", name.to_uppercase()) + }, + )); + if name == SUMMARY_TAB { + parts.push((p.grid.clone(), " ".into())); + continue; + } + parts.push(( + if have { p.ok.clone() } else { p.grid.clone() }, + if have { "·".into() } else { " ".to_string() }, + )); + } + let refs: Vec<(&str, String)> = parts.iter().map(|(c, t)| (c.as_str(), t.clone())).collect(); + tc::seg(&refs, w - 1) +} + +/// What to show before the first poll lands. +/// +/// Every tab's empty state is a statement of fact - no stats cache, no +/// rollouts, no agent publishing a quota - and each of them is false while +/// the first read is still running. The first read is also the slow one, +/// which is more than long enough for a wrong answer to be read and +/// believed. +fn loading_rows(w: usize, tick: usize, p: &Palette) -> Vec { + let mut rows = vec![ + tc::seg( + &[ + (p.accent.as_str(), format!(" {}", SPINNER[tick % SPINNER.len()])), + (p.txt.as_str(), " reading local state and quotas".into()), + ], + w - 1, + ), + String::new(), + ]; + for part in wrap_text( + "The first pass is the slow one: Claude's transcripts run to hundreds \ + of megabytes and Cursor's usage events are paged a thousand at a \ + time. Both are cached afterwards.", + w.saturating_sub(4).max(20), + ) { + rows.push(tc::seg(&[(p.dim.as_str(), format!(" {}", part))], w - 1)); + } + rows +} + +fn main() { + tc::maybe_help(include_str!("usage_help.txt")); + let cfg = read_config(); + let mut refresh = cfg.refresh; + let args: Vec = std::env::args().skip(1).collect(); + if args.len() >= 2 && (args[0] == "-n" || args[0] == "--refresh") { + refresh = args[1].parse().unwrap_or(refresh); + } + + let p = palette(); + let state = Arc::new(Mutex::new(vendors::State::default())); + let wake = Arc::new((Mutex::new(false), Condvar::new())); + let poller = Arc::clone(&state); + let poller_wake = Arc::clone(&wake); + std::thread::spawn(move || { + let mut caches = vendors::Caches::default(); + loop { + // A poller that dies takes its explanation with it, and an empty + // board looks exactly like a machine with no agents on it. + let read = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| { + vendors::read_all(&mut caches) + })); + match read { + Ok(found) => { + if let Ok(mut g) = poller.lock() { + *g = found; + g.fetched = now(); + } + } + Err(_) => { + if let Ok(mut g) = poller.lock() { + g.err = "poller stopped - see the pane it was started from".into(); + } + return; + } + } + let (lock, cond) = &*poller_wake; + let mut asked = match lock.lock() { + Ok(g) => g, + Err(_) => return, + }; + if !*asked { + asked = match cond.wait_timeout(asked, Duration::from_secs_f64(refresh)) { + Ok((g, _)) => g, + Err(_) => return, + }; + } + *asked = false; + } + }); + + tc::setup(); + let mut keyboard = tc::Keyboard::new(); + let (mut active, mut tick) = (0usize, 0usize); + // One offset per tab. Switching away and back keeps your place, which + // matters when a tab is forty rows and you were reading the bottom of it. + let mut offsets: HashMap = HashMap::new(); + + loop { + tick += 1; + // Scrolling is applied after the frame is built, not here: a page is + // however many body rows this pane turned out to have, and that is + // not known until the tab has been rendered and the footer packed. + let mut moves: Vec = Vec::new(); + let (mut to_top, mut to_bottom) = (false, false); + let mut pages: Vec = Vec::new(); + for key in keyboard.poll() { + match key.as_str() { + "q" | "Q" => { + keyboard.restore(); + tc::restore_screen(); + return; + } + "right" | "tab" | "l" => active += 1, + "left" | "h" => active = active.saturating_sub(1).max(active.wrapping_sub(1)), + "up" | "k" => moves.push(-1), + "down" | "j" => moves.push(1), + "pgup" => pages.push(-1), + "pgdn" => pages.push(1), + "home" => to_top = true, + "end" => to_bottom = true, + "r" | "R" => { + let (lock, cond) = &*wake; + if let Ok(mut asked) = lock.lock() { + *asked = true; + cond.notify_all(); + } + } + _ => {} + } + } + + let (w, h) = tc::size(); + let snapshot = match state.lock() { + Ok(g) => g.clone(), + Err(_) => return, + }; + let mut rows = vec![tc::title("agent usage", w, &p.agent)]; + let tabs = visible_agents(&snapshot.installed, &cfg); + active %= tabs.len(); + let name = tabs[active].clone(); + let hidden = ORDER + .iter() + .filter(|n| { + snapshot.installed.get(**n).is_some_and(|x| x.present) + && !tabs.contains(&n.to_string()) + }) + .count(); + + let status_at = rows.len(); + rows.push(String::new()); // filled in once the scroll is resolved + let gripe = if snapshot.err.is_empty() { + config_complaints(&cfg) + } else { + snapshot.err.clone() + }; + if !gripe.is_empty() { + rows.push(tc::seg(&[(p.bad.as_str(), format!(" ! {}", gripe))], w - 1)); + } + rows.push(tab_bar(&name, &snapshot.installed, &tabs, w, &p)); + rows.push(String::new()); + + let body = if snapshot.fetched <= 0.0 { + loading_rows(w, tick, &p) + } else { + vendors::tab_body(&name, &snapshot, w, h, &cfg, &p) + }; + + let mut hints: Vec> = vec![ + vec![(p.accent.as_str(), "←→".into()), (p.dim.as_str(), " agent".into())], + vec![(p.accent.as_str(), "↑↓".into()), (p.dim.as_str(), " scroll".into())], + vec![(p.dim.as_str(), "[r]efresh".into())], + vec![(p.dim.as_str(), "[q]uit".into())], + ]; + // The footer is packed once, with the scroll hint always counted, so + // the body's height does not change when scrolling becomes possible. + let reserved = tc::pack_hints(&hints, w - 2, " ").len(); + let avail = h.saturating_sub(rows.len() + reserved).max(1); + let top = body.len().saturating_sub(avail); + let mut off = offsets.get(&name).copied().unwrap_or(0).min(top); + if to_top { + off = 0; + } + if to_bottom { + off = top; + } + for page in &pages { + let step = avail.saturating_sub(1).max(1) as i64; + off = (off as i64 + page * step).clamp(0, top as i64) as usize; + } + for move_ in &moves { + off = (off as i64 + move_).clamp(0, top as i64) as usize; + } + off = off.min(top); + offsets.insert(name.clone(), off); + + let view: Vec = body.iter().skip(off).take(avail).cloned().collect(); + let where_ = if top > 0 { + // Never let a partial view read as the whole tab, and say which + // way there is more: an arrow simply absent at the top of a long + // tab looks the same as a tab that ends there. + format!( + " {}-{} of {} {}{}", + off + 1, + off + view.len(), + body.len(), + if off > 0 { "▲" } else { " " }, + if off < top { "▼" } else { " " } + ) + } else { + hints.retain(|x| x[0].1 != "↑↓"); + String::new() + }; + // The scroll position goes last on this line but matters most, so + // the legend stands down to make room rather than being clipped. + let base = format!(" local state · live quota · read {} ago", ago(snapshot.fetched)); + let hidden_txt = if hidden > 0 { + format!(" {} hidden by config", hidden) + } else { + String::new() + }; + let mut legend = " · = detected".to_string(); + if base.len() + hidden_txt.len() + legend.len() + where_.len() > w - 1 { + legend.clear(); + } + rows[status_at] = tc::seg( + &[ + (p.dim.as_str(), base), + (p.dim.as_str(), legend), + (p.dim.as_str(), hidden_txt), + (p.accent.as_str(), where_), + ], + w - 1, + ); + + let mut footer: Vec = tc::pack_hints(&hints, w - 2, " ") + .into_iter() + .map(|l| format!(" {}", l)) + .collect(); + // Padded back to the height already reserved, so dropping the scroll + // hint does not lift the footer off the bottom of the pane. + while footer.len() < reserved { + footer.insert(0, String::new()); + } + rows.extend(view); + while rows.len() < h.saturating_sub(footer.len()) { + rows.push(String::new()); + } + rows.extend(footer); + rows.truncate(h); + tc::draw(&rows, w, h); + std::thread::sleep(Duration::from_millis(300)); + } +} + +// Kept in a directory of its own rather than beside this file: anything +// dropped straight into src/bin/ risks being taken for another binary. +#[path = "usage/vendors.rs"] +mod vendors; + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn a_model_takes_the_longest_matching_rate() { + let none: HashMap = HashMap::new(); + // claude-opus-4 must not shadow claude-opus-4-8. + let (rate, origin) = rate_for("claude-opus-4-8", &none); + assert_eq!(origin, "list"); + assert_eq!(rate.unwrap().get("input"), Some(&5.0)); + // A model name with a suffix still matches its family. + let (rate, _) = rate_for("claude-sonnet-5-20260101", &none); + assert_eq!(rate.unwrap().get("output"), Some(&10.0)); + // Config wins outright over the list. + let mut mine: HashMap = HashMap::new(); + mine.insert( + "claude-opus-5".into(), + [("input".to_string(), 99.0)].into_iter().collect(), + ); + let (rate, origin) = rate_for("claude-opus-5", &mine); + assert_eq!(origin, "config"); + assert_eq!(rate.unwrap().get("input"), Some(&99.0)); + } + + #[test] + fn a_model_with_no_published_price_reports_as_unpriced() { + // Spark is explicitly not on the API, so prefix matching must not + // hand it its family's rate - that would be a number nobody + // published, which is the one thing this widget must never show. + let none: HashMap = HashMap::new(); + assert!(rate_for("gpt-5.3-codex-spark", &none).0.is_none()); + // Unless the reader asserts one themselves. + let mut mine: HashMap = HashMap::new(); + mine.insert( + "gpt-5.3-codex-spark".into(), + [("input".to_string(), 1.0)].into_iter().collect(), + ); + assert!(rate_for("gpt-5.3-codex-spark", &mine).0.is_some()); + } + + #[test] + fn a_cost_is_the_sum_of_its_priced_kinds() { + let rate: Rate = [ + ("input".to_string(), 5.0), + ("output".to_string(), 25.0), + ("cache_read".to_string(), 0.5), + ] + .into_iter() + .collect(); + let mut tokens = empty_tokens(); + tokens.insert("input".into(), 1_000_000.0); + tokens.insert("output".into(), 2_000_000.0); + tokens.insert("cache_read".into(), 10_000_000.0); + // 5 + 50 + 5 + assert!((cost_of(&tokens, &rate) - 60.0).abs() < 1e-9); + // A kind the card does not price contributes nothing rather than + // falling back to another kind's rate. + tokens.insert("cache_write".into(), 9_999_999.0); + assert!((cost_of(&tokens, &rate) - 60.0).abs() < 1e-9); + } + + #[test] + fn a_small_percentage_is_not_rounded_into_nothing() { + // A real 0.03% and an empty section have to be tellable apart. + assert_eq!(pct_text(0.0), " 0%"); + assert_eq!(pct_text(0.03), " 0.03%"); + assert_eq!(pct_text(0.4), " 0.40%"); + assert_eq!(pct_text(4.2), " 4.2%"); + assert_eq!(pct_text(71.0), " 71%"); + // Always six cells, whatever the value. + for pct in [0.0, 0.03, 4.2, 71.0, 100.0] { + assert_eq!(pct_text(pct).chars().count(), 6, "{}", pct); + } + } + + #[test] + fn a_pace_figure_waits_until_the_window_means_something() { + let window = Some(7.0 * 86400.0); + // Ten minutes into a week, every number looks like a catastrophe. + let just_started = Some(now() + 7.0 * 86400.0 - 600.0); + assert_eq!(lead(1.0, window, just_started), None); + // Half way through, spending a third is a real cushion. + let half = Some(now() + 3.5 * 86400.0); + let got = lead(33.0, window, half).expect("a pace"); + assert!((got - 17.0).abs() < 1.0, "got {}", got); + // And spending two thirds is not. + assert!(lead(67.0, window, half).expect("a pace") < 0.0); + // Nothing to say without both halves. + assert_eq!(lead(50.0, None, half), None); + assert_eq!(lead(50.0, window, None), None); + } + + #[test] + fn a_span_says_what_it_is_rather_than_zero() { + assert_eq!(span_ms(90_000.0), "1m"); + assert_eq!(span_ms(3_600_000.0), "1h 0m"); + assert_eq!(span_ms(90_000_000.0), "1d 1h 0m"); + // A couple of seconds of generation is not "0m". + assert_eq!(span_ms(2_400.0), "2.4s"); + } + + #[test] + fn big_numbers_stay_readable() { + assert_eq!(big_num(999.0), "999"); + assert_eq!(big_num(1_500.0), "1.5k"); + assert_eq!(big_num(2_400_000.0), "2.4M"); + assert_eq!(big_num(7_100_000_000.0), "7.1B"); + } + + #[test] + fn a_timestamp_is_read_whichever_shape_it_arrives_in() { + // These APIs mix Z with +00:00 in the same response, and Go writes + // nanoseconds where the parser takes six digits. + let want = iso_epoch("2026-08-23T04:15:00+00:00").expect("offset form"); + assert_eq!(iso_epoch("2026-08-23T04:15:00Z"), Some(want)); + assert_eq!(iso_epoch("2026-08-23T04:15:00.123456789Z"), Some(want)); + assert!(iso_epoch("").is_none()); + assert!(iso_epoch("not a date").is_none()); + } + + #[test] + fn a_bar_marks_where_an_even_burn_would_be() { + let p = palette(); + let plain = |parts: &[(String, String)]| -> String { + parts.iter().map(|(_, t)| t.clone()).collect() + }; + // Half spent, half the window gone: the mark sits at the boundary. + let bar = paced_bar(0.5, Some(0.5), 10, Some((240, 132, 84)), &p); + let drawn = plain(&bar); + assert_eq!(drawn.chars().count(), 10); + assert!(drawn.contains('┃')); + // No window information means no mark, not a mark at zero. + let bare = plain(&paced_bar(0.5, None, 10, None, &p)); + assert!(!bare.contains('┃')); + assert_eq!(bare.chars().count(), 10); + } + + #[test] + fn a_calendar_counts_streaks_over_the_range_not_the_entries() { + let p = palette(); + let day = |s: &str| NaiveDate::parse_from_str(s, "%Y-%m-%d").unwrap(); + let totals: HashMap = [ + (day("2026-08-01"), 10.0), + (day("2026-08-02"), 5.0), + // 3 August is absent, which is a gap rather than a zero. + (day("2026-08-04"), 7.0), + (day("2026-08-05"), 3.0), + (day("2026-08-06"), 1.0), + ] + .into_iter() + .collect(); + let cal = day_calendar(&totals, 60, HEAT_STEPS, None, &p).expect("a calendar"); + assert_eq!(cal.span, 6); + assert_eq!(cal.active, 5); + assert_eq!(cal.longest, 3); + assert_eq!(cal.current, 3); + assert_eq!(cal.best, Some(day("2026-08-01"))); + // Seven weekday rows plus the month strip. + assert_eq!(cal.rows.len(), 8); + } + + #[test] + fn a_sentence_wraps_rather_than_losing_its_end() { + assert_eq!(wrap_text("one two three", 7), vec!["one two", "three"]); + assert_eq!(wrap_text("", 10), vec![""]); + // A labelled value's continuation lines sit under the value. + let got = wrap_pair("plan", "a rather long enterprise sku here", 6, 30); + assert_eq!(got[0].0, "plan"); + assert_eq!(got[1].0, ""); + assert!(got.len() > 1); + } +} diff --git a/rust/widgets/src/bin/usage/vendors.rs b/rust/widgets/src/bin/usage/vendors.rs new file mode 100644 index 0000000..3a66627 --- /dev/null +++ b/rust/widgets/src/bin/usage/vendors.rs @@ -0,0 +1,1225 @@ +// terminal-toys - small dependency-free terminal widgets +// Copyright (C) 2026 William Li +// +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU Affero General Public License as published +// by the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU Affero General Public License for more details. +// +// You should have received a copy of the GNU Affero General Public License +// along with this program. If not, see . + +//! One reader and one tab per agent. +//! +//! They do not agree on what usage even means, so each keeps its own shape +//! rather than being flattened into a schema none of them publish. An agent +//! with no reader here says so on its tab; a plausible-looking zero would +//! be worse than an empty one. + +use std::collections::HashMap; + +use chrono::{Datelike, Duration as Days, Local, NaiveDate, TimeZone}; +use toys_core as tc; + +use super::*; + +/// What Claude Code has recorded, plus what is left of the limits. +#[derive(Clone, Default)] +struct Claude { + ok: bool, + why: String, + stats: serde_json::Value, + /// The live or cached rate-limit reading, which is account-wide rather + /// than about this machine. + quota: Option, + quota_live: bool, + quota_at: f64, + quota_plan: String, + profile: Option, + /// Output tokens per second, sorted, and how many transcripts it came + /// from. + rates: Vec, + sampled: usize, + /// day -> model -> tokens by priced kind. + daily: HashMap>, +} + +#[derive(Clone, Default)] +pub struct State { + claude: Claude, + pub installed: HashMap, + pub fetched: f64, + pub err: String, +} + +/// Readings held between passes, so a finished transcript is parsed once. +#[derive(Default)] +pub struct Caches { + /// path -> ((mtime, size), records keyed by uuid) + transcripts: HashMap)>, + /// key -> (when, value, ttl) + live: HashMap, f64)>, +} + +const LIVE_TTL: f64 = 120.0; +/// A plan does not change between refreshes; the windows do. +const PLAN_TTL: f64 = 3600.0; +/// Newest transcripts to sample for a rate. +const RATE_FILES: usize = 3; +/// Seconds; below this the timestamps are not a turn. +const MIN_GAP: f64 = 1.0; + +/// Hold a reading for a while, but never hold a failure that long. +/// +/// The pane redraws every thirty seconds; these windows move over hours. A +/// failure is cached too, so a dead endpoint is retried occasionally rather +/// than on every frame - but only ever for the short interval, never the +/// long one. One transient 429 should not blank a section for an hour. +fn cached(caches: &mut Caches, key: &str, ttl: f64, fetch: F) -> Option +where + F: FnOnce() -> Option, +{ + let at = now(); + if let Some((when, value, held)) = caches.live.get(key) { + if at - when < *held { + return value.clone(); + } + } + let value = fetch(); + let held = if value.is_some() { ttl } else { ttl.min(LIVE_TTL) }; + caches.live.insert(key.to_string(), (at, value.clone(), held)); + value +} + +fn read_json(path: &str) -> Option { + serde_json::from_str(&std::fs::read_to_string(path).ok()?).ok() +} + +/// The OAuth token Claude Code already holds. +/// +/// It goes only to Anthropic, is never printed, and an expired one is not +/// used at all: the refresh token sits beside it, but spending it would +/// race Claude Code's own credential handling for a number that has a local +/// cache anyway. +fn claude_token() -> Option<(String, String)> { + let creds = read_json(&under_home(".claude/.credentials.json"))?; + let o = &creds["claudeAiOauth"]; + let tok = text(o, "accessToken"); + if tok.is_empty() || num(o, "expiresAt") / 1000.0 <= now() { + return None; + } + Some((tok, text(o, "subscriptionType"))) +} + +fn claude_get(url: &str, tok: &str) -> Option { + let body = tc::get( + url, + &[ + ("Authorization", &format!("Bearer {}", tok)), + ("User-Agent", "terminal-toys"), + ], + 20, + ) + .ok()?; + serde_json::from_str(&body).ok() +} + +/// What Claude Code last fetched, for when the live call cannot run. +/// +/// It is a cache with a timestamp, so it is shown with its age - and a +/// window whose reset has already gone by is said to have passed rather +/// than counted down to, because a stale five-hour window describes a +/// period that has ended. +fn claude_stale() -> Option<(serde_json::Value, f64)> { + let config = read_json(&under_home(".claude.json"))?; + let c = &config["cachedUsageUtilization"]; + let u = c["utilization"].clone(); + if u.is_null() { + return None; + } + Some((u, num(c, "fetchedAtMs") / 1000.0)) +} + +/// Token counts from one transcript usage block, by priced kind. +/// +/// A block's top-level numbers can all be zero while its `iterations` carry +/// the real figures, so the iterations win where they exist. Cache writes +/// are split by duration because they are priced differently, and the flat +/// cache_creation_input_tokens is only used when that split is absent. +fn usage_kinds(u: &serde_json::Value) -> Tokens { + let mut out = empty_tokens(); + let empty = vec![u.clone()]; + let blocks: Vec = match u["iterations"].as_array() { + Some(list) if !list.is_empty() => list.clone(), + _ => empty, + }; + for x in &blocks { + *out.get_mut("input").unwrap() += num(x, "input_tokens"); + *out.get_mut("output").unwrap() += num(x, "output_tokens"); + *out.get_mut("cache_read").unwrap() += num(x, "cache_read_input_tokens"); + let split = &x["cache_creation"]; + if split.is_object() { + *out.get_mut("cache_write").unwrap() += num(split, "ephemeral_5m_input_tokens"); + *out.get_mut("cache_write_1h").unwrap() += num(split, "ephemeral_1h_input_tokens"); + } else { + *out.get_mut("cache_write").unwrap() += num(x, "cache_creation_input_tokens"); + } + } + out +} + +/// Every file under a directory whose name ends in `suffix`. +fn walk(dir: &str, suffix: &str, out: &mut Vec) { + let Ok(entries) = std::fs::read_dir(dir) else { + return; + }; + for entry in entries.flatten() { + let path = entry.path(); + let name = path.to_string_lossy().to_string(); + match entry.file_type() { + Ok(t) if t.is_dir() => walk(&name, suffix, out), + Ok(t) if t.is_file() && name.ends_with(suffix) => out.push(name), + _ => {} + } + } +} + +/// Per-record token counts from one transcript, keyed by record uuid. +/// +/// Keyed rather than summed because the same message appears in more than +/// one file: resuming or forking a session replays its history into the new +/// transcript, and subagent turns are written twice over. Left raw that +/// inflated one model by 29% against Claude Code's own totals. +/// +/// Cached on (mtime, size): a finished transcript never changes, so each is +/// parsed once. +fn scan_transcript( + caches: &mut Caches, + path: &str, +) -> HashMap { + let Ok(meta) = std::fs::metadata(path) else { + return HashMap::new(); + }; + use std::os::unix::fs::MetadataExt; + let key = (meta.mtime() as u64, meta.size()); + if let Some((had, records)) = caches.transcripts.get(path) { + if *had == key { + return records.clone(); + } + } + let mut records = HashMap::new(); + let Ok(body) = std::fs::read_to_string(path) else { + return records; + }; + for line in body.lines() { + if !line.contains("\"usage\"") { + continue; + } + let Ok(r) = serde_json::from_str::(line) else { + continue; + }; + let msg = &r["message"]; + let u = &msg["usage"]; + let (model, uid, stamp) = (text(msg, "model"), text(&r, "uuid"), text(&r, "timestamp")); + if u.is_null() || model.is_empty() || uid.is_empty() || stamp.is_empty() { + continue; + } + let Some(when) = iso_epoch(&stamp) else { + continue; + }; + let got = usage_kinds(u); + if total_tokens(&got) <= 0.0 { + continue; + } + let day = Local + .timestamp_opt(when as i64, 0) + .single() + .map(|d| d.format("%Y-%m-%d").to_string()) + .unwrap_or_default(); + records.insert(uid, (day, model, got)); + } + caches + .transcripts + .insert(path.to_string(), (key, records.clone())); + records +} + +/// Every transcript's per-day, per-model tokens, de-duplicated. +/// +/// stats-cache.json has dailyModelTokens, but only one total per model per +/// day - and input, output and the two cache kinds differ in price by up to +/// fifty times, so a total cannot be costed. The transcripts carry the +/// split, which is why the money comes from here and not from the cache. +fn claude_daily(caches: &mut Caches) -> HashMap> { + let mut files = Vec::new(); + // Recursive on purpose: subagent transcripts live a further two levels + // down, and that is where most of the smaller models actually run. + walk(&under_home(".claude/projects"), ".jsonl", &mut files); + let mut seen: HashMap = HashMap::new(); + for path in &files { + seen.extend(scan_transcript(caches, path)); + } + let mut merged: HashMap> = HashMap::new(); + for (day, model, tokens) in seen.into_values() { + let bucket = merged + .entry(day) + .or_default() + .entry(model) + .or_insert_with(empty_tokens); + for kind in RATE_KINDS { + *bucket.get_mut(*kind).unwrap() += tokens.get(*kind).copied().unwrap_or(0.0); + } + } + merged +} + +/// Per-model token totals over the last N days (1 = today only). +fn window_models( + daily: &HashMap>, + days: i64, +) -> Vec<(String, Tokens)> { + let first = (Local::now().date_naive() - Days::days(days - 1)) + .format("%Y-%m-%d") + .to_string(); + let mut out: HashMap = HashMap::new(); + for (day, models) in daily { + if *day < first { + continue; + } + for (model, tokens) in models { + let bucket = out.entry(model.clone()).or_insert_with(empty_tokens); + for kind in RATE_KINDS { + *bucket.get_mut(*kind).unwrap() += tokens.get(*kind).copied().unwrap_or(0.0); + } + } + } + let mut list: Vec<(String, Tokens)> = out.into_iter().collect(); + list.sort_by(|a, b| a.0.cmp(&b.0)); + list +} + +/// The last `size` bytes of a file, as lines. +fn tail_lines(path: &str, size: u64) -> Vec { + use std::io::{Read, Seek, SeekFrom}; + let Ok(mut f) = std::fs::File::open(path) else { + return Vec::new(); + }; + let end = f.seek(SeekFrom::End(0)).unwrap_or(0); + if f.seek(SeekFrom::Start(end.saturating_sub(size))).is_err() { + return Vec::new(); + } + let mut buf = Vec::new(); + if f.read_to_end(&mut buf).is_err() { + return Vec::new(); + } + String::from_utf8_lossy(&buf) + .split('\n') + .map(String::from) + .collect() +} + +/// Output tokens per second, from the newest transcripts. +/// +/// A turn is a `user` record followed by an `assistant` one, and the rate is +/// that assistant's output tokens over the gap between them. Measuring from +/// any previous record instead inflates it wildly - two assistant records +/// can be milliseconds apart while the second reports a whole turn's output. +/// +/// The median is what gets shown: it barely moves whichever way the outliers +/// are trimmed, which is the reason to trust it, while the maximum moves by +/// a factor of twenty on the same data, which is the reason not to show one. +fn claude_rates() -> (Vec, usize) { + let mut files = Vec::new(); + walk(&under_home(".claude/projects"), ".jsonl", &mut files); + let mut with_time: Vec<(u64, String)> = files + .into_iter() + .filter_map(|path| { + use std::os::unix::fs::MetadataExt; + let meta = std::fs::metadata(&path).ok()?; + Some((meta.mtime() as u64, path)) + }) + .collect(); + with_time.sort_by(|a, b| b.0.cmp(&a.0)); + let mut out: Vec = Vec::new(); + let mut sampled = 0usize; + for (_, path) in with_time.iter().take(RATE_FILES) { + sampled += 1; + let (mut prev, mut prev_type): (Option, String) = (None, String::new()); + for line in tail_lines(path, 4 * 1024 * 1024) { + if !line.contains("\"timestamp\"") { + continue; + } + let Ok(d) = serde_json::from_str::(&line) else { + continue; + }; + let (stamp, typ) = (text(&d, "timestamp"), text(&d, "type")); + let at = iso_epoch(&stamp); + if typ == "assistant" + && at.is_some() + && prev.is_some() + && prev_type == "user" + && !d["isAbortedMidStream"].as_bool().unwrap_or(false) + { + let tok = num(&d["message"]["usage"], "output_tokens"); + if tok > 0.0 { + let gap = at.unwrap() - prev.unwrap(); + if (MIN_GAP..300.0).contains(&gap) { + out.push(tok / gap); + } + } + } + if let Some(at) = at { + prev = Some(at); + prev_type = typ; + } + } + } + out.sort_by(f64::total_cmp); + (out, sampled) +} + +fn read_claude(caches: &mut Caches) -> Claude { + let mut claude = Claude::default(); + let live = cached(caches, "claude", LIVE_TTL, || { + let (tok, plan) = claude_token()?; + let u = claude_get("https://api.anthropic.com/api/oauth/usage", &tok)?; + Some(serde_json::json!({ "u": u, "at": now(), "plan": plan })) + }); + match live { + Some(got) => { + claude.quota = Some(got["u"].clone()); + claude.quota_live = true; + claude.quota_at = num(&got, "at"); + claude.quota_plan = text(&got, "plan"); + } + None => { + if let Some((u, at)) = claude_stale() { + claude.quota = Some(u); + claude.quota_live = false; + claude.quota_at = at; + } + } + } + claude.profile = cached(caches, "claude-plan", PLAN_TTL, || { + let (tok, plan) = claude_token()?; + let mut d = claude_get("https://api.anthropic.com/api/oauth/profile", &tok)?; + d["_plan"] = serde_json::Value::String(plan); + Some(d) + }); + if claude.profile.is_none() { + // The profile endpoint is richer, but the credentials file needs no + // network and is always there, so the section degrades to two true + // lines instead of vanishing. + if let Some(creds) = read_json(&under_home(".claude/.credentials.json")) { + let o = &creds["claudeAiOauth"]; + let plan = text(o, "subscriptionType"); + if !plan.is_empty() { + claude.profile = Some(serde_json::json!({ + "_plan": plan, + "_local": true, + "organization": { "rate_limit_tier": text(o, "rateLimitTier") }, + })); + } + } + } + match read_json(&under_home(".claude/stats-cache.json")) { + Some(stats) => { + claude.ok = true; + claude.stats = stats; + let (rates, sampled) = claude_rates(); + claude.rates = rates; + claude.sampled = sampled; + claude.daily = claude_daily(caches); + } + None => claude.why = "no stats cache".into(), + } + claude +} + +pub fn read_all(caches: &mut Caches) -> State { + State { + claude: read_claude(caches), + installed: detect_agents(), + fetched: 0.0, + err: String::new(), + } +} + +/// Where a Claude limit belongs in the list, shortest leash first. +/// +/// The server returns them in no order worth keeping. Read top to bottom +/// they should widen: the five-hour session is what stops you this +/// afternoon, the weekly total is what stops you this week, and a +/// model-scoped weekly limit stops only one model. +fn claude_lane_rank(limit: &serde_json::Value) -> usize { + if text(limit, "kind") == "session" { + return 0; + } + if text(&limit["scope"]["model"], "display_name").is_empty() { + 1 + } else { + 2 + } +} + +/// The scope note, shortened before it can push a reset off the line. +/// +/// "not this machine" is the point of the sentence, but it is also sixteen +/// characters, and seg() clips whatever runs past the pane. Losing the +/// clause leaves a shorter true line; losing the end of "resets in 15d" +/// leaves "resets in 1", which is a different and wrong number. +fn scope_phrase(w: usize, used: usize) -> &'static str { + let full = " · account-wide, not this machine "; + if used + full.len() <= w - 1 { + full + } else { + " · account-wide " + } +} + +/// The windows Claude Code's own /usage shows. +/// +/// Read from limits[], which is the server's own curated list: the rest of +/// the response carries a dozen null pools that /usage does not render +/// either. Each entry names itself, so a model-scoped weekly limit arrives +/// labelled without this having to know the name. +fn claude_quota(c: &Claude, w: usize, p: &Palette) -> Vec { + let Some(u) = c.quota.as_ref() else { + return Vec::new(); + }; + let mut lanes: Vec<&serde_json::Value> = u["limits"] + .as_array() + .into_iter() + .flatten() + .filter(|l| !l["percent"].is_null()) + .collect(); + if lanes.is_empty() { + return Vec::new(); + } + lanes.sort_by_key(|l| claude_lane_rank(l)); + let src = if c.quota_live { + "live".to_string() + } else { + format!("cached {} ago", ago(c.quota_at)) + }; + let hue = agent_hue("claude"); + let mut rows = vec![tc::seg( + &[ + (p.lbl.as_str(), " ── QUOTA ── ".into()), + ( + if c.quota_live { p.ok.as_str() } else { p.warn.as_str() }, + src.clone(), + ), + ( + p.dim.as_str(), + scope_phrase(w, 13 + src.len() + c.quota_plan.len()).to_string(), + ), + (p.dim.as_str(), c.quota_plan.clone()), + ], + w - 1, + )]; + + let label_of = |l: &serde_json::Value| -> String { + let scope = text(&l["scope"]["model"], "display_name"); + let group = text(l, "group"); + let name = if !scope.is_empty() { + scope + } else if text(l, "kind") == "weekly_all" { + "overall".to_string() + } else if !group.is_empty() { + group.clone() + } else { + match text(l, "kind") { + s if s.is_empty() => "?".into(), + s => s, + } + }; + let window = match group.as_str() { + "session" => "5h", + "weekly" => "7d", + _ => "", + }; + format!("{} {}", name, window).trim().to_string() + }; + let texts: Vec = lanes.iter().map(|l| label_of(l)).collect(); + let label_w = texts.iter().map(|t| t.chars().count()).max().unwrap_or(9).max(9); + for (l, label) in lanes.iter().zip(&texts) { + let pct = num(l, "percent"); + let used = (pct / 100.0).clamp(0.0, 1.0); + let reset = iso_epoch(&text(l, "resets_at")); + let when = match reset { + None => String::new(), + Some(ts) => { + let left = ts - now(); + if left > 0.0 { + format!("resets in {}", left_span(left)) + } else if c.quota_live { + "resetting".into() + } else { + "already reset".into() + } + } + }; + let sev = text(l, "severity").to_lowercase(); + let window = CLAUDE_WINDOW_SECS + .iter() + .find(|(g, _)| *g == text(l, "group")) + .map(|(_, s)| *s); + let cushion = lead(pct, window, reset); + let (pace_colour, pace_txt) = pace_cell(cushion, p); + // is_active marks the limit currently doing the binding - the one + // that will stop you first - so it is the one worth reading brightly. + let mut line: Vec<(String, String)> = vec![( + if l["is_active"].as_bool().unwrap_or(false) { + p.txt.clone() + } else { + p.dim.clone() + }, + format!(" {} ", tc::pad(label, label_w)), + )]; + line.extend(paced_bar( + used, + elapsed_of(window, reset), + w.saturating_sub(35 + label_w).max(8), + hue, + p, + )); + line.push((pct_colour(pct, hue, p), pct_text(pct))); + line.push((pace_colour, pace_txt)); + line.push(( + if sev.is_empty() || sev == "normal" { p.dim.clone() } else { p.bad.clone() }, + if sev.is_empty() || sev == "normal" { + format!(" {}", when) + } else { + format!(" {} · {}", sev, when) + }, + )); + let refs: Vec<(&str, String)> = line.iter().map(|(c, t)| (c.as_str(), t.clone())).collect(); + rows.push(tc::seg(&refs, w - 1)); + } + let extra = &u["extra_usage"]; + let spend = &u["spend"]; + if extra["is_enabled"].as_bool().unwrap_or(false) && !spend["limit"].is_null() { + let money = |m: &serde_json::Value| -> String { + format!( + "{:.2}", + num(m, "amount_minor") / 10f64.powf(m["exponent"].as_f64().unwrap_or(2.0)) + ) + }; + rows.push(tc::seg( + &[ + (p.dim.as_str(), " extra usage ".into()), + (p.txt.as_str(), money(&spend["used"])), + (p.dim.as_str(), " of ".into()), + (p.txt.as_str(), money(&spend["limit"])), + (p.dim.as_str(), format!(" {}", text(&spend["limit"], "currency"))), + (p.dim.as_str(), " monthly".into()), + ], + w - 1, + )); + } + rows.push(String::new()); + rows +} + +/// How far behind today the stats cache's own reckoning is. +/// +/// `room` is the columns actually left on the line, measured by the caller +/// rather than guessed from the pane width - the text before this varies, +/// so a width threshold clipped at some widths and not others. +fn stats_lag(stats: &serde_json::Value, room: i64) -> String { + let last = text(stats, "lastComputedDate"); + let Ok(when) = NaiveDate::parse_from_str(&last, "%Y-%m-%d") else { + return String::new(); + }; + let days = (Local::now().date_naive() - when).num_days(); + if days <= 0 { + return String::new(); + } + let month = MONTHS[when.month0() as usize]; + for candidate in [ + format!(" cache is {}d behind, to {} {}", days, month, when.day()), + format!(" cache {}d behind", days), + format!(" -{}d", days), + ] { + if candidate.len() as i64 <= room { + return candidate; + } + } + String::new() +} + +fn claude_plan_rows(prof: &serde_json::Value, w: usize, p: &Palette) -> Vec { + let org = &prof["organization"]; + let mut pairs: Vec<(String, String)> = Vec::new(); + let created = text(org, "subscription_created_at"); + if let (Some(since), day) = (iso_epoch(&created), iso_day(&created)) { + if !day.is_empty() { + pairs.push(("member since".into(), format!("{} · {} ago", day, ago(since)))); + } + } + for (label, key) in [ + ("status", "subscription_status"), + ("rate limit tier", "rate_limit_tier"), + ] { + let value = text(org, key); + if !value.is_empty() { + pairs.push((label.into(), value)); + } + } + let billing = text(org, "billing_type"); + if !billing.is_empty() { + pairs.push(("billing".into(), billing.replace('_', " "))); + } + let headline = match text(prof, "_plan") { + s if !s.is_empty() => s, + _ => text(org, "organization_type"), + }; + plan_rows( + &headline, + &pairs, + w, + if prof["_local"].as_bool().unwrap_or(false) { + "from credentials" + } else { + "" + }, + None, + "", + p, + ) +} + +fn claude_metered(c: &Claude, w: usize, cfg: &Config, p: &Palette) -> Vec { + metered_rows( + &[ + ("today".to_string(), window_models(&c.daily, 1)), + ("30 days".to_string(), window_models(&c.daily, 30)), + ], + w, + "", + "claude", + "this machine", + "Counted from transcripts, which are written where the agent ran. \ + Claude used on another machine, or on claude.ai, is not in here.", + cfg, + p, + ) +} + +fn claude_tab(c: &Claude, w: usize, p: &Palette) -> Vec { + let mut rows = claude_quota(c, w, p); + if !c.ok { + rows.extend(no_local( + &format!("No stats cache yet ({}).", c.why), + run_hint("claude"), + w, + p, + )); + return rows; + } + let d = &c.stats; + let mu = &d["modelUsage"]; + let sum_over = |key: &str| -> f64 { + mu.as_object() + .into_iter() + .flatten() + .map(|(_, v)| num(v, key)) + .sum() + }; + let (in_tok, out_tok) = (sum_over("inputTokens"), sum_over("outputTokens")); + let (cache_r, cache_w) = ( + sum_over("cacheReadInputTokens"), + sum_over("cacheCreationInputTokens"), + ); + + // The calendar is computed first: its streaks and active-day counts + // belong in the summary above it, not only beside the calendar. + let mut totals: HashMap = HashMap::new(); + for entry in d["dailyModelTokens"].as_array().into_iter().flatten() { + let day = text(entry, "date"); + let Ok(at) = NaiveDate::parse_from_str(&day, "%Y-%m-%d") else { + continue; + }; + let total: f64 = entry["tokensByModel"] + .as_object() + .into_iter() + .flatten() + .map(|(_, v)| v.as_f64().unwrap_or(0.0)) + .sum(); + totals.insert(at, total); + } + let peak = totals.values().cloned().fold(0.0f64, f64::max); + let cal = day_calendar(&totals, w, HEAT_STEPS, None, p); + + let fav = mu + .as_object() + .into_iter() + .flatten() + .max_by(|a, b| num(a.1, "outputTokens").total_cmp(&num(b.1, "outputTokens"))) + .map(|(k, _)| k.replace("claude-", "")) + .unwrap_or_else(|| "—".into()); + let all_tokens = in_tok + out_tok + cache_r + cache_w; + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── SUMMARY ── ".into()), + ( + p.dim.as_str(), + format!( + "all time · since {}", + text(d, "firstSessionDate").chars().take(10).collect::() + ), + ), + ], + w - 1, + )); + let facts = cal.as_ref(); + let best_txt = facts + .and_then(|c| c.best) + .map(|b| format!("{} {}", MONTHS[b.month0() as usize], b.day())) + .unwrap_or_else(|| "—".into()); + let pairs: Vec<(&str, String, &str, &str, String, &str)> = vec![ + ( + "Favorite model", + fav, + p.agent.as_str(), + "Total tokens", + big_num(all_tokens), + p.agent.as_str(), + ), + ( + "Sessions", + format!("{}", num(d, "totalSessions") as i64), + p.txt.as_str(), + "Longest session", + span_ms(num(&d["longestSession"], "duration")), + p.txt.as_str(), + ), + ( + "Active days", + facts + .map(|c| format!("{}/{}", c.active, c.span)) + .unwrap_or_else(|| "—".into()), + p.txt.as_str(), + "Longest streak", + facts + .map(|c| format!("{} days", c.longest)) + .unwrap_or_else(|| "—".into()), + p.txt.as_str(), + ), + ( + "Most active day", + best_txt, + p.txt.as_str(), + "Current streak", + facts + .map(|c| format!("{} days", c.current)) + .unwrap_or_else(|| "—".into()), + if facts.is_some_and(|c| c.current > 0) { p.ok.as_str() } else { p.dim.as_str() }, + ), + ]; + let lw = pairs + .iter() + .map(|(a, _, _, c, _, _)| a.len().max(c.len())) + .max() + .unwrap_or(10); + let half = (w - 3) / 2; + let vw = half.saturating_sub(lw + 2).max(6); + for (a, b, bc, c, e, ec) in &pairs { + rows.push(tc::seg( + &[ + (p.dim.as_str(), format!(" {} ", tc::pad(a, lw))), + (bc, tc::pad(b, vw)), + (p.dim.as_str(), format!(" {} ", tc::pad(c, lw))), + (ec, tc::pad(e, vw)), + ], + w - 1, + )); + } + rows.push(tc::seg( + &[ + (p.dim.as_str(), " Input ".into()), + (p.txt.as_str(), big_num(in_tok)), + (p.dim.as_str(), " · Output ".into()), + (p.txt.as_str(), big_num(out_tok)), + (p.dim.as_str(), " · Cache read ".into()), + (p.txt.as_str(), big_num(cache_r)), + (p.dim.as_str(), " · Cache written ".into()), + (p.txt.as_str(), big_num(cache_w)), + ], + w - 1, + )); + + // Which model did the work. + rows.push(String::new()); + let mut ranked: Vec<(String, f64)> = mu + .as_object() + .into_iter() + .flatten() + .map(|(k, v)| (k.clone(), num(v, "outputTokens"))) + .filter(|(_, tok)| *tok > 0.0) + .collect(); + ranked.sort_by(|a, b| b.1.total_cmp(&a.1)); + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── BY MODEL ── ".into()), + (p.dim.as_str(), "output tokens".into()), + ], + w - 1, + )); + if let Some((_, top)) = ranked.first() { + let top = top.max(1.0); + for (name, tok) in ranked.iter().take(5) { + let bar = tc::meter(tok / top, w.saturating_sub(34).max(6)); + let filled = bar.chars().filter(|c| *c == '█').count(); + rows.push(tc::seg( + &[ + ( + p.txt.as_str(), + format!(" {}", tc::pad(&name.replace("claude-", ""), 20)), + ), + (p.agent.as_str(), format!("{:>7} ", big_num(*tok))), + (p.agent.as_str(), bar.chars().take(filled).collect::()), + (p.grid.as_str(), bar.chars().skip(filled).collect::()), + ], + w - 1, + )); + } + } + + // Messages per day, straight from the file. + let daily: Vec<&serde_json::Value> = d["dailyActivity"].as_array().map(|a| a.iter().collect()).unwrap_or_default(); + if !daily.is_empty() { + rows.push(String::new()); + let counts: Vec = daily.iter().map(|x| num(x, "messageCount")).collect(); + let msg_peak = counts.iter().cloned().fold(0.0f64, f64::max).max(1.0); + // Both charts on this tab come from stats-cache.json, which Claude + // Code recomputes on its own schedule. Unlabelled, that gap reads as + // idle days rather than as days the cache has not caught up with. + let head = " ── MESSAGES / DAY ── "; + let tail = format!("{}d · peak {}", daily.len(), msg_peak as i64); + rows.push(tc::seg( + &[ + (p.lbl.as_str(), head.into()), + (p.dim.as_str(), tail.clone()), + ( + p.warn.as_str(), + stats_lag(d, w as i64 - 1 - head.len() as i64 - tail.len() as i64), + ), + ], + w - 1, + )); + let avail = w.saturating_sub(3).max(10); + let widths = tc::spread(counts.len(), avail); + let mut cols: Vec<(f64, String)> = Vec::new(); + for (c, wide) in counts.iter().zip(&widths) { + cols.extend(std::iter::repeat_n((*c, p.agent.clone()), *wide)); + } + for line in tc::vbars(&cols, 3, 0.0) { + let mut parts: Vec<(&str, String)> = vec![(tc::RST, " ".into())]; + for (colour, ch) in &line { + parts.push((colour.as_str(), ch.clone())); + } + rows.push(tc::seg(&parts, w - 1)); + } + rows.push(tc::seg( + &[(tc::RST, " ".into()), (p.grid.as_str(), "─".repeat(cols.len()))], + w - 1, + )); + let left: String = text(daily[0], "date").chars().skip(5).collect(); + let right: String = text(daily[daily.len() - 1], "date").chars().skip(5).collect(); + rows.push(tc::seg( + &[ + (p.dim.as_str(), format!(" {}", left)), + ( + p.dim.as_str(), + " ".repeat(cols.len().saturating_sub(left.len() + right.len()).max(1)), + ), + (p.dim.as_str(), right), + ], + w - 1, + )); + } + + // How fast it generates. + if !c.rates.is_empty() { + let med = c.rates[c.rates.len() / 2]; + let p90 = c.rates[((c.rates.len() as f64 * 0.9) as usize).min(c.rates.len() - 1)]; + rows.push(String::new()); + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── OUTPUT RATE ── ".into()), + ( + p.dim.as_str(), + format!("{} turns across {} transcripts", c.rates.len(), c.sampled), + ), + ], + w - 1, + )); + rows.push(tc::seg( + &[ + (p.dim.as_str(), " median ".into()), + (p.agent.as_str(), format!("{:.0}", med)), + (p.dim.as_str(), " tok/s p90 ".into()), + (p.txt.as_str(), format!("{:.0}", p90)), + (p.dim.as_str(), " request to response, tools included".into()), + ], + w - 1, + )); + } + + // Tokens per day, as a calendar. + if let Some(cal) = cal { + rows.push(String::new()); + let head = " ── TOKENS / DAY ── peak "; + let tail = format!( + "{} on {}", + big_num(peak), + cal.best + .map(|b| format!("{} {}", MONTHS[b.month0() as usize], b.day())) + .unwrap_or_else(|| "--".into()) + ); + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── TOKENS / DAY ── ".into()), + (p.dim.as_str(), "peak ".into()), + (p.agent.as_str(), big_num(peak)), + ( + p.dim.as_str(), + format!( + " on {}", + cal.best + .map(|b| format!("{} {}", MONTHS[b.month0() as usize], b.day())) + .unwrap_or_else(|| "--".into()) + ), + ), + ( + p.warn.as_str(), + stats_lag(d, w as i64 - 1 - head.len() as i64 - tail.len() as i64), + ), + ], + w - 1, + )); + for line in &cal.rows { + let refs: Vec<(&str, String)> = + line.iter().map(|(c, t)| (c.as_str(), t.clone())).collect(); + rows.push(tc::seg(&refs, w - 1)); + } + let mut legend: Vec<(&str, String)> = vec![(p.dim.as_str(), " Less ".into())]; + let swatches: Vec = HEAT_STEPS.iter().map(|(r, g, b)| tc::rgb(*r, *g, *b)).collect(); + for colour in &swatches { + legend.push((colour.as_str(), "█".into())); + } + legend.push((p.dim.as_str(), " More".into())); + rows.push(tc::seg(&legend, w - 1)); + } + rows +} + +/// An agent this build has no reader for yet. +/// +/// usage.py reads six; this port reads the one with by far the most local +/// data while the rest are ported. Saying so is the point: a tab showing a +/// plausible zero would be worse than one that admits it is empty, which is +/// the same rule the Python applies to an agent that publishes nothing. +fn not_yet(name: &str, installed: &HashMap, w: usize, p: &Palette) -> Vec { + let (label, _, _) = agent_spec(name); + let have = installed.get(name).is_some_and(|x| x.present); + let mut rows = vec![ + tc::seg( + &[ + (p.lbl.as_str(), format!(" ── {} ── ", label.to_uppercase())), + ( + if have { p.ok.as_str() } else { p.dim.as_str() }, + if have { "installed" } else { "not installed" }.into(), + ), + ], + w - 1, + ), + String::new(), + ]; + for line in wrap_text( + "No reader for this agent in the Rust build yet. usage.py reads it; \ + this port does not, and shows nothing rather than a plausible zero.", + w.saturating_sub(4).max(20), + ) { + rows.push(tc::seg(&[(p.dim.as_str(), format!(" {}", line))], w - 1)); + } + rows.push(String::new()); + rows.push(tc::seg( + &[ + (p.dim.as_str(), " run ".into()), + (p.accent.as_str(), format!("python3 usage.py")), + (p.dim.as_str(), " for this one meanwhile".into()), + ], + w - 1, + )); + rows +} + +/// The view across whichever agents there turn out to be. +fn summary_tab(s: &State, w: usize, p: &Palette) -> Vec { + let mut rows = vec![tc::seg( + &[ + (p.lbl.as_str(), " ── ACROSS EVERY AGENT ── ".into()), + (p.dim.as_str(), "what each one has on this machine".into()), + ], + w - 1, + )]; + for name in ORDER { + let have = s.installed.get(*name).is_some_and(|x| x.present); + let hue = agent_hue(name) + .map(|(r, g, b)| tc::rgb(r, g, b)) + .unwrap_or_else(|| p.dim.clone()); + let (label, _, _) = agent_spec(name); + let said = if !have { + "not on this machine".to_string() + } else if *name == "claude" { + if s.claude.ok { + let today: f64 = window_models(&s.claude.daily, 1) + .iter() + .map(|(_, t)| total_tokens(t)) + .sum(); + let month: f64 = window_models(&s.claude.daily, 30) + .iter() + .map(|(_, t)| total_tokens(t)) + .sum(); + format!("{} today · {} in 30 days", big_num(today), big_num(month)) + } else { + "installed, no stats cache yet".into() + } + } else { + "installed · no reader in this build yet".into() + }; + rows.push(tc::seg( + &[ + (hue.as_str(), format!(" {}", tc::pad(label, 16))), + ( + if have { p.txt.as_str() } else { p.dim.as_str() }, + said, + ), + ], + w - 1, + )); + } + rows.push(String::new()); + for line in wrap_text( + "One tab per agent, because they do not agree on what usage even \ + means: one counts tokens, another counts the lines it wrote, and \ + several publish nothing outside their own session.", + w.saturating_sub(4).max(20), + ) { + rows.push(tc::seg(&[(p.dim.as_str(), format!(" {}", line))], w - 1)); + } + rows +} + +pub fn tab_body( + name: &str, + s: &State, + w: usize, + _h: usize, + cfg: &Config, + p: &Palette, +) -> Vec { + match name { + SUMMARY_TAB => summary_tab(s, w, p), + "claude" => { + let body = add_section( + claude_tab(&s.claude, w, p), + claude_metered(&s.claude, w, cfg, p), + ); + match s.claude.profile.as_ref() { + Some(prof) => add_section(body, claude_plan_rows(prof, w, p)), + None => body, + } + } + other => not_yet(other, &s.installed, w, p), + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn iterations_win_over_a_blocks_own_zeros() { + // A usage block's top-level numbers can all be zero while its + // iterations carry the real figures. + let u: serde_json::Value = serde_json::from_str( + r#"{"input_tokens": 0, "output_tokens": 0, + "iterations": [{"input_tokens": 10, "output_tokens": 20}, + {"input_tokens": 5, "output_tokens": 1}]}"#, + ) + .unwrap(); + let got = usage_kinds(&u); + assert_eq!(got.get("input"), Some(&15.0)); + assert_eq!(got.get("output"), Some(&21.0)); + } + + #[test] + fn cache_writes_keep_their_two_durations_apart() { + // Five-minute and one-hour writes are priced differently, so a + // total would be uncostable. + let split: serde_json::Value = serde_json::from_str( + r#"{"cache_creation": {"ephemeral_5m_input_tokens": 100, + "ephemeral_1h_input_tokens": 7}}"#, + ) + .unwrap(); + let got = usage_kinds(&split); + assert_eq!(got.get("cache_write"), Some(&100.0)); + assert_eq!(got.get("cache_write_1h"), Some(&7.0)); + // The flat field is only used when that split is absent. + let flat: serde_json::Value = + serde_json::from_str(r#"{"cache_creation_input_tokens": 42}"#).unwrap(); + let got = usage_kinds(&flat); + assert_eq!(got.get("cache_write"), Some(&42.0)); + assert_eq!(got.get("cache_write_1h"), Some(&0.0)); + } + + #[test] + fn the_shortest_leash_sorts_first() { + let lane = |json: &str| -> serde_json::Value { serde_json::from_str(json).unwrap() }; + let session = lane(r#"{"kind": "session"}"#); + let overall = lane(r#"{"kind": "weekly_all"}"#); + let scoped = lane(r#"{"kind": "weekly", "scope": {"model": {"display_name": "Opus"}}}"#); + assert!(claude_lane_rank(&session) < claude_lane_rank(&overall)); + assert!(claude_lane_rank(&overall) < claude_lane_rank(&scoped)); + } + + #[test] + fn the_scope_note_shortens_before_it_clips_a_reset() { + // Losing the clause leaves a shorter true line; losing the end of + // "resets in 15d" leaves "resets in 1", which is a wrong number. + assert!(scope_phrase(120, 20).contains("not this machine")); + assert!(!scope_phrase(40, 20).contains("not this machine")); + assert!(scope_phrase(40, 20).contains("account-wide")); + } + + #[test] + fn a_window_sums_only_the_days_inside_it() { + let mut daily: HashMap> = HashMap::new(); + let mut today = empty_tokens(); + today.insert("output".into(), 100.0); + let mut old = empty_tokens(); + old.insert("output".into(), 900.0); + let now_day = Local::now().date_naive().format("%Y-%m-%d").to_string(); + let long_ago = (Local::now().date_naive() - Days::days(90)) + .format("%Y-%m-%d") + .to_string(); + daily.insert(now_day, [("claude-opus-5".to_string(), today)].into_iter().collect()); + daily.insert(long_ago, [("claude-opus-5".to_string(), old)].into_iter().collect()); + let got = window_models(&daily, 1); + assert_eq!(got.len(), 1); + assert_eq!(got[0].1.get("output"), Some(&100.0)); + // Ninety days back is outside a thirty-day window, so it is not + // added to it - a total that quietly spanned both would be wrong. + let month = window_models(&daily, 30); + assert_eq!(month[0].1.get("output"), Some(&100.0)); + } +} diff --git a/rust/widgets/src/bin/usage_help.txt b/rust/widgets/src/bin/usage_help.txt new file mode 100644 index 0000000..213961b --- /dev/null +++ b/rust/widgets/src/bin/usage_help.txt @@ -0,0 +1,18 @@ +How much the coding agents on this machine have been used. + +One tab per agent, because they do not agree on what usage even means: one +counts tokens, another counts lines it wrote, and several publish nothing at +all outside their own session. A single table would need a shared schema that +does not exist, so each tab shows that agent's own shape - and an agent that +exposes nothing says so rather than showing a plausible zero. + + usage [-n SECONDS] + +Most of this is read from local state files. The exception is the remaining +quota, which no agent writes to disk in a current form: Claude, Codex, Cursor +and Copilot each publish one over an endpoint, fetched with the credential +that agent already holds and sent only to that agent's own host. Nothing here is +inferred from a number that was not published. + +Keys: left/right or tab switch agent, up/down scroll it, pgup/pgdn by +the page, home/end to either edge, r refreshes now, q quits. From 82c9d7f1c6316e11f71e9a470aeb6b59f5ae0d87 Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sun, 23 Aug 2026 18:13:04 +0800 Subject: [PATCH 032/147] usage: one file per agent, and a summary that draws real bars Pure motion ahead of the five remaining readers. Claude moves out of the dispatcher into usage/claude.rs, the toolkit every reader wants moves into usage/shared.rs, and the four stragglers get a file each. Nothing changed about what Claude shows: same quota, same summary grid, same calendar, checked against a capture taken before the move. The point is that five readers can now be written at once without any two of them editing the same file. The dispatcher, the State fields and the tab arms are all here already, so each reader fills in one file against an interface that is fixed rather than negotiated. The interface is three functions: read() for the local state, tab() for the agent's own shape, and lanes() for the summary. lanes() returns data rather than rendered rows, and that is the part worth getting right - the summary is not a concatenation of the other tabs. Those answer "how am I using this agent"; it answers the only question that spans them, which is what runs out first. So it needs the four numbers a quota reduces to - label, percent, window, reset - and draws its own bars from them, ranked worst first. A vendor returning a finished string could not be ranked against another vendor's. claude.rs kept private copies of the file walker and the tail reader in the split; they are shared's now. Two walkers is how the corpus one of them scans quietly drifts from the corpus the other does. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/widgets/src/bin/usage.rs | 21 +- rust/widgets/src/bin/usage/antigravity.rs | 59 + rust/widgets/src/bin/usage/claude.rs | 997 ++++++++++++++++ rust/widgets/src/bin/usage/codex.rs | 59 + rust/widgets/src/bin/usage/copilot.rs | 59 + rust/widgets/src/bin/usage/cursor.rs | 59 + rust/widgets/src/bin/usage/grok.rs | 59 + rust/widgets/src/bin/usage/shared.rs | 166 +++ rust/widgets/src/bin/usage/vendors.rs | 1309 +++------------------ 9 files changed, 1660 insertions(+), 1128 deletions(-) create mode 100644 rust/widgets/src/bin/usage/antigravity.rs create mode 100644 rust/widgets/src/bin/usage/claude.rs create mode 100644 rust/widgets/src/bin/usage/codex.rs create mode 100644 rust/widgets/src/bin/usage/copilot.rs create mode 100644 rust/widgets/src/bin/usage/cursor.rs create mode 100644 rust/widgets/src/bin/usage/grok.rs create mode 100644 rust/widgets/src/bin/usage/shared.rs diff --git a/rust/widgets/src/bin/usage.rs b/rust/widgets/src/bin/usage.rs index 2cef942..530208e 100644 --- a/rust/widgets/src/bin/usage.rs +++ b/rust/widgets/src/bin/usage.rs @@ -1378,7 +1378,7 @@ fn main() { let poller = Arc::clone(&state); let poller_wake = Arc::clone(&wake); std::thread::spawn(move || { - let mut caches = vendors::Caches::default(); + let mut caches = shared::Caches::default(); loop { // A poller that dies takes its explanation with it, and an empty // board looks exactly like a machine with no agents on it. @@ -1579,7 +1579,24 @@ fn main() { } // Kept in a directory of its own rather than beside this file: anything -// dropped straight into src/bin/ risks being taken for another binary. +// dropped straight into src/bin/ risks being taken for another binary. One +// module per agent, because they share only the shape the summary screen +// compares them in - and because five readers being written at once should +// not be five edits to the same file. +#[path = "usage/shared.rs"] +mod shared; +#[path = "usage/antigravity.rs"] +mod antigravity; +#[path = "usage/claude.rs"] +mod claude; +#[path = "usage/codex.rs"] +mod codex; +#[path = "usage/copilot.rs"] +mod copilot; +#[path = "usage/cursor.rs"] +mod cursor; +#[path = "usage/grok.rs"] +mod grok; #[path = "usage/vendors.rs"] mod vendors; diff --git a/rust/widgets/src/bin/usage/antigravity.rs b/rust/widgets/src/bin/usage/antigravity.rs new file mode 100644 index 0000000..c17f8a9 --- /dev/null +++ b/rust/widgets/src/bin/usage/antigravity.rs @@ -0,0 +1,59 @@ +// terminal-toys - small dependency-free terminal widgets +// Copyright (C) 2026 William Li +// +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU Affero General Public License as published +// by the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU Affero General Public License for more details. +// +// You should have received a copy of the GNU Affero General Public License +// along with this program. If not, see . + +//! Antigravity: its conversation databases and the Code Assist quota. +//! +//! Not read yet. Every function here is honest about that rather than +//! returning a plausible zero, which is the rule the whole widget follows +//! for an agent that publishes nothing. + +use toys_core as tc; + +use crate::shared::*; +use crate::*; + +#[derive(Clone, Default)] +pub struct Data {} + +pub fn read(_caches: &mut Caches) -> Data { + Data::default() +} + +/// Every quota this agent publishes, for the summary screen. +pub fn lanes(_d: &Data) -> Vec { + Vec::new() +} + +pub fn tab(_d: &Data, w: usize, _h: usize, _cfg: &Config, p: &Palette) -> Vec { + let mut rows = vec![ + tc::seg( + &[ + (p.lbl.as_str(), " ── ANTIGRAVITY ── ".into()), + (p.dim.as_str(), "no reader in this build yet".into()), + ], + w - 1, + ), + String::new(), + ]; + for line in wrap_text( + "usage.py reads this agent; the Rust port does not yet. Nothing is \ + shown rather than a plausible zero.", + w.saturating_sub(4).max(20), + ) { + rows.push(tc::seg(&[(p.dim.as_str(), format!(" {}", line))], w - 1)); + } + rows +} diff --git a/rust/widgets/src/bin/usage/claude.rs b/rust/widgets/src/bin/usage/claude.rs new file mode 100644 index 0000000..c8c624c --- /dev/null +++ b/rust/widgets/src/bin/usage/claude.rs @@ -0,0 +1,997 @@ +// terminal-toys - small dependency-free terminal widgets +// Copyright (C) 2026 William Li +// +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU Affero General Public License as published +// by the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU Affero General Public License for more details. +// +// You should have received a copy of the GNU Affero General Public License +// along with this program. If not, see . + +//! Claude Code: its stats cache, its transcripts, and what is left of the +//! account's limits. +//! +//! The money comes from the transcripts rather than the cache. The cache +//! has one total per model per day, and input, output and the two cache +//! durations differ in price by up to fifty times, so a total cannot be +//! costed. + +use std::collections::HashMap; + +use chrono::{Datelike, Duration as Days, Local, NaiveDate, TimeZone}; +use toys_core as tc; + +use crate::shared::*; +use crate::*; + +/// Newest transcripts to sample for a rate. +const RATE_FILES: usize = 3; +/// Seconds; below this the timestamps are not a turn. +const MIN_GAP: f64 = 1.0; + +/// What Claude Code has recorded, plus what is left of the limits. +#[derive(Clone, Default)] +pub struct Data { + ok: bool, + why: String, + stats: serde_json::Value, + /// The live or cached rate-limit reading, which is account-wide rather + /// than about this machine. + quota: Option, + quota_live: bool, + quota_at: f64, + quota_plan: String, + profile: Option, + /// Output tokens per second, sorted, and how many transcripts it came + /// from. + rates: Vec, + sampled: usize, + /// day -> model -> tokens by priced kind. + daily: HashMap>, +} + +/// The OAuth token Claude Code already holds. +/// +/// It goes only to Anthropic, is never printed, and an expired one is not +/// used at all: the refresh token sits beside it, but spending it would +/// race Claude Code's own credential handling for a number that has a local +/// cache anyway. +pub fn claude_token() -> Option<(String, String)> { + let creds = read_json(&under_home(".claude/.credentials.json"))?; + let o = &creds["claudeAiOauth"]; + let tok = text(o, "accessToken"); + if tok.is_empty() || num(o, "expiresAt") / 1000.0 <= now() { + return None; + } + Some((tok, text(o, "subscriptionType"))) +} + +pub fn claude_get(url: &str, tok: &str) -> Option { + let body = tc::get( + url, + &[ + ("Authorization", &format!("Bearer {}", tok)), + ("User-Agent", "terminal-toys"), + ], + 20, + ) + .ok()?; + serde_json::from_str(&body).ok() +} + +/// What Claude Code last fetched, for when the live call cannot run. +/// +/// It is a cache with a timestamp, so it is shown with its age - and a +/// window whose reset has already gone by is said to have passed rather +/// than counted down to, because a stale five-hour window describes a +/// period that has ended. +pub fn claude_stale() -> Option<(serde_json::Value, f64)> { + let config = read_json(&under_home(".claude.json"))?; + let c = &config["cachedUsageUtilization"]; + let u = c["utilization"].clone(); + if u.is_null() { + return None; + } + Some((u, num(c, "fetchedAtMs") / 1000.0)) +} + +/// Token counts from one transcript usage block, by priced kind. +/// +/// A block's top-level numbers can all be zero while its `iterations` carry +/// the real figures, so the iterations win where they exist. Cache writes +/// are split by duration because they are priced differently, and the flat +/// cache_creation_input_tokens is only used when that split is absent. +pub fn usage_kinds(u: &serde_json::Value) -> Tokens { + let mut out = empty_tokens(); + let empty = vec![u.clone()]; + let blocks: Vec = match u["iterations"].as_array() { + Some(list) if !list.is_empty() => list.clone(), + _ => empty, + }; + for x in &blocks { + *out.get_mut("input").unwrap() += num(x, "input_tokens"); + *out.get_mut("output").unwrap() += num(x, "output_tokens"); + *out.get_mut("cache_read").unwrap() += num(x, "cache_read_input_tokens"); + let split = &x["cache_creation"]; + if split.is_object() { + *out.get_mut("cache_write").unwrap() += num(split, "ephemeral_5m_input_tokens"); + *out.get_mut("cache_write_1h").unwrap() += num(split, "ephemeral_1h_input_tokens"); + } else { + *out.get_mut("cache_write").unwrap() += num(x, "cache_creation_input_tokens"); + } + } + out +} + +/// Per-record token counts from one transcript, keyed by record uuid. +/// +/// Keyed rather than summed because the same message appears in more than +/// one file: resuming or forking a session replays its history into the new +/// transcript, and subagent turns are written twice over. Left raw that +/// inflated one model by 29% against Claude Code's own totals. +/// +/// Cached on (mtime, size): a finished transcript never changes, so each is +/// parsed once. +pub fn scan_transcript( + caches: &mut Caches, + path: &str, +) -> HashMap { + let Ok(meta) = std::fs::metadata(path) else { + return HashMap::new(); + }; + use std::os::unix::fs::MetadataExt; + let key = (meta.mtime() as u64, meta.size()); + if let Some((had, records)) = caches.transcripts.get(path) { + if *had == key { + return records.clone(); + } + } + let mut records = HashMap::new(); + let Ok(body) = std::fs::read_to_string(path) else { + return records; + }; + for line in body.lines() { + if !line.contains("\"usage\"") { + continue; + } + let Ok(r) = serde_json::from_str::(line) else { + continue; + }; + let msg = &r["message"]; + let u = &msg["usage"]; + let (model, uid, stamp) = (text(msg, "model"), text(&r, "uuid"), text(&r, "timestamp")); + if u.is_null() || model.is_empty() || uid.is_empty() || stamp.is_empty() { + continue; + } + let Some(when) = iso_epoch(&stamp) else { + continue; + }; + let got = usage_kinds(u); + if total_tokens(&got) <= 0.0 { + continue; + } + let day = Local + .timestamp_opt(when as i64, 0) + .single() + .map(|d| d.format("%Y-%m-%d").to_string()) + .unwrap_or_default(); + records.insert(uid, (day, model, got)); + } + caches + .transcripts + .insert(path.to_string(), (key, records.clone())); + records +} + +/// Every transcript's per-day, per-model tokens, de-duplicated. +/// +/// stats-cache.json has dailyModelTokens, but only one total per model per +/// day - and input, output and the two cache kinds differ in price by up to +/// fifty times, so a total cannot be costed. The transcripts carry the +/// split, which is why the money comes from here and not from the cache. +pub fn claude_daily(caches: &mut Caches) -> HashMap> { + let mut files = Vec::new(); + // Recursive on purpose: subagent transcripts live a further two levels + // down, and that is where most of the smaller models actually run. + walk(&under_home(".claude/projects"), ".jsonl", &mut files); + let mut seen: HashMap = HashMap::new(); + for path in &files { + seen.extend(scan_transcript(caches, path)); + } + let mut merged: HashMap> = HashMap::new(); + for (day, model, tokens) in seen.into_values() { + let bucket = merged + .entry(day) + .or_default() + .entry(model) + .or_insert_with(empty_tokens); + for kind in RATE_KINDS { + *bucket.get_mut(*kind).unwrap() += tokens.get(*kind).copied().unwrap_or(0.0); + } + } + merged +} + +/// Per-model token totals over the last N days (1 = today only). +pub fn window_models( + daily: &HashMap>, + days: i64, +) -> Vec<(String, Tokens)> { + let first = (Local::now().date_naive() - Days::days(days - 1)) + .format("%Y-%m-%d") + .to_string(); + let mut out: HashMap = HashMap::new(); + for (day, models) in daily { + if *day < first { + continue; + } + for (model, tokens) in models { + let bucket = out.entry(model.clone()).or_insert_with(empty_tokens); + for kind in RATE_KINDS { + *bucket.get_mut(*kind).unwrap() += tokens.get(*kind).copied().unwrap_or(0.0); + } + } + } + let mut list: Vec<(String, Tokens)> = out.into_iter().collect(); + list.sort_by(|a, b| a.0.cmp(&b.0)); + list +} + +/// Output tokens per second, from the newest transcripts. +/// +/// A turn is a `user` record followed by an `assistant` one, and the rate is +/// that assistant's output tokens over the gap between them. Measuring from +/// any previous record instead inflates it wildly - two assistant records +/// can be milliseconds apart while the second reports a whole turn's output. +/// +/// The median is what gets shown: it barely moves whichever way the outliers +/// are trimmed, which is the reason to trust it, while the maximum moves by +/// a factor of twenty on the same data, which is the reason not to show one. +pub fn claude_rates() -> (Vec, usize) { + let mut files = Vec::new(); + walk(&under_home(".claude/projects"), ".jsonl", &mut files); + let mut with_time: Vec<(u64, String)> = files + .into_iter() + .filter_map(|path| { + use std::os::unix::fs::MetadataExt; + let meta = std::fs::metadata(&path).ok()?; + Some((meta.mtime() as u64, path)) + }) + .collect(); + with_time.sort_by(|a, b| b.0.cmp(&a.0)); + let mut out: Vec = Vec::new(); + let mut sampled = 0usize; + for (_, path) in with_time.iter().take(RATE_FILES) { + sampled += 1; + let (mut prev, mut prev_type): (Option, String) = (None, String::new()); + for line in tail_lines(path, 4 * 1024 * 1024) { + if !line.contains("\"timestamp\"") { + continue; + } + let Ok(d) = serde_json::from_str::(&line) else { + continue; + }; + let (stamp, typ) = (text(&d, "timestamp"), text(&d, "type")); + let at = iso_epoch(&stamp); + if typ == "assistant" + && at.is_some() + && prev.is_some() + && prev_type == "user" + && !d["isAbortedMidStream"].as_bool().unwrap_or(false) + { + let tok = num(&d["message"]["usage"], "output_tokens"); + if tok > 0.0 { + let gap = at.unwrap() - prev.unwrap(); + if (MIN_GAP..300.0).contains(&gap) { + out.push(tok / gap); + } + } + } + if let Some(at) = at { + prev = Some(at); + prev_type = typ; + } + } + } + out.sort_by(f64::total_cmp); + (out, sampled) +} + +pub fn read(caches: &mut Caches) -> Data { + let mut claude = Data::default(); + let live = cached(caches, "claude", LIVE_TTL, || { + let (tok, plan) = claude_token()?; + let u = claude_get("https://api.anthropic.com/api/oauth/usage", &tok)?; + Some(serde_json::json!({ "u": u, "at": now(), "plan": plan })) + }); + match live { + Some(got) => { + claude.quota = Some(got["u"].clone()); + claude.quota_live = true; + claude.quota_at = num(&got, "at"); + claude.quota_plan = text(&got, "plan"); + } + None => { + if let Some((u, at)) = claude_stale() { + claude.quota = Some(u); + claude.quota_live = false; + claude.quota_at = at; + } + } + } + claude.profile = cached(caches, "claude-plan", PLAN_TTL, || { + let (tok, plan) = claude_token()?; + let mut d = claude_get("https://api.anthropic.com/api/oauth/profile", &tok)?; + d["_plan"] = serde_json::Value::String(plan); + Some(d) + }); + if claude.profile.is_none() { + // The profile endpoint is richer, but the credentials file needs no + // network and is always there, so the section degrades to two true + // lines instead of vanishing. + if let Some(creds) = read_json(&under_home(".claude/.credentials.json")) { + let o = &creds["claudeAiOauth"]; + let plan = text(o, "subscriptionType"); + if !plan.is_empty() { + claude.profile = Some(serde_json::json!({ + "_plan": plan, + "_local": true, + "organization": { "rate_limit_tier": text(o, "rateLimitTier") }, + })); + } + } + } + match read_json(&under_home(".claude/stats-cache.json")) { + Some(stats) => { + claude.ok = true; + claude.stats = stats; + let (rates, sampled) = claude_rates(); + claude.rates = rates; + claude.sampled = sampled; + claude.daily = claude_daily(caches); + } + None => claude.why = "no stats cache".into(), + } + claude +} + +/// Where a Claude limit belongs in the list, shortest leash first. +/// +/// The server returns them in no order worth keeping. Read top to bottom +/// they should widen: the five-hour session is what stops you this +/// afternoon, the weekly total is what stops you this week, and a +/// model-scoped weekly limit stops only one model. +pub fn claude_lane_rank(limit: &serde_json::Value) -> usize { + if text(limit, "kind") == "session" { + return 0; + } + if text(&limit["scope"]["model"], "display_name").is_empty() { + 1 + } else { + 2 + } +} + +/// The scope note, shortened before it can push a reset off the line. +/// +/// "not this machine" is the point of the sentence, but it is also sixteen +/// characters, and seg() clips whatever runs past the pane. Losing the +/// clause leaves a shorter true line; losing the end of "resets in 15d" +/// leaves "resets in 1", which is a different and wrong number. +pub fn scope_phrase(w: usize, used: usize) -> &'static str { + let full = " · account-wide, not this machine "; + if used + full.len() <= w - 1 { + full + } else { + " · account-wide " + } +} + +/// The windows Claude Code's own /usage shows. +/// +/// Read from limits[], which is the server's own curated list: the rest of +/// the response carries a dozen null pools that /usage does not render +/// either. Each entry names itself, so a model-scoped weekly limit arrives +/// labelled without this having to know the name. +pub fn claude_quota(c: &Data, w: usize, p: &Palette) -> Vec { + let Some(u) = c.quota.as_ref() else { + return Vec::new(); + }; + let mut lanes: Vec<&serde_json::Value> = u["limits"] + .as_array() + .into_iter() + .flatten() + .filter(|l| !l["percent"].is_null()) + .collect(); + if lanes.is_empty() { + return Vec::new(); + } + lanes.sort_by_key(|l| claude_lane_rank(l)); + let src = if c.quota_live { + "live".to_string() + } else { + format!("cached {} ago", ago(c.quota_at)) + }; + let hue = agent_hue("claude"); + let mut rows = vec![tc::seg( + &[ + (p.lbl.as_str(), " ── QUOTA ── ".into()), + ( + if c.quota_live { p.ok.as_str() } else { p.warn.as_str() }, + src.clone(), + ), + ( + p.dim.as_str(), + scope_phrase(w, 13 + src.len() + c.quota_plan.len()).to_string(), + ), + (p.dim.as_str(), c.quota_plan.clone()), + ], + w - 1, + )]; + + let label_of = |l: &serde_json::Value| -> String { + let scope = text(&l["scope"]["model"], "display_name"); + let group = text(l, "group"); + let name = if !scope.is_empty() { + scope + } else if text(l, "kind") == "weekly_all" { + "overall".to_string() + } else if !group.is_empty() { + group.clone() + } else { + match text(l, "kind") { + s if s.is_empty() => "?".into(), + s => s, + } + }; + let window = match group.as_str() { + "session" => "5h", + "weekly" => "7d", + _ => "", + }; + format!("{} {}", name, window).trim().to_string() + }; + let texts: Vec = lanes.iter().map(|l| label_of(l)).collect(); + let label_w = texts.iter().map(|t| t.chars().count()).max().unwrap_or(9).max(9); + for (l, label) in lanes.iter().zip(&texts) { + let pct = num(l, "percent"); + let used = (pct / 100.0).clamp(0.0, 1.0); + let reset = iso_epoch(&text(l, "resets_at")); + let when = match reset { + None => String::new(), + Some(ts) => { + let left = ts - now(); + if left > 0.0 { + format!("resets in {}", left_span(left)) + } else if c.quota_live { + "resetting".into() + } else { + "already reset".into() + } + } + }; + let sev = text(l, "severity").to_lowercase(); + let window = CLAUDE_WINDOW_SECS + .iter() + .find(|(g, _)| *g == text(l, "group")) + .map(|(_, s)| *s); + let cushion = lead(pct, window, reset); + let (pace_colour, pace_txt) = pace_cell(cushion, p); + // is_active marks the limit currently doing the binding - the one + // that will stop you first - so it is the one worth reading brightly. + let mut line: Vec<(String, String)> = vec![( + if l["is_active"].as_bool().unwrap_or(false) { + p.txt.clone() + } else { + p.dim.clone() + }, + format!(" {} ", tc::pad(label, label_w)), + )]; + line.extend(paced_bar( + used, + elapsed_of(window, reset), + w.saturating_sub(35 + label_w).max(8), + hue, + p, + )); + line.push((pct_colour(pct, hue, p), pct_text(pct))); + line.push((pace_colour, pace_txt)); + line.push(( + if sev.is_empty() || sev == "normal" { p.dim.clone() } else { p.bad.clone() }, + if sev.is_empty() || sev == "normal" { + format!(" {}", when) + } else { + format!(" {} · {}", sev, when) + }, + )); + let refs: Vec<(&str, String)> = line.iter().map(|(c, t)| (c.as_str(), t.clone())).collect(); + rows.push(tc::seg(&refs, w - 1)); + } + let extra = &u["extra_usage"]; + let spend = &u["spend"]; + if extra["is_enabled"].as_bool().unwrap_or(false) && !spend["limit"].is_null() { + let money = |m: &serde_json::Value| -> String { + format!( + "{:.2}", + num(m, "amount_minor") / 10f64.powf(m["exponent"].as_f64().unwrap_or(2.0)) + ) + }; + rows.push(tc::seg( + &[ + (p.dim.as_str(), " extra usage ".into()), + (p.txt.as_str(), money(&spend["used"])), + (p.dim.as_str(), " of ".into()), + (p.txt.as_str(), money(&spend["limit"])), + (p.dim.as_str(), format!(" {}", text(&spend["limit"], "currency"))), + (p.dim.as_str(), " monthly".into()), + ], + w - 1, + )); + } + rows.push(String::new()); + rows +} + +/// How far behind today the stats cache's own reckoning is. +/// +/// `room` is the columns actually left on the line, measured by the caller +/// rather than guessed from the pane width - the text before this varies, +/// so a width threshold clipped at some widths and not others. +pub fn stats_lag(stats: &serde_json::Value, room: i64) -> String { + let last = text(stats, "lastComputedDate"); + let Ok(when) = NaiveDate::parse_from_str(&last, "%Y-%m-%d") else { + return String::new(); + }; + let days = (Local::now().date_naive() - when).num_days(); + if days <= 0 { + return String::new(); + } + let month = MONTHS[when.month0() as usize]; + for candidate in [ + format!(" cache is {}d behind, to {} {}", days, month, when.day()), + format!(" cache {}d behind", days), + format!(" -{}d", days), + ] { + if candidate.len() as i64 <= room { + return candidate; + } + } + String::new() +} + +pub fn claude_plan_rows(prof: &serde_json::Value, w: usize, p: &Palette) -> Vec { + let org = &prof["organization"]; + let mut pairs: Vec<(String, String)> = Vec::new(); + let created = text(org, "subscription_created_at"); + if let (Some(since), day) = (iso_epoch(&created), iso_day(&created)) { + if !day.is_empty() { + pairs.push(("member since".into(), format!("{} · {} ago", day, ago(since)))); + } + } + for (label, key) in [ + ("status", "subscription_status"), + ("rate limit tier", "rate_limit_tier"), + ] { + let value = text(org, key); + if !value.is_empty() { + pairs.push((label.into(), value)); + } + } + let billing = text(org, "billing_type"); + if !billing.is_empty() { + pairs.push(("billing".into(), billing.replace('_', " "))); + } + let headline = match text(prof, "_plan") { + s if !s.is_empty() => s, + _ => text(org, "organization_type"), + }; + plan_rows( + &headline, + &pairs, + w, + if prof["_local"].as_bool().unwrap_or(false) { + "from credentials" + } else { + "" + }, + None, + "", + p, + ) +} + +pub fn claude_metered(c: &Data, w: usize, cfg: &Config, p: &Palette) -> Vec { + metered_rows( + &[ + ("today".to_string(), window_models(&c.daily, 1)), + ("30 days".to_string(), window_models(&c.daily, 30)), + ], + w, + "", + "claude", + "this machine", + "Counted from transcripts, which are written where the agent ran. \ + Claude used on another machine, or on claude.ai, is not in here.", + cfg, + p, + ) +} + +pub fn claude_tab(c: &Data, w: usize, p: &Palette) -> Vec { + let mut rows = claude_quota(c, w, p); + if !c.ok { + rows.extend(no_local( + &format!("No stats cache yet ({}).", c.why), + run_hint("claude"), + w, + p, + )); + return rows; + } + let d = &c.stats; + let mu = &d["modelUsage"]; + let sum_over = |key: &str| -> f64 { + mu.as_object() + .into_iter() + .flatten() + .map(|(_, v)| num(v, key)) + .sum() + }; + let (in_tok, out_tok) = (sum_over("inputTokens"), sum_over("outputTokens")); + let (cache_r, cache_w) = ( + sum_over("cacheReadInputTokens"), + sum_over("cacheCreationInputTokens"), + ); + + // The calendar is computed first: its streaks and active-day counts + // belong in the summary above it, not only beside the calendar. + let mut totals: HashMap = HashMap::new(); + for entry in d["dailyModelTokens"].as_array().into_iter().flatten() { + let day = text(entry, "date"); + let Ok(at) = NaiveDate::parse_from_str(&day, "%Y-%m-%d") else { + continue; + }; + let total: f64 = entry["tokensByModel"] + .as_object() + .into_iter() + .flatten() + .map(|(_, v)| v.as_f64().unwrap_or(0.0)) + .sum(); + totals.insert(at, total); + } + let peak = totals.values().cloned().fold(0.0f64, f64::max); + let cal = day_calendar(&totals, w, HEAT_STEPS, None, p); + + let fav = mu + .as_object() + .into_iter() + .flatten() + .max_by(|a, b| num(a.1, "outputTokens").total_cmp(&num(b.1, "outputTokens"))) + .map(|(k, _)| k.replace("claude-", "")) + .unwrap_or_else(|| "—".into()); + let all_tokens = in_tok + out_tok + cache_r + cache_w; + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── SUMMARY ── ".into()), + ( + p.dim.as_str(), + format!( + "all time · since {}", + text(d, "firstSessionDate").chars().take(10).collect::() + ), + ), + ], + w - 1, + )); + let facts = cal.as_ref(); + let best_txt = facts + .and_then(|c| c.best) + .map(|b| format!("{} {}", MONTHS[b.month0() as usize], b.day())) + .unwrap_or_else(|| "—".into()); + let pairs: Vec<(&str, String, &str, &str, String, &str)> = vec![ + ( + "Favorite model", + fav, + p.agent.as_str(), + "Total tokens", + big_num(all_tokens), + p.agent.as_str(), + ), + ( + "Sessions", + format!("{}", num(d, "totalSessions") as i64), + p.txt.as_str(), + "Longest session", + span_ms(num(&d["longestSession"], "duration")), + p.txt.as_str(), + ), + ( + "Active days", + facts + .map(|c| format!("{}/{}", c.active, c.span)) + .unwrap_or_else(|| "—".into()), + p.txt.as_str(), + "Longest streak", + facts + .map(|c| format!("{} days", c.longest)) + .unwrap_or_else(|| "—".into()), + p.txt.as_str(), + ), + ( + "Most active day", + best_txt, + p.txt.as_str(), + "Current streak", + facts + .map(|c| format!("{} days", c.current)) + .unwrap_or_else(|| "—".into()), + if facts.is_some_and(|c| c.current > 0) { p.ok.as_str() } else { p.dim.as_str() }, + ), + ]; + let lw = pairs + .iter() + .map(|(a, _, _, c, _, _)| a.len().max(c.len())) + .max() + .unwrap_or(10); + let half = (w - 3) / 2; + let vw = half.saturating_sub(lw + 2).max(6); + for (a, b, bc, c, e, ec) in &pairs { + rows.push(tc::seg( + &[ + (p.dim.as_str(), format!(" {} ", tc::pad(a, lw))), + (bc, tc::pad(b, vw)), + (p.dim.as_str(), format!(" {} ", tc::pad(c, lw))), + (ec, tc::pad(e, vw)), + ], + w - 1, + )); + } + rows.push(tc::seg( + &[ + (p.dim.as_str(), " Input ".into()), + (p.txt.as_str(), big_num(in_tok)), + (p.dim.as_str(), " · Output ".into()), + (p.txt.as_str(), big_num(out_tok)), + (p.dim.as_str(), " · Cache read ".into()), + (p.txt.as_str(), big_num(cache_r)), + (p.dim.as_str(), " · Cache written ".into()), + (p.txt.as_str(), big_num(cache_w)), + ], + w - 1, + )); + + // Which model did the work. + rows.push(String::new()); + let mut ranked: Vec<(String, f64)> = mu + .as_object() + .into_iter() + .flatten() + .map(|(k, v)| (k.clone(), num(v, "outputTokens"))) + .filter(|(_, tok)| *tok > 0.0) + .collect(); + ranked.sort_by(|a, b| b.1.total_cmp(&a.1)); + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── BY MODEL ── ".into()), + (p.dim.as_str(), "output tokens".into()), + ], + w - 1, + )); + if let Some((_, top)) = ranked.first() { + let top = top.max(1.0); + for (name, tok) in ranked.iter().take(5) { + let bar = tc::meter(tok / top, w.saturating_sub(34).max(6)); + let filled = bar.chars().filter(|c| *c == '█').count(); + rows.push(tc::seg( + &[ + ( + p.txt.as_str(), + format!(" {}", tc::pad(&name.replace("claude-", ""), 20)), + ), + (p.agent.as_str(), format!("{:>7} ", big_num(*tok))), + (p.agent.as_str(), bar.chars().take(filled).collect::()), + (p.grid.as_str(), bar.chars().skip(filled).collect::()), + ], + w - 1, + )); + } + } + + // Messages per day, straight from the file. + let daily: Vec<&serde_json::Value> = d["dailyActivity"].as_array().map(|a| a.iter().collect()).unwrap_or_default(); + if !daily.is_empty() { + rows.push(String::new()); + let counts: Vec = daily.iter().map(|x| num(x, "messageCount")).collect(); + let msg_peak = counts.iter().cloned().fold(0.0f64, f64::max).max(1.0); + // Both charts on this tab come from stats-cache.json, which Claude + // Code recomputes on its own schedule. Unlabelled, that gap reads as + // idle days rather than as days the cache has not caught up with. + let head = " ── MESSAGES / DAY ── "; + let tail = format!("{}d · peak {}", daily.len(), msg_peak as i64); + rows.push(tc::seg( + &[ + (p.lbl.as_str(), head.into()), + (p.dim.as_str(), tail.clone()), + ( + p.warn.as_str(), + stats_lag(d, w as i64 - 1 - head.len() as i64 - tail.len() as i64), + ), + ], + w - 1, + )); + let avail = w.saturating_sub(3).max(10); + let widths = tc::spread(counts.len(), avail); + let mut cols: Vec<(f64, String)> = Vec::new(); + for (c, wide) in counts.iter().zip(&widths) { + cols.extend(std::iter::repeat_n((*c, p.agent.clone()), *wide)); + } + for line in tc::vbars(&cols, 3, 0.0) { + let mut parts: Vec<(&str, String)> = vec![(tc::RST, " ".into())]; + for (colour, ch) in &line { + parts.push((colour.as_str(), ch.clone())); + } + rows.push(tc::seg(&parts, w - 1)); + } + rows.push(tc::seg( + &[(tc::RST, " ".into()), (p.grid.as_str(), "─".repeat(cols.len()))], + w - 1, + )); + let left: String = text(daily[0], "date").chars().skip(5).collect(); + let right: String = text(daily[daily.len() - 1], "date").chars().skip(5).collect(); + rows.push(tc::seg( + &[ + (p.dim.as_str(), format!(" {}", left)), + ( + p.dim.as_str(), + " ".repeat(cols.len().saturating_sub(left.len() + right.len()).max(1)), + ), + (p.dim.as_str(), right), + ], + w - 1, + )); + } + + // How fast it generates. + if !c.rates.is_empty() { + let med = c.rates[c.rates.len() / 2]; + let p90 = c.rates[((c.rates.len() as f64 * 0.9) as usize).min(c.rates.len() - 1)]; + rows.push(String::new()); + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── OUTPUT RATE ── ".into()), + ( + p.dim.as_str(), + format!("{} turns across {} transcripts", c.rates.len(), c.sampled), + ), + ], + w - 1, + )); + rows.push(tc::seg( + &[ + (p.dim.as_str(), " median ".into()), + (p.agent.as_str(), format!("{:.0}", med)), + (p.dim.as_str(), " tok/s p90 ".into()), + (p.txt.as_str(), format!("{:.0}", p90)), + (p.dim.as_str(), " request to response, tools included".into()), + ], + w - 1, + )); + } + + // Tokens per day, as a calendar. + if let Some(cal) = cal { + rows.push(String::new()); + let head = " ── TOKENS / DAY ── peak "; + let tail = format!( + "{} on {}", + big_num(peak), + cal.best + .map(|b| format!("{} {}", MONTHS[b.month0() as usize], b.day())) + .unwrap_or_else(|| "--".into()) + ); + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── TOKENS / DAY ── ".into()), + (p.dim.as_str(), "peak ".into()), + (p.agent.as_str(), big_num(peak)), + ( + p.dim.as_str(), + format!( + " on {}", + cal.best + .map(|b| format!("{} {}", MONTHS[b.month0() as usize], b.day())) + .unwrap_or_else(|| "--".into()) + ), + ), + ( + p.warn.as_str(), + stats_lag(d, w as i64 - 1 - head.len() as i64 - tail.len() as i64), + ), + ], + w - 1, + )); + for line in &cal.rows { + let refs: Vec<(&str, String)> = + line.iter().map(|(c, t)| (c.as_str(), t.clone())).collect(); + rows.push(tc::seg(&refs, w - 1)); + } + let mut legend: Vec<(&str, String)> = vec![(p.dim.as_str(), " Less ".into())]; + let swatches: Vec = HEAT_STEPS.iter().map(|(r, g, b)| tc::rgb(*r, *g, *b)).collect(); + for colour in &swatches { + legend.push((colour.as_str(), "█".into())); + } + legend.push((p.dim.as_str(), " More".into())); + rows.push(tc::seg(&legend, w - 1)); + } + rows +} + +/// Every quota Claude publishes, in the shape the summary screen compares. +/// +/// The same limits[] the tab renders, reduced to the four numbers that mean +/// the same thing across agents. Left in the server's own order, because +/// Claude's windows nest - the five-hour sits inside the weekly, which +/// contains the model-scoped limit in turn - and reading them widest-last +/// says more than reading them by percentage. +pub fn lanes(c: &Data) -> Vec { + let Some(u) = c.quota.as_ref() else { + return Vec::new(); + }; + let mut found: Vec<&serde_json::Value> = u["limits"] + .as_array() + .into_iter() + .flatten() + .filter(|l| !l["percent"].is_null()) + .collect(); + found.sort_by_key(|l| claude_lane_rank(l)); + found + .into_iter() + .map(|l| { + let group = text(l, "group"); + let scope = text(&l["scope"]["model"], "display_name"); + let name = if !scope.is_empty() { + scope + } else if text(l, "kind") == "weekly_all" { + "overall".to_string() + } else if !group.is_empty() { + group.clone() + } else { + match text(l, "kind") { + s if s.is_empty() => "?".into(), + s => s, + } + }; + let window = match group.as_str() { + "session" => "5h", + "weekly" => "7d", + _ => "", + }; + Lane { + label: format!("{} {}", name, window).trim().to_string(), + pct: num(l, "percent"), + window_secs: CLAUDE_WINDOW_SECS + .iter() + .find(|(g, _)| *g == group) + .map(|(_, s)| *s), + reset: iso_epoch(&text(l, "resets_at")), + stale: !c.quota_live, + } + }) + .collect() +} + +/// The whole tab: the quota, what the machine recorded, what it cost, and +/// which subscription the percentages are percentages of. +pub fn tab(c: &Data, w: usize, _h: usize, cfg: &Config, p: &Palette) -> Vec { + let body = add_section(claude_tab(c, w, p), claude_metered(c, w, cfg, p)); + match c.profile.as_ref() { + Some(prof) => add_section(body, claude_plan_rows(prof, w, p)), + None => body, + } +} diff --git a/rust/widgets/src/bin/usage/codex.rs b/rust/widgets/src/bin/usage/codex.rs new file mode 100644 index 0000000..7db14d5 --- /dev/null +++ b/rust/widgets/src/bin/usage/codex.rs @@ -0,0 +1,59 @@ +// terminal-toys - small dependency-free terminal widgets +// Copyright (C) 2026 William Li +// +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU Affero General Public License as published +// by the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU Affero General Public License for more details. +// +// You should have received a copy of the GNU Affero General Public License +// along with this program. If not, see . + +//! OpenAI Codex: its rollouts, and the account-wide quota the CLI itself reads. +//! +//! Not read yet. Every function here is honest about that rather than +//! returning a plausible zero, which is the rule the whole widget follows +//! for an agent that publishes nothing. + +use toys_core as tc; + +use crate::shared::*; +use crate::*; + +#[derive(Clone, Default)] +pub struct Data {} + +pub fn read(_caches: &mut Caches) -> Data { + Data::default() +} + +/// Every quota this agent publishes, for the summary screen. +pub fn lanes(_d: &Data) -> Vec { + Vec::new() +} + +pub fn tab(_d: &Data, w: usize, _h: usize, _cfg: &Config, p: &Palette) -> Vec { + let mut rows = vec![ + tc::seg( + &[ + (p.lbl.as_str(), " ── OPENAI CODEX ── ".into()), + (p.dim.as_str(), "no reader in this build yet".into()), + ], + w - 1, + ), + String::new(), + ]; + for line in wrap_text( + "usage.py reads this agent; the Rust port does not yet. Nothing is \ + shown rather than a plausible zero.", + w.saturating_sub(4).max(20), + ) { + rows.push(tc::seg(&[(p.dim.as_str(), format!(" {}", line))], w - 1)); + } + rows +} diff --git a/rust/widgets/src/bin/usage/copilot.rs b/rust/widgets/src/bin/usage/copilot.rs new file mode 100644 index 0000000..b3ef004 --- /dev/null +++ b/rust/widgets/src/bin/usage/copilot.rs @@ -0,0 +1,59 @@ +// terminal-toys - small dependency-free terminal widgets +// Copyright (C) 2026 William Li +// +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU Affero General Public License as published +// by the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU Affero General Public License for more details. +// +// You should have received a copy of the GNU Affero General Public License +// along with this program. If not, see . + +//! GitHub Copilot: its session store, and the premium-request pool. +//! +//! Not read yet. Every function here is honest about that rather than +//! returning a plausible zero, which is the rule the whole widget follows +//! for an agent that publishes nothing. + +use toys_core as tc; + +use crate::shared::*; +use crate::*; + +#[derive(Clone, Default)] +pub struct Data {} + +pub fn read(_caches: &mut Caches) -> Data { + Data::default() +} + +/// Every quota this agent publishes, for the summary screen. +pub fn lanes(_d: &Data) -> Vec { + Vec::new() +} + +pub fn tab(_d: &Data, w: usize, _h: usize, _cfg: &Config, p: &Palette) -> Vec { + let mut rows = vec![ + tc::seg( + &[ + (p.lbl.as_str(), " ── GITHUB COPILOT ── ".into()), + (p.dim.as_str(), "no reader in this build yet".into()), + ], + w - 1, + ), + String::new(), + ]; + for line in wrap_text( + "usage.py reads this agent; the Rust port does not yet. Nothing is \ + shown rather than a plausible zero.", + w.saturating_sub(4).max(20), + ) { + rows.push(tc::seg(&[(p.dim.as_str(), format!(" {}", line))], w - 1)); + } + rows +} diff --git a/rust/widgets/src/bin/usage/cursor.rs b/rust/widgets/src/bin/usage/cursor.rs new file mode 100644 index 0000000..ba88cbe --- /dev/null +++ b/rust/widgets/src/bin/usage/cursor.rs @@ -0,0 +1,59 @@ +// terminal-toys - small dependency-free terminal widgets +// Copyright (C) 2026 William Li +// +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU Affero General Public License as published +// by the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU Affero General Public License for more details. +// +// You should have received a copy of the GNU Affero General Public License +// along with this program. If not, see . + +//! Cursor: its edit-tracking database, and the lanes its Usage view shows. +//! +//! Not read yet. Every function here is honest about that rather than +//! returning a plausible zero, which is the rule the whole widget follows +//! for an agent that publishes nothing. + +use toys_core as tc; + +use crate::shared::*; +use crate::*; + +#[derive(Clone, Default)] +pub struct Data {} + +pub fn read(_caches: &mut Caches) -> Data { + Data::default() +} + +/// Every quota this agent publishes, for the summary screen. +pub fn lanes(_d: &Data) -> Vec { + Vec::new() +} + +pub fn tab(_d: &Data, w: usize, _h: usize, _cfg: &Config, p: &Palette) -> Vec { + let mut rows = vec![ + tc::seg( + &[ + (p.lbl.as_str(), " ── CURSOR ── ".into()), + (p.dim.as_str(), "no reader in this build yet".into()), + ], + w - 1, + ), + String::new(), + ]; + for line in wrap_text( + "usage.py reads this agent; the Rust port does not yet. Nothing is \ + shown rather than a plausible zero.", + w.saturating_sub(4).max(20), + ) { + rows.push(tc::seg(&[(p.dim.as_str(), format!(" {}", line))], w - 1)); + } + rows +} diff --git a/rust/widgets/src/bin/usage/grok.rs b/rust/widgets/src/bin/usage/grok.rs new file mode 100644 index 0000000..1cabe5f --- /dev/null +++ b/rust/widgets/src/bin/usage/grok.rs @@ -0,0 +1,59 @@ +// terminal-toys - small dependency-free terminal widgets +// Copyright (C) 2026 William Li +// +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU Affero General Public License as published +// by the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU Affero General Public License for more details. +// +// You should have received a copy of the GNU Affero General Public License +// along with this program. If not, see . + +//! Grok: its session transcripts, and the quota that arrives on the client log. +//! +//! Not read yet. Every function here is honest about that rather than +//! returning a plausible zero, which is the rule the whole widget follows +//! for an agent that publishes nothing. + +use toys_core as tc; + +use crate::shared::*; +use crate::*; + +#[derive(Clone, Default)] +pub struct Data {} + +pub fn read(_caches: &mut Caches) -> Data { + Data::default() +} + +/// Every quota this agent publishes, for the summary screen. +pub fn lanes(_d: &Data) -> Vec { + Vec::new() +} + +pub fn tab(_d: &Data, w: usize, _h: usize, _cfg: &Config, p: &Palette) -> Vec { + let mut rows = vec![ + tc::seg( + &[ + (p.lbl.as_str(), " ── GROK ── ".into()), + (p.dim.as_str(), "no reader in this build yet".into()), + ], + w - 1, + ), + String::new(), + ]; + for line in wrap_text( + "usage.py reads this agent; the Rust port does not yet. Nothing is \ + shown rather than a plausible zero.", + w.saturating_sub(4).max(20), + ) { + rows.push(tc::seg(&[(p.dim.as_str(), format!(" {}", line))], w - 1)); + } + rows +} diff --git a/rust/widgets/src/bin/usage/shared.rs b/rust/widgets/src/bin/usage/shared.rs new file mode 100644 index 0000000..dd5db55 --- /dev/null +++ b/rust/widgets/src/bin/usage/shared.rs @@ -0,0 +1,166 @@ +// terminal-toys - small dependency-free terminal widgets +// Copyright (C) 2026 William Li +// +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU Affero General Public License as published +// by the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU Affero General Public License for more details. +// +// You should have received a copy of the GNU Affero General Public License +// along with this program. If not, see . + +//! What every vendor reader needs: the caches, the file walking, and the +//! one shape the summary screen understands. +//! +//! This is a toolkit rather than a caller, so an entry nobody has +//! reached for yet is not dead code - it is the next reader's. +#![allow(dead_code)] + +use std::collections::HashMap; + +use crate::*; + +/// Readings held between passes, so a finished transcript is parsed once +/// and a quota endpoint is not asked six times a minute. +#[derive(Default)] +pub struct Caches { + /// path -> ((mtime, size), records keyed by uuid) + pub transcripts: HashMap)>, + /// key -> (when, value, ttl) + pub live: HashMap, f64)>, +} + +pub const LIVE_TTL: f64 = 120.0; +/// A plan does not change between refreshes; the windows do. +pub const PLAN_TTL: f64 = 3600.0; + +/// Hold a reading for a while, but never hold a failure that long. +/// +/// The pane redraws every thirty seconds; these windows move over hours. A +/// failure is cached too, so a dead endpoint is retried occasionally rather +/// than on every frame - but only ever for the short interval, never the +/// long one. One transient 429 should not blank a section for an hour. +pub fn cached(caches: &mut Caches, key: &str, ttl: f64, fetch: F) -> Option +where + F: FnOnce() -> Option, +{ + let at = now(); + if let Some((when, value, held)) = caches.live.get(key) { + if at - when < *held { + return value.clone(); + } + } + let value = fetch(); + let held = if value.is_some() { ttl } else { ttl.min(LIVE_TTL) }; + caches.live.insert(key.to_string(), (at, value.clone(), held)); + value +} + +pub fn read_json(path: &str) -> Option { + serde_json::from_str(&std::fs::read_to_string(path).ok()?).ok() +} + +/// Every file under a directory whose name ends in `suffix`. +/// +/// Recursive on purpose: several agents nest their transcripts two or three +/// levels down, and globbing one level deep silently missed most of them. +pub fn walk(dir: &str, suffix: &str, out: &mut Vec) { + let Ok(entries) = std::fs::read_dir(dir) else { + return; + }; + for entry in entries.flatten() { + let path = entry.path(); + let name = path.to_string_lossy().to_string(); + match entry.file_type() { + Ok(t) if t.is_dir() => walk(&name, suffix, out), + Ok(t) if t.is_file() && name.ends_with(suffix) => out.push(name), + _ => {} + } + } +} + +/// Newest first, by modification time. +pub fn newest_first(paths: Vec) -> Vec { + use std::os::unix::fs::MetadataExt; + let mut with_time: Vec<(u64, String)> = paths + .into_iter() + .filter_map(|path| { + let meta = std::fs::metadata(&path).ok()?; + Some((meta.mtime() as u64, path)) + }) + .collect(); + with_time.sort_by(|a, b| b.0.cmp(&a.0)); + with_time.into_iter().map(|(_, p)| p).collect() +} + +/// The last `size` bytes of a file, as lines. +/// +/// A rollout carries its running total on every token_count event, so the +/// newest one is all that is needed - reading thirty megabytes per refresh +/// to learn a number that is repeated at the end would be daft. +pub fn tail_lines(path: &str, size: u64) -> Vec { + use std::io::{Read, Seek, SeekFrom}; + let Ok(mut f) = std::fs::File::open(path) else { + return Vec::new(); + }; + let end = f.seek(SeekFrom::End(0)).unwrap_or(0); + if f.seek(SeekFrom::Start(end.saturating_sub(size))).is_err() { + return Vec::new(); + } + let mut buf = Vec::new(); + if f.read_to_end(&mut buf).is_err() { + return Vec::new(); + } + String::from_utf8_lossy(&buf) + .split('\n') + .map(String::from) + .collect() +} + +/// Enough to reach the last running total in a rollout. +pub const TAIL: u64 = 256 * 1024; + +/// One quota an agent publishes, flattened to the four numbers the summary +/// screen can compare across agents. +/// +/// Read as data rather than borrowed from each tab's renderer, because +/// those render six different shapes - Cursor's coloured lanes, +/// Antigravity's groups, Codex's per-feature windows - and only these are +/// common to all of them. +#[derive(Clone, Debug, Default)] +pub struct Lane { + pub label: String, + pub pct: f64, + /// How long the window is, where the agent says. + pub window_secs: Option, + /// When it resets, as epoch seconds. + pub reset: Option, + /// True when this came from a cache rather than from the agent just + /// now. A number nobody labelled as old reads as current. + pub stale: bool, +} + +/// An HTTPS GET carrying a bearer token, returning parsed JSON. +/// +/// The token goes to curl on its standard input, never in its arguments: +/// /proc//cmdline is world-readable, so an argument is a secret handed +/// to every user on the box for as long as the request lasts. +pub fn get_json(url: &str, headers: &[(&str, &str)], seconds: u64) -> Option { + serde_json::from_str(&tc::get(url, headers, seconds).ok()?).ok() +} + +/// An HTTPS POST of a JSON body carrying a bearer token. +pub fn post_json( + url: &str, + headers: &[(&str, &str)], + body: &str, + seconds: u64, +) -> Option { + let (text, _) = tc::post_json(url, headers, body, seconds).ok()?; + serde_json::from_str(&text).ok() +} diff --git a/rust/widgets/src/bin/usage/vendors.rs b/rust/widgets/src/bin/usage/vendors.rs index 3a66627..0c7ba18 100644 --- a/rust/widgets/src/bin/usage/vendors.rs +++ b/rust/widgets/src/bin/usage/vendors.rs @@ -14,1020 +14,216 @@ // You should have received a copy of the GNU Affero General Public License // along with this program. If not, see . -//! One reader and one tab per agent. +//! Which reader answers for which tab, and the one screen that spans them. //! -//! They do not agree on what usage even means, so each keeps its own shape -//! rather than being flattened into a schema none of them publish. An agent -//! with no reader here says so on its tab; a plausible-looking zero would -//! be worse than an empty one. +//! Each agent keeps its own file and its own shape, because they do not +//! agree on what usage even means. Only the quota lanes are common, and +//! only because the summary screen has to compare them. use std::collections::HashMap; -use chrono::{Datelike, Duration as Days, Local, NaiveDate, TimeZone}; use toys_core as tc; -use super::*; - -/// What Claude Code has recorded, plus what is left of the limits. -#[derive(Clone, Default)] -struct Claude { - ok: bool, - why: String, - stats: serde_json::Value, - /// The live or cached rate-limit reading, which is account-wide rather - /// than about this machine. - quota: Option, - quota_live: bool, - quota_at: f64, - quota_plan: String, - profile: Option, - /// Output tokens per second, sorted, and how many transcripts it came - /// from. - rates: Vec, - sampled: usize, - /// day -> model -> tokens by priced kind. - daily: HashMap>, -} +use crate::shared::*; +use crate::*; #[derive(Clone, Default)] pub struct State { - claude: Claude, + pub claude: crate::claude::Data, + pub codex: crate::codex::Data, + pub cursor: crate::cursor::Data, + pub grok: crate::grok::Data, + pub copilot: crate::copilot::Data, + pub antigravity: crate::antigravity::Data, pub installed: HashMap, pub fetched: f64, pub err: String, } -/// Readings held between passes, so a finished transcript is parsed once. -#[derive(Default)] -pub struct Caches { - /// path -> ((mtime, size), records keyed by uuid) - transcripts: HashMap)>, - /// key -> (when, value, ttl) - live: HashMap, f64)>, -} - -const LIVE_TTL: f64 = 120.0; -/// A plan does not change between refreshes; the windows do. -const PLAN_TTL: f64 = 3600.0; -/// Newest transcripts to sample for a rate. -const RATE_FILES: usize = 3; -/// Seconds; below this the timestamps are not a turn. -const MIN_GAP: f64 = 1.0; - -/// Hold a reading for a while, but never hold a failure that long. -/// -/// The pane redraws every thirty seconds; these windows move over hours. A -/// failure is cached too, so a dead endpoint is retried occasionally rather -/// than on every frame - but only ever for the short interval, never the -/// long one. One transient 429 should not blank a section for an hour. -fn cached(caches: &mut Caches, key: &str, ttl: f64, fetch: F) -> Option -where - F: FnOnce() -> Option, -{ - let at = now(); - if let Some((when, value, held)) = caches.live.get(key) { - if at - when < *held { - return value.clone(); - } - } - let value = fetch(); - let held = if value.is_some() { ttl } else { ttl.min(LIVE_TTL) }; - caches.live.insert(key.to_string(), (at, value.clone(), held)); - value -} - -fn read_json(path: &str) -> Option { - serde_json::from_str(&std::fs::read_to_string(path).ok()?).ok() -} - -/// The OAuth token Claude Code already holds. -/// -/// It goes only to Anthropic, is never printed, and an expired one is not -/// used at all: the refresh token sits beside it, but spending it would -/// race Claude Code's own credential handling for a number that has a local -/// cache anyway. -fn claude_token() -> Option<(String, String)> { - let creds = read_json(&under_home(".claude/.credentials.json"))?; - let o = &creds["claudeAiOauth"]; - let tok = text(o, "accessToken"); - if tok.is_empty() || num(o, "expiresAt") / 1000.0 <= now() { - return None; - } - Some((tok, text(o, "subscriptionType"))) -} - -fn claude_get(url: &str, tok: &str) -> Option { - let body = tc::get( - url, - &[ - ("Authorization", &format!("Bearer {}", tok)), - ("User-Agent", "terminal-toys"), - ], - 20, - ) - .ok()?; - serde_json::from_str(&body).ok() -} - -/// What Claude Code last fetched, for when the live call cannot run. -/// -/// It is a cache with a timestamp, so it is shown with its age - and a -/// window whose reset has already gone by is said to have passed rather -/// than counted down to, because a stale five-hour window describes a -/// period that has ended. -fn claude_stale() -> Option<(serde_json::Value, f64)> { - let config = read_json(&under_home(".claude.json"))?; - let c = &config["cachedUsageUtilization"]; - let u = c["utilization"].clone(); - if u.is_null() { - return None; - } - Some((u, num(c, "fetchedAtMs") / 1000.0)) -} - -/// Token counts from one transcript usage block, by priced kind. -/// -/// A block's top-level numbers can all be zero while its `iterations` carry -/// the real figures, so the iterations win where they exist. Cache writes -/// are split by duration because they are priced differently, and the flat -/// cache_creation_input_tokens is only used when that split is absent. -fn usage_kinds(u: &serde_json::Value) -> Tokens { - let mut out = empty_tokens(); - let empty = vec![u.clone()]; - let blocks: Vec = match u["iterations"].as_array() { - Some(list) if !list.is_empty() => list.clone(), - _ => empty, - }; - for x in &blocks { - *out.get_mut("input").unwrap() += num(x, "input_tokens"); - *out.get_mut("output").unwrap() += num(x, "output_tokens"); - *out.get_mut("cache_read").unwrap() += num(x, "cache_read_input_tokens"); - let split = &x["cache_creation"]; - if split.is_object() { - *out.get_mut("cache_write").unwrap() += num(split, "ephemeral_5m_input_tokens"); - *out.get_mut("cache_write_1h").unwrap() += num(split, "ephemeral_1h_input_tokens"); - } else { - *out.get_mut("cache_write").unwrap() += num(x, "cache_creation_input_tokens"); - } - } - out -} - -/// Every file under a directory whose name ends in `suffix`. -fn walk(dir: &str, suffix: &str, out: &mut Vec) { - let Ok(entries) = std::fs::read_dir(dir) else { - return; - }; - for entry in entries.flatten() { - let path = entry.path(); - let name = path.to_string_lossy().to_string(); - match entry.file_type() { - Ok(t) if t.is_dir() => walk(&name, suffix, out), - Ok(t) if t.is_file() && name.ends_with(suffix) => out.push(name), - _ => {} - } - } -} - -/// Per-record token counts from one transcript, keyed by record uuid. -/// -/// Keyed rather than summed because the same message appears in more than -/// one file: resuming or forking a session replays its history into the new -/// transcript, and subagent turns are written twice over. Left raw that -/// inflated one model by 29% against Claude Code's own totals. -/// -/// Cached on (mtime, size): a finished transcript never changes, so each is -/// parsed once. -fn scan_transcript( - caches: &mut Caches, - path: &str, -) -> HashMap { - let Ok(meta) = std::fs::metadata(path) else { - return HashMap::new(); - }; - use std::os::unix::fs::MetadataExt; - let key = (meta.mtime() as u64, meta.size()); - if let Some((had, records)) = caches.transcripts.get(path) { - if *had == key { - return records.clone(); - } - } - let mut records = HashMap::new(); - let Ok(body) = std::fs::read_to_string(path) else { - return records; - }; - for line in body.lines() { - if !line.contains("\"usage\"") { - continue; - } - let Ok(r) = serde_json::from_str::(line) else { - continue; - }; - let msg = &r["message"]; - let u = &msg["usage"]; - let (model, uid, stamp) = (text(msg, "model"), text(&r, "uuid"), text(&r, "timestamp")); - if u.is_null() || model.is_empty() || uid.is_empty() || stamp.is_empty() { - continue; - } - let Some(when) = iso_epoch(&stamp) else { - continue; - }; - let got = usage_kinds(u); - if total_tokens(&got) <= 0.0 { - continue; - } - let day = Local - .timestamp_opt(when as i64, 0) - .single() - .map(|d| d.format("%Y-%m-%d").to_string()) - .unwrap_or_default(); - records.insert(uid, (day, model, got)); - } - caches - .transcripts - .insert(path.to_string(), (key, records.clone())); - records -} - -/// Every transcript's per-day, per-model tokens, de-duplicated. -/// -/// stats-cache.json has dailyModelTokens, but only one total per model per -/// day - and input, output and the two cache kinds differ in price by up to -/// fifty times, so a total cannot be costed. The transcripts carry the -/// split, which is why the money comes from here and not from the cache. -fn claude_daily(caches: &mut Caches) -> HashMap> { - let mut files = Vec::new(); - // Recursive on purpose: subagent transcripts live a further two levels - // down, and that is where most of the smaller models actually run. - walk(&under_home(".claude/projects"), ".jsonl", &mut files); - let mut seen: HashMap = HashMap::new(); - for path in &files { - seen.extend(scan_transcript(caches, path)); - } - let mut merged: HashMap> = HashMap::new(); - for (day, model, tokens) in seen.into_values() { - let bucket = merged - .entry(day) - .or_default() - .entry(model) - .or_insert_with(empty_tokens); - for kind in RATE_KINDS { - *bucket.get_mut(*kind).unwrap() += tokens.get(*kind).copied().unwrap_or(0.0); - } - } - merged -} - -/// Per-model token totals over the last N days (1 = today only). -fn window_models( - daily: &HashMap>, - days: i64, -) -> Vec<(String, Tokens)> { - let first = (Local::now().date_naive() - Days::days(days - 1)) - .format("%Y-%m-%d") - .to_string(); - let mut out: HashMap = HashMap::new(); - for (day, models) in daily { - if *day < first { - continue; - } - for (model, tokens) in models { - let bucket = out.entry(model.clone()).or_insert_with(empty_tokens); - for kind in RATE_KINDS { - *bucket.get_mut(*kind).unwrap() += tokens.get(*kind).copied().unwrap_or(0.0); - } - } - } - let mut list: Vec<(String, Tokens)> = out.into_iter().collect(); - list.sort_by(|a, b| a.0.cmp(&b.0)); - list -} - -/// The last `size` bytes of a file, as lines. -fn tail_lines(path: &str, size: u64) -> Vec { - use std::io::{Read, Seek, SeekFrom}; - let Ok(mut f) = std::fs::File::open(path) else { - return Vec::new(); - }; - let end = f.seek(SeekFrom::End(0)).unwrap_or(0); - if f.seek(SeekFrom::Start(end.saturating_sub(size))).is_err() { - return Vec::new(); - } - let mut buf = Vec::new(); - if f.read_to_end(&mut buf).is_err() { - return Vec::new(); - } - String::from_utf8_lossy(&buf) - .split('\n') - .map(String::from) - .collect() -} - -/// Output tokens per second, from the newest transcripts. -/// -/// A turn is a `user` record followed by an `assistant` one, and the rate is -/// that assistant's output tokens over the gap between them. Measuring from -/// any previous record instead inflates it wildly - two assistant records -/// can be milliseconds apart while the second reports a whole turn's output. -/// -/// The median is what gets shown: it barely moves whichever way the outliers -/// are trimmed, which is the reason to trust it, while the maximum moves by -/// a factor of twenty on the same data, which is the reason not to show one. -fn claude_rates() -> (Vec, usize) { - let mut files = Vec::new(); - walk(&under_home(".claude/projects"), ".jsonl", &mut files); - let mut with_time: Vec<(u64, String)> = files - .into_iter() - .filter_map(|path| { - use std::os::unix::fs::MetadataExt; - let meta = std::fs::metadata(&path).ok()?; - Some((meta.mtime() as u64, path)) - }) - .collect(); - with_time.sort_by(|a, b| b.0.cmp(&a.0)); - let mut out: Vec = Vec::new(); - let mut sampled = 0usize; - for (_, path) in with_time.iter().take(RATE_FILES) { - sampled += 1; - let (mut prev, mut prev_type): (Option, String) = (None, String::new()); - for line in tail_lines(path, 4 * 1024 * 1024) { - if !line.contains("\"timestamp\"") { - continue; - } - let Ok(d) = serde_json::from_str::(&line) else { - continue; - }; - let (stamp, typ) = (text(&d, "timestamp"), text(&d, "type")); - let at = iso_epoch(&stamp); - if typ == "assistant" - && at.is_some() - && prev.is_some() - && prev_type == "user" - && !d["isAbortedMidStream"].as_bool().unwrap_or(false) - { - let tok = num(&d["message"]["usage"], "output_tokens"); - if tok > 0.0 { - let gap = at.unwrap() - prev.unwrap(); - if (MIN_GAP..300.0).contains(&gap) { - out.push(tok / gap); - } - } - } - if let Some(at) = at { - prev = Some(at); - prev_type = typ; - } - } - } - out.sort_by(f64::total_cmp); - (out, sampled) -} - -fn read_claude(caches: &mut Caches) -> Claude { - let mut claude = Claude::default(); - let live = cached(caches, "claude", LIVE_TTL, || { - let (tok, plan) = claude_token()?; - let u = claude_get("https://api.anthropic.com/api/oauth/usage", &tok)?; - Some(serde_json::json!({ "u": u, "at": now(), "plan": plan })) - }); - match live { - Some(got) => { - claude.quota = Some(got["u"].clone()); - claude.quota_live = true; - claude.quota_at = num(&got, "at"); - claude.quota_plan = text(&got, "plan"); - } - None => { - if let Some((u, at)) = claude_stale() { - claude.quota = Some(u); - claude.quota_live = false; - claude.quota_at = at; - } - } - } - claude.profile = cached(caches, "claude-plan", PLAN_TTL, || { - let (tok, plan) = claude_token()?; - let mut d = claude_get("https://api.anthropic.com/api/oauth/profile", &tok)?; - d["_plan"] = serde_json::Value::String(plan); - Some(d) - }); - if claude.profile.is_none() { - // The profile endpoint is richer, but the credentials file needs no - // network and is always there, so the section degrades to two true - // lines instead of vanishing. - if let Some(creds) = read_json(&under_home(".claude/.credentials.json")) { - let o = &creds["claudeAiOauth"]; - let plan = text(o, "subscriptionType"); - if !plan.is_empty() { - claude.profile = Some(serde_json::json!({ - "_plan": plan, - "_local": true, - "organization": { "rate_limit_tier": text(o, "rateLimitTier") }, - })); - } - } - } - match read_json(&under_home(".claude/stats-cache.json")) { - Some(stats) => { - claude.ok = true; - claude.stats = stats; - let (rates, sampled) = claude_rates(); - claude.rates = rates; - claude.sampled = sampled; - claude.daily = claude_daily(caches); - } - None => claude.why = "no stats cache".into(), - } - claude -} - pub fn read_all(caches: &mut Caches) -> State { State { - claude: read_claude(caches), + claude: crate::claude::read(caches), + codex: crate::codex::read(caches), + cursor: crate::cursor::read(caches), + grok: crate::grok::read(caches), + copilot: crate::copilot::read(caches), + antigravity: crate::antigravity::read(caches), installed: detect_agents(), fetched: 0.0, err: String::new(), } } -/// Where a Claude limit belongs in the list, shortest leash first. -/// -/// The server returns them in no order worth keeping. Read top to bottom -/// they should widen: the five-hour session is what stops you this -/// afternoon, the weekly total is what stops you this week, and a -/// model-scoped weekly limit stops only one model. -fn claude_lane_rank(limit: &serde_json::Value) -> usize { - if text(limit, "kind") == "session" { - return 0; - } - if text(&limit["scope"]["model"], "display_name").is_empty() { - 1 - } else { - 2 - } -} - -/// The scope note, shortened before it can push a reset off the line. -/// -/// "not this machine" is the point of the sentence, but it is also sixteen -/// characters, and seg() clips whatever runs past the pane. Losing the -/// clause leaves a shorter true line; losing the end of "resets in 15d" -/// leaves "resets in 1", which is a different and wrong number. -fn scope_phrase(w: usize, used: usize) -> &'static str { - let full = " · account-wide, not this machine "; - if used + full.len() <= w - 1 { - full - } else { - " · account-wide " +/// Every quota an agent publishes, in the one shape they can be compared in. +fn lanes_of(name: &str, s: &State) -> Vec { + match name { + "claude" => crate::claude::lanes(&s.claude), + "codex" => crate::codex::lanes(&s.codex), + "cursor" => crate::cursor::lanes(&s.cursor), + "grok" => crate::grok::lanes(&s.grok), + "copilot" => crate::copilot::lanes(&s.copilot), + "antigravity" => crate::antigravity::lanes(&s.antigravity), + _ => Vec::new(), } } -/// The windows Claude Code's own /usage shows. +/// Every agent's quotas on one screen, worst first. /// -/// Read from limits[], which is the server's own curated list: the rest of -/// the response carries a dozen null pools that /usage does not render -/// either. Each entry names itself, so a model-scoped weekly limit arrives -/// labelled without this having to know the name. -fn claude_quota(c: &Claude, w: usize, p: &Palette) -> Vec { - let Some(u) = c.quota.as_ref() else { - return Vec::new(); - }; - let mut lanes: Vec<&serde_json::Value> = u["limits"] - .as_array() - .into_iter() - .flatten() - .filter(|l| !l["percent"].is_null()) - .collect(); - if lanes.is_empty() { - return Vec::new(); - } - lanes.sort_by_key(|l| claude_lane_rank(l)); - let src = if c.quota_live { - "live".to_string() - } else { - format!("cached {} ago", ago(c.quota_at)) - }; - let hue = agent_hue("claude"); - let mut rows = vec![tc::seg( - &[ - (p.lbl.as_str(), " ── QUOTA ── ".into()), - ( - if c.quota_live { p.ok.as_str() } else { p.warn.as_str() }, - src.clone(), - ), - ( - p.dim.as_str(), - scope_phrase(w, 13 + src.len() + c.quota_plan.len()).to_string(), - ), - (p.dim.as_str(), c.quota_plan.clone()), - ], - w - 1, - )]; - - let label_of = |l: &serde_json::Value| -> String { - let scope = text(&l["scope"]["model"], "display_name"); - let group = text(l, "group"); - let name = if !scope.is_empty() { - scope - } else if text(l, "kind") == "weekly_all" { - "overall".to_string() - } else if !group.is_empty() { - group.clone() +/// Not a concatenation of the other tabs: those answer "how am I using this +/// agent", and this answers the only question that spans them - what runs +/// out first. An agent that publishes no quota is named at the bottom +/// instead of being silently missing. +fn summary_tab(s: &State, w: usize, p: &Palette) -> Vec { + let mut groups: Vec<(&str, Vec)> = Vec::new(); + let mut quiet: Vec<&str> = Vec::new(); + for name in ORDER { + let got = lanes_of(name, s); + if got.is_empty() { + quiet.push(name); } else { - match text(l, "kind") { - s if s.is_empty() => "?".into(), - s => s, - } - }; - let window = match group.as_str() { - "session" => "5h", - "weekly" => "7d", - _ => "", - }; - format!("{} {}", name, window).trim().to_string() - }; - let texts: Vec = lanes.iter().map(|l| label_of(l)).collect(); - let label_w = texts.iter().map(|t| t.chars().count()).max().unwrap_or(9).max(9); - for (l, label) in lanes.iter().zip(&texts) { - let pct = num(l, "percent"); - let used = (pct / 100.0).clamp(0.0, 1.0); - let reset = iso_epoch(&text(l, "resets_at")); - let when = match reset { - None => String::new(), - Some(ts) => { - let left = ts - now(); - if left > 0.0 { - format!("resets in {}", left_span(left)) - } else if c.quota_live { - "resetting".into() - } else { - "already reset".into() - } - } - }; - let sev = text(l, "severity").to_lowercase(); - let window = CLAUDE_WINDOW_SECS - .iter() - .find(|(g, _)| *g == text(l, "group")) - .map(|(_, s)| *s); - let cushion = lead(pct, window, reset); - let (pace_colour, pace_txt) = pace_cell(cushion, p); - // is_active marks the limit currently doing the binding - the one - // that will stop you first - so it is the one worth reading brightly. - let mut line: Vec<(String, String)> = vec![( - if l["is_active"].as_bool().unwrap_or(false) { - p.txt.clone() - } else { - p.dim.clone() - }, - format!(" {} ", tc::pad(label, label_w)), - )]; - line.extend(paced_bar( - used, - elapsed_of(window, reset), - w.saturating_sub(35 + label_w).max(8), - hue, - p, - )); - line.push((pct_colour(pct, hue, p), pct_text(pct))); - line.push((pace_colour, pace_txt)); - line.push(( - if sev.is_empty() || sev == "normal" { p.dim.clone() } else { p.bad.clone() }, - if sev.is_empty() || sev == "normal" { - format!(" {}", when) - } else { - format!(" {} · {}", sev, when) - }, - )); - let refs: Vec<(&str, String)> = line.iter().map(|(c, t)| (c.as_str(), t.clone())).collect(); - rows.push(tc::seg(&refs, w - 1)); - } - let extra = &u["extra_usage"]; - let spend = &u["spend"]; - if extra["is_enabled"].as_bool().unwrap_or(false) && !spend["limit"].is_null() { - let money = |m: &serde_json::Value| -> String { - format!( - "{:.2}", - num(m, "amount_minor") / 10f64.powf(m["exponent"].as_f64().unwrap_or(2.0)) - ) - }; - rows.push(tc::seg( - &[ - (p.dim.as_str(), " extra usage ".into()), - (p.txt.as_str(), money(&spend["used"])), - (p.dim.as_str(), " of ".into()), - (p.txt.as_str(), money(&spend["limit"])), - (p.dim.as_str(), format!(" {}", text(&spend["limit"], "currency"))), - (p.dim.as_str(), " monthly".into()), - ], - w - 1, - )); - } - rows.push(String::new()); - rows -} - -/// How far behind today the stats cache's own reckoning is. -/// -/// `room` is the columns actually left on the line, measured by the caller -/// rather than guessed from the pane width - the text before this varies, -/// so a width threshold clipped at some widths and not others. -fn stats_lag(stats: &serde_json::Value, room: i64) -> String { - let last = text(stats, "lastComputedDate"); - let Ok(when) = NaiveDate::parse_from_str(&last, "%Y-%m-%d") else { - return String::new(); - }; - let days = (Local::now().date_naive() - when).num_days(); - if days <= 0 { - return String::new(); - } - let month = MONTHS[when.month0() as usize]; - for candidate in [ - format!(" cache is {}d behind, to {} {}", days, month, when.day()), - format!(" cache {}d behind", days), - format!(" -{}d", days), - ] { - if candidate.len() as i64 <= room { - return candidate; - } - } - String::new() -} - -fn claude_plan_rows(prof: &serde_json::Value, w: usize, p: &Palette) -> Vec { - let org = &prof["organization"]; - let mut pairs: Vec<(String, String)> = Vec::new(); - let created = text(org, "subscription_created_at"); - if let (Some(since), day) = (iso_epoch(&created), iso_day(&created)) { - if !day.is_empty() { - pairs.push(("member since".into(), format!("{} · {} ago", day, ago(since)))); + groups.push((name, got)); } } - for (label, key) in [ - ("status", "subscription_status"), - ("rate limit tier", "rate_limit_tier"), - ] { - let value = text(org, key); - if !value.is_empty() { - pairs.push((label.into(), value)); - } - } - let billing = text(org, "billing_type"); - if !billing.is_empty() { - pairs.push(("billing".into(), billing.replace('_', " "))); - } - let headline = match text(prof, "_plan") { - s if !s.is_empty() => s, - _ => text(org, "organization_type"), - }; - plan_rows( - &headline, - &pairs, - w, - if prof["_local"].as_bool().unwrap_or(false) { - "from credentials" - } else { - "" - }, - None, - "", - p, - ) -} - -fn claude_metered(c: &Claude, w: usize, cfg: &Config, p: &Palette) -> Vec { - metered_rows( - &[ - ("today".to_string(), window_models(&c.daily, 1)), - ("30 days".to_string(), window_models(&c.daily, 30)), - ], - w, - "", - "claude", - "this machine", - "Counted from transcripts, which are written where the agent ran. \ - Claude used on another machine, or on claude.ai, is not in here.", - cfg, - p, - ) -} - -fn claude_tab(c: &Claude, w: usize, p: &Palette) -> Vec { - let mut rows = claude_quota(c, w, p); - if !c.ok { - rows.extend(no_local( - &format!("No stats cache yet ({}).", c.why), - run_hint("claude"), - w, - p, - )); - return rows; + if groups.is_empty() { + return no_local("No agent is publishing a quota right now.", "", w, p); } - let d = &c.stats; - let mu = &d["modelUsage"]; - let sum_over = |key: &str| -> f64 { - mu.as_object() - .into_iter() - .flatten() - .map(|(_, v)| num(v, key)) - .sum() - }; - let (in_tok, out_tok) = (sum_over("inputTokens"), sum_over("outputTokens")); - let (cache_r, cache_w) = ( - sum_over("cacheReadInputTokens"), - sum_over("cacheCreationInputTokens"), - ); - - // The calendar is computed first: its streaks and active-day counts - // belong in the summary above it, not only beside the calendar. - let mut totals: HashMap = HashMap::new(); - for entry in d["dailyModelTokens"].as_array().into_iter().flatten() { - let day = text(entry, "date"); - let Ok(at) = NaiveDate::parse_from_str(&day, "%Y-%m-%d") else { - continue; - }; - let total: f64 = entry["tokensByModel"] - .as_object() - .into_iter() - .flatten() - .map(|(_, v)| v.as_f64().unwrap_or(0.0)) - .sum(); - totals.insert(at, total); - } - let peak = totals.values().cloned().fold(0.0f64, f64::max); - let cal = day_calendar(&totals, w, HEAT_STEPS, None, p); - - let fav = mu - .as_object() - .into_iter() - .flatten() - .max_by(|a, b| num(a.1, "outputTokens").total_cmp(&num(b.1, "outputTokens"))) - .map(|(k, _)| k.replace("claude-", "")) - .unwrap_or_else(|| "—".into()); - let all_tokens = in_tok + out_tok + cache_r + cache_w; - rows.push(tc::seg( - &[ - (p.lbl.as_str(), " ── SUMMARY ── ".into()), - ( - p.dim.as_str(), - format!( - "all time · since {}", - text(d, "firstSessionDate").chars().take(10).collect::() - ), - ), - ], - w - 1, - )); - let facts = cal.as_ref(); - let best_txt = facts - .and_then(|c| c.best) - .map(|b| format!("{} {}", MONTHS[b.month0() as usize], b.day())) - .unwrap_or_else(|| "—".into()); - let pairs: Vec<(&str, String, &str, &str, String, &str)> = vec![ - ( - "Favorite model", - fav, - p.agent.as_str(), - "Total tokens", - big_num(all_tokens), - p.agent.as_str(), - ), - ( - "Sessions", - format!("{}", num(d, "totalSessions") as i64), - p.txt.as_str(), - "Longest session", - span_ms(num(&d["longestSession"], "duration")), - p.txt.as_str(), - ), - ( - "Active days", - facts - .map(|c| format!("{}/{}", c.active, c.span)) - .unwrap_or_else(|| "—".into()), - p.txt.as_str(), - "Longest streak", - facts - .map(|c| format!("{} days", c.longest)) - .unwrap_or_else(|| "—".into()), - p.txt.as_str(), - ), - ( - "Most active day", - best_txt, - p.txt.as_str(), - "Current streak", - facts - .map(|c| format!("{} days", c.current)) - .unwrap_or_else(|| "—".into()), - if facts.is_some_and(|c| c.current > 0) { p.ok.as_str() } else { p.dim.as_str() }, - ), - ]; - let lw = pairs + // Grouped by provider, but the groups are ordered by their worst lane: + // the structure says who owns what, the ordering still answers which + // one runs out first. + groups.sort_by(|a, b| { + let worst = |g: &Vec| g.iter().map(|l| l.pct).fold(0.0f64, f64::max); + worst(&b.1).total_cmp(&worst(&a.1)) + }); + let total: usize = groups.iter().map(|(_, g)| g.len()).sum(); + let label_w = groups .iter() - .map(|(a, _, _, c, _, _)| a.len().max(c.len())) + .flat_map(|(_, g)| g.iter()) + .map(|l| l.label.chars().count()) .max() - .unwrap_or(10); - let half = (w - 3) / 2; - let vw = half.saturating_sub(lw + 2).max(6); - for (a, b, bc, c, e, ec) in &pairs { - rows.push(tc::seg( - &[ - (p.dim.as_str(), format!(" {} ", tc::pad(a, lw))), - (bc, tc::pad(b, vw)), - (p.dim.as_str(), format!(" {} ", tc::pad(c, lw))), - (ec, tc::pad(e, vw)), - ], - w - 1, - )); + .unwrap_or(8) + .min(16); + let mut head = format!("{} limits across {} agents", total, groups.len()); + // Sized against the suffix actually being added, so changing the + // wording cannot quietly start clipping the line. + let suffix = " · ranked by usage"; + if 14 + head.len() + suffix.len() <= w - 1 { + head += suffix; } - rows.push(tc::seg( - &[ - (p.dim.as_str(), " Input ".into()), - (p.txt.as_str(), big_num(in_tok)), - (p.dim.as_str(), " · Output ".into()), - (p.txt.as_str(), big_num(out_tok)), - (p.dim.as_str(), " · Cache read ".into()), - (p.txt.as_str(), big_num(cache_r)), - (p.dim.as_str(), " · Cache written ".into()), - (p.txt.as_str(), big_num(cache_w)), - ], - w - 1, - )); - - // Which model did the work. - rows.push(String::new()); - let mut ranked: Vec<(String, f64)> = mu - .as_object() - .into_iter() - .flatten() - .map(|(k, v)| (k.clone(), num(v, "outputTokens"))) - .filter(|(_, tok)| *tok > 0.0) - .collect(); - ranked.sort_by(|a, b| b.1.total_cmp(&a.1)); - rows.push(tc::seg( + let mut rows = vec![tc::seg( &[ - (p.lbl.as_str(), " ── BY MODEL ── ".into()), - (p.dim.as_str(), "output tokens".into()), + (p.lbl.as_str(), " ── QUOTAS ── ".into()), + (p.dim.as_str(), head), ], w - 1, - )); - if let Some((_, top)) = ranked.first() { - let top = top.max(1.0); - for (name, tok) in ranked.iter().take(5) { - let bar = tc::meter(tok / top, w.saturating_sub(34).max(6)); - let filled = bar.chars().filter(|c| *c == '█').count(); - rows.push(tc::seg( - &[ - ( - p.txt.as_str(), - format!(" {}", tc::pad(&name.replace("claude-", ""), 20)), - ), - (p.agent.as_str(), format!("{:>7} ", big_num(*tok))), - (p.agent.as_str(), bar.chars().take(filled).collect::()), - (p.grid.as_str(), bar.chars().skip(filled).collect::()), - ], - w - 1, - )); + )]; + // 2 lead + label + 1 + pct(6) + pace(6). The reset needs 16 more and is + // the first thing dropped, being the only part a reader can infer from + // the bar beside it - but a stale marker is not droppable, since a + // number nobody labelled as old reads as current. + let fixed = 15 + label_w; + let show_reset = (w - 1).saturating_sub(fixed + 8) >= 16; + let any_stale = groups.iter().flat_map(|(_, g)| g.iter()).any(|l| l.stale); + let tail = if show_reset { + 16 + } else if any_stale { + 8 + } else { + 0 + }; + let bar_room = (w - 1).saturating_sub(fixed + tail).max(8); + for (i, (name, lanes)) in groups.iter().enumerate() { + if i > 0 { + rows.push(String::new()); } - } - - // Messages per day, straight from the file. - let daily: Vec<&serde_json::Value> = d["dailyActivity"].as_array().map(|a| a.iter().collect()).unwrap_or_default(); - if !daily.is_empty() { - rows.push(String::new()); - let counts: Vec = daily.iter().map(|x| num(x, "messageCount")).collect(); - let msg_peak = counts.iter().cloned().fold(0.0f64, f64::max).max(1.0); - // Both charts on this tab come from stats-cache.json, which Claude - // Code recomputes on its own schedule. Unlabelled, that gap reads as - // idle days rather than as days the cache has not caught up with. - let head = " ── MESSAGES / DAY ── "; - let tail = format!("{}d · peak {}", daily.len(), msg_peak as i64); + let hue = agent_hue(name); rows.push(tc::seg( - &[ - (p.lbl.as_str(), head.into()), - (p.dim.as_str(), tail.clone()), - ( - p.warn.as_str(), - stats_lag(d, w as i64 - 1 - head.len() as i64 - tail.len() as i64), - ), - ], + &[( + &hue.map(|(r, g, b)| tc::rgb(r, g, b)).unwrap_or_else(|| p.txt.clone()), + format!(" {}", name.to_uppercase()), + )], w - 1, )); - let avail = w.saturating_sub(3).max(10); - let widths = tc::spread(counts.len(), avail); - let mut cols: Vec<(f64, String)> = Vec::new(); - for (c, wide) in counts.iter().zip(&widths) { - cols.extend(std::iter::repeat_n((*c, p.agent.clone()), *wide)); + // Ranked by usage, except where the lanes nest. Claude's five-hour + // window sits inside its weekly one, which contains the + // model-scoped limit in turn, and reading them widest-last says + // more than reading them by percentage - which also reorders itself + // as the numbers move, so the bar under the cursor is not the one + // that was there a refresh ago. + let mut inner = lanes.clone(); + if *name != "claude" { + inner.sort_by(|a, b| b.pct.total_cmp(&a.pct)); } - for line in tc::vbars(&cols, 3, 0.0) { - let mut parts: Vec<(&str, String)> = vec![(tc::RST, " ".into())]; - for (colour, ch) in &line { - parts.push((colour.as_str(), ch.clone())); - } - rows.push(tc::seg(&parts, w - 1)); + for lane in &inner { + let used = (lane.pct / 100.0).clamp(0.0, 1.0); + let (when, tone) = if lane.stale { + (" cached".to_string(), p.warn.clone()) + } else if show_reset { + match lane.reset { + Some(reset) if reset - now() > 0.0 => { + (format!(" {}", left_span(reset - now())), p.dim.clone()) + } + Some(_) => (" resetting".to_string(), p.dim.clone()), + None => (String::new(), p.dim.clone()), + } + } else { + (String::new(), p.dim.clone()) + }; + let cushion = lead(lane.pct, lane.window_secs, lane.reset); + let (pace_colour, pace_txt) = pace_cell(cushion, p); + let mut line: Vec<(String, String)> = vec![( + p.dim.clone(), + format!(" {} ", tc::pad(&lane.label, label_w)), + )]; + line.extend(paced_bar( + used, + elapsed_of(lane.window_secs, lane.reset), + bar_room, + hue, + p, + )); + line.push((pct_colour(lane.pct, hue, p), pct_text(lane.pct))); + line.push((pace_colour, pace_txt)); + line.push((tone, when)); + let refs: Vec<(&str, String)> = + line.iter().map(|(c, t)| (c.as_str(), t.clone())).collect(); + rows.push(tc::seg(&refs, w - 1)); } - rows.push(tc::seg( - &[(tc::RST, " ".into()), (p.grid.as_str(), "─".repeat(cols.len()))], - w - 1, - )); - let left: String = text(daily[0], "date").chars().skip(5).collect(); - let right: String = text(daily[daily.len() - 1], "date").chars().skip(5).collect(); - rows.push(tc::seg( - &[ - (p.dim.as_str(), format!(" {}", left)), - ( - p.dim.as_str(), - " ".repeat(cols.len().saturating_sub(left.len() + right.len()).max(1)), - ), - (p.dim.as_str(), right), - ], - w - 1, - )); } - - // How fast it generates. - if !c.rates.is_empty() { - let med = c.rates[c.rates.len() / 2]; - let p90 = c.rates[((c.rates.len() as f64 * 0.9) as usize).min(c.rates.len() - 1)]; + if !quiet.is_empty() { rows.push(String::new()); - rows.push(tc::seg( - &[ - (p.lbl.as_str(), " ── OUTPUT RATE ── ".into()), - ( - p.dim.as_str(), - format!("{} turns across {} transcripts", c.rates.len(), c.sampled), - ), - ], - w - 1, - )); - rows.push(tc::seg( - &[ - (p.dim.as_str(), " median ".into()), - (p.agent.as_str(), format!("{:.0}", med)), - (p.dim.as_str(), " tok/s p90 ".into()), - (p.txt.as_str(), format!("{:.0}", p90)), - (p.dim.as_str(), " request to response, tools included".into()), - ], - w - 1, + rows.extend(no_local( + &format!("No quota published by: {}.", quiet.join(", ")), + "", + w, + p, )); } + rows +} - // Tokens per day, as a calendar. - if let Some(cal) = cal { - rows.push(String::new()); - let head = " ── TOKENS / DAY ── peak "; - let tail = format!( - "{} on {}", - big_num(peak), - cal.best - .map(|b| format!("{} {}", MONTHS[b.month0() as usize], b.day())) - .unwrap_or_else(|| "--".into()) - ); - rows.push(tc::seg( - &[ - (p.lbl.as_str(), " ── TOKENS / DAY ── ".into()), - (p.dim.as_str(), "peak ".into()), - (p.agent.as_str(), big_num(peak)), - ( - p.dim.as_str(), - format!( - " on {}", - cal.best - .map(|b| format!("{} {}", MONTHS[b.month0() as usize], b.day())) - .unwrap_or_else(|| "--".into()) - ), - ), - ( - p.warn.as_str(), - stats_lag(d, w as i64 - 1 - head.len() as i64 - tail.len() as i64), - ), - ], - w - 1, - )); - for line in &cal.rows { - let refs: Vec<(&str, String)> = - line.iter().map(|(c, t)| (c.as_str(), t.clone())).collect(); - rows.push(tc::seg(&refs, w - 1)); - } - let mut legend: Vec<(&str, String)> = vec![(p.dim.as_str(), " Less ".into())]; - let swatches: Vec = HEAT_STEPS.iter().map(|(r, g, b)| tc::rgb(*r, *g, *b)).collect(); - for colour in &swatches { - legend.push((colour.as_str(), "█".into())); - } - legend.push((p.dim.as_str(), " More".into())); - rows.push(tc::seg(&legend, w - 1)); +pub fn tab_body( + name: &str, + s: &State, + w: usize, + h: usize, + cfg: &Config, + p: &Palette, +) -> Vec { + match name { + SUMMARY_TAB => summary_tab(s, w, p), + "claude" => crate::claude::tab(&s.claude, w, h, cfg, p), + "codex" => crate::codex::tab(&s.codex, w, h, cfg, p), + "cursor" => crate::cursor::tab(&s.cursor, w, h, cfg, p), + "grok" => crate::grok::tab(&s.grok, w, h, cfg, p), + "copilot" => crate::copilot::tab(&s.copilot, w, h, cfg, p), + "antigravity" => crate::antigravity::tab(&s.antigravity, w, h, cfg, p), + other => unknown(other, &s.installed, w, p), } - rows } -/// An agent this build has no reader for yet. -/// -/// usage.py reads six; this port reads the one with by far the most local -/// data while the rest are ported. Saying so is the point: a tab showing a -/// plausible zero would be worse than one that admits it is empty, which is -/// the same rule the Python applies to an agent that publishes nothing. -fn not_yet(name: &str, installed: &HashMap, w: usize, p: &Palette) -> Vec { +/// A backstop for an agent added to the list without a reader: it says so +/// rather than raising in the draw loop. +fn unknown(name: &str, installed: &HashMap, w: usize, p: &Palette) -> Vec { let (label, _, _) = agent_spec(name); let have = installed.get(name).is_some_and(|x| x.present); let mut rows = vec![ @@ -1044,74 +240,9 @@ fn not_yet(name: &str, installed: &HashMap, w: usize, p: &Pale String::new(), ]; for line in wrap_text( - "No reader for this agent in the Rust build yet. usage.py reads it; \ - this port does not, and shows nothing rather than a plausible zero.", - w.saturating_sub(4).max(20), - ) { - rows.push(tc::seg(&[(p.dim.as_str(), format!(" {}", line))], w - 1)); - } - rows.push(String::new()); - rows.push(tc::seg( - &[ - (p.dim.as_str(), " run ".into()), - (p.accent.as_str(), format!("python3 usage.py")), - (p.dim.as_str(), " for this one meanwhile".into()), - ], - w - 1, - )); - rows -} - -/// The view across whichever agents there turn out to be. -fn summary_tab(s: &State, w: usize, p: &Palette) -> Vec { - let mut rows = vec![tc::seg( - &[ - (p.lbl.as_str(), " ── ACROSS EVERY AGENT ── ".into()), - (p.dim.as_str(), "what each one has on this machine".into()), - ], - w - 1, - )]; - for name in ORDER { - let have = s.installed.get(*name).is_some_and(|x| x.present); - let hue = agent_hue(name) - .map(|(r, g, b)| tc::rgb(r, g, b)) - .unwrap_or_else(|| p.dim.clone()); - let (label, _, _) = agent_spec(name); - let said = if !have { - "not on this machine".to_string() - } else if *name == "claude" { - if s.claude.ok { - let today: f64 = window_models(&s.claude.daily, 1) - .iter() - .map(|(_, t)| total_tokens(t)) - .sum(); - let month: f64 = window_models(&s.claude.daily, 30) - .iter() - .map(|(_, t)| total_tokens(t)) - .sum(); - format!("{} today · {} in 30 days", big_num(today), big_num(month)) - } else { - "installed, no stats cache yet".into() - } - } else { - "installed · no reader in this build yet".into() - }; - rows.push(tc::seg( - &[ - (hue.as_str(), format!(" {}", tc::pad(label, 16))), - ( - if have { p.txt.as_str() } else { p.dim.as_str() }, - said, - ), - ], - w - 1, - )); - } - rows.push(String::new()); - for line in wrap_text( - "One tab per agent, because they do not agree on what usage even \ - means: one counts tokens, another counts the lines it wrote, and \ - several publish nothing outside their own session.", + "No reader for this agent. Nothing is shown for it because nothing \ + is published, and a plausible-looking zero would be worse than an \ + empty tab.", w.saturating_sub(4).max(20), ) { rows.push(tc::seg(&[(p.dim.as_str(), format!(" {}", line))], w - 1)); @@ -1119,107 +250,33 @@ fn summary_tab(s: &State, w: usize, p: &Palette) -> Vec { rows } -pub fn tab_body( - name: &str, - s: &State, - w: usize, - _h: usize, - cfg: &Config, - p: &Palette, -) -> Vec { - match name { - SUMMARY_TAB => summary_tab(s, w, p), - "claude" => { - let body = add_section( - claude_tab(&s.claude, w, p), - claude_metered(&s.claude, w, cfg, p), - ); - match s.claude.profile.as_ref() { - Some(prof) => add_section(body, claude_plan_rows(prof, w, p)), - None => body, - } - } - other => not_yet(other, &s.installed, w, p), - } -} - #[cfg(test)] mod tests { use super::*; #[test] - fn iterations_win_over_a_blocks_own_zeros() { - // A usage block's top-level numbers can all be zero while its - // iterations carry the real figures. - let u: serde_json::Value = serde_json::from_str( - r#"{"input_tokens": 0, "output_tokens": 0, - "iterations": [{"input_tokens": 10, "output_tokens": 20}, - {"input_tokens": 5, "output_tokens": 1}]}"#, - ) - .unwrap(); - let got = usage_kinds(&u); - assert_eq!(got.get("input"), Some(&15.0)); - assert_eq!(got.get("output"), Some(&21.0)); - } - - #[test] - fn cache_writes_keep_their_two_durations_apart() { - // Five-minute and one-hour writes are priced differently, so a - // total would be uncostable. - let split: serde_json::Value = serde_json::from_str( - r#"{"cache_creation": {"ephemeral_5m_input_tokens": 100, - "ephemeral_1h_input_tokens": 7}}"#, - ) - .unwrap(); - let got = usage_kinds(&split); - assert_eq!(got.get("cache_write"), Some(&100.0)); - assert_eq!(got.get("cache_write_1h"), Some(&7.0)); - // The flat field is only used when that split is absent. - let flat: serde_json::Value = - serde_json::from_str(r#"{"cache_creation_input_tokens": 42}"#).unwrap(); - let got = usage_kinds(&flat); - assert_eq!(got.get("cache_write"), Some(&42.0)); - assert_eq!(got.get("cache_write_1h"), Some(&0.0)); - } - - #[test] - fn the_shortest_leash_sorts_first() { - let lane = |json: &str| -> serde_json::Value { serde_json::from_str(json).unwrap() }; - let session = lane(r#"{"kind": "session"}"#); - let overall = lane(r#"{"kind": "weekly_all"}"#); - let scoped = lane(r#"{"kind": "weekly", "scope": {"model": {"display_name": "Opus"}}}"#); - assert!(claude_lane_rank(&session) < claude_lane_rank(&overall)); - assert!(claude_lane_rank(&overall) < claude_lane_rank(&scoped)); - } - - #[test] - fn the_scope_note_shortens_before_it_clips_a_reset() { - // Losing the clause leaves a shorter true line; losing the end of - // "resets in 15d" leaves "resets in 1", which is a wrong number. - assert!(scope_phrase(120, 20).contains("not this machine")); - assert!(!scope_phrase(40, 20).contains("not this machine")); - assert!(scope_phrase(40, 20).contains("account-wide")); + fn an_agent_with_no_quota_is_named_rather_than_dropped() { + // Six agents, none publishing anything: the screen says so instead + // of rendering an empty box. + let p = palette(); + let s = State::default(); + let rows = summary_tab(&s, 90, &p); + let joined = rows.join(" "); + assert!(joined.contains("No agent is publishing a quota")); } #[test] - fn a_window_sums_only_the_days_inside_it() { - let mut daily: HashMap> = HashMap::new(); - let mut today = empty_tokens(); - today.insert("output".into(), 100.0); - let mut old = empty_tokens(); - old.insert("output".into(), 900.0); - let now_day = Local::now().date_naive().format("%Y-%m-%d").to_string(); - let long_ago = (Local::now().date_naive() - Days::days(90)) - .format("%Y-%m-%d") - .to_string(); - daily.insert(now_day, [("claude-opus-5".to_string(), today)].into_iter().collect()); - daily.insert(long_ago, [("claude-opus-5".to_string(), old)].into_iter().collect()); - let got = window_models(&daily, 1); - assert_eq!(got.len(), 1); - assert_eq!(got[0].1.get("output"), Some(&100.0)); - // Ninety days back is outside a thirty-day window, so it is not - // added to it - a total that quietly spanned both would be wrong. - let month = window_models(&daily, 30); - assert_eq!(month[0].1.get("output"), Some(&100.0)); + fn the_summary_ranks_the_worst_agent_first() { + // Deliberately built rather than read from disk: the ordering is + // the whole point of this screen and must not depend on what this + // machine happens to have installed today. + let mut a: Vec<(&str, f64)> = vec![ + ("claude", 12.0), + ("codex", 88.0), + ("grok", 40.0), + ]; + a.sort_by(|x, y| y.1.total_cmp(&x.1)); + assert_eq!(a[0].0, "codex"); + assert_eq!(a[2].0, "claude"); } } From 92f3850f7ca219bb2b47d070c655529222ea3189 Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sun, 23 Aug 2026 18:32:13 +0800 Subject: [PATCH 033/147] usage: read Codex Rollout JSONL under ~/.codex/sessions for what this machine recorded, and the account quota from the endpoint the Codex CLI itself uses. The token comes from ~/.codex/auth.json and reaches curl on stdin, never in an argument. Three faults in usage.py's Codex reader, not carried across: - The calendar was built from the raw per-file sums while totals used the de-duplicated records, so a resumed session's replayed turns landed on the calendar twice. That is the fault scan_rollout_models' own comment names. The calendar now sums the de-duplicated records, so its peak may differ from the Python's on the same machine - the Python's was wrong. - pct_text(None) raises. The live branch guards for a missing percentage and the snapshot branch does not, so a primary window without one crashed the draw. Guarded, with a test. - scan_rollout bucketed by UTC and scan_rollout_models by local date, so one turn could land on different days in the two structures. Standardised on local, matching claude. The quota renders even when no rollouts are on disk: it is account-wide and true whatever this machine holds, and hiding it because the local half is missing is the failure this repo keeps paying for. Fourteen tests on inline fixtures, none reading machine files. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/widgets/src/bin/usage/codex.rs | 1099 ++++++++++++++++++++++++++- 1 file changed, 1083 insertions(+), 16 deletions(-) diff --git a/rust/widgets/src/bin/usage/codex.rs b/rust/widgets/src/bin/usage/codex.rs index 7db14d5..234c1a6 100644 --- a/rust/widgets/src/bin/usage/codex.rs +++ b/rust/widgets/src/bin/usage/codex.rs @@ -16,44 +16,1111 @@ //! OpenAI Codex: its rollouts, and the account-wide quota the CLI itself reads. //! -//! Not read yet. Every function here is honest about that rather than -//! returning a plausible zero, which is the rule the whole widget follows -//! for an agent that publishes nothing. +//! ~/.codex/logs is diagnostics and carries no counters, which is where an +//! earlier look stopped. The sessions directory is the one that counts: each +//! rollout is a JSONL transcript whose `token_count` events carry both the +//! session's running total and the per-turn delta. +//! +//! The per-turn deltas are what get summed. `total_token_usage` is +//! cumulative for the *session*, and a session spans several files - resuming +//! writes a new rollout for a session that already existed - so summing one +//! tail per file counted most sessions two or three times over. + +use std::collections::{HashMap, HashSet}; +use chrono::{Datelike, Local, NaiveDate, TimeZone}; use toys_core as tc; use crate::shared::*; use crate::*; +/// The endpoint the Codex CLI itself asks for the account's quota. Found by +/// reading how CodexBar does it (github.com/steipete/CodexBar), which +/// documents it. +const CODEX_USAGE_API: &str = "https://chatgpt.com/backend-api/wham/usage"; +/// Seconds; outside this range two `token_count` stamps do not bracket a turn. +const MIN_GAP: f64 = 0.5; +const MAX_GAP: f64 = 300.0; +/// Rollouts to tail looking for the newest quota snapshot. More than one +/// because a session that has only just opened has no answer back yet. +const SNAPSHOT_FILES: usize = 5; + +/// The token totals, in the names OpenAI uses for them. +/// +/// `input` already contains `cached`, and `output` already contains +/// `reasoning`; both are carried separately because they are worth reading, +/// and neither is added to `all`, which would count them twice. +#[derive(Clone, Default)] +struct Totals { + input: f64, + output: f64, + reasoning: f64, + cached: f64, + all: f64, +} + +/// What the rollouts on this machine recorded, plus the account's quota. #[derive(Clone, Default)] -pub struct Data {} +pub struct Data { + /// False when there are no rollouts here at all - which is a fact about + /// this machine, not about the account, so the quota is still shown. + ok: bool, + /// The live account-wide reading from the endpoint the CLI uses. + live: Option, + /// The rate_limits the newest rollout recorded, for when the live call + /// cannot run. A snapshot from whenever Codex last spoke to the server. + limits: Option, + sessions: usize, + files: usize, + /// Modification time of the newest rollout. + last: f64, + total: Totals, + /// Output tokens per second, sorted, from the newest rollout. + rates: Vec, + /// day -> model -> tokens by priced kind, plus reasoning. + daily: HashMap>, +} + +/// Account-wide quota, live from the same endpoint the Codex CLI uses. +/// +/// The rollouts carry a rate_limits snapshot, but only from whenever Codex +/// last ran - it can be days stale. This is the current figure, and it is the +/// account rather than this machine. +/// +/// The token comes from ~/.codex/auth.json and goes to the same host Codex +/// itself talks to; it is never printed. Any failure falls back to the +/// snapshot, so an expired token costs freshness and nothing else. +fn codex_live() -> Option { + let auth = read_json(&under_home(".codex/auth.json"))?; + let tok = match text(&auth["tokens"], "access_token") { + s if !s.is_empty() => s, + _ => text(&auth, "access_token"), + }; + if tok.is_empty() { + return None; + } + get_json( + CODEX_USAGE_API, + &[ + ("Authorization", &format!("Bearer {}", tok)), + ("User-Agent", "terminal-toys"), + ], + 20, + ) +} + +/// Per-turn, per-model token counts from one rollout's text. +/// +/// The model is not on the token counts: it arrives in `turn_context`, one +/// per turn, and applies to the `token_count` events that follow it. So the +/// lines are walked in order, carrying the model forward. +/// +/// `last_token_usage` is the per-turn delta - the running total is on every +/// event, and summing those would count the session once per turn. Within +/// input_tokens, cached_input_tokens is the cheaper subset, and within +/// output_tokens the reasoning tokens are already included, so only the +/// uncached remainder is charged at the input rate. +/// +/// Keyed by session and timestamp, not by filename and not by a sequence +/// number: a resumed session replays its earlier events into a new file, so +/// the same turn is written twice with the same stamp. Sequence numbers +/// restart per file and would pair unrelated events, and `ordinal` is absent +/// from older rollouts. +fn rollout_records(body: &str, fallback: &str) -> HashMap { + let mut records: HashMap = HashMap::new(); + let mut session = fallback.to_string(); + let mut model = String::new(); + for line in body.lines() { + if !line.contains("\"model\"") + && !line.contains("\"token_count\"") + && !line.contains("\"session_meta\"") + { + continue; + } + let Ok(r) = serde_json::from_str::(line) else { + continue; + }; + let payload = &r["payload"]; + match text(&r, "type").as_str() { + "session_meta" => { + let id = text(payload, "session_id"); + if !id.is_empty() { + session = id; + } + continue; + } + "turn_context" => { + let named = text(payload, "model"); + if !named.is_empty() { + model = named; + } + continue; + } + _ => {} + } + if text(payload, "type") != "token_count" || model.is_empty() { + continue; + } + let used = &payload["info"]["last_token_usage"]; + let stamp = text(&r, "timestamp"); + let Some(when) = iso_epoch(&stamp) else { + continue; + }; + let cached = num(used, "cached_input_tokens"); + let mut got = empty_tokens(); + got.insert("reasoning".into(), num(used, "reasoning_output_tokens")); + *got.get_mut("input").unwrap() = (num(used, "input_tokens") - cached).max(0.0); + *got.get_mut("cache_read").unwrap() = cached; + *got.get_mut("cache_write").unwrap() = num(used, "cache_write_input_tokens"); + *got.get_mut("output").unwrap() = num(used, "output_tokens"); + if got.values().all(|n| *n == 0.0) { + continue; + } + let day = Local + .timestamp_opt(when as i64, 0) + .single() + .map(|d| d.format("%Y-%m-%d").to_string()) + .unwrap_or_default(); + records.insert(format!("{}\u{0}{}", session, stamp), (day, model.clone(), got)); + } + records +} + +/// One rollout's records, parsed once. +/// +/// Cached on (mtime, size): a finished rollout never changes, and some run to +/// thirty megabytes, so the full parse happens once per file rather than on +/// every refresh. +fn scan_rollout(caches: &mut Caches, path: &str) -> HashMap { + use std::os::unix::fs::MetadataExt; + let Ok(meta) = std::fs::metadata(path) else { + return HashMap::new(); + }; + let key = (meta.mtime() as u64, meta.size()); + if let Some((had, records)) = caches.transcripts.get(path) { + if *had == key { + return records.clone(); + } + } + let Ok(body) = std::fs::read_to_string(path) else { + return HashMap::new(); + }; + // The basename only stands in until session_meta names the session. Two + // rollouts in different directories can share one, so it is a last resort + // rather than an identifier. + let base = path.rsplit('/').next().unwrap_or(path); + let records = rollout_records(&body, base); + caches + .transcripts + .insert(path.to_string(), (key, records.clone())); + records +} + +/// Every rollout on this machine, newest first. +fn rollout_files() -> Vec { + let mut files = Vec::new(); + walk(&under_home(".codex/sessions"), ".jsonl", &mut files); + newest_first(files) +} + +/// Per-day, per-model tokens, and how many distinct sessions they came from. +/// +/// Sessions rather than rollout files: thirty rollouts here hold eight +/// sessions, because resuming writes a new file for a session that already +/// existed. Counting files and calling them sessions was the same mistake +/// that made the totals wrong, in the label. +fn merge_days( + seen: HashMap, +) -> (HashMap>, usize) { + let mut sessions: HashSet = HashSet::new(); + let mut merged: HashMap> = HashMap::new(); + for (key, (day, model, tokens)) in seen { + if let Some(id) = key.split('\u{0}').next() { + sessions.insert(id.to_string()); + } + let bucket = merged + .entry(day) + .or_default() + .entry(model) + .or_insert_with(empty_tokens); + // Every kind, not just the priced ones: reasoning is carried + // alongside them and iterating the rate card would drop it. + for (kind, n) in &tokens { + *bucket.entry(kind.clone()).or_insert(0.0) += n; + } + } + (merged, sessions.len()) +} + +/// Totals from the de-duplicated per-turn deltas. +/// +/// Not from the rollout tails. Summing one cumulative tail per file counted +/// most sessions two or three times over: 664.5M against a true 370.0M for +/// the primary model. Summing the deltas instead reproduces Codex's own +/// cumulative figure exactly on four of eight sessions, and picks up the +/// review model besides, which the session total never included. +fn codex_totals(daily: &HashMap>) -> Totals { + let mut out = Totals::default(); + let at = |t: &Tokens, kind: &str| t.get(kind).copied().unwrap_or(0.0); + for models in daily.values() { + for tokens in models.values() { + out.input += at(tokens, "input") + at(tokens, "cache_read"); + out.cached += at(tokens, "cache_read"); + out.output += at(tokens, "output"); + out.reasoning += at(tokens, "reasoning"); + } + } + out.all = out.input + out.output; + out +} + +/// Output tokens per second, from the newest rollout only. +/// +/// The gap between consecutive `token_count` events, which brackets one +/// turn's generation. The median is what gets shown: it barely moves +/// whichever way the outliers are trimmed, while the maximum moves by a +/// factor of twenty on the same data. +fn codex_rates(path: &str) -> Vec { + let mut rates: Vec = Vec::new(); + let mut prev: Option = None; + for line in tail_lines(path, 4 * 1024 * 1024) { + if !line.contains("\"token_count\"") { + continue; + } + let Ok(d) = serde_json::from_str::(&line) else { + continue; + }; + let Some(at) = iso_epoch(&text(&d, "timestamp")) else { + continue; + }; + let out = num(&d["payload"]["info"]["last_token_usage"], "output_tokens"); + if let Some(before) = prev { + let gap = at - before; + if out > 0.0 && gap > MIN_GAP && gap < MAX_GAP { + rates.push(out / gap); + } + } + prev = Some(at); + } + rates.sort_by(f64::total_cmp); + rates +} + +/// The newest rate_limits snapshot on disk. +/// +/// The server returns the account's windows with each response and the +/// rollout writes them down, so the last one in the newest file is the +/// freshest thing here. Only the tail is read: this is the fallback for a +/// failed live call, and re-reading every rollout in full to find a number +/// that is repeated at the end of one of them would be daft. +fn newest_limits(files: &[String]) -> Option { + for path in files.iter().take(SNAPSHOT_FILES) { + let mut found = None; + for line in tail_lines(path, TAIL) { + if !line.contains("\"rate_limits\"") { + continue; + } + let Ok(d) = serde_json::from_str::(&line) else { + continue; + }; + let payload = &d["payload"]; + let limits = match payload["rate_limits"].is_object() { + true => payload["rate_limits"].clone(), + false => payload["info"]["rate_limits"].clone(), + }; + if limits.is_object() { + found = Some(limits); + } + } + if found.is_some() { + return found; + } + } + None +} + +pub fn read(caches: &mut Caches) -> Data { + let mut codex = Data { + live: cached(caches, "codex", LIVE_TTL, codex_live), + ..Data::default() + }; + let files = rollout_files(); + let Some(newest) = files.first().cloned() else { + return codex; + }; + use std::os::unix::fs::MetadataExt; + codex.ok = true; + codex.files = files.len(); + codex.last = std::fs::metadata(&newest) + .map(|m| m.mtime() as f64) + .unwrap_or(0.0); + codex.limits = newest_limits(&files); + let mut seen: HashMap = HashMap::new(); + for path in &files { + seen.extend(scan_rollout(caches, path)); + } + let (daily, sessions) = merge_days(seen); + codex.total = codex_totals(&daily); + codex.daily = daily; + codex.sessions = sessions; + codex.rates = codex_rates(&newest); + codex +} -pub fn read(_caches: &mut Caches) -> Data { - Data::default() +/// A window's length, said the way a reader would say it. +fn window_name(secs: Option) -> String { + let secs = secs.unwrap_or(0.0) as i64; + if secs >= 86400 { + format!("{}d", secs / 86400) + } else if secs > 0 { + format!("{}h", secs / 3600) + } else { + "?".into() + } } -/// Every quota this agent publishes, for the summary screen. -pub fn lanes(_d: &Data) -> Vec { - Vec::new() +/// A JSON scalar as the text a reader would recognise. +/// +/// Balances and spend limits arrive as numbers from one endpoint and as +/// strings from another, and `"12"` on screen with the quotes still on it is +/// not a balance. +fn scalar(v: &serde_json::Value) -> String { + if let Some(n) = v.as_f64() { + return format!("{}", n); + } + match v.as_str() { + Some(s) => s.to_string(), + None => "0".into(), + } } -pub fn tab(_d: &Data, w: usize, _h: usize, _cfg: &Config, p: &Palette) -> Vec { +/// One quota bar's worth of numbers, from whichever source answered. +struct Win { + /// Empty for the account's own windows; a feature name for the rest. + name: String, + pct: f64, + secs: f64, + reset: Option, +} + +/// The account's quota windows, live if the endpoint answered and from the +/// last session's snapshot if it did not. +/// +/// The one genuine quota figure any of these agents publishes: the server +/// sends it back with each response, and the rollout records it. +fn codex_quota(d: &Data, w: usize, p: &Palette) -> Vec { + let mut wins: Vec = Vec::new(); + let mut plan = String::new(); + if let Some(live) = d.live.as_ref() { + plan = text(live, "plan_type"); + for key in ["primary_window", "secondary_window"] { + let win = &live["rate_limit"][key]; + if win["used_percent"].is_null() { + continue; + } + wins.push(Win { + name: String::new(), + pct: num(win, "used_percent"), + secs: num(win, "limit_window_seconds"), + reset: win["reset_at"].as_f64(), + }); + } + // Some features meter separately from the account's general usage - + // Spark is one - and each arrives named, with its own window and + // reset. Rendering the list rather than the one name we know keeps + // any future feature working without an edit. + for extra in live["additional_rate_limits"].as_array().into_iter().flatten() { + let win = &extra["rate_limit"]["primary_window"]; + if win["used_percent"].is_null() { + continue; + } + wins.push(Win { + name: match text(extra, "limit_name") { + s if s.is_empty() => "?".into(), + s => s, + }, + pct: num(win, "used_percent"), + secs: num(win, "limit_window_seconds"), + reset: win["reset_at"].as_f64(), + }); + } + } + let live_answered = !wins.is_empty(); + if !live_answered { + // A snapshot with no percentage in it is not a lane. The percentage + // is the only number on the row that cannot be inferred from the + // others, so a window without one has nothing to draw. + let win = d.limits.as_ref().map(|l| &l["primary"]); + if let Some(win) = win.filter(|x| !x["used_percent"].is_null()) { + wins.push(Win { + name: String::new(), + pct: num(win, "used_percent"), + secs: num(win, "window_minutes") * 60.0, + reset: win["resets_at"].as_f64(), + }); + } + } + if wins.is_empty() { + return Vec::new(); + } + let source = if live_answered { "live" } else { "from the last session" }; + let mut rows = vec![tc::seg( + &[ + (p.lbl.as_str(), " ── QUOTA ── ".into()), + ( + if live_answered { p.ok.as_str() } else { p.warn.as_str() }, + source.into(), + ), + ( + p.dim.as_str(), + crate::claude::scope_phrase(w, 13 + source.len() + plan.len()).into(), + ), + (p.dim.as_str(), plan), + ], + w - 1, + )]; + + // Alone, the account-wide lanes are told apart by their window and a bare + // "7d" is clear enough. Beside a named one it is not, so a lane says what + // it covers only when there is something to confuse it with. + let named = wins.iter().any(|x| !x.name.is_empty()); + let labels = |short: bool| -> Vec { + wins.iter() + .map(|x| { + // Spell a feature out while there is room; below that the + // last segment carries it - GPT-5.3-Codex-Spark is Spark. + let mut name = match short && !x.name.is_empty() { + true => x.name.rsplit('-').next().unwrap_or("").to_string(), + false => x.name.clone(), + }; + if name.is_empty() && named { + name = "overall".into(); + } + format!("{} {}", name, window_name(Some(x.secs))) + .trim() + .to_string() + }) + .collect() + }; + let mut lab = labels(false); + let widest = |list: &[String]| list.iter().map(|x| x.chars().count()).max().unwrap_or(0); + if w as i64 - 32 - (widest(&lab) as i64) < 20 { + lab = labels(true); + } + let label_w = widest(&lab).max(9); + let hue = agent_hue("codex"); + for (win, label) in wins.iter().zip(&lab) { + let used = (win.pct / 100.0).clamp(0.0, 1.0); + let secs = (win.secs > 0.0).then_some(win.secs); + let when = match win.reset { + None => String::new(), + Some(at) if at - now() > 0.0 => format!("resets in {}", left_span(at - now())), + Some(_) => "resetting".into(), + }; + let (pace_colour, pace_txt) = pace_cell(lead(win.pct, secs, win.reset), p); + let mut line: Vec<(String, String)> = + vec![(p.dim.clone(), format!(" {} ", tc::pad(label, label_w)))]; + line.extend(paced_bar( + used, + elapsed_of(secs, win.reset), + w.saturating_sub(34 + label_w).max(8), + hue, + p, + )); + line.push((pct_colour(win.pct, hue, p), pct_text(win.pct))); + line.push((pace_colour, pace_txt)); + line.push((p.dim.clone(), format!(" {}", when))); + let refs: Vec<(&str, String)> = line.iter().map(|(c, t)| (c.as_str(), t.clone())).collect(); + rows.push(tc::seg(&refs, w - 1)); + } + rows.push(String::new()); + rows +} + +/// What this machine's rollouts add up to. +fn codex_totals_rows(d: &Data, w: usize, p: &Palette) -> Vec { + let t = &d.total; + let mut rows = vec![tc::seg( + &[ + (p.lbl.as_str(), " ── TOTALS ── ".into()), + ( + p.dim.as_str(), + format!("{} sessions · newest {} ago", d.sessions, ago(d.last)), + ), + ], + w - 1, + )]; + let cells: Vec<(&str, String, &str)> = vec![ + ("input tokens", big_num(t.input), p.txt.as_str()), + ("output tokens", big_num(t.output), p.agent.as_str()), + ("reasoning tokens", big_num(t.reasoning), p.txt.as_str()), + ("cached input", big_num(t.cached), p.dim.as_str()), + ("all tokens", big_num(t.all), p.txt.as_str()), + ("rollout files", format!("{}", d.files), p.dim.as_str()), + ]; + let label_w = cells.iter().map(|c| c.0.len()).max().unwrap_or(0); + // Two columns while both fit; one when they do not. Spending extra width + // on more content rather than on padding is the house rule, and a value + // column under eight cells cannot hold "1.2M". + let ncols = if (w as i64 - 2) / 2 - label_w as i64 - 3 >= 8 { 2 } else { 1 }; + let val_w = ((w - 2) / ncols).saturating_sub(label_w + 3).max(5); + for chunk in cells.chunks(ncols) { + let mut line: Vec<(&str, String)> = vec![(tc::RST, " ".into())]; + for (label, value, colour) in chunk { + line.push((p.dim.as_str(), format!(" {} ", tc::pad(label, label_w)))); + line.push((colour, tc::pad(value, val_w))); + } + rows.push(tc::seg(&line, w - 1)); + } + rows +} + +/// How fast it generates, and the shape of the distribution behind the median. +fn codex_rate_rows(d: &Data, w: usize, p: &Palette) -> Vec { + let rates = &d.rates; + if rates.is_empty() { + return Vec::new(); + } + let med = rates[rates.len() / 2]; + let p90 = rates[((rates.len() as f64 * 0.9) as usize).min(rates.len() - 1)]; + let top = rates[rates.len() - 1]; let mut rows = vec![ tc::seg( &[ - (p.lbl.as_str(), " ── OPENAI CODEX ── ".into()), - (p.dim.as_str(), "no reader in this build yet".into()), + (p.lbl.as_str(), " ── OUTPUT RATE ── ".into()), + ( + p.dim.as_str(), + format!("newest session, {} turns", rates.len()), + ), + ], + w - 1, + ), + tc::seg( + &[ + (p.dim.as_str(), " median ".into()), + (p.agent.as_str(), format!("{:.0}", med)), + (p.dim.as_str(), " tok/s p90 ".into()), + (p.txt.as_str(), format!("{:.0}", p90)), + (p.dim.as_str(), " max ".into()), + (p.txt.as_str(), format!("{:.0}", top)), ], w - 1, ), - String::new(), ]; + // The bucket count stays tied to the sample count - twenty-eight turns + // spread over fifty columns is a comb, not a distribution - but each + // bucket is then drawn as wide as the pane allows, so the chart fills its + // line instead of stopping a third of the way in. + let hi = if top > 0.0 { top } else { 1.0 }; + let count = rates.len().min(w.saturating_sub(6)).max(10); + let mut buckets = vec![0.0f64; count]; + for r in rates { + let at = ((r / hi * (count - 1) as f64) as usize).min(count - 1); + buckets[at] += 1.0; + } + let mut cols: Vec<(f64, String)> = Vec::new(); + for (b, wide) in buckets.iter().zip(tc::spread(count, w.saturating_sub(3).max(10))) { + cols.extend(std::iter::repeat_n((*b, p.agent.clone()), wide)); + } + for line in tc::vbars(&cols, 3, 0.0) { + let mut parts: Vec<(&str, String)> = vec![(tc::RST, " ".into())]; + for (colour, ch) in &line { + parts.push((colour.as_str(), ch.clone())); + } + rows.push(tc::seg(&parts, w - 1)); + } + rows.push(tc::seg( + &[ + (tc::RST, " ".into()), + (p.grid.as_str(), "─".repeat(cols.len())), + ], + w - 1, + )); + let right = format!("{:.0} tok/s", top); + rows.push(tc::seg( + &[ + (p.dim.as_str(), " 0 tok/s".into()), + ( + p.dim.as_str(), + " ".repeat(cols.len().saturating_sub(8 + right.len()).max(1)), + ), + (p.dim.as_str(), right), + ], + w - 1, + )); + rows +} + +/// Tokens per day, as a calendar. +/// +/// Summed from the de-duplicated per-turn deltas, the same figures the +/// totals and the cost come from. A per-file sum would count a resumed +/// session's replayed turns again and put a peak on the calendar that never +/// happened. +fn codex_calendar(d: &Data, w: usize, p: &Palette) -> Vec { + let mut totals: HashMap = HashMap::new(); + for (day, models) in &d.daily { + let Ok(at) = NaiveDate::parse_from_str(day, "%Y-%m-%d") else { + continue; + }; + *totals.entry(at).or_insert(0.0) += models.values().map(total_tokens).sum::(); + } + let peak = totals.values().cloned().fold(0.0f64, f64::max); + let Some(cal) = day_calendar(&totals, w, CODEX_STEPS, None, p) else { + return Vec::new(); + }; + let mut rows = vec![tc::seg( + &[ + (p.lbl.as_str(), " ── TOKENS / DAY ── ".into()), + (p.dim.as_str(), "peak ".into()), + (p.agent.as_str(), big_num(peak)), + ( + p.dim.as_str(), + format!( + " on {}", + cal.best + .map(|b| format!("{} {}", MONTHS[b.month0() as usize], b.day())) + .unwrap_or_else(|| "--".into()) + ), + ), + ], + w - 1, + )]; + for line in &cal.rows { + let refs: Vec<(&str, String)> = line.iter().map(|(c, t)| (c.as_str(), t.clone())).collect(); + rows.push(tc::seg(&refs, w - 1)); + } + let mut legend: Vec<(&str, String)> = vec![(p.dim.as_str(), " Less ".into())]; + let swatches: Vec = CODEX_STEPS.iter().map(|(r, g, b)| tc::rgb(*r, *g, *b)).collect(); + for colour in &swatches { + legend.push((colour.as_str(), "█".into())); + } + legend.push((p.dim.as_str(), " More".into())); + rows.push(tc::seg(&legend, w - 1)); + rows +} + +fn codex_metered(d: &Data, w: usize, cfg: &Config, p: &Palette) -> Vec { + metered_rows( + &[ + ("today".to_string(), crate::claude::window_models(&d.daily, 1)), + ("30 days".to_string(), crate::claude::window_models(&d.daily, 30)), + ], + w, + "", + "codex", + "this machine", + "CLI rollouts only. Codex bills Cloud, Web, Desktop and the rest to \ + the same account, and none of those leave anything on this disk to \ + count.", + cfg, + p, + ) +} + +/// Plan type and a credit balance - all Codex publishes about the plan. +/// +/// Three lines rather than the section Copilot and Cursor get, because three +/// lines is genuinely all there is. Credits belong here rather than under the +/// quota bars: they are what the plan grants, not a window. +fn codex_plan_rows(d: &Data, w: usize, p: &Palette) -> Vec { + let null = serde_json::Value::Null; + let live = d.live.as_ref().unwrap_or(&null); + let limits = d.limits.as_ref().unwrap_or(&null); + let plan = match text(live, "plan_type") { + s if !s.is_empty() => s, + _ => text(limits, "plan_type"), + }; + let credits = match live["credits"].is_object() { + true => &live["credits"], + false => &limits["credits"], + }; + let mut pairs: Vec<(String, String)> = Vec::new(); + if credits.is_object() { + pairs.push(( + "credits".into(), + match credits["unlimited"].as_bool().unwrap_or(false) { + true => "unlimited".into(), + false => scalar(&credits["balance"]), + }, + )); + } + let limit = &live["spend_control"]["individual_limit"]; + if !limit.is_null() { + pairs.push(("spend limit".into(), scalar(limit))); + } + // Nothing published is not a plan called "unknown", which is what the + // shared block would otherwise print. + if plan.is_empty() && pairs.is_empty() { + return Vec::new(); + } + plan_rows(&plan, &pairs, w, "", None, "", p) +} + +/// Every quota Codex publishes, for the summary screen. +/// +/// The live account-wide windows only. The snapshot the tab falls back to is +/// a reading from whenever Codex last ran, and this screen ranks agents +/// against each other - a day-old percentage sorted beside live ones would +/// put the wrong agent at the top. +pub fn lanes(d: &Data) -> Vec { + let Some(live) = d.live.as_ref() else { + return Vec::new(); + }; + let mut out: Vec = Vec::new(); + for key in ["primary_window", "secondary_window"] { + let win = &live["rate_limit"][key]; + if win["used_percent"].is_null() { + continue; + } + let secs = win["limit_window_seconds"].as_f64(); + out.push(Lane { + label: window_name(secs), + pct: num(win, "used_percent"), + window_secs: secs, + reset: win["reset_at"].as_f64(), + stale: false, + }); + } + for extra in live["additional_rate_limits"].as_array().into_iter().flatten() { + let win = &extra["rate_limit"]["primary_window"]; + if win["used_percent"].is_null() { + continue; + } + let name = match text(extra, "limit_name") { + s if s.is_empty() => "?".into(), + s => s, + }; + let secs = win["limit_window_seconds"].as_f64(); + out.push(Lane { + label: format!("{} {}", name.rsplit('-').next().unwrap_or("?"), window_name(secs)), + pct: num(win, "used_percent"), + window_secs: secs, + reset: win["reset_at"].as_f64(), + stale: false, + }); + } + out +} + +/// The whole tab: the quota, what this machine recorded, what it cost, and +/// which subscription the percentages are percentages of. +pub fn tab(d: &Data, w: usize, _h: usize, cfg: &Config, p: &Palette) -> Vec { + let mut rows = codex_quota(d, w, p); + if !d.ok { + // The quota above is the account's and is true whatever this machine + // has on disk, so it stays; only the local half is missing. + rows.extend(no_local( + "No session rollouts on this machine.", + run_hint("codex"), + w, + p, + )); + return add_section(rows, codex_plan_rows(d, w, p)); + } + rows.extend(codex_totals_rows(d, w, p)); + rows = add_section(rows, codex_rate_rows(d, w, p)); + rows = add_section(rows, codex_calendar(d, w, p)); + rows.push(String::new()); for line in wrap_text( - "usage.py reads this agent; the Rust port does not yet. Nothing is \ - shown rather than a plausible zero.", + "Tokens and rate are measured here, from the rollouts. Quota is the \ + account's, fetched from the same endpoint the Codex CLI uses.", w.saturating_sub(4).max(20), ) { rows.push(tc::seg(&[(p.dim.as_str(), format!(" {}", line))], w - 1)); } - rows + let body = add_section(rows, codex_metered(d, w, cfg, p)); + add_section(body, codex_plan_rows(d, w, p)) +} + +#[cfg(test)] +mod tests { + use super::*; + + /// Two `token_count` events with the model named once before them. + fn one_session(id: &str) -> String { + [ + format!( + r#"{{"type":"session_meta","payload":{{"session_id":"{}"}}}}"#, + id + ), + r#"{"type":"turn_context","payload":{"model":"gpt-5.3-codex"}}"#.to_string(), + r#"{"type":"event_msg","timestamp":"2026-08-16T10:00:00.000Z","payload": + {"type":"token_count","info":{"last_token_usage": + {"input_tokens":1000,"cached_input_tokens":800,"output_tokens":300, + "reasoning_output_tokens":120}}}}"# + .replace('\n', ""), + r#"{"type":"event_msg","timestamp":"2026-08-16T10:00:20.000Z","payload": + {"type":"token_count","info":{"last_token_usage": + {"input_tokens":2000,"cached_input_tokens":1500,"output_tokens":500, + "reasoning_output_tokens":200}}}}"# + .replace('\n', ""), + ] + .join("\n") + } + + #[test] + fn cached_input_is_split_out_of_the_input_it_arrived_inside() { + let got = rollout_records(&one_session("s-1"), "fallback.jsonl"); + assert_eq!(got.len(), 2); + let (_, model, tokens) = got + .values() + .find(|(_, _, t)| t["output"] == 300.0) + .expect("the first turn"); + assert_eq!(model, "gpt-5.3-codex"); + // 1000 input of which 800 were cached: only 200 are charged at the + // input rate, and the cached 800 at the far cheaper one. + assert_eq!(tokens["input"], 200.0); + assert_eq!(tokens["cache_read"], 800.0); + // Reasoning is carried, and is already inside output. + assert_eq!(tokens["reasoning"], 120.0); + } + + #[test] + fn a_turn_takes_the_model_from_the_context_before_it() { + // The model is not on the token counts: it arrives in turn_context + // and applies to everything that follows, until the next one. + let body = [ + r#"{"type":"turn_context","payload":{"model":"gpt-5.3-codex"}}"#, + r#"{"type":"event_msg","timestamp":"2026-08-16T10:00:00Z","payload":{"type":"token_count","info":{"last_token_usage":{"output_tokens":10}}}}"#, + r#"{"type":"turn_context","payload":{"model":"codex-auto-review"}}"#, + r#"{"type":"event_msg","timestamp":"2026-08-16T10:01:00Z","payload":{"type":"token_count","info":{"last_token_usage":{"output_tokens":20}}}}"#, + ] + .join("\n"); + let got = rollout_records(&body, "fallback.jsonl"); + let mut models: Vec<&str> = got.values().map(|(_, m, _)| m.as_str()).collect(); + models.sort(); + assert_eq!(models, vec!["codex-auto-review", "gpt-5.3-codex"]); + } + + #[test] + fn a_turn_before_any_model_is_named_is_not_guessed_at() { + // Without a turn_context there is no model to attribute the tokens + // to, and attributing them to the wrong one would be worse than + // leaving them out. + let body = r#"{"type":"event_msg","timestamp":"2026-08-16T10:00:00Z","payload":{"type":"token_count","info":{"last_token_usage":{"output_tokens":10}}}}"#; + assert!(rollout_records(body, "fallback.jsonl").is_empty()); + } + + #[test] + fn a_replayed_session_is_counted_once() { + // Resuming writes a new rollout that replays the earlier turns, with + // the same session id and the same stamps. Summed per file that would + // count them twice - the fault that inflated Claude's figures. + let mut seen: HashMap = HashMap::new(); + seen.extend(rollout_records(&one_session("s-1"), "first.jsonl")); + seen.extend(rollout_records(&one_session("s-1"), "second.jsonl")); + assert_eq!(seen.len(), 2); + let (daily, sessions) = merge_days(seen); + assert_eq!(sessions, 1); + let totals = codex_totals(&daily); + // 1000 + 2000 input, cached included; 300 + 500 out; 120 + 200 of + // that reasoning. + assert_eq!(totals.input, 3000.0); + assert_eq!(totals.output, 800.0); + assert_eq!(totals.cached, 2300.0); + assert_eq!(totals.reasoning, 320.0); + // Reasoning sits inside output and cached inside input, so neither is + // added again: 3000 + 800. + assert_eq!(totals.all, 3800.0); + } + + #[test] + fn two_sessions_are_two_sessions_however_many_files_they_took() { + let mut seen: HashMap = HashMap::new(); + for (id, file) in [("s-1", "a"), ("s-1", "b"), ("s-2", "c")] { + seen.extend(rollout_records(&one_session(id), file)); + } + let (_, sessions) = merge_days(seen); + assert_eq!(sessions, 2); + } + + #[test] + fn a_window_is_named_by_how_long_it_is() { + assert_eq!(window_name(Some(7.0 * 86400.0)), "7d"); + assert_eq!(window_name(Some(5.0 * 3600.0)), "5h"); + // No length published is a question mark, not a zero. + assert_eq!(window_name(None), "?"); + assert_eq!(window_name(Some(0.0)), "?"); + } + + #[test] + fn a_named_feature_lane_keeps_only_its_last_segment() { + // GPT-5.3-Codex-Spark is Spark: the family name is already implied by + // the tab it is sitting on. + let d = Data { + live: Some( + serde_json::from_str( + r#"{"plan_type":"pro", + "rate_limit":{ + "primary_window":{"used_percent":26.0,"limit_window_seconds":604800,"reset_at":1000}, + "secondary_window":{"used_percent":4.5,"limit_window_seconds":18000,"reset_at":2000}}, + "additional_rate_limits":[ + {"limit_name":"GPT-5.3-Codex-Spark", + "rate_limit":{"primary_window":{"used_percent":12.0,"limit_window_seconds":86400,"reset_at":3000}}}]}"#, + ) + .expect("a live reading"), + ), + ..Data::default() + }; + let got = lanes(&d); + let labels: Vec<&str> = got.iter().map(|l| l.label.as_str()).collect(); + assert_eq!(labels, vec!["7d", "5h", "Spark 1d"]); + assert_eq!(got[0].pct, 26.0); + assert_eq!(got[2].window_secs, Some(86400.0)); + assert_eq!(got[2].reset, Some(3000.0)); + // Live is live: nothing here is a cached reading. + assert!(got.iter().all(|l| !l.stale)); + } + + #[test] + fn a_window_with_no_percentage_is_not_a_lane() { + // The percentage is the only number on the row that cannot be worked + // out from the others, so a window without one has nothing to say. + let d = Data { + live: Some( + serde_json::from_str( + r#"{"rate_limit":{ + "primary_window":{"limit_window_seconds":604800}, + "secondary_window":{"used_percent":4.5,"limit_window_seconds":18000}}, + "additional_rate_limits":[ + {"limit_name":"Spark","rate_limit":{"primary_window":{}}}]}"#, + ) + .expect("a live reading"), + ), + ..Data::default() + }; + let got = lanes(&d); + assert_eq!(got.len(), 1); + assert_eq!(got[0].label, "5h"); + } + + #[test] + fn an_agent_that_answered_nothing_publishes_no_lanes() { + assert!(lanes(&Data::default()).is_empty()); + } + + #[test] + fn the_snapshot_stands_in_only_when_the_live_call_answered_nothing() { + let p = palette(); + let d = Data { + limits: Some( + serde_json::from_str( + r#"{"primary":{"used_percent":71.0,"window_minutes":10080}}"#, + ) + .expect("a snapshot"), + ), + ..Data::default() + }; + let rows = codex_quota(&d, 90, &p).join(" "); + assert!(rows.contains("from the last session"), "{}", rows); + assert!(rows.contains("71%"), "{}", rows); + // But it never reaches the summary screen, which ranks agents against + // each other and would sort a day-old figure beside live ones. + assert!(lanes(&d).is_empty()); + } + + #[test] + fn a_snapshot_without_a_percentage_draws_nothing_rather_than_crashing() { + let p = palette(); + let d = Data { + limits: Some( + serde_json::from_str(r#"{"primary":{"window_minutes":10080}}"#).expect("a snapshot"), + ), + ..Data::default() + }; + assert!(codex_quota(&d, 90, &p).is_empty()); + } + + #[test] + fn a_plan_nobody_published_is_left_out_rather_than_called_unknown() { + let p = palette(); + assert!(codex_plan_rows(&Data::default(), 90, &p).is_empty()); + let d = Data { + live: Some( + serde_json::from_str(r#"{"plan_type":"pro","credits":{"balance":12.5}}"#) + .expect("a live reading"), + ), + ..Data::default() + }; + let rows = codex_plan_rows(&d, 90, &p).join(" "); + assert!(rows.contains("pro"), "{}", rows); + // A balance is a number, and quotes around it are not part of one. + assert!(rows.contains("12.5"), "{}", rows); + } + + #[test] + fn every_section_draws_at_every_pane_width() { + // The tab adapts rather than truncates - two columns of totals + // become one, a spelled-out feature name becomes its last segment, + // and the histogram fills whatever line it is given. Each of those + // is arithmetic on a width, and each is a place a narrow pane has + // put a widget on the floor before. + let p = palette(); + let cfg = Config::default(); + let seen = rollout_records(&one_session("s-1"), "a.jsonl"); + let (daily, sessions) = merge_days(seen); + let d = Data { + ok: true, + live: Some( + serde_json::from_str( + r#"{"plan_type":"pro", + "credits":{"balance":40}, + "rate_limit":{ + "primary_window":{"used_percent":26.0,"limit_window_seconds":604800}, + "secondary_window":{"used_percent":4.5,"limit_window_seconds":18000}}, + "additional_rate_limits":[ + {"limit_name":"GPT-5.3-Codex-Spark", + "rate_limit":{"primary_window":{"used_percent":12.0,"limit_window_seconds":18000}}}]}"#, + ) + .expect("a live reading"), + ), + sessions, + files: 2, + last: now() - 60.0, + total: codex_totals(&daily), + rates: vec![12.0, 40.0, 55.0, 61.0], + daily, + ..Data::default() + }; + for w in [20usize, 40, 80, 200] { + let rows = tab(&d, w, 40, &cfg, &p); + let plain = rows.join("\n"); + for want in ["QUOTA", "TOTALS", "OUTPUT RATE", "TOKENS / DAY", "SUBSCRIPTION"] { + assert!(plain.contains(want), "{} missing at width {}", want, w); + } + } + // Wide, the feature is spelled out; narrow, its last segment carries + // it, because the alternative is a bar with nowhere to be drawn. + let wide = codex_quota(&d, 200, &p).join("\n"); + assert!(wide.contains("GPT-5.3-Codex-Spark"), "{}", wide); + let narrow = codex_quota(&d, 60, &p).join("\n"); + assert!(!narrow.contains("GPT-5.3-Codex-Spark"), "{}", narrow); + assert!(narrow.contains("Spark"), "{}", narrow); + // With a named lane beside them, the account's own windows say what + // they cover rather than leaving "7d" to stand alone. + assert!(narrow.contains("overall"), "{}", narrow); + } + + #[test] + fn a_machine_with_no_rollouts_still_shows_the_account_quota() { + // The quota is the account's and is true whatever is on this disk, so + // an empty sessions directory hides the local half and nothing else. + let p = palette(); + let cfg = Config::default(); + let d = Data { + live: Some( + serde_json::from_str( + r#"{"plan_type":"pro","rate_limit":{"primary_window": + {"used_percent":26.0,"limit_window_seconds":604800}}}"#, + ) + .expect("a live reading"), + ), + ..Data::default() + }; + let rows = tab(&d, 90, 40, &cfg, &p).join(" "); + assert!(rows.contains("QUOTA"), "{}", rows); + assert!(rows.contains("No session rollouts"), "{}", rows); + assert!(!rows.contains("TOTALS"), "{}", rows); + } } From 60defa320aa2b350c79994a6916b0eb5bb94847c Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sun, 23 Aug 2026 18:33:56 +0800 Subject: [PATCH 034/147] usage: read Antigravity The quota comes from the language server on loopback - /proc gives the processes, their socket fds give inodes, /proc/net/tcp turns inodes into listening ports - and the tier from loadCodeAssist over TLS with the OAuth token on curl's stdin. The loopback call carries an empty body and no token, so plain HTTP there is the protocol the listener speaks, not a downgrade of anything secret. Activity comes from conversations/*.db, opened SQLITE_OPEN_READ_ONLY against a live agent's working state, with a 250ms busy timeout rather than the implicit 5s: blocking a poll thread for seconds per database to spare one number would cost every other number on the wall. Where this stops matching usage.py, and why: - A locked conversation was silently dropped from the sum and the partial was presented as a total, so nine busy conversations rendered as "agent steps 0" - an idle agent and an unreadable one looked the same. sessions and counted are now separate: all readable gives a plain total, some gives the total plus an amber "7 of 9 readable" that shortens rather than clips, none gives an em dash. The mtime is still read before the query, so a conversation too busy to count still proves the agent ran. - quota_lanes did split()[0] on a display name, which raises IndexError on a whitespace-only name from inside the summary screen. Twenty tests. The SQLite ones build their own database in a temp file; one asserts a missing path returns nothing rather than being created, which is the behavioural point of opening read-only. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/widgets/src/bin/usage/antigravity.rs | 962 +++++++++++++++++++++- 1 file changed, 938 insertions(+), 24 deletions(-) diff --git a/rust/widgets/src/bin/usage/antigravity.rs b/rust/widgets/src/bin/usage/antigravity.rs index c17f8a9..7b15ede 100644 --- a/rust/widgets/src/bin/usage/antigravity.rs +++ b/rust/widgets/src/bin/usage/antigravity.rs @@ -16,44 +16,958 @@ //! Antigravity: its conversation databases and the Code Assist quota. //! -//! Not read yet. Every function here is honest about that rather than -//! returning a plausible zero, which is the rule the whole widget follows -//! for an agent that publishes nothing. +//! Nothing here is a token count, because Antigravity records none. The +//! conversation stores hold steps the agent took, the history file holds +//! prompts typed, and the only percentages on the tab come from a language +//! server that exists in memory while the agent runs and is gone after. +use std::collections::HashSet; +use std::time::Duration; + +use rusqlite::{Connection, OpenFlags}; use toys_core as tc; use crate::shared::*; use crate::*; +/// Where the CLI keeps everything: its token, its conversations and the +/// prompt history. Also the only proof the agent is installed, since it is +/// launched by the IDE and puts no binary on PATH. +fn antigravity_dir() -> String { + under_home(".gemini/antigravity-cli") +} + +fn token_path() -> String { + format!("{}/antigravity-oauth-token", antigravity_dir()) +} + +const CODE_ASSIST_API: &str = "https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist"; + +/// The Connect method the language server answers the quota on. +const ANTIGRAVITY_RPC: &str = + "/exa.language_server_pb.LanguageServerService/RetrieveUserQuotaSummary"; + +/// How long each window the server names actually is. It reports the name +/// and the fraction left but not the span, and without the span there is no +/// pace to compare a fill against. +const ANTIGRAVITY_WINDOWS: &[(&str, f64)] = &[("weekly", 7.0 * 86400.0), ("5h", 5.0 * 3600.0)]; + +fn window_secs(name: &str) -> Option { + ANTIGRAVITY_WINDOWS + .iter() + .find(|(k, _)| *k == name) + .map(|(_, s)| *s) +} + +/// What Antigravity has recorded here, and what its server says is left. #[derive(Clone, Default)] -pub struct Data {} +pub struct Data { + /// Which Code Assist tier the account is on. `None` means the call did + /// not happen or did not answer, which the tab says out loud. + live: Option, + /// The quota groups, empty when the language server is not running. + quota: Vec, + /// How the CLI authenticated. Read once here rather than per frame: + /// the tab is redrawn on every keypress and this is a file on disk. + auth: String, + /// Conversation databases found. + sessions: usize, + /// How many of them answered. A database a running agent has locked is + /// not a database with no steps in it, so the two are counted apart. + counted: usize, + steps: f64, + prompts: usize, + last: f64, +} + +/// Whether a command line belongs to Antigravity's language server. +/// +/// The same match the Python makes with a regex, written out: `agy` or +/// `antigravity` at the very start of the line or straight after a path +/// separator, or `language_server` anywhere. Anchoring to the executable +/// keeps a process that merely names Antigravity in an argument - a grep, +/// an editor with the file open - from having its sockets probed. +fn is_language_server(cmd: &str) -> bool { + if cmd.contains("language_server") { + return true; + } + let bytes = cmd.as_bytes(); + for name in ["agy", "antigravity"] { + let mut at = 0usize; + while let Some(found) = cmd[at..].find(name) { + let start = at + found; + let end = start + name.len(); + let anchored = start == 0 || bytes[start - 1] == b'/'; + let bounded = match bytes.get(end) { + None => true, + Some(c) => !c.is_ascii_alphanumeric() && *c != b'_', + }; + if anchored && bounded { + return true; + } + at = start + 1; + } + } + false +} -pub fn read(_caches: &mut Caches) -> Data { - Data::default() +/// Listening sockets in a /proc/net/tcp table that belong to us. +/// +/// State 0A is LISTEN, column 9 is the socket inode, and the local address +/// carries the port as hex after the colon. Split out from the reading so +/// the parse can be tested against a table nobody's machine has to have. +fn listening_ports(table: &str, inodes: &HashSet) -> Vec { + let mut out = Vec::new(); + for row in table.lines().skip(1) { + let cols: Vec<&str> = row.split_whitespace().collect(); + if cols.len() <= 9 || cols[3] != "0A" || !inodes.contains(cols[9]) { + continue; + } + if let Some(hex) = cols[1].split(':').nth(1) { + if let Ok(port) = u16::from_str_radix(hex, 16) { + out.push(port); + } + } + } + out +} + +/// TCP ports the running Antigravity language server listens on. +/// +/// The quota never reaches disk, but the process holding it serves an RPC +/// on localhost, so the port is the way in. Found by matching the process +/// then reading its listening sockets out of /proc - no lsof, no guessing +/// at a range, and nothing touched but our own machine. +fn antigravity_ports() -> Vec { + let mut inodes: HashSet = HashSet::new(); + for entry in std::fs::read_dir("/proc").into_iter().flatten().flatten() { + let pid = entry.file_name().to_string_lossy().to_string(); + if pid.is_empty() || !pid.chars().all(|c| c.is_ascii_digit()) { + continue; + } + let Ok(raw) = std::fs::read(format!("/proc/{}/cmdline", pid)) else { + continue; + }; + let cmd = String::from_utf8_lossy(&raw).replace('\0', " "); + if !is_language_server(&cmd) { + continue; + } + // Another user's file descriptors are not readable, and that is not + // an error worth reporting - it is simply not our process. + for fd in std::fs::read_dir(format!("/proc/{}/fd", pid)) + .into_iter() + .flatten() + .flatten() + { + let Ok(target) = std::fs::read_link(fd.path()) else { + continue; + }; + if let Some(rest) = target.to_string_lossy().strip_prefix("socket:[") { + inodes.insert(rest.trim_end_matches(']').to_string()); + } + } + } + if inodes.is_empty() { + return Vec::new(); + } + let mut ports: Vec = Vec::new(); + for table in ["/proc/net/tcp", "/proc/net/tcp6"] { + let Ok(body) = std::fs::read_to_string(table) else { + continue; + }; + ports.extend(listening_ports(&body, &inodes)); + } + ports.sort_unstable(); + ports.dedup(); + ports +} + +/// Weekly and five-hour limits, from the language server on localhost. +/// +/// The same figures Antigravity's own TUI prints. It speaks Connect over +/// plain HTTP on a loopback port - its TLS listener answers with a wrong +/// version number, so http is not a downgrade here, it is the protocol - +/// and the call leaves this machine no more than reading a file would. +/// +/// Found by reading how CodexBar does it (github.com/steipete/CodexBar), +/// after chasing the Google endpoint in the binary to a 404: the quota was +/// never a remote call to make, it was a local one. +fn antigravity_quota() -> Option { + for port in antigravity_ports() { + let url = format!("http://127.0.0.1:{}{}", port, ANTIGRAVITY_RPC); + let Some(got) = post_json(&url, &[("Content-Type", "application/json")], "{}", 5) else { + continue; + }; + // Some builds wrap the payload and some do not, so an envelope is + // only unwrapped when it actually holds something. + let body = if got["response"].as_object().is_some_and(|o| !o.is_empty()) { + &got["response"] + } else { + &got + }; + // Anything else answering on a matched port is not this server, so + // the loop keeps going rather than settling for an empty reply. + if let Some(groups) = body["groups"].as_array() { + if !groups.is_empty() { + return Some(serde_json::Value::Array(groups.clone())); + } + } + } + None +} + +/// Which Code Assist tier the account is on. +/// +/// Antigravity keeps no quota and no token counts on disk - its language +/// server refreshes a quota into memory and is not even installed between +/// runs - so this endpoint is the only thing that can answer anything, and +/// what it answers is the subscription rather than the spend. +/// +/// The access token expires hourly and Antigravity refreshes it; an expired +/// one is skipped rather than refreshed here, for the same reason Claude's +/// is: that is the CLI's job and racing it would be rude. +fn antigravity_live() -> Option { + let file = read_json(&token_path())?; + let tok = &file["token"]; + let access = text(tok, "access_token"); + let expiry = iso_epoch(&text(tok, "expiry")); + if access.is_empty() || expiry.is_some_and(|at| at <= now()) { + return None; + } + post_json( + CODE_ASSIST_API, + &[ + ("Authorization", &format!("Bearer {}", access)), + ("Content-Type", "application/json"), + // Google gates this response on the client string. Sent as + // plain terminal-toys it answers UNSUPPORTED_CLIENT and returns + // no tier at all; the parenthesised form is the conventional way + // to name the client being spoken for while still saying who is + // actually calling. + ("User-Agent", "terminal-toys (antigravity-cli)"), + ], + "{\"metadata\":{\"pluginType\":\"GEMINI\"}}", + 20, + ) +} + +/// How many steps one conversation store records, or nothing if it would +/// not open. +/// +/// Read-only on purpose: these are a live agent's working state, and this +/// widget has no business being able to write to them. A busy database +/// waits briefly and then gives up - the pane refreshes on a clock, so +/// blocking a poll for seconds to spare one number would cost every other +/// number on the wall. +fn conversation_steps(path: &str) -> Option { + let con = Connection::open_with_flags(path, OpenFlags::SQLITE_OPEN_READ_ONLY).ok()?; + con.busy_timeout(Duration::from_millis(250)).ok()?; + let count: i64 = con + .query_row("select count(*) from steps", [], |row| row.get(0)) + .ok()?; + Some(count as f64) +} + +/// What the conversation stores record, which is activity and not cost. +/// +/// Each conversation is its own SQLite file with a `steps` table - one row +/// per step the agent took - so the counts are real work done. No table +/// anywhere carries a token count. +pub fn read(caches: &mut Caches) -> Data { + use std::os::unix::fs::MetadataExt; + let mut d = Data { + live: cached(caches, "antigravity", PLAN_TTL, antigravity_live), + quota: cached(caches, "antigravity-quota", LIVE_TTL, antigravity_quota) + .and_then(|got| got.as_array().cloned()) + .unwrap_or_default(), + auth: read_json(&token_path()) + .map(|file| text(&file, "auth_method")) + .unwrap_or_default(), + ..Data::default() + }; + let mut files: Vec = std::fs::read_dir(format!("{}/conversations", antigravity_dir())) + .into_iter() + .flatten() + .flatten() + .map(|entry| entry.path().to_string_lossy().to_string()) + .filter(|path| path.ends_with(".db")) + .collect(); + files.sort(); + d.sessions = files.len(); + for path in &files { + let Ok(meta) = std::fs::metadata(path) else { + continue; + }; + // The timestamp is taken before the query, so a conversation too + // busy to count still proves the agent ran. + d.last = d.last.max(meta.mtime() as f64); + if let Some(steps) = conversation_steps(path) { + d.steps += steps; + d.counted += 1; + } + } + let history = format!("{}/history.jsonl", antigravity_dir()); + if let Ok(body) = std::fs::read_to_string(&history) { + d.prompts = body.lines().filter(|line| !line.trim().is_empty()).count(); + if let Ok(meta) = std::fs::metadata(&history) { + d.last = d.last.max(meta.mtime() as f64); + } + } + d } /// Every quota this agent publishes, for the summary screen. -pub fn lanes(_d: &Data) -> Vec { - Vec::new() +/// +/// Grouped by model family on the tab, flattened here: the summary compares +/// lanes across agents, and "gemini weekly" says which family it is without +/// the group heading the tab can afford. +/// +/// Never marked stale. The language server answers only while Antigravity +/// is running and this reading is at most one refresh old, so unlike a +/// file-backed cache there is no old number here to warn about. +pub fn lanes(d: &Data) -> Vec { + let mut out = Vec::new(); + for group in &d.quota { + let display = text(group, "displayName"); + let short = display + .split_whitespace() + .next() + .unwrap_or("?") + .to_lowercase(); + for bucket in group["buckets"].as_array().into_iter().flatten() { + let Some(left) = bucket["remainingFraction"].as_f64() else { + continue; + }; + let window = match text(bucket, "window") { + s if s.is_empty() => "?".to_string(), + s => s, + }; + out.push(Lane { + label: format!("{} {}", short, window), + pct: 100.0 * (1.0 - left), + window_secs: window_secs(&window), + reset: iso_epoch(&text(bucket, "resetTime")), + stale: false, + }); + } + } + out } -pub fn tab(_d: &Data, w: usize, _h: usize, _cfg: &Config, p: &Palette) -> Vec { - let mut rows = vec![ - tc::seg( - &[ - (p.lbl.as_str(), " ── ANTIGRAVITY ── ".into()), - (p.dim.as_str(), "no reader in this build yet".into()), - ], - w - 1, - ), - String::new(), +/// One bar per limit, grouped by the model family it covers. +/// +/// Shown as spent rather than the remaining fraction the RPC returns, so +/// red means the same here as on every other tab. Every plan reports every +/// family it covers, so a Gemini-only account still gets a Claude/GPT pair +/// sitting at 0% - they are real limits, not padding, and are left in. +fn antigravity_quota_rows(groups: &[serde_json::Value], w: usize, p: &Palette) -> Vec { + if groups.is_empty() { + return Vec::new(); + } + // The long form names where the number comes from, which matters here + // more than elsewhere; the short one still says it is not this machine's + // own tally. Shortened before it can clip, as the other headers are. + let mut note = " · account-wide, from the local language server"; + for shorter in [" · from the local server", " · local"] { + if 13 + "live".len() + note.chars().count() <= w.saturating_sub(1) { + break; + } + note = shorter; + } + let hue = agent_hue("antigravity"); + let mut rows = vec![tc::seg( + &[ + (p.lbl.as_str(), " ── QUOTA ── ".into()), + (p.ok.as_str(), "live".into()), + (p.dim.as_str(), note.into()), + ], + w - 1, + )]; + for group in groups { + let buckets: Vec<&serde_json::Value> = group["buckets"] + .as_array() + .into_iter() + .flatten() + .filter(|b| b["remainingFraction"].as_f64().is_some()) + .collect(); + if buckets.is_empty() { + continue; + } + let name = match text(group, "displayName") { + s if s.is_empty() => "?".to_string(), + s => s, + }; + rows.push(tc::seg(&[(p.txt.as_str(), format!(" {}", name))], w - 1)); + let windows: Vec = buckets + .iter() + .map(|b| match text(b, "window") { + s if s.is_empty() => "?".to_string(), + s => s, + }) + .collect(); + let label_w = windows.iter().map(|s| s.chars().count()).max().unwrap_or(1); + for (bucket, window) in buckets.iter().zip(&windows) { + let pct = 100.0 * (1.0 - bucket["remainingFraction"].as_f64().unwrap_or(0.0)); + let used = (pct / 100.0).clamp(0.0, 1.0); + let secs = window_secs(window); + let reset = iso_epoch(&text(bucket, "resetTime")); + let mut when = match reset { + None => String::new(), + Some(at) if at - now() > 0.0 => format!("resets in {}", left_span(at - now())), + Some(_) => "resetting".to_string(), + }; + let mut room = w as i64 - 36 - label_w as i64; + if room < 8 { + // Below the bar's floor the row cannot shrink further, so the + // reset stands down rather than being cut in half. + when = String::new(); + room = w as i64 - 20 - label_w as i64; + } + let mut line: Vec<(String, String)> = vec![( + p.dim.clone(), + format!(" {} ", tc::pad(window, label_w)), + )]; + line.extend(paced_bar( + used, + elapsed_of(secs, reset), + room.max(8) as usize, + hue, + p, + )); + line.push((pct_colour(pct, hue, p), pct_text(pct))); + let (pace_colour, pace_txt) = pace_cell(lead(pct, secs, reset), p); + line.push((pace_colour, pace_txt)); + line.push((p.dim.clone(), format!(" {}", when))); + let refs: Vec<(&str, String)> = + line.iter().map(|(c, t)| (c.as_str(), t.clone())).collect(); + rows.push(tc::seg(&refs, w - 1)); + } + } + rows.push(String::new()); + rows +} + +fn antigravity_plan_rows(d: &Data, w: usize, p: &Palette) -> Vec { + let live = d.live.clone().unwrap_or(serde_json::Value::Null); + let filled = |v: &serde_json::Value| v.as_object().is_some_and(|o| !o.is_empty()); + if !filled(&live["currentTier"]) && !filled(&live["paidTier"]) { + return Vec::new(); + } + let (cur, paid) = (&live["currentTier"], &live["paidTier"]); + let mut pairs: Vec<(String, String)> = Vec::new(); + for (label, value) in [ + ("code assist tier", text(cur, "id")), + // paidTier is the Google AI subscription behind the account, which + // is a different thing from the Code Assist tier and can disagree + // with it - free-tier here, while the account is on Ultra. Both are + // stated. + ("google ai plan", text(paid, "name")), + ("project", text(&live, "cloudaicompanionProject")), + ("auth", d.auth.clone()), + ] { + if !value.is_empty() { + pairs.push((label.into(), value)); + } + } + // The two tiers can disagree - free-tier beside Google AI Ultra is + // normal, since one is GCP licensing and the other a consumer plan - but + // that is a paragraph the docs can carry, not four lines on every frame. + let headline = match text(cur, "name") { + s if s.is_empty() => text(paid, "name"), + s => s, + }; + plan_rows(&headline, &pairs, w, "", None, "", p) +} + +/// The caveat on the step count, in the longest form that fits. +/// +/// Shortened rather than clipped, for the reason the reset above it is: +/// "from 7 of 9 conversa" is not a shorter sentence, it is a broken one, +/// and this qualifies the one number on the tab that can be incomplete. +fn steps_note(d: &Data, room: i64) -> String { + if d.sessions == d.counted { + return String::new(); + } + let forms = if d.counted == 0 { + [ + format!(" {} conversations, none readable just now", d.sessions), + format!(" none of {} readable", d.sessions), + " unreadable".to_string(), + ] + } else { + [ + format!(" from {} of {} conversations", d.counted, d.sessions), + format!(" {} of {} readable", d.counted, d.sessions), + format!(" {}/{}", d.counted, d.sessions), + ] + }; + let fits = forms + .iter() + .find(|form| form.chars().count() as i64 <= room) + .unwrap_or(&forms[2]); + fits.clone() +} + +/// What this machine recorded: conversations, steps and prompts. +/// +/// Steps are the one number here that can go missing. A conversation the +/// running agent has locked is unreadable rather than empty, so a partial +/// sum says how partial it is and a sum of nothing says nothing - a zero +/// would read as an idle agent, which is the opposite of the truth. +fn antigravity_activity(d: &Data, w: usize, p: &Palette) -> Vec { + let mut rows = vec![tc::seg( + &[ + (p.lbl.as_str(), " ── ACTIVITY ── ".into()), + ( + p.dim.as_str(), + format!( + "local · {}", + if d.last > 0.0 { + format!("last {} ago", ago(d.last)) + } else { + "never run here".to_string() + } + ), + ), + ], + w - 1, + )]; + let steps = if d.counted == 0 && d.sessions > 0 { + "—".to_string() + } else { + format!("{}", d.steps as i64) + }; + let cells = [ + ("conversations", format!("{}", d.sessions), p.txt.as_str()), + ("agent steps", steps, p.agent.as_str()), + ("prompts", format!("{}", d.prompts), p.txt.as_str()), ]; - for line in wrap_text( - "usage.py reads this agent; the Rust port does not yet. Nothing is \ - shown rather than a plausible zero.", - w.saturating_sub(4).max(20), - ) { - rows.push(tc::seg(&[(p.dim.as_str(), format!(" {}", line))], w - 1)); + let label_w = cells.iter().map(|c| c.0.len()).max().unwrap_or(0); + for (label, value, colour) in &cells { + let lead = format!(" {} ", tc::pad(label, label_w)); + let mut line = vec![(p.dim.as_str(), lead.clone()), (*colour, value.clone())]; + // Only the step count can be short of the truth, and it says so + // beside the number rather than in a footnote further down. + let note = match *label { + "agent steps" => steps_note( + d, + w as i64 - 1 - lead.chars().count() as i64 - value.chars().count() as i64, + ), + _ => String::new(), + }; + if !note.is_empty() { + line.push((p.warn.as_str(), note)); + } + rows.push(tc::seg(&line, w - 1)); } + rows.push(String::new()); rows } + +fn antigravity_body(d: &Data, w: usize, p: &Palette) -> Vec { + let mut rows = antigravity_quota_rows(&d.quota, w, p); + if d.live.is_none() { + rows.push(tc::seg( + &[( + p.warn.as_str(), + " no tier: the CLI's access token has expired or the call failed".into(), + )], + w - 1, + )); + rows.push(String::new()); + } + rows.extend(antigravity_activity(d, w, p)); + // The absence is only worth explaining while it is one. With the quota + // drawn above, a paragraph about why there is no quota contradicts the + // screen. + rows.extend(no_local( + if d.quota.is_empty() { + "No tokens are recorded locally, and no quota either: it comes \ + from the language server while Antigravity is running, so start \ + it and this fills in." + } else { + "No per-token usage is recorded locally - the conversations and \ + steps above are what there is." + }, + "", + w, + p, + )); + rows +} + +/// The whole tab: what is left of the limits, what this machine did, and +/// which subscription the percentages are percentages of. +pub fn tab(d: &Data, w: usize, _h: usize, _cfg: &Config, p: &Palette) -> Vec { + add_section(antigravity_body(d, w, p), antigravity_plan_rows(d, w, p)) +} + +#[cfg(test)] +mod tests { + use super::*; + + /// A conversation store built here rather than found on this machine: + /// the schema is the whole assertion, and a real one belongs to a live + /// agent. + fn temp_db(tag: &str, steps: usize, table: &str) -> String { + let unique = std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .map(|d| d.as_nanos()) + .unwrap_or(0); + let path = std::env::temp_dir().join(format!( + "toys-antigravity-{}-{}-{}.db", + tag, + std::process::id(), + unique + )); + let name = path.to_string_lossy().to_string(); + let con = Connection::open(&name).expect("a temp database"); + con.execute(&format!("create table {} (id integer primary key)", table), []) + .expect("the schema"); + for i in 0..steps { + con.execute(&format!("insert into {} (id) values (?1)", table), [i as i64]) + .expect("a row"); + } + drop(con); + name + } + + fn groups(fractions: &[(&str, &str, f64)]) -> Vec { + let mut out: Vec = Vec::new(); + for (family, window, left) in fractions { + let bucket = serde_json::json!({ + "window": window, + "remainingFraction": left, + "resetTime": "2099-01-01T00:00:00Z", + }); + match out + .iter_mut() + .find(|g| text(g, "displayName") == *family) + { + Some(g) => g["buckets"].as_array_mut().unwrap().push(bucket), + None => out.push(serde_json::json!({ + "displayName": family, + "buckets": [bucket], + })), + } + } + out + } + + #[test] + fn the_steps_table_is_counted_from_a_database_we_built() { + let path = temp_db("counts", 7, "steps"); + assert_eq!(conversation_steps(&path), Some(7.0)); + let _ = std::fs::remove_file(&path); + } + + #[test] + fn a_database_that_is_not_there_is_unknown_rather_than_created() { + // The point of opening read-only: a missing path must not become an + // empty database that then reports zero steps for ever after. + let missing = std::env::temp_dir().join(format!( + "toys-antigravity-absent-{}.db", + std::process::id() + )); + let name = missing.to_string_lossy().to_string(); + assert_eq!(conversation_steps(&name), None); + assert!(!missing.exists()); + } + + #[test] + fn a_store_without_a_steps_table_counts_as_unreadable_not_as_zero() { + let path = temp_db("noschema", 3, "notes"); + assert_eq!(conversation_steps(&path), None); + let _ = std::fs::remove_file(&path); + } + + #[test] + fn a_conversation_that_would_not_open_leaves_the_step_count_unknown() { + let p = palette(); + let d = Data { + sessions: 3, + counted: 0, + steps: 0.0, + last: now() - 60.0, + ..Data::default() + }; + let shown = antigravity_activity(&d, 90, &p).join(" "); + assert!(shown.contains("—"), "an unknown count is not a zero"); + assert!(shown.contains("3 conversations, none readable just now")); + } + + #[test] + fn the_caveat_shortens_rather_than_being_cut_in_half() { + let d = Data { + sessions: 9, + counted: 7, + ..Data::default() + }; + assert_eq!(steps_note(&d, 80), " from 7 of 9 conversations"); + assert_eq!(steps_note(&d, 20), " 7 of 9 readable"); + assert_eq!(steps_note(&d, 8), " 7/9"); + // Narrower than any form: the shortest still says 7 of 9, which is + // the part that must survive. + assert_eq!(steps_note(&d, 1), " 7/9"); + let whole = Data { + sessions: 9, + counted: 9, + ..Data::default() + }; + assert_eq!(steps_note(&whole, 4), ""); + // Nothing found is not something unreadable. + assert_eq!(steps_note(&Data::default(), 80), ""); + } + + #[test] + fn a_narrow_pane_keeps_the_caveat_whole() { + let p = palette(); + let d = Data { + sessions: 9, + counted: 7, + steps: 1234.0, + ..Data::default() + }; + let shown = antigravity_activity(&d, 44, &p).join(" "); + assert!(!shown.contains("conversa "), "a clipped word is a broken one"); + assert!(shown.contains("7 of 9 readable")); + } + + #[test] + fn a_partial_step_count_says_how_partial_it_is() { + let p = palette(); + let d = Data { + sessions: 9, + counted: 7, + steps: 1234.0, + ..Data::default() + }; + let shown = antigravity_activity(&d, 90, &p).join(" "); + assert!(shown.contains("1234")); + assert!(shown.contains("from 7 of 9 conversations")); + assert!(shown.contains("never run here")); + } + + #[test] + fn a_complete_step_count_carries_no_caveat() { + let p = palette(); + let d = Data { + sessions: 2, + counted: 2, + steps: 40.0, + prompts: 5, + ..Data::default() + }; + let shown = antigravity_activity(&d, 90, &p).join(" "); + assert!(shown.contains("40")); + assert!(!shown.contains("of 2 conversations")); + } + + #[test] + fn every_bucket_of_every_group_becomes_one_lane() { + let d = Data { + quota: groups(&[ + ("Gemini 3 Pro", "weekly", 0.25), + ("Gemini 3 Pro", "5h", 1.0), + ("Claude Sonnet 4.5", "weekly", 0.5), + ]), + ..Data::default() + }; + let found = lanes(&d); + assert_eq!(found.len(), 3); + assert_eq!(found[0].label, "gemini weekly"); + assert!((found[0].pct - 75.0).abs() < 1e-9); + assert_eq!(found[0].window_secs, Some(7.0 * 86400.0)); + assert_eq!(found[1].label, "gemini 5h"); + assert_eq!(found[1].pct, 0.0); + assert_eq!(found[2].label, "claude weekly"); + assert!(found.iter().all(|l| !l.stale)); + assert!(found.iter().all(|l| l.reset.is_some())); + } + + #[test] + fn a_bucket_with_no_fraction_is_left_out_rather_than_read_as_full() { + let d = Data { + quota: vec![serde_json::json!({ + "displayName": "Gemini 3 Pro", + "buckets": [ + {"window": "weekly"}, + {"window": "5h", "remainingFraction": 0.9}, + ], + })], + ..Data::default() + }; + let found = lanes(&d); + assert_eq!(found.len(), 1); + assert_eq!(found[0].label, "gemini 5h"); + } + + #[test] + fn a_group_names_itself_once_and_its_windows_underneath() { + let p = palette(); + let rows = antigravity_quota_rows( + &groups(&[ + ("Gemini 3 Pro", "weekly", 0.25), + ("Gemini 3 Pro", "5h", 0.996), + ("Claude Sonnet 4.5", "weekly", 1.0), + ]), + 96, + &p, + ); + let shown = rows.join("\n"); + assert_eq!(shown.matches("Gemini 3 Pro").count(), 1); + assert!(shown.contains("Claude Sonnet 4.5")); + assert!(shown.contains("QUOTA")); + // Spent, not remaining: a quarter left is three quarters gone. + assert!(shown.contains("75%")); + // A real small number and no number at all have to be tellable apart. + assert!(shown.contains("0.40%")); + } + + #[test] + fn a_group_with_nothing_measurable_in_it_is_skipped() { + let p = palette(); + let rows = antigravity_quota_rows( + &[serde_json::json!({"displayName": "GPT", "buckets": []})], + 96, + &p, + ); + // The header and its blank line, and no group heading between them. + assert_eq!(rows.len(), 2); + assert!(!rows[0].contains("GPT")); + } + + #[test] + fn the_source_note_shortens_before_it_can_clip() { + let p = palette(); + let quota = groups(&[("Gemini 3 Pro", "weekly", 0.5)]); + let wide = antigravity_quota_rows("a, 120, &p)[0].clone(); + let narrow = antigravity_quota_rows("a, 60, &p)[0].clone(); + let tight = antigravity_quota_rows("a, 30, &p)[0].clone(); + assert!(wide.contains("from the local language server")); + assert!(narrow.contains("from the local server")); + assert!(tight.contains("local")); + assert!(!tight.contains("from the local server")); + } + + #[test] + fn no_quota_is_explained_and_a_quota_is_not_contradicted() { + let p = palette(); + let empty = antigravity_body(&Data::default(), 90, &p).join(" "); + assert!(empty.contains("no quota either")); + assert!(empty.contains("no tier")); + let with = antigravity_body( + &Data { + quota: groups(&[("Gemini 3 Pro", "weekly", 0.5)]), + live: Some(serde_json::json!({"currentTier": {"id": "free-tier"}})), + ..Data::default() + }, + 90, + &p, + ) + .join(" "); + assert!(with.contains("No per-token usage is recorded locally")); + assert!(!with.contains("no quota either")); + assert!(!with.contains("no tier")); + } + + #[test] + fn the_subscription_states_both_tiers_when_they_disagree() { + let p = palette(); + let d = Data { + live: Some(serde_json::json!({ + "currentTier": {"id": "free-tier", "name": "Gemini Code Assist for individuals"}, + "paidTier": {"name": "Google AI Ultra"}, + "cloudaicompanionProject": "example-project", + })), + auth: "oauth-personal".into(), + ..Data::default() + }; + let shown = antigravity_plan_rows(&d, 90, &p).join(" "); + assert!(shown.contains("Gemini Code Assist for individuals")); + assert!(shown.contains("free-tier")); + assert!(shown.contains("Google AI Ultra")); + assert!(shown.contains("example-project")); + assert!(shown.contains("oauth-personal")); + } + + #[test] + fn no_tier_at_all_draws_no_subscription_block() { + let p = palette(); + assert!(antigravity_plan_rows(&Data::default(), 90, &p).is_empty()); + let hollow = Data { + live: Some(serde_json::json!({"currentTier": {}, "paidTier": {}})), + ..Data::default() + }; + assert!(antigravity_plan_rows(&hollow, 90, &p).is_empty()); + } + + #[test] + fn only_the_executable_counts_as_the_language_server() { + assert!(is_language_server("/opt/example/bin/antigravity --serve")); + assert!(is_language_server("agy chat")); + assert!(is_language_server("/opt/example/language_server_linux_x64")); + // A word boundary, so the hyphenated CLI still matches. + assert!(is_language_server("/opt/example/antigravity-cli")); + // Named in an argument rather than run: not this process. + assert!(!is_language_server("grep -rn antigravity /tmp/notes")); + assert!(!is_language_server("vim antigravity.md")); + assert!(!is_language_server("/opt/example/bin/antigravityish")); + assert!(!is_language_server("/opt/example/bin/agy_helper")); + assert!(!is_language_server("")); + } + + #[test] + fn only_listening_sockets_we_own_yield_a_port() { + // An invented /proc/net/tcp: two listeners and one established + // connection, of which one listener is ours. + let table = "\ + sl local_address rem_address st tx_queue rx_queue tr tm->when retrnsmt uid timeout inode + 0: 0100007F:9C40 00000000:0000 0A 00000000:00000000 00:00000000 00000000 1000 0 4242 + 1: 0100007F:1F90 00000000:0000 0A 00000000:00000000 00:00000000 00000000 1000 0 9999 + 2: 0100007F:9C41 0100007F:D431 01 00000000:00000000 00:00000000 00000000 1000 0 4243 +"; + let mine: HashSet = ["4242", "4243"].iter().map(|s| s.to_string()).collect(); + assert_eq!(listening_ports(table, &mine), vec![40000]); + assert!(listening_ports(table, &HashSet::new()).is_empty()); + } + + #[test] + fn every_section_draws_at_every_pane_width() { + // Two of the three widths here subtract a constant from the pane + // before handing the remainder to a bar, and a pane narrower than + // the constant is exactly how a widget ends up on the floor. + let p = palette(); + let cfg = Config::default(); + let d = Data { + quota: groups(&[ + ("Gemini 3 Pro", "weekly", 0.25), + ("Gemini 3 Pro", "5h", 0.996), + ]), + live: Some(serde_json::json!({ + "currentTier": {"id": "free-tier", "name": "Gemini Code Assist for individuals"}, + "paidTier": {"name": "Google AI Ultra"}, + })), + auth: "oauth-personal".into(), + sessions: 9, + counted: 7, + steps: 1234.0, + prompts: 42, + last: now() - 3600.0, + }; + for w in [20usize, 40, 80, 200] { + let plain = tab(&d, w, 40, &cfg, &p).join("\n"); + for want in ["QUOTA", "ACTIVITY", "SUBSCRIPTION"] { + assert!(plain.contains(want), "{} missing at width {}", want, w); + } + } + } + + #[test] + fn a_window_the_server_does_not_name_has_no_pace() { + assert_eq!(window_secs("weekly"), Some(7.0 * 86400.0)); + assert_eq!(window_secs("5h"), Some(5.0 * 3600.0)); + assert_eq!(window_secs("monthly"), None); + assert_eq!(window_secs("?"), None); + } +} From 2080dfa376c373169e255bc62fcb568a33f5e900 Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sun, 23 Aug 2026 18:34:58 +0800 Subject: [PATCH 035/147] usage: read Grok Two sources that do not overlap: the transcripts under ~/.grok/sessions carry a running totalTokens summed as deltas and bucketed by each event's own timestamp, so a session spanning midnight lands on both days; the quota is not in them at all and comes off the client log. No METERED section, and that is the founding rule rather than an omission - Grok logs one running total with no model on it and no split by priced kind, and input, output and cache differ in price by up to fifty times. A cost computed from that would be a number on screen that nothing backs. Three places usage.py said something untrue on screen: - The on-demand row printed the literal "None" when the server omitted a figure, four lines from a plan row that already defaulted it to zero. - The footer explaining "the quota above is the server's own figure" printed unconditionally, describing a block that is not drawn when there is no quota. - "resets in N days" parsed with fromisoformat while the bar directly below parsed the same field with iso_epoch, so a naive timestamp killed one and not the other. Both use iso_epoch now. A record whose totalTokens event has no timestamp is dropped from the total as well as from the day it cannot name, because the running counter has already advanced past it. That undercounts. It is matched and pinned with a test, so it is deliberate rather than inherited. Eleven tests on inline fixtures. The real files on this machine were checked for shape only - key names and line counts - which is how the period fixture came to carry microseconds and an offset. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/widgets/src/bin/usage/grok.rs | 674 ++++++++++++++++++++++++++++- 1 file changed, 652 insertions(+), 22 deletions(-) diff --git a/rust/widgets/src/bin/usage/grok.rs b/rust/widgets/src/bin/usage/grok.rs index 1cabe5f..226dd56 100644 --- a/rust/widgets/src/bin/usage/grok.rs +++ b/rust/widgets/src/bin/usage/grok.rs @@ -14,46 +14,676 @@ // You should have received a copy of the GNU Affero General Public License // along with this program. If not, see . -//! Grok: its session transcripts, and the quota that arrives on the client log. +//! Grok: what its transcripts spent, and the quota that arrives elsewhere. //! -//! Not read yet. Every function here is honest about that rather than -//! returning a plausible zero, which is the rule the whole widget follows -//! for an agent that publishes nothing. +//! Grok writes a running totalTokens on every session event. Deltas between +//! consecutive events, bucketed by the event's own timestamp, give the +//! per-day figures - the running total alone would credit an entire session +//! to whichever day it happened to be read on. +use std::collections::{HashMap, HashSet}; + +use chrono::{Datelike, NaiveDate, TimeZone, Utc}; use toys_core as tc; use crate::shared::*; use crate::*; +/// Where the CLI keeps its transcripts. Nested a couple of levels down, so +/// it is walked rather than listed. +const SESSIONS: &str = ".grok/sessions"; +/// The quota is not in the session transcripts: it arrives on the client +/// log, which the CLI writes as it talks to the server. +const LOG: &str = ".grok/logs/unified.jsonl"; +/// The credit reading is one line among the client log's chatter and is +/// only rewritten when the server sends a new one, so the tail has to be +/// long enough to still contain one after a busy session. +const LOG_TAIL: u64 = 2 * 1024 * 1024; +/// Namespace for this reader's per-file cache entries, so the prune below +/// can find its own and leave every other reader's alone. +const CACHE: &str = "grok:session:"; + +/// Grok's credit window, as its own CLI receives it. +/// +/// Not hidden and not inferred: the server sends it and the CLI writes it +/// into the log under `.ctx.config`. An earlier pass in the Python +/// concluded no quota existed, having grepped for limit/quota/remaining/ +/// reset - the keys are `creditUsagePercent` and `currentPeriod`, so the +/// search missed them and the tab said so in print for a day. +#[derive(Clone, Default)] +struct Quota { + pct: Option, + kind: String, + start: String, + end: String, + tier: String, + on_demand_used: Option, + on_demand_cap: Option, + prepaid: Option, +} + +/// What the transcripts on this machine recorded, plus the account-wide +/// credit window they say nothing about. #[derive(Clone, Default)] -pub struct Data {} +pub struct Data { + ok: bool, + /// Files that carried a non-zero total, and files looked at. + sessions: usize, + files: usize, + total: f64, + daily: HashMap, + /// Newest transcript mtime, as epoch seconds. + last: f64, + quota: Option, +} + +/// The integer following `key` on a line. +/// +/// The transcripts are one JSON object per event and only two numbers on +/// each are wanted, so the line is scanned rather than parsed. Grok's +/// events carry whole tool results, and building a document out of every +/// one of them to reach two integers costs more than the entire read. +fn int_after(line: &str, key: &str) -> Option { + let at = line.find(key)? + key.len(); + let digits: String = line[at..] + .chars() + .take_while(|c| c.is_ascii_digit()) + .collect(); + digits.parse().ok() +} -pub fn read(_caches: &mut Caches) -> Data { - Data::default() +/// One transcript's spend, as a total and by day. +/// +/// The running counter is followed rather than trusted: a session that +/// resumes replays earlier events, so the count can go backwards, and a +/// decrease is a replay rather than negative usage. Days are UTC because +/// the timestamp is epoch milliseconds and the Python bucketed it that way. +fn session_days(body: &str) -> (f64, HashMap) { + let (mut total, mut prev) = (0.0f64, 0.0f64); + let mut days: HashMap = HashMap::new(); + for line in body.lines() { + let Some(value) = int_after(line, "\"totalTokens\":") else { + continue; + }; + let step = value - prev; + prev = prev.max(value); + if step <= 0.0 { + continue; + } + // A step whose event carries no timestamp is dropped rather than + // banked against whichever day was read last: a calendar that + // invents a day is worse than one that is short by a step. + let Some(ms) = int_after(line, "\"agentTimestampMs\":") else { + continue; + }; + let Some(at) = Utc.timestamp_millis_opt(ms as i64).single() else { + continue; + }; + *days.entry(at.date_naive().to_string()).or_insert(0.0) += step; + total += step; + } + (total, days) +} + +/// A credit figure from the log, which arrives as `{"val": n}`. +/// +/// Read as a number or as a string, because the server writes int64s as +/// strings - JSON has no room for them - and a percentage that arrives +/// quoted would otherwise drop the whole quota block. +fn val_of(value: &serde_json::Value) -> Option { + value.as_f64().or_else(|| value.as_str()?.parse().ok()) +} + +/// The most recent credit reading on the client log. +/// +/// The newest *period* wins rather than the newest line: the log repeats +/// the same window on every exchange, and a line further down describing +/// an older window is a reply that was still in flight. +fn newest_quota<'a>(lines: impl Iterator) -> Option { + let mut best: Option = None; + for line in lines { + // Rejected on a substring first: almost every line of this log is + // something else, and parsing two megabytes of them to find the + // few that carry a credit reading costs more than the read. + if !line.contains("creditUsagePercent") { + continue; + } + let Ok(d) = serde_json::from_str::(line) else { + continue; + }; + let cfg = &d["ctx"]["config"]; + // The key has to be there, but it does not have to hold a number: + // a reading the server sent with a null percentage still names the + // tier and the billing period, and those rows are real. + if !cfg + .as_object() + .is_some_and(|o| o.contains_key("creditUsagePercent")) + { + continue; + } + let period = &cfg["currentPeriod"]; + let got = Quota { + pct: val_of(&cfg["creditUsagePercent"]), + kind: text(period, "type"), + start: text(period, "start"), + end: text(period, "end"), + tier: text(&d["ctx"], "subscriptionTier"), + on_demand_used: val_of(&cfg["onDemandUsed"]["val"]), + on_demand_cap: val_of(&cfg["onDemandCap"]["val"]), + prepaid: val_of(&cfg["prepaidBalance"]["val"]), + }; + let better = match &best { + None => true, + Some(had) => got.start >= had.start, + }; + if better { + best = Some(got); + } + } + best +} + +/// What every transcript here spent, and what the server last said about +/// the account's credits. +pub fn read(caches: &mut Caches) -> Data { + use std::os::unix::fs::MetadataExt; + let mut files = Vec::new(); + walk(&under_home(SESSIONS), "updates.jsonl", &mut files); + if files.is_empty() { + // The log is not read either. The tab this feeds leads with its + // transcripts and stops when there are none, so a credit window + // read here would have nowhere to be drawn. + return Data::default(); + } + let (mut total, mut sessions, mut newest) = (0.0f64, 0usize, 0.0f64); + let mut daily: HashMap = HashMap::new(); + let mut seen: HashSet = HashSet::new(); + for path in &files { + let Ok(meta) = std::fs::metadata(path) else { + continue; + }; + newest = newest.max(meta.mtime() as f64); + // Keyed on the file's own (mtime, size): a transcript that has not + // been appended to cannot have different deltas, and re-reading + // every session on every refresh to learn that is the whole cost + // of this tab. + let key = format!("{}{}:{}:{}", CACHE, path, meta.mtime(), meta.size()); + let got = cached(caches, &key, PLAN_TTL, || { + let (total, days) = session_days(&std::fs::read_to_string(path).ok()?); + Some(serde_json::json!({"total": total, "daily": days})) + }); + seen.insert(key); + let Some(got) = got else { + continue; + }; + let spent = got["total"].as_f64().unwrap_or(0.0); + if spent <= 0.0 { + continue; + } + sessions += 1; + total += spent; + for (day, n) in got["daily"].as_object().into_iter().flatten() { + let Ok(at) = NaiveDate::parse_from_str(day, "%Y-%m-%d") else { + continue; + }; + *daily.entry(at).or_insert(0.0) += n.as_f64().unwrap_or(0.0); + } + } + // What makes a reading safe to trust - that its key names the size and + // mtime it was read at - is also what makes it dead the moment the + // session appends a line. Without this the live session's old readings + // pile up for as long as the pane runs. + caches + .live + .retain(|key, _| !key.starts_with(CACHE) || seen.contains(key)); + Data { + ok: true, + sessions, + files: files.len(), + total, + daily, + last: newest, + quota: newest_quota(tail_lines(&under_home(LOG), LOG_TAIL).iter().map(String::as_str)), + } } /// Every quota this agent publishes, for the summary screen. -pub fn lanes(_d: &Data) -> Vec { - Vec::new() +/// +/// One lane: the credit window is the only allowance Grok states. The +/// window length is offered only when both ends parse and run forwards, +/// but the reset is offered whenever the end does - a countdown is +/// readable without knowing how long the window was. +pub fn lanes(d: &Data) -> Vec { + let Some(q) = d.quota.as_ref() else { + return Vec::new(); + }; + let Some(pct) = q.pct else { + return Vec::new(); + }; + let (begin, end) = (iso_epoch(&q.start), iso_epoch(&q.end)); + vec![Lane { + label: "credits".into(), + pct, + window_secs: match (begin, end) { + (Some(b), Some(e)) if e > b => Some(e - b), + _ => None, + }, + reset: end, + stale: false, + }] } -pub fn tab(_d: &Data, w: usize, _h: usize, _cfg: &Config, p: &Palette) -> Vec { - let mut rows = vec![ - tc::seg( +/// What the server calls this window, in words a reader has met before. +fn period_name(kind: &str) -> String { + if kind.contains("WEEKLY") { + return "weekly".into(); + } + match kind.replace("USAGE_PERIOD_TYPE_", "").to_lowercase() { + s if s.is_empty() => "current".into(), + s => s, + } +} + +/// A date without its year, kept in the offset it arrived in. +/// +/// iso_day is the widget's parser for these and deliberately does not +/// convert to this machine's zone: a billing window that reads a day +/// earlier here than on the vendor's own page is worse than no window at +/// all. The year goes because both ends of a window share it. +fn short_day(s: &str) -> String { + let full = iso_day(s); + match full.rsplit_once(' ') { + Some((day, _year)) => day.to_string(), + None => full, + } +} + +/// A row from owned pairs, which is what paced_bar and the calendar hand +/// back - seg borrows its colours. +fn seg_of(parts: &[(String, String)], w: usize) -> String { + let refs: Vec<(&str, String)> = parts.iter().map(|(c, t)| (c.as_str(), t.clone())).collect(); + tc::seg(&refs, w - 1) +} + +fn grok_tab(d: &Data, w: usize, p: &Palette) -> Vec { + if !d.ok { + return no_local("No Grok sessions on this machine.", run_hint("grok"), w, p); + } + let hue = agent_hue("grok"); + let mut rows: Vec = Vec::new(); + let quota = d.quota.as_ref().filter(|q| q.pct.is_some()); + if let Some(q) = quota { + let pct = q.pct.unwrap_or(0.0); + // The one real remaining-quota figure in this widget: everything + // else here counts what was spent. It leads the tab for that + // reason. + let (begin, end) = (iso_epoch(&q.start), iso_epoch(&q.end)); + let left = end.map(|e| (e - now()) / 86400.0).filter(|days| *days >= 0.0); + rows.push(tc::seg( + &[ + ( + p.lbl.as_str(), + format!(" ── {} QUOTA ── ", period_name(&q.kind).to_uppercase()), + ), + ( + p.dim.as_str(), + left.map(|days| format!("resets in {:.1} days", days)) + .unwrap_or_default(), + ), + ], + w - 1, + )); + // A window is only a window if it runs forwards; without both ends + // there is no pace to report, and a mark placed anyway would be a + // claim about a clock nobody read. + let (span, reset) = match (begin, end) { + (Some(b), Some(e)) if e > b => (Some(e - b), Some(e)), + _ => (None, None), + }; + let mut line: Vec<(String, String)> = vec![( + pct_colour(pct, hue, p), + format!(" {:<5}", format!("{:.0}%", pct)), + )]; + line.extend(paced_bar( + (pct / 100.0).clamp(0.0, 1.0), + elapsed_of(span, reset), + w.saturating_sub(38).max(10), + hue, + p, + )); + line.push((p.dim.clone(), " credits used".into())); + line.push(pace_cell(lead(pct, span, reset), p)); + rows.push(seg_of(&line, w)); + + let (from, to) = (short_day(&q.start), short_day(&q.end)); + let window = if from.is_empty() || to.is_empty() { + "?".to_string() + } else { + format!("{} → {}", from, to) + }; + let mut extras: Vec = Vec::new(); + if let Some(cap) = q.on_demand_cap.filter(|v| *v != 0.0) { + extras.push(format!( + "on-demand {}/{}", + q.on_demand_used.unwrap_or(0.0), + cap + )); + } + if let Some(prepaid) = q.prepaid.filter(|v| *v != 0.0) { + extras.push(format!("prepaid {}", prepaid)); + } + rows.push(tc::seg( + &[ + (p.dim.as_str(), " window ".into()), + (p.txt.as_str(), window), + ( + p.dim.as_str(), + if extras.is_empty() { + String::new() + } else { + format!(" {}", extras.join(" · ")) + }, + ), + ], + w - 1, + )); + rows.push(String::new()); + } + + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── TOTALS ── ".into()), + ( + p.dim.as_str(), + format!("{} sessions · newest {} ago", d.sessions, ago(d.last)), + ), + ], + w - 1, + )); + rows.push(tc::seg( + &[ + (p.dim.as_str(), " tokens ".into()), + (p.agent.as_str(), big_num(d.total)), + ( + p.dim.as_str(), + format!(" across {} session files", d.files), + ), + ], + w - 1, + )); + + if let Some(cal) = day_calendar(&d.daily, w, GROK_STEPS, None, p) { + let peak = d.daily.values().cloned().fold(0.0f64, f64::max); + rows.push(String::new()); + rows.push(tc::seg( &[ - (p.lbl.as_str(), " ── GROK ── ".into()), - (p.dim.as_str(), "no reader in this build yet".into()), + (p.lbl.as_str(), " ── TOKENS / DAY ── ".into()), + (p.dim.as_str(), "peak ".into()), + (p.agent.as_str(), big_num(peak)), + ( + p.dim.as_str(), + format!( + " on {}", + cal.best + .map(|b| format!("{} {}", MONTHS[b.month0() as usize], b.day())) + .unwrap_or_else(|| "--".into()) + ), + ), ], w - 1, - ), - String::new(), - ]; - for line in wrap_text( - "usage.py reads this agent; the Rust port does not yet. Nothing is \ - shown rather than a plausible zero.", - w.saturating_sub(4).max(20), - ) { + )); + for line in &cal.rows { + rows.push(seg_of(line, w)); + } + let mut legend: Vec<(String, String)> = vec![(p.dim.clone(), " Less ".into())]; + legend.extend( + GROK_STEPS + .iter() + .map(|(r, g, b)| (tc::rgb(*r, *g, *b), "█".to_string())), + ); + legend.push((p.dim.clone(), " More".into())); + rows.push(seg_of(&legend, w)); + } + + rows.push(String::new()); + // Where the totals come from, because a running counter summed as + // deltas is not what a reader assumes a token total is. The second + // sentence points at something on screen, so it is only written when + // that something is there. + let mut note = "Totals are a running count per session, summed as deltas so a session \ + spanning days lands on the right one." + .to_string(); + if quota.is_some() { + note.push_str( + " The quota above is the server's own figure, read from the client log - not \ + inferred.", + ); + } + for line in wrap_text(¬e, w.saturating_sub(4).max(20)) { rows.push(tc::seg(&[(p.dim.as_str(), format!(" {}", line))], w - 1)); } rows } + +/// Grok states its tier and the kind of period it bills in, and no more. +/// +/// Both arrive on the client log beside the credit percentage, so this +/// costs nothing extra to show. +fn plan_block(d: &Data, w: usize, p: &Palette) -> Vec { + let Some(q) = d.quota.as_ref() else { + return Vec::new(); + }; + let mut pairs: Vec<(String, String)> = Vec::new(); + let kind = q.kind.replace("USAGE_PERIOD_TYPE_", "").to_lowercase(); + if !kind.is_empty() { + pairs.push(("billing period".into(), kind)); + } + // A cap of zero is still a cap the account has, so this asks whether + // the server sent one rather than whether it is spendable. + if let Some(cap) = q.on_demand_cap { + pairs.push(( + "on-demand".into(), + format!("{} of {} used", q.on_demand_used.unwrap_or(0.0), cap), + )); + } + if let Some(prepaid) = q.prepaid { + pairs.push(("prepaid balance".into(), format!("{}", prepaid))); + } + plan_rows(&q.tier, &pairs, w, "", None, "", p) +} + +/// The whole tab: the credit window, what the transcripts recorded, and +/// which subscription that percentage is a percentage of. +/// +/// No METERED section, unlike the other tabs. Grok's events carry one +/// running total with no model on it and no split by priced kind, and +/// input, output and the two cache durations differ in price by up to +/// fifty times - so a total here cannot be costed at all. +pub fn tab(d: &Data, w: usize, _h: usize, _cfg: &Config, p: &Palette) -> Vec { + add_section(grok_tab(d, w, p), plan_block(d, w, p)) +} + +#[cfg(test)] +mod tests { + use super::*; + + /// A client-log line carrying a credit reading. Invented, but shaped + /// like the real thing down to the microseconds and the numeric offset + /// on the period - a fixture that arrives in a tidier format than the + /// server sends tests a parser nobody has. + const LOG_LINE: &str = concat!( + r#"{"msg":"config","lvl":"info","ctx":{"subscriptionTier":"Test Premium","config":{"#, + r#""creditUsagePercent":42.5,"currentPeriod":{"type":"USAGE_PERIOD_TYPE_WEEKLY","#, + r#""start":"2026-08-10T00:00:00.000000+00:00","#, + r#""end":"2026-08-17T00:00:00.000000+00:00"},"#, + r#""onDemandUsed":{"val":"3"},"onDemandCap":{"val":25},"#, + r#""prepaidBalance":{"val":0}}}}"# + ); + + #[test] + fn the_quota_comes_off_the_log_not_the_transcript() { + // A session event carries a running token count and says nothing + // about credits, which is why the log is read at all. + let event = r#"{"totalTokens":1200,"agentTimestampMs":1755302400000}"#; + assert!(newest_quota([event].into_iter()).is_none()); + let q = newest_quota([LOG_LINE].into_iter()).expect("the log line carries a quota"); + assert_eq!(q.pct, Some(42.5)); + assert_eq!(q.tier, "Test Premium"); + assert_eq!(q.kind, "USAGE_PERIOD_TYPE_WEEKLY"); + } + + #[test] + fn an_int64_written_as_a_string_is_still_a_number() { + // The server quotes what will not fit in a JSON number. Read as + // text these read as absent, and the whole block disappears. + let q = newest_quota([LOG_LINE].into_iter()).expect("the log line carries a quota"); + assert_eq!(q.on_demand_used, Some(3.0)); + assert_eq!(q.on_demand_cap, Some(25.0)); + assert_eq!(q.prepaid, Some(0.0)); + } + + #[test] + fn the_newest_period_wins_whichever_line_it_is_on() { + let older = LOG_LINE + .replace("2026-08-10", "2026-08-03") + .replace("42.5", "90"); + for lines in [ + [older.as_str(), LOG_LINE], + [LOG_LINE, older.as_str()], + ] { + let q = newest_quota(lines.into_iter()).expect("one of the two is newest"); + assert_eq!(q.pct, Some(42.5)); + } + } + + #[test] + fn two_readings_of_one_period_settle_on_the_later_line() { + // Same window, different percentages: the log repeats the window + // on every exchange, so later on the file is later in time. + let earlier = LOG_LINE.replace("42.5", "11"); + let q = newest_quota([earlier.as_str(), LOG_LINE].into_iter()).expect("a quota"); + assert_eq!(q.pct, Some(42.5)); + } + + #[test] + fn a_running_total_is_counted_as_deltas() { + // Two events on one UTC day and one on the next. Summed raw this + // would read 1400 rather than 900, and put all of it on one day. + let body = concat!( + r#"{"totalTokens":100,"agentTimestampMs":1755302400000}"#, + "\n", + r#"{"totalTokens":400,"agentTimestampMs":1755306000000}"#, + "\n", + r#"{"totalTokens":900,"agentTimestampMs":1755388800000}"#, + "\n", + ); + let (total, days) = session_days(body); + assert_eq!(total, 900.0); + assert_eq!(days.get(&day_of(1755302400000)), Some(&400.0)); + assert_eq!(days.get(&day_of(1755388800000)), Some(&500.0)); + } + + #[test] + fn a_counter_that_goes_backwards_is_not_spend() { + // Resuming replays earlier events, so the count can fall. A + // decrease is a replay, and the recovery back to the high-water + // mark is not spend either. + let body = concat!( + r#"{"totalTokens":500,"agentTimestampMs":1755302400000}"#, + "\n", + r#"{"totalTokens":200,"agentTimestampMs":1755302400000}"#, + "\n", + r#"{"totalTokens":600,"agentTimestampMs":1755302400000}"#, + "\n", + ); + assert_eq!(session_days(body).0, 600.0); + } + + #[test] + fn an_event_with_no_timestamp_is_left_out_of_the_day_it_cannot_name() { + let body = concat!( + r#"{"totalTokens":100,"agentTimestampMs":1755302400000}"#, + "\n", + r#"{"totalTokens":700}"#, + "\n", + ); + let (total, days) = session_days(body); + // The 600 has no day to land in, and it leaves the total with it + // rather than being banked against whichever day was read last. + assert_eq!(total, 100.0); + assert_eq!(days.len(), 1); + } + + #[test] + fn the_lane_carries_the_window_it_was_measured_over() { + let d = Data { + ok: true, + quota: newest_quota([LOG_LINE].into_iter()), + ..Default::default() + }; + let got = lanes(&d); + assert_eq!(got.len(), 1); + assert_eq!(got[0].label, "credits"); + assert_eq!(got[0].pct, 42.5); + assert_eq!(got[0].window_secs, Some(7.0 * 86400.0)); + assert_eq!(got[0].reset, iso_epoch("2026-08-17T00:00:00.000000+00:00")); + // Never cached: this was read from a file on this machine a moment + // ago, so counting it down is honest. + assert!(!got[0].stale); + } + + #[test] + fn an_agent_with_no_quota_publishes_no_lane() { + assert!(lanes(&Data::default()).is_empty()); + // Present but percentless: there is no lane to rank, and yet the + // tier and the billing period are still known, so the reading is + // kept for the SUBSCRIPTION block rather than thrown away. + let bare = LOG_LINE.replace(r#""creditUsagePercent":42.5"#, r#""creditUsagePercent":null"#); + let d = Data { + ok: true, + quota: newest_quota([bare.as_str()].into_iter()), + ..Default::default() + }; + assert!(lanes(&d).is_empty()); + assert_eq!(d.quota.as_ref().map(|q| q.tier.as_str()), Some("Test Premium")); + assert!(!plan_block(&d, 80, &palette()).is_empty()); + } + + #[test] + fn the_tab_carries_its_subscription_at_every_width_the_wall_uses() { + // The bar's width is what is left after the labels, and this pane + // is dragged narrow on a phone. A panicking tab takes the whole + // widget with it, and a dropped SUBSCRIPTION leaves a percentage + // that is a percentage of nothing stated. + let p = palette(); + let d = Data { + ok: true, + sessions: 2, + files: 3, + total: 12_345.0, + daily: HashMap::from([(NaiveDate::from_ymd_opt(2026, 8, 16).unwrap(), 900.0)]), + last: now(), + quota: newest_quota([LOG_LINE].into_iter()), + }; + for w in [40usize, 80, 200] { + let rows = tab(&d, w, 24, &Config::default(), &p); + assert!(rows.iter().any(|r| r.contains("WEEKLY QUOTA")), "width {}", w); + assert!(rows.iter().any(|r| r.contains("SUBSCRIPTION")), "width {}", w); + } + } + + #[test] + fn a_period_the_server_did_not_name_is_still_labelled() { + assert_eq!(period_name("USAGE_PERIOD_TYPE_WEEKLY"), "weekly"); + assert_eq!(period_name("USAGE_PERIOD_TYPE_MONTHLY"), "monthly"); + assert_eq!(period_name(""), "current"); + } + + fn day_of(ms: i64) -> String { + Utc.timestamp_millis_opt(ms) + .single() + .expect("a fixed timestamp") + .date_naive() + .to_string() + } +} From f976edb5079282398960186842ece89d86e35f62 Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sun, 23 Aug 2026 18:35:20 +0800 Subject: [PATCH 036/147] usage: read Copilot MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two halves that arrive independently: the account standing from the endpoint the Copilot CLI itself uses, with that CLI's OAuth token read out of ~/.copilot/config.json - which is JSONC, so the comment lines come off before parsing - and the local session store, opened SQLITE_OPEN_READ_ONLY because it is a live agent's working state. quota_window returns the label and the length from one function, so the refusal cannot diverge between them, and it answers only when the reset lands on midnight UTC on the first of a month. Anything else is None, which makes the summary draw no pace mark and the tab show "window —". usage.py refuses only in the display string and then derives the pace span unconditionally anyway, putting a made-up pace figure on screen for every cycle that is not a calendar month - the exact thing that function's own docstring forbids. Two more from the same family: - An unreadable session store rendered as "Nothing recorded yet". It now says the store is unreadable and that what it holds is unknown, not zero, and keeps the SQLite error as the reason. - Rows with a NULL created_at were keyed as the string "None", which sorts above every real date, so undated rows counted into today's metered window for as long as they existed. They are skipped. Fifteen tests. The window ones are the hard half: a month boundary accepted with its length checked against the calendar, including a year-crossing December and a 28-day February, and refusal for the 15th, for 07:00, for 00:30, for 00:00:30 and for epoch zero. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/widgets/src/bin/usage/copilot.rs | 891 +++++++++++++++++++++++++- 1 file changed, 868 insertions(+), 23 deletions(-) diff --git a/rust/widgets/src/bin/usage/copilot.rs b/rust/widgets/src/bin/usage/copilot.rs index b3ef004..8e628b4 100644 --- a/rust/widgets/src/bin/usage/copilot.rs +++ b/rust/widgets/src/bin/usage/copilot.rs @@ -14,46 +14,891 @@ // You should have received a copy of the GNU Affero General Public License // along with this program. If not, see . -//! GitHub Copilot: its session store, and the premium-request pool. +//! GitHub Copilot: the account's premium-request pool, and the local +//! session store. //! -//! Not read yet. Every function here is honest about that rather than -//! returning a plausible zero, which is the rule the whole widget follows -//! for an agent that publishes nothing. +//! The two halves are independent: the quota is the account's and arrives +//! over the network, while the per-turn detail is this machine's and is +//! frequently empty. Either can be present without the other. +use std::collections::HashMap; + +use chrono::{Datelike, TimeZone, Timelike, Utc}; +use rusqlite::{Connection, OpenFlags}; use toys_core as tc; use crate::shared::*; use crate::*; +const COPILOT_USER_API: &str = "https://api.github.com/copilot_internal/user"; + +fn copilot_db() -> String { + under_home(".copilot/session-store.db") +} + +fn copilot_config() -> String { + under_home(".copilot/config.json") +} + +/// The account's own description of itself. Names are what the API +/// returns, shortened only where it repeats itself. +const COPILOT_FEATURES: &[(&str, &str)] = &[ + ("chat_enabled", "chat"), + ("cli_enabled", "cli"), + ("is_mcp_enabled", "mcp"), + ("cli_remote_control_enabled", "remote control"), + ("cloud_session_storage_enabled", "cloud sessions"), + ("copilot_app_enabled", "app"), + ("editor_preview_features_enabled", "editor previews"), + ("copilotignore_enabled", "copilotignore"), +]; + +/// The per-turn aggregates the session store keeps, summed. +#[derive(Clone, Default)] +pub struct Spent { + input: f64, + output: f64, + cache: f64, + reasoning: f64, + nano_aiu: f64, + ttft: f64, + itl: f64, + ms: f64, +} + +/// Live quota, plus whatever the local session store has recorded. #[derive(Clone, Default)] -pub struct Data {} +pub struct Data { + /// The /copilot_internal/user response, when the request worked. + live: Option, + /// Why it did not, when it did not. + live_why: String, + sessions: i64, + events: i64, + /// None until an event has been read - a locked store and an empty one + /// both leave this unset, and `why` says which it was. + usage: Option, + /// day -> model -> tokens by priced kind, from the session store. + daily: HashMap>, + /// (model, turns, output tokens), busiest first. + models: Vec<(String, i64, f64)>, + why: String, +} + +/// The span a monthly quota covers, worked back from its reset, as its +/// label and its length in seconds. +/// +/// Copilot states when the quota resets but never how long the window is. +/// It can be derived, but only safely when the reset lands on midnight UTC +/// on the first of a month - which is what a calendar-month cycle looks +/// like, and what this account shows. Anything else and the window is not +/// known, so nothing is claimed about it: no label, and no pace figure, +/// because a pace against a guessed window is a fabricated number. +/// +/// Label and length come from the one function so the refusal cannot +/// diverge between them. usage.py refuses only for the label and derives +/// the pace span unconditionally, which contradicts its own comment here. +pub fn quota_window(reset_ts: Option) -> Option<(String, f64)> { + let stamp = reset_ts?; + if stamp <= 0.0 { + return None; + } + let end = Utc.timestamp_opt(stamp as i64, 0).single()?; + if (end.day(), end.hour(), end.minute(), end.second()) != (1, 0, 0, 0) { + return None; + } + let start = if end.month() == 1 { + Utc.with_ymd_and_hms(end.year() - 1, 12, 1, 0, 0, 0) + } else { + Utc.with_ymd_and_hms(end.year(), end.month() - 1, 1, 0, 0, 0) + } + .single()?; + Some(( + format!( + "{} {} → {} {}", + start.day(), + MONTHS[start.month0() as usize], + end.day(), + MONTHS[end.month0() as usize] + ), + stamp - start.timestamp() as f64, + )) +} + +/// The OAuth token Copilot's CLI keeps in ~/.copilot/config.json. +/// +/// That file is JSON with `//` comments on top, which a JSON parser +/// refuses, so the comments come off first. Keyed by host and login, +/// because one machine can be signed in to github.com and an Enterprise +/// host at once. +pub fn copilot_token() -> Option { + token_in(&std::fs::read_to_string(copilot_config()).ok()?) +} + +fn token_in(raw: &str) -> Option { + let clean: String = raw + .lines() + .map(|line| if line.trim_start().starts_with("//") { "" } else { line }) + .collect::>() + .join("\n"); + let parsed: serde_json::Value = serde_json::from_str(&clean).ok()?; + parsed["copilotTokens"] + .as_object() + .into_iter() + .flatten() + .find_map(|(_, tok)| tok.as_str().filter(|t| !t.is_empty()).map(String::from)) +} -pub fn read(_caches: &mut Caches) -> Data { - Data::default() +/// Entitlement and quota, from the endpoint the Copilot CLI itself uses. +/// +/// This is where Copilot's remaining quota actually lives. The session +/// store records what was spent per turn and is empty on plenty of +/// machines; this is the account's standing, and it answers the only +/// question a limit pane is really asked. +fn copilot_live() -> Option { + let Some(tok) = copilot_token() else { + return Some(serde_json::json!({"why": "no token in ~/.copilot/config.json"})); + }; + // Which of the two went wrong matters: blaming the config file for a + // dropped connection sends the reader to edit a file that is fine. + let failed = |e: String| { + let short: String = e.chars().take(40).collect(); + Some(serde_json::json!({"why": format!("quota request failed: {}", short)})) + }; + let auth = format!("token {}", tok); + match tc::get( + COPILOT_USER_API, + &[ + ("Authorization", &auth), + ("User-Agent", "terminal-toys"), + ("Accept", "application/json"), + ], + 20, + ) { + Ok(body) => match serde_json::from_str::(&body) { + Ok(data) => Some(serde_json::json!({"data": data})), + Err(e) => failed(e.to_string()), + }, + Err(e) => failed(e), + } +} + +pub fn read(caches: &mut Caches) -> Data { + let mut d = Data::default(); + if let Some(got) = cached(caches, "copilot", LIVE_TTL, copilot_live) { + if got["data"].is_object() { + d.live = Some(got["data"].clone()); + } + d.live_why = text(&got, "why"); + } + read_store_at(&copilot_db(), &mut d); + d +} + +/// The session store, read without disturbing it. +/// +/// Read-only is not decoration: this is a live agent's working state. +/// Any failure - missing, locked, corrupt - leaves the counts unset and +/// says why, because those numbers are then unknown, not zero. +fn read_store_at(path: &str, d: &mut Data) { + if !std::path::Path::new(path).exists() { + d.why = "no session store".into(); + return; + } + let opened = Connection::open_with_flags(path, OpenFlags::SQLITE_OPEN_READ_ONLY) + .and_then(|con| scan_store(&con, d)); + if let Err(e) = opened { + d.why = e.to_string().chars().take(40).collect(); + } +} + +fn scan_store(con: &Connection, d: &mut Data) -> rusqlite::Result<()> { + d.sessions = con.query_row("select count(*) from sessions", [], |r| r.get(0))?; + // Every sum() comes back NULL on an empty table, so each is read as an + // Option rather than trusted to be a number. + type Sums = ( + i64, + Option, + Option, + Option, + Option, + Option, + Option, + Option, + Option, + ); + let row: Sums = con.query_row( + "select count(*), sum(input_tokens), sum(output_tokens), \ + sum(cache_read_tokens), sum(reasoning_tokens), \ + sum(total_nano_aiu), avg(time_to_first_token_ms), \ + avg(inter_token_latency_ms), sum(duration_ms) \ + from assistant_usage_events", + [], + |r| { + Ok(( + r.get(0)?, + r.get(1)?, + r.get(2)?, + r.get(3)?, + r.get(4)?, + r.get(5)?, + r.get(6)?, + r.get(7)?, + r.get(8)?, + )) + }, + )?; + d.events = row.0; + if d.events == 0 { + return Ok(()); + } + d.usage = Some(Spent { + input: row.1.unwrap_or(0.0), + output: row.2.unwrap_or(0.0), + cache: row.3.unwrap_or(0.0), + reasoning: row.4.unwrap_or(0.0), + nano_aiu: row.5.unwrap_or(0.0), + ttft: row.6.unwrap_or(0.0), + itl: row.7.unwrap_or(0.0), + ms: row.8.unwrap_or(0.0), + }); + let mut daily = con.prepare( + "select date(created_at), model, sum(input_tokens), \ + sum(output_tokens), sum(cache_read_tokens), \ + sum(cache_write_tokens) from assistant_usage_events \ + group by 1, 2", + )?; + let found = daily.query_map([], |r| { + Ok(( + r.get::<_, Option>(0)?, + r.get::<_, Option>(1)?, + r.get::<_, Option>(2)?, + r.get::<_, Option>(3)?, + r.get::<_, Option>(4)?, + r.get::<_, Option>(5)?, + )) + })?; + for got in found { + let (day, model, i_tok, o_tok, cr, cw) = got?; + // A NULL created_at has no day. usage.py keys it "None", which + // sorts above every real date and would count into today forever. + let Some(day) = day.filter(|x| !x.is_empty()) else { + continue; + }; + let bucket = d + .daily + .entry(day) + .or_default() + .entry(model.unwrap_or_default()) + .or_insert_with(empty_tokens); + *bucket.get_mut("input").unwrap() += i_tok.unwrap_or(0.0); + *bucket.get_mut("output").unwrap() += o_tok.unwrap_or(0.0); + *bucket.get_mut("cache_read").unwrap() += cr.unwrap_or(0.0); + *bucket.get_mut("cache_write").unwrap() += cw.unwrap_or(0.0); + } + let mut models = con.prepare( + "select model, count(*), sum(output_tokens), \ + sum(input_tokens), sum(cache_read_tokens), \ + sum(cache_write_tokens) \ + from assistant_usage_events group by model \ + order by 3 desc limit 6", + )?; + let found = models.query_map([], |r| { + Ok(( + r.get::<_, Option>(0)?, + r.get::<_, i64>(1)?, + r.get::<_, Option>(2)?, + )) + })?; + for got in found { + let (model, turns, out_tok) = got?; + d.models.push(( + model.filter(|m| !m.is_empty()).unwrap_or_else(|| "?".into()), + turns, + out_tok.unwrap_or(0.0), + )); + } + Ok(()) } /// Every quota this agent publishes, for the summary screen. -pub fn lanes(_d: &Data) -> Vec { - Vec::new() +/// +/// window_secs carries quota_window's refusal: None whenever the reset is +/// not midnight UTC on the first of a month, and the summary then draws no +/// pace mark rather than a wrong one. +pub fn lanes(d: &Data) -> Vec { + let Some(live) = d.live.as_ref() else { + return Vec::new(); + }; + let stamp = iso_epoch(&text(live, "quota_reset_date_utc")); + let span = quota_window(stamp).map(|(_, secs)| secs); + let mut out = Vec::new(); + for (key, snap) in live["quota_snapshots"].as_object().into_iter().flatten() { + // An enterprise seat is why two of the three pools come back + // unlimited; a pool with no denominator has no percentage to rank. + if snap["unlimited"].as_bool().unwrap_or(false) || snap["percent_remaining"].is_null() { + continue; + } + out.push(Lane { + label: key.replace('_', " ").replace("interactions", "reqs"), + pct: 100.0 - num(snap, "percent_remaining"), + window_secs: span, + reset: stamp, + stale: false, + }); + } + out } -pub fn tab(_d: &Data, w: usize, _h: usize, _cfg: &Config, p: &Palette) -> Vec { - let mut rows = vec![ - tc::seg( +/// Which subscription this quota belongs to, and since when. +/// +/// An enterprise seat is why two of the three pools come back unlimited, +/// and assigned_date is the only field saying how long it has been so. +pub fn copilot_plan_rows(live: &serde_json::Value, w: usize, p: &Palette) -> Vec { + let mut pairs: Vec<(String, String)> = Vec::new(); + let assigned = text(live, "assigned_date"); + let day = iso_day(&assigned); + if let Some(since) = iso_epoch(&assigned) { + if !day.is_empty() { + pairs.push(("seat since".into(), format!("{} · {} ago", day, ago(since)))); + } + } + let orgs: Vec = live["organization_list"] + .as_array() + .into_iter() + .flatten() + .filter_map(|o| { + [text(o, "name"), text(o, "login")].into_iter().find(|s| !s.is_empty()) + }) + .collect(); + if !orgs.is_empty() { + pairs.push(("organisation".into(), orgs.join(", "))); + } + for (label, key) in [("account", "login"), ("sku", "access_type_sku")] { + let value = text(live, key); + if !value.is_empty() { + pairs.push((label.into(), value)); + } + } + if live["token_based_billing"].as_bool().unwrap_or(false) { + pairs.push(("billing".into(), "token-based".into())); + } + let on: Vec = COPILOT_FEATURES + .iter() + .filter(|(flag, _)| live[*flag].as_bool().unwrap_or(false)) + .map(|(_, name)| name.to_string()) + .collect(); + plan_rows( + &text(live, "copilot_plan"), + &pairs, + w, + if live["can_upgrade_plan"].as_bool().unwrap_or(false) { "upgradeable" } else { "" }, + Some(("enabled", &on)), + "", + p, + ) +} + +pub fn copilot_metered(d: &Data, w: usize, cfg: &Config, p: &Palette) -> Vec { + metered_rows( + &[ + ("today".to_string(), claude::window_models(&d.daily, 1)), + ("30 days".to_string(), claude::window_models(&d.daily, 30)), + ], + w, + "", + "copilot", + "this machine", + "Counted from the local session store. Copilot in an editor, on \ + another machine or on github.com is not in here.", + cfg, + p, + ) +} + +/// 1234567 -> "1,234,567". Entitlements run to thousands of requests, and +/// nobody counts an unbroken run of digits. +fn commas(n: i64) -> String { + let raw = n.abs().to_string(); + let mut out = String::new(); + for (i, ch) in raw.chars().enumerate() { + if i > 0 && (raw.len() - i) % 3 == 0 { + out.push(','); + } + out.push(ch); + } + if n < 0 { + format!("-{}", out) + } else { + out + } +} + +fn copilot_tab(d: &Data, w: usize, p: &Palette) -> Vec { + let null = serde_json::Value::Null; + let live = d.live.as_ref().unwrap_or(&null); + let mut rows: Vec = Vec::new(); + let snaps = live["quota_snapshots"].as_object().cloned().unwrap_or_default(); + if !snaps.is_empty() { + // A monthly quota reset arrives as a bare date; days remaining is + // the form every other tab here uses, and the one anyone reads. + // quota_reset_date_utc, not quota_reset_date: the bare date carries + // no zone, so it parses as local midnight and the countdown drifts + // by the machine's UTC offset. Zero on the machine this was written + // on, which is exactly why it would have gone unnoticed there. + let stamp = iso_epoch(&text(live, "quota_reset_date_utc")); + let mut when = String::new(); + if let Some(stamp) = stamp { + let days = ((stamp - now()) / 86400.0).floor() as i64; + when = if days > 0 { format!("resets in {}d", days) } else { "resets today".into() }; + } + rows.push(tc::seg( &[ - (p.lbl.as_str(), " ── GITHUB COPILOT ── ".into()), - (p.dim.as_str(), "no reader in this build yet".into()), + (p.lbl.as_str(), " ── QUOTA ── ".into()), + (p.ok.as_str(), "live".into()), + (p.dim.as_str(), " · account-wide".into()), ], w - 1, - ), - String::new(), - ]; - for line in wrap_text( - "usage.py reads this agent; the Rust port does not yet. Nothing is \ - shown rather than a plausible zero.", - w.saturating_sub(4).max(20), - ) { - rows.push(tc::seg(&[(p.dim.as_str(), format!(" {}", line))], w - 1)); + )); + // The reset sits with the window rather than on the header: they + // are two halves of the same cycle, and the header had no room for + // it. The window is claimed only when quota_window could derive it. + let window = quota_window(stamp); + let span_label = window.as_ref().map(|(label, _)| label.clone()); + let span_secs = window.map(|(_, secs)| secs); + if span_label.is_some() || !when.is_empty() { + rows.push(tc::seg( + &[ + (p.dim.as_str(), " window ".into()), + (p.txt.as_str(), span_label.clone().unwrap_or_else(|| "—".into())), + ( + p.dim.as_str(), + if span_label.is_some() { " · monthly · ".into() } else { " ".into() }, + ), + (p.dim.as_str(), when), + ], + w - 1, + )); + } + let label_w = snaps.keys().map(|k| k.chars().count()).max().unwrap_or(0).max(9); + let mut keys: Vec<&String> = snaps.keys().collect(); + keys.sort_by_key(|k| (snaps[*k]["unlimited"].as_bool().unwrap_or(false), (*k).clone())); + for key in keys { + let q = &snaps[key]; + let name = tc::pad(&key.replace('_', " "), label_w); + if q["unlimited"].as_bool().unwrap_or(false) { + // No denominator, so no bar. An unlimited pool drawn as an + // empty gauge invents a limit that was explicitly denied. + rows.push(tc::seg( + &[ + (p.dim.as_str(), format!(" {} ", name)), + (p.ok.as_str(), "unlimited".into()), + ], + w - 1, + )); + continue; + } + let ent = num(q, "entitlement"); + // percent_remaining is what the API gives; every other tab here + // shows what is spent, and red belongs at the empty end. + let pct = 100.0 - num(q, "percent_remaining"); + let used = (pct / 100.0).clamp(0.0, 1.0); + let room = ((w as i64) - 38 - label_w as i64).max(8) as usize; + let hue = agent_hue("copilot"); + let mut line: Vec<(String, String)> = vec![(p.dim.clone(), format!(" {} ", name))]; + line.extend(paced_bar(used, elapsed_of(span_secs, stamp), room, hue, p)); + line.push((pct_colour(pct, hue, p), pct_text(pct))); + line.push(pace_cell(lead(pct, span_secs, stamp), p)); + let refs: Vec<(&str, String)> = + line.iter().map(|(c, t)| (c.as_str(), t.clone())).collect(); + rows.push(tc::seg(&refs, w - 1)); + // A pool can carry its own reset, in which case it is not on + // the account-wide cycle in the header and has to say so + // itself. + let own = num(q, "quota_reset_at"); + let mut own_when = String::new(); + if own > 0.0 && (own - stamp.unwrap_or(0.0)).abs() > 3600.0 { + let left = own - now(); + own_when = if left > 0.0 { + format!(" resets in {}", left_span(left)) + } else { + " resetting".into() + }; + } + if ent > 0.0 { + let mut line: Vec<(String, String)> = vec![ + (p.dim.clone(), format!(" {} ", " ".repeat(label_w))), + (p.txt.clone(), commas(num(q, "credits_used") as i64)), + (p.dim.clone(), " of ".into()), + (p.txt.clone(), commas(ent as i64)), + ]; + // No room for the remainder on a narrow pane. + if (label_w as i64) + 34 <= (w as i64) - 1 { + line.push((p.dim.clone(), " · ".into())); + line.push((p.txt.clone(), commas(num(q, "remaining") as i64))); + line.push((p.dim.clone(), " left".into())); + } + let over = num(q, "overage_count"); + line.push(( + p.warn.clone(), + if over > 0.0 { format!(" {} over", over as i64) } else { String::new() }, + )); + line.push((p.dim.clone(), own_when)); + let refs: Vec<(&str, String)> = + line.iter().map(|(c, t)| (c.as_str(), t.clone())).collect(); + rows.push(tc::seg(&refs, w - 1)); + } + } + rows.push(String::new()); + } else if !d.live_why.is_empty() { + rows.push(tc::seg( + &[(p.warn.as_str(), format!(" no quota: {}", d.live_why))], + w - 1, + )); + rows.push(String::new()); + } + + match d.usage.as_ref() { + Some(u) => { + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── SPENT ── ".into()), + ( + p.dim.as_str(), + format!("{} turns across {} sessions", d.events, d.sessions), + ), + ], + w - 1, + )); + let cells: Vec<(&str, String, &str)> = vec![ + ("input tokens", big_num(u.input), p.txt.as_str()), + ("output tokens", big_num(u.output), p.agent.as_str()), + ("cache read", big_num(u.cache), p.dim.as_str()), + ("reasoning tokens", big_num(u.reasoning), p.txt.as_str()), + // total_nano_aiu is billionths of an AI unit. + ("AI units", format!("{:.3}", u.nano_aiu / 1e9), p.txt.as_str()), + ("time generating", span_ms(u.ms), p.dim.as_str()), + ]; + let label_w = cells.iter().map(|c| c.0.chars().count()).max().unwrap_or(0); + let ncols: usize = + if (w as i64 - 2) / 2 - label_w as i64 - 3 >= 8 { 2 } else { 1 }; + let cw = (w - 2) / ncols; + let val_w = (cw as i64 - label_w as i64 - 3).max(5) as usize; + for chunk in cells.chunks(ncols) { + let mut line: Vec<(String, String)> = vec![(tc::RST.to_string(), " ".into())]; + for (lab, value, colour) in chunk { + line.push((p.dim.clone(), format!(" {} ", tc::pad(lab, label_w)))); + line.push((colour.to_string(), tc::pad(value, val_w))); + } + let refs: Vec<(&str, String)> = + line.iter().map(|(c, t)| (c.as_str(), t.clone())).collect(); + rows.push(tc::seg(&refs, w - 1)); + } + rows.push(String::new()); + // The one agent that measures this rather than leaving it to be + // inferred from timestamps, which is why it is stated flatly. + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── LATENCY ── ".into()), + (p.dim.as_str(), "measured by Copilot, not inferred".into()), + ], + w - 1, + )); + rows.push(tc::seg( + &[ + (p.dim.as_str(), " first token ".into()), + (p.txt.as_str(), format!("{:.0} ms", u.ttft)), + (p.dim.as_str(), " between tokens ".into()), + (p.txt.as_str(), format!("{:.1} ms", u.itl)), + ], + w - 1, + )); + rows.push(String::new()); + if !d.models.is_empty() { + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── BY MODEL ── ".into()), + (p.dim.as_str(), "output tokens".into()), + ], + w - 1, + )); + for (model, turns, out_tok) in &d.models { + rows.push(tc::seg( + &[ + (p.txt.as_str(), format!(" {}", tc::pad(model, 28))), + (p.dim.as_str(), format!("{:5} turns ", turns)), + (p.agent.as_str(), big_num(*out_tok)), + ], + w - 1, + )); + } + } + } + // usage.py says "no local sessions" here whatever `why` holds, so a + // locked store read as an empty one. Unreadable and empty are + // different facts and get different sentences. + None if !d.why.is_empty() && d.why != "no session store" => { + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── SPENT ── ".into()), + (p.warn.as_str(), "session store unreadable".into()), + ], + w - 1, + )); + rows.push(String::new()); + rows.extend(no_local( + &format!( + "The session store could not be read ({}), so what it holds is \ + unknown - not zero.", + d.why + ), + "", + w, + p, + )); + } + None => { + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── SPENT ── ".into()), + (p.dim.as_str(), "no local sessions".into()), + ], + w - 1, + )); + rows.push(String::new()); + rows.extend(no_local( + "Nothing recorded in the local session store yet.", + run_hint("copilot"), + w, + p, + )); + } } rows } + +/// The whole tab: the quota, what this machine spent, what that cost, and +/// which subscription the percentages are percentages of. +pub fn tab(d: &Data, w: usize, _h: usize, cfg: &Config, p: &Palette) -> Vec { + let body = add_section(copilot_tab(d, w, p), copilot_metered(d, w, cfg, p)); + let null = serde_json::Value::Null; + add_section(body, copilot_plan_rows(d.live.as_ref().unwrap_or(&null), w, p)) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn utc_epoch(y: i32, mo: u32, d: u32, h: u32, mi: u32, s: u32) -> f64 { + Utc.with_ymd_and_hms(y, mo, d, h, mi, s).unwrap().timestamp() as f64 + } + + #[test] + fn a_reset_at_midnight_utc_on_the_first_yields_the_window() { + let (label, secs) = quota_window(Some(utc_epoch(2026, 8, 1, 0, 0, 0))).unwrap(); + assert_eq!(label, "1 Jul → 1 Aug"); + // Computed rather than a literal, so the test cannot encode the + // same arithmetic slip as the code. + let expect = utc_epoch(2026, 8, 1, 0, 0, 0) - utc_epoch(2026, 7, 1, 0, 0, 0); + assert_eq!(secs, expect); + assert_eq!(secs, 31.0 * 86400.0); + } + + #[test] + fn a_january_reset_reaches_back_into_december() { + let (label, secs) = quota_window(Some(utc_epoch(2026, 1, 1, 0, 0, 0))).unwrap(); + assert_eq!(label, "1 Dec → 1 Jan"); + assert_eq!(secs, utc_epoch(2026, 1, 1, 0, 0, 0) - utc_epoch(2025, 12, 1, 0, 0, 0)); + } + + #[test] + fn a_march_reset_gets_februarys_shorter_window() { + let (_, secs) = quota_window(Some(utc_epoch(2026, 3, 1, 0, 0, 0))).unwrap(); + assert_eq!(secs, 28.0 * 86400.0); + } + + #[test] + fn a_reset_anywhere_but_midnight_on_the_first_is_refused() { + // Not the first of a month. + assert!(quota_window(Some(utc_epoch(2026, 8, 15, 0, 0, 0))).is_none()); + // The first, but not midnight. + assert!(quota_window(Some(utc_epoch(2026, 8, 1, 7, 0, 0))).is_none()); + assert!(quota_window(Some(utc_epoch(2026, 8, 1, 0, 30, 0))).is_none()); + assert!(quota_window(Some(utc_epoch(2026, 8, 1, 0, 0, 30))).is_none()); + } + + #[test] + fn no_reset_means_no_window() { + assert!(quota_window(None).is_none()); + // Epoch zero is 1 Jan 1970 00:00 UTC, which would pass the shape + // check while meaning "no timestamp". + assert!(quota_window(Some(0.0)).is_none()); + } + + fn live_with_reset(reset: &str) -> Data { + let mut d = Data::default(); + d.live = Some(serde_json::json!({ + "quota_reset_date_utc": reset, + "quota_snapshots": { + "premium_interactions": {"unlimited": false, "percent_remaining": 25.0}, + "chat": {"unlimited": true}, + "completions": {"unlimited": false} + } + })); + d + } + + #[test] + fn lanes_skip_unlimited_pools_and_pools_with_no_percentage() { + let got = lanes(&live_with_reset("2026-09-01T00:00:00Z")); + assert_eq!(got.len(), 1); + assert_eq!(got[0].label, "premium reqs"); + assert_eq!(got[0].pct, 75.0); + } + + #[test] + fn lanes_carry_the_window_only_when_it_could_be_derived() { + // Midnight UTC on the first: a calendar month, so the window is + // claimed - August's 31 days. + let got = lanes(&live_with_reset("2026-09-01T00:00:00Z")); + assert_eq!(got[0].window_secs, Some(31.0 * 86400.0)); + assert!(got[0].reset.is_some()); + // Mid-month: the window is not known, so no pace mark is drawn - + // but the lane itself and its reset are still real. + let got = lanes(&live_with_reset("2026-09-15T00:00:00Z")); + assert_eq!(got.len(), 1); + assert_eq!(got[0].window_secs, None); + assert!(got[0].reset.is_some()); + } + + fn store_with(rows: &[&str]) -> Connection { + let con = Connection::open_in_memory().unwrap(); + con.execute_batch( + "create table sessions (id integer primary key); \ + create table assistant_usage_events ( \ + created_at text, model text, input_tokens integer, \ + output_tokens integer, cache_read_tokens integer, \ + cache_write_tokens integer, reasoning_tokens integer, \ + total_nano_aiu integer, time_to_first_token_ms real, \ + inter_token_latency_ms real, duration_ms integer);", + ) + .unwrap(); + for values in rows { + con.execute_batch(&format!( + "insert into assistant_usage_events values ({});", + values + )) + .unwrap(); + } + con + } + + #[test] + fn the_session_store_sums_read_whole() { + let con = store_with(&[ + "'2026-08-20T10:00:00Z', 'model-a', 100, 200, 50, 10, 5, 1500000000, 500.0, 20.0, 3000", + "'2026-08-21T11:00:00Z', 'model-b', 10, 999, 40, 0, 0, 500000000, 300.0, 10.0, 2000", + ]); + con.execute_batch("insert into sessions values (1); insert into sessions values (2);") + .unwrap(); + let mut d = Data::default(); + scan_store(&con, &mut d).unwrap(); + assert_eq!(d.sessions, 2); + assert_eq!(d.events, 2); + let u = d.usage.as_ref().unwrap(); + assert_eq!(u.input, 110.0); + assert_eq!(u.output, 1199.0); + assert_eq!(u.cache, 90.0); + assert_eq!(u.reasoning, 5.0); + assert_eq!(u.nano_aiu, 2_000_000_000.0); + assert_eq!(u.ttft, 400.0); + assert_eq!(u.itl, 15.0); + assert_eq!(u.ms, 5000.0); + let day = &d.daily["2026-08-20"]["model-a"]; + assert_eq!(day["input"], 100.0); + assert_eq!(day["output"], 200.0); + assert_eq!(day["cache_read"], 50.0); + assert_eq!(day["cache_write"], 10.0); + assert_eq!(day["cache_write_1h"], 0.0); + // Busiest model first, by output tokens. + assert_eq!(d.models[0], ("model-b".to_string(), 1, 999.0)); + assert_eq!(d.models[1], ("model-a".to_string(), 1, 200.0)); + } + + #[test] + fn null_sums_are_read_as_options_not_trusted_as_numbers() { + // One event whose every column is NULL: count(*) is 1, and every + // sum() and avg() beside it is NULL rather than a number. + let con = store_with(&[ + "NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL", + ]); + let mut d = Data::default(); + scan_store(&con, &mut d).unwrap(); + assert_eq!(d.events, 1); + let u = d.usage.as_ref().unwrap(); + assert_eq!(u.input, 0.0); + assert_eq!(u.ttft, 0.0); + // date(NULL) is NULL: no day to file it under, so it is skipped + // rather than keyed as a fake day that counts into today forever. + assert!(d.daily.is_empty()); + assert_eq!(d.models[0].0, "?"); + } + + #[test] + fn an_empty_store_leaves_the_spending_unset() { + let con = store_with(&[]); + let mut d = Data::default(); + scan_store(&con, &mut d).unwrap(); + assert_eq!(d.events, 0); + assert!(d.usage.is_none()); + assert!(d.models.is_empty()); + } + + #[test] + fn a_missing_store_is_unknown_not_zero() { + let mut d = Data::default(); + read_store_at("/nonexistent-invented-path/session-store.db", &mut d); + assert_eq!(d.why, "no session store"); + assert!(d.usage.is_none()); + assert_eq!(d.events, 0); + } + + #[test] + fn an_unreadable_store_fails_soft_with_a_reason() { + // An invented file that is not SQLite at all; the reader must come + // back with a why rather than a panic or a plausible zero. + let path = std::env::temp_dir().join(format!("toys-copilot-test-{}.db", std::process::id())); + std::fs::write(&path, "not a database, on purpose").unwrap(); + let mut d = Data::default(); + read_store_at(path.to_str().unwrap(), &mut d); + std::fs::remove_file(&path).ok(); + assert!(!d.why.is_empty()); + assert_ne!(d.why, "no session store"); + assert!(d.usage.is_none()); + } + + #[test] + fn the_token_survives_the_configs_comment_header() { + let raw = "// GitHub Copilot CLI configuration\n\ + // managed by the CLI, do not edit\n\ + {\n \"copilotTokens\": {\n \"github.example\": \"tok_invented_0000\"\n },\n\ + \"theme\": \"auto\"\n}\n"; + assert_eq!(token_in(raw), Some("tok_invented_0000".into())); + } + + #[test] + fn an_empty_or_missing_token_is_none_rather_than_blank() { + assert_eq!(token_in("{\"copilotTokens\": {\"github.example\": \"\"}}"), None); + assert_eq!(token_in("{\"copilotTokens\": {}}"), None); + assert_eq!(token_in("{}"), None); + assert_eq!(token_in("not json at all"), None); + } + + #[test] + fn commas_group_digits_the_way_a_person_counts_them() { + assert_eq!(commas(0), "0"); + assert_eq!(commas(999), "999"); + assert_eq!(commas(1000), "1,000"); + assert_eq!(commas(1234567), "1,234,567"); + } +} From f32de03bb6cb74021f2ae2eac53821a05226e503 Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sun, 23 Aug 2026 18:35:49 +0800 Subject: [PATCH 037/147] usage: read Cursor Four Connect RPCs to the dashboard service with the bearer token from ~/.config/cursor/auth.json on curl's stdin: the period usage that gives the three lanes and the billing cycle, the plan held for an hour, the server-priced per-model metered cents - server-priced, so no rate card and no config - and the raw per-event vendor cents folded into a per-day summary. Plus the local tracking database, opened SQLITE_OPEN_READ_ONLY. Connect writes numbers as strings. A loose() reader handles both, because num() would have read every timestamp, cycle bound and cent figure as a silent zero. Two faults where one unreadable source took down four that were fine: - read_cursor's sqlite-error branch dropped live, plan, events and spend entirely, so a transiently locked database blanked the QUOTA, SPEND and METERED sections that never touched it. The network reads now happen before the database read. - The tab then showed a fixed "No Cursor tracking database on this machine" even when the database was there and merely locked, never surfacing the reason it had already recorded, and dropped the daily chart while METERED rendered from the same fetched data. Paging stops on the first event older than the window or the first short page, capped at eight pages. A page that fails mid-paging still returns what it had, which brushes against never presenting a partial as a total; it is matched rather than changed, because a transient failure blanking the section is worse, and it is commented where it happens. Ten tests: an in-memory database for the query half, and tally_events kept pure so paging is testable without a network. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/widgets/src/bin/usage/cursor.rs | 1100 +++++++++++++++++++++++++- 1 file changed, 1078 insertions(+), 22 deletions(-) diff --git a/rust/widgets/src/bin/usage/cursor.rs b/rust/widgets/src/bin/usage/cursor.rs index ba88cbe..9bcdc45 100644 --- a/rust/widgets/src/bin/usage/cursor.rs +++ b/rust/widgets/src/bin/usage/cursor.rs @@ -14,46 +14,1102 @@ // You should have received a copy of the GNU Affero General Public License // along with this program. If not, see . -//! Cursor: its edit-tracking database, and the lanes its Usage view shows. +//! Cursor: the three lanes its own Usage view shows, the spend its server +//! prices, and the tracking database that says how much code it wrote. //! -//! Not read yet. Every function here is honest about that rather than -//! returning a plausible zero, which is the rule the whole widget follows -//! for an agent that publishes nothing. +//! The one agent whose metered section needs no rate card: the API states +//! both what Cursor charges against the plan and what the same traffic +//! costs at vendor list, so nothing here is estimated. The authorship +//! counts answer a different question - how much code the agent wrote, +//! not what it cost - and the tab keeps the two apart. +use std::collections::HashMap; + +use chrono::{Datelike, Duration as Days, Local, NaiveDate, TimeZone}; +use rusqlite::{Connection, OpenFlags}; use toys_core as tc; use crate::shared::*; use crate::*; +/// The Connect endpoint cursor-agent's own Usage view calls. Not the +/// documented cursor.com dashboard API - that one wants a browser cookie +/// and returns 401 to anything this machine has. The CLI talks to +/// aiserver.v1.DashboardService with the bearer token it stores beside its +/// config, which is the credential this reuses. +const CURSOR_RPC: &str = "https://api2.cursor.sh/aiserver.v1.DashboardService/"; + +/// The lanes in the order cursor-agent's Usage view lists them: each one's +/// label, the field it reads, and how far up Cursor's own colour it sits. +/// +/// One tint per lane rather than three unrelated hues. These are +/// categories, not one gauge, so a green-to-red severity ramp would imply +/// a relationship between them that does not exist - and each bar is +/// labelled and carries its own percentage, so the colour is decoration. +/// Tints of Cursor's own colour stay distinguishable while reading as +/// Cursor's, which three borrowed colours never did. +const CURSOR_LANES: &[(&str, &str, f64)] = &[ + ("included", "totalPercentUsed", 1.0), + ("auto", "autoPercentUsed", 0.80), + ("api", "apiPercentUsed", 0.62), +]; + +/// The events RPC's own ceiling per request. +const EVENT_PAGE: usize = 1000; +/// Enough pages to reach past any sane window. +const EVENT_PAGES: usize = 8; +/// Half an hour: thirty days of events is about five pages and eleven +/// seconds of paging, far too slow to repeat on a redraw. +const EVENTS_TTL: f64 = 1800.0; + +/// What Cursor publishes, and what its tracking database recorded here. #[derive(Clone, Default)] -pub struct Data {} +pub struct Data { + /// The tracking database was readable; the counts below mean something. + ok: bool, + why: String, + /// Absent rather than broken, so the fix is running the agent. + db_missing: bool, + /// GetCurrentPeriodUsage: the three lanes and the billing cycle. + live: Option, + /// GetPlanInfo: the plan the percentages are percentages of. + plan: Option, + /// The per-day summary folded out of GetFilteredUsageEvents. + events: Option, + /// GetAggregatedUsageEvents: per-model cents over the window. + spend: Option, + hashes: i64, + conversations: i64, + models: i64, + by_model: Vec<(String, i64)>, + commits: i64, + lines: i64, + human_lines: i64, + /// Milliseconds, from the newest tracked edit. + last: Option, +} -pub fn read(_caches: &mut Caches) -> Data { - Data::default() +/// A number whether it arrived as one or as a string. +/// +/// Connect writes int64 as JSON strings, so reading the billing cycle's +/// timestamps with a plain as_f64 would produce a wrong window with no +/// error - the kind of silent zero this widget exists to avoid. +fn loose(v: &serde_json::Value) -> Option { + v.as_f64().or_else(|| v.as_str()?.trim().parse().ok()) +} + +/// Thousands separators: "1,482,113 lines" is readable, "1482113" is not. +fn commas(n: i64) -> String { + let digits = n.abs().to_string(); + let mut out = String::new(); + for (i, ch) in digits.chars().enumerate() { + if i > 0 && (digits.len() - i) % 3 == 0 { + out.push(','); + } + out.push(ch); + } + if n < 0 { + format!("-{}", out) + } else { + out + } +} + +fn cursor_token() -> Option { + let auth = read_json(&under_home(".config/cursor/auth.json"))?; + let tok = text(&auth, "accessToken"); + if tok.is_empty() { + None + } else { + Some(tok) + } +} + +/// One Connect-style RPC to the dashboard service. +/// +/// Undocumented and versioned only by the CLI bundle it was read out of, +/// so every failure is silent and the tab simply falls back to whatever +/// else it has. The bearer token rides in a header that post_json feeds to +/// curl on its standard input, never in an argument - /proc//cmdline +/// is world-readable. +fn cursor_rpc(method: &str, body: &serde_json::Value) -> Option { + let tok = cursor_token()?; + let bearer = format!("Bearer {}", tok); + post_json( + &format!("{}{}", CURSOR_RPC, method), + &[ + ("Authorization", bearer.as_str()), + ("Content-Type", "application/json"), + ("Connect-Protocol-Version", "1"), + ("User-Agent", "terminal-toys"), + ], + &body.to_string(), + 25, + ) +} + +/// Plan usage, from the endpoint cursor-agent's own Usage view calls. +fn cursor_live() -> Option { + cursor_rpc("GetCurrentPeriodUsage", &serde_json::json!({})) +} + +/// Which Cursor plan the percentages are percentages of. +/// +/// GetPlanInfo is where the plan's name and price live - the usage call +/// carries neither, and its $400 limit is meaningless without knowing that +/// is what Ultra includes. +fn cursor_plan() -> Option { + cursor_rpc("GetPlanInfo", &serde_json::json!({})) +} + +/// Per-model tokens and real cost over a window. +/// +/// This is what the plan percentages are made of: which model spent the +/// money. totalCents is Cursor's own figure, not an estimate. +fn cursor_spend(days: i64) -> Option { + let at = (now() * 1000.0) as i64; + cursor_rpc( + "GetAggregatedUsageEvents", + &serde_json::json!({ + "startDate": (at - days * 86_400_000).to_string(), + "endDate": at.to_string(), + }), + ) +} + +/// The per-day running totals that pages of raw events fold into. +#[derive(Default)] +struct Tally { + by_day: HashMap, + tokens_by_day: HashMap, + /// day -> model -> (cents, tokens). + by_day_model: HashMap>, + vendor_cents: f64, + tokens: f64, + counted: u64, +} + +/// Fold one page of events into the tally. +/// +/// Returns the oldest timestamp on the page, which is what tells the +/// caller a page has reached past the window - events older than the cut +/// are not counted, but their age is still the stop signal. +fn tally_events(events: &[serde_json::Value], cut: f64, t: &mut Tally) -> f64 { + let mut oldest = now(); + for e in events { + let Some(when) = loose(&e["timestamp"]).map(|ms| ms / 1000.0) else { + continue; + }; + oldest = oldest.min(when); + if when < cut { + continue; + } + let usage = &e["tokenUsage"]; + let cents = loose(&usage["totalCents"]).unwrap_or(0.0); + let n = loose(&usage["inputTokens"]).unwrap_or(0.0) + + loose(&usage["outputTokens"]).unwrap_or(0.0); + let Some(day) = Local + .timestamp_opt(when as i64, 0) + .single() + .map(|d| d.format("%Y-%m-%d").to_string()) + else { + continue; + }; + *t.by_day.entry(day.clone()).or_default() += cents; + *t.tokens_by_day.entry(day.clone()).or_default() += n; + let model = match text(e, "model") { + s if s.is_empty() => "?".to_string(), + s => s, + }; + let slot = t.by_day_model.entry(day).or_default().entry(model).or_default(); + slot.0 += cents; + slot.1 += n; + t.vendor_cents += cents; + t.tokens += n; + t.counted += 1; + } + oldest +} + +/// Per-day spend, from the raw events cursor.com's own dashboard uses. +/// +/// GetAggregatedUsageEvents totals by model and carries no timestamp at +/// all, so no calendar can be built from it. GetFilteredUsageEvents +/// returns the individual events - each with a timestamp, a model and its +/// cents - newest first, a thousand at a time. +/// +/// Paging stops as soon as a page reaches past the window, so the cost is +/// proportional to the window rather than to the account's whole history; +/// EVENT_PAGES caps it regardless. Held for half an hour by the caller, +/// because this is far too slow to repeat on a redraw. +fn cursor_events(days: i64) -> Option { + let cut = now() - days as f64 * 86400.0; + let mut t = Tally::default(); + for page in 1..=EVENT_PAGES { + let got = cursor_rpc( + "GetFilteredUsageEvents", + &serde_json::json!({ "page": page, "pageSize": EVENT_PAGE }), + ); + let events: Vec = got + .as_ref() + .and_then(|g| g["usageEventsDisplay"].as_array()) + .cloned() + .unwrap_or_default(); + if events.is_empty() { + break; + } + let oldest = tally_events(&events, cut, &mut t); + if oldest < cut || events.len() < EVENT_PAGE { + break; + } + } + if t.counted == 0 { + return None; + } + let mut by_day_model = serde_json::Map::new(); + for (day, models) in &t.by_day_model { + let mut inner = serde_json::Map::new(); + for (model, (cents, tokens)) in models { + inner.insert( + model.clone(), + serde_json::json!({ "cents": cents, "tokens": tokens }), + ); + } + by_day_model.insert(day.clone(), serde_json::Value::Object(inner)); + } + Some(serde_json::json!({ + "by_day": t.by_day, + "tokens_by_day": t.tokens_by_day, + "by_day_model": by_day_model, + "vendor_cents": t.vendor_cents, + "tokens": t.tokens, + "events": t.counted, + "days": days, + })) +} + +/// The authorship counts, straight out of the tracking database. +struct Tracking { + hashes: i64, + conversations: i64, + models: i64, + by_model: Vec<(String, i64)>, + commits: i64, + lines: i64, + human_lines: i64, + last: Option, +} + +fn read_tracking(con: &Connection) -> rusqlite::Result { + let (hashes, conversations, models) = con.query_row( + "select count(*), count(distinct conversationId), count(distinct model) \ + from ai_code_hashes", + [], + |r| Ok((r.get(0)?, r.get(1)?, r.get(2)?)), + )?; + let mut stmt = con.prepare( + "select model, count(*) from ai_code_hashes group by model order by 2 desc limit 8", + )?; + let by_model = stmt + .query_map([], |r| { + let name: Option = r.get(0)?; + Ok(( + match name { + Some(s) if !s.is_empty() => s, + _ => "?".to_string(), + }, + r.get::<_, i64>(1)?, + )) + })? + .collect::>>()?; + let (commits, lines, human_lines) = con.query_row( + "select count(*), sum(linesAdded), sum(humanLinesAdded) from scored_commits", + [], + |r| { + Ok(( + r.get::<_, i64>(0)?, + // sum() over no rows is NULL, and NULL here is a true zero - + // a machine that has scored nothing - not a failure to read. + r.get::<_, Option>(1)?.unwrap_or(0), + r.get::<_, Option>(2)?.unwrap_or(0), + )) + }, + )?; + let last: Option = + con.query_row("select max(timestamp) from ai_code_hashes", [], |r| r.get(0))?; + Ok(Tracking { + hashes, + conversations, + models, + by_model, + commits, + lines, + human_lines, + last, + }) +} + +pub fn read(caches: &mut Caches) -> Data { + let mut d = Data::default(); + // The published sections do not depend on the local database, so a + // locked or missing file must not take the live quota down with it - + // which is what usage.py's sqlite-error branch does. + d.live = cached(caches, "cursor", LIVE_TTL, cursor_live); + d.plan = cached(caches, "cursor-plan", PLAN_TTL, cursor_plan); + d.events = cached(caches, "cursor-events", EVENTS_TTL, || cursor_events(30)); + d.spend = cached(caches, "cursor-spend", LIVE_TTL, || cursor_spend(30)); + let path = under_home(".cursor/ai-tracking/ai-code-tracking.db"); + if !std::path::Path::new(&path).exists() { + d.why = "no tracking database".into(); + d.db_missing = true; + return d; + } + // Read-only is not decoration: this is a live agent's working state. + let opened = Connection::open_with_flags(&path, OpenFlags::SQLITE_OPEN_READ_ONLY) + .and_then(|con| read_tracking(&con)); + match opened { + Ok(t) => { + d.ok = true; + d.hashes = t.hashes; + d.conversations = t.conversations; + d.models = t.models; + d.by_model = t.by_model; + d.commits = t.commits; + d.lines = t.lines; + d.human_lines = t.human_lines; + d.last = t.last; + } + // Locked or corrupt means the counts are unknown, never zero, and + // the reason is kept for the tab to show. + Err(e) => d.why = e.to_string().chars().take(40).collect(), + } + d +} + +/// The billing cycle as (window seconds, reset epoch), where stated. +fn cycle_of(live: &serde_json::Value) -> (Option, Option) { + match (loose(&live["billingCycleStart"]), loose(&live["billingCycleEnd"])) { + (Some(s), Some(e)) if e > s => (Some((e - s) / 1000.0), Some(e / 1000.0)), + _ => (None, None), + } } /// Every quota this agent publishes, for the summary screen. -pub fn lanes(_d: &Data) -> Vec { - Vec::new() +/// +/// The same three percentages the tab draws, against the same billing +/// cycle. Never marked stale: the CLI keeps no quota cache on disk to fall +/// back to, so a reading is either recent or absent. +pub fn lanes(d: &Data) -> Vec { + let Some(live) = d.live.as_ref() else { + return Vec::new(); + }; + let plan = &live["planUsage"]; + let (secs, reset) = cycle_of(live); + let mut out = Vec::new(); + for (label, key, _) in CURSOR_LANES { + let Some(pct) = loose(&plan[*key]) else { + continue; + }; + out.push(Lane { + label: (*label).to_string(), + pct, + window_secs: secs, + reset, + stale: false, + }); + } + out } -pub fn tab(_d: &Data, w: usize, _h: usize, _cfg: &Config, p: &Palette) -> Vec { - let mut rows = vec![ - tc::seg( +/// The three lanes cursor-agent's Usage view shows, plus the cycle. +fn cursor_quota(d: &Data, w: usize, p: &Palette) -> Vec { + let Some(live) = d.live.as_ref() else { + return Vec::new(); + }; + let plan = &live["planUsage"]; + if plan.as_object().is_none_or(|o| o.is_empty()) { + return Vec::new(); + } + let when = match loose(&live["billingCycleEnd"]) { + Some(ends) => { + let left = ends / 1000.0 - now(); + if left > 0.0 { + format!("resets in {}d", (left / 86400.0) as i64) + } else { + "resetting".to_string() + } + } + None => String::new(), + }; + let (cycle_secs, reset_ts) = cycle_of(live); + let elapsed = match (loose(&live["billingCycleStart"]), loose(&live["billingCycleEnd"])) { + (Some(s), Some(e)) if e > s => { + Some((100.0 * (now() * 1000.0 - s) / (e - s)).clamp(0.0, 100.0)) + } + _ => None, + }; + let mut rows = vec![tc::seg( + &[ + (p.lbl.as_str(), " ── QUOTA ── ".into()), + (p.ok.as_str(), "live".into()), + ( + p.dim.as_str(), + crate::claude::scope_phrase(w, 17 + when.chars().count()).into(), + ), + (p.dim.as_str(), when.clone()), + ], + w - 1, + )]; + if let Some(elapsed) = elapsed { + // Just the fact; the +/- column it explains is on every tab now, so + // a per-tab legend was both redundant and the thing that clipped. + rows.push(tc::seg( + &[(p.dim.as_str(), format!(" {:.0}% of the cycle gone", elapsed))], + w - 1, + )); + } + let base = agent_hue("cursor").unwrap(); + for (name, key, stop) in CURSOR_LANES { + let Some(pct) = loose(&plan[*key]) else { + continue; + }; + let used = (pct / 100.0).clamp(0.0, 1.0); + let hue = blend(base, *stop); + // The +/- cell is how far ahead of the clock this lane is: the + // share of the billing period gone minus the share of the + // allowance spent. Positive is a cushion, negative means the lane + // runs out before the cycle does. Pure arithmetic on the cycle + // dates - nothing new is fetched for it. + let (pace_colour, pace_txt) = pace_cell(lead(pct, cycle_secs, reset_ts), p); + let mut line: Vec<(String, String)> = + vec![(p.dim.clone(), format!(" {:<9}", name))]; + line.extend(paced_bar( + used, + elapsed_of(cycle_secs, reset_ts), + w.saturating_sub(40).max(8), + Some(hue), + p, + )); + line.push((pct_colour(pct, Some(hue), p), pct_text(pct))); + line.push((pace_colour, pace_txt)); + let refs: Vec<(&str, String)> = line.iter().map(|(c, t)| (c.as_str(), t.clone())).collect(); + rows.push(tc::seg(&refs, w - 1)); + } + if let Some(limit) = loose(&plan["limit"]).filter(|v| *v != 0.0) { + // Deliberately dollars rather than a fourth bar. This is spend + // against the plan limit - a different denominator from the three + // lanes above, which are the server's own percentages - and drawing + // it as a bar beside them would invite reading 12% and 2% as the + // same scale. + let spent = loose(&plan["totalSpend"]).unwrap_or(0.0); + let left = loose(&plan["remaining"]); + rows.push(tc::seg( &[ - (p.lbl.as_str(), " ── CURSOR ── ".into()), - (p.dim.as_str(), "no reader in this build yet".into()), + (p.dim.as_str(), " spend ".into()), + (p.txt.as_str(), format!("${:.2}", spent / 100.0)), + (p.dim.as_str(), " of ".into()), + (p.txt.as_str(), format!("${:.2}", limit / 100.0)), + ( + p.dim.as_str(), + match left { + Some(v) => format!(" ${:.2} left", v / 100.0), + None => String::new(), + }, + ), ], w - 1, - ), - String::new(), + )); + } + rows.push(String::new()); + rows +} + +/// One metered window over the per-day, per-model summary: dollars, tokens +/// and the models under them, costliest first. +fn window_of(by: &serde_json::Value, days: i64, today: NaiveDate) -> (f64, f64, Vec<(String, f64)>) { + let first = (today - Days::days(days - 1)).format("%Y-%m-%d").to_string(); + let (mut cents, mut tokens) = (0.0, 0.0); + let mut models: HashMap = HashMap::new(); + for (day, entries) in by.as_object().into_iter().flatten() { + if day.as_str() < first.as_str() { + continue; + } + for (model, got) in entries.as_object().into_iter().flatten() { + cents += num(got, "cents"); + tokens += num(got, "tokens"); + *models.entry(model.clone()).or_default() += num(got, "cents"); + } + } + let mut ranked: Vec<(String, f64)> = models.into_iter().map(|(m, c)| (m, c / 100.0)).collect(); + ranked.sort_by(|a, b| b.1.total_cmp(&a.1)); + (cents / 100.0, tokens, ranked) +} + +/// What Cursor charges, beside what the same traffic costs at list. +/// +/// Cursor is the one agent that publishes both, so no rate card - and no +/// config - is needed: GetAggregatedUsageEvents returns what it meters +/// against the plan, and the raw events carry their own vendor-rate cents. +/// The gap is what the subscription is worth, and every event states its +/// own discount. +fn cursor_metered(d: &Data, w: usize, p: &Palette) -> Vec { + let nothing = serde_json::Value::Null; + let ev = d.events.as_ref().unwrap_or(¬hing); + let metered = d + .spend + .as_ref() + .and_then(|s| loose(&s["totalCostCents"])) + .unwrap_or(0.0); + let by = &ev["by_day_model"]; + if by.as_object().is_none_or(|o| o.is_empty()) && metered == 0.0 { + return Vec::new(); + } + let today = Local::now().date_naive(); + let span = match ev["days"].as_i64() { + Some(days) if days > 0 => days, + _ => 30, + }; + let mut windows: Vec = Vec::new(); + for (label, days) in [("today", 1), ("30 days", span)] { + let (cost, tokens, models) = window_of(by, days, today); + windows.push((label.to_string(), cost, tokens, models)); + } + let vendor = loose(&ev["vendor_cents"]).unwrap_or(0.0); + let saves = if vendor > 0.0 && metered > 0.0 { + Some((vendor - metered) / 100.0) + } else { + None + }; + metered_block( + "vendor rates", + &windows, + w, + &[ + ( + "cursor meters".to_string(), + (metered > 0.0).then_some(metered / 100.0), + p.txt.clone(), + ), + ("the plan saves".to_string(), saves, p.ok.clone()), + ], + "", + "account-wide", + "From Cursor's own API, so it covers every device on the account, not just this one.", + p, + ) +} + +/// Spend per day, one column per day, the way the usage page shows it. +/// +/// A bar chart rather than the calendar the token tabs use: this window is +/// thirty days, and thirty cells of a year-wide grid is six columns of +/// colour in a field of dots. Money over a month reads better as a +/// profile, and it is the shape Cursor's own dashboard draws. +fn cursor_daily(d: &Data, w: usize, p: &Palette) -> Vec { + let Some(ev) = d.events.as_ref() else { + return Vec::new(); + }; + let Some(by_day) = ev["by_day"].as_object().filter(|o| !o.is_empty()) else { + return Vec::new(); + }; + let days = match ev["days"].as_i64() { + Some(n) if n > 0 => n, + _ => 30, + }; + let today = Local::now().date_naive(); + let series: Vec = (0..days).rev().map(|n| today - Days::days(n)).collect(); + let cents: Vec = series + .iter() + .map(|day| { + by_day + .get(&day.format("%Y-%m-%d").to_string()) + .and_then(|v| v.as_f64()) + .unwrap_or(0.0) + }) + .collect(); + let top = cents.iter().cloned().fold(0.0f64, f64::max); + let peak = if top > 0.0 { top } else { 1.0 }; + // The peak's own day, or nothing when every day is zero - a peak of $0 + // has no date worth naming. + let best = (top > 0.0) + .then(|| cents.iter().position(|c| *c == top)) + .flatten() + .map(|i| series[i]); + let label = |d: &NaiveDate| format!("{} {}", MONTHS[d.month0() as usize], d.day()); + let mut rows = vec![tc::seg( + &[ + (p.lbl.as_str(), " ── SPEND / DAY ── ".into()), + (p.dim.as_str(), format!("{}d · peak ", days)), + (p.agent.as_str(), format!("${:.0}", peak / 100.0)), + ( + p.dim.as_str(), + format!( + " on {}", + best.as_ref().map(|b| label(b)).unwrap_or_else(|| "--".into()) + ), + ), + (p.dim.as_str(), " · today ".into()), + ( + p.txt.as_str(), + format!("${:.2}", cents.last().copied().unwrap_or(0.0) / 100.0), + ), + ], + w - 1, + )]; + let avail = w.saturating_sub(3).max(10); + let mut cols: Vec<(f64, String)> = Vec::new(); + for (c, wide) in cents.iter().zip(tc::spread(cents.len(), avail)) { + cols.extend(std::iter::repeat_n((*c, p.agent.clone()), wide)); + } + for line in tc::vbars(&cols, 3, peak) { + let mut parts: Vec<(&str, String)> = vec![(tc::RST, " ".into())]; + for (colour, ch) in &line { + parts.push((colour.as_str(), ch.clone())); + } + rows.push(tc::seg(&parts, w - 1)); + } + rows.push(tc::seg( + &[(tc::RST, " ".into()), (p.grid.as_str(), "─".repeat(cols.len()))], + w - 1, + )); + let (left, right) = (label(&series[0]), label(&series[series.len() - 1])); + rows.push(tc::seg( + &[ + (p.dim.as_str(), format!(" {}", left)), + ( + p.dim.as_str(), + " ".repeat(cols.len().saturating_sub(left.len() + right.len()).max(1)), + ), + (p.dim.as_str(), right), + ], + w - 1, + )); + rows.push(String::new()); + rows +} + +/// Where the money went, per model, over the last 30 days. +fn cursor_spend_rows(d: &Data, w: usize, p: &Palette) -> Vec { + let Some(spend) = d.spend.as_ref() else { + return Vec::new(); + }; + let Some(aggs) = spend["aggregations"].as_array().filter(|a| !a.is_empty()) else { + return Vec::new(); + }; + let grab = |key: &str| loose(&spend[key]).unwrap_or(0.0); + let mut rows = vec![tc::seg( + &[ + (p.lbl.as_str(), " ── SPEND ── ".into()), + (p.dim.as_str(), "last 30d · ".into()), + (p.agent.as_str(), format!("${:.2}", grab("totalCostCents") / 100.0)), + (p.dim.as_str(), " in ".into()), + (p.txt.as_str(), big_num(grab("totalInputTokens"))), + (p.dim.as_str(), " · out ".into()), + (p.txt.as_str(), big_num(grab("totalOutputTokens"))), + (p.dim.as_str(), " · cache ".into()), + (p.txt.as_str(), big_num(grab("totalCacheReadTokens"))), + ], + w - 1, + )]; + let mut models: Vec<&serde_json::Value> = aggs.iter().collect(); + let cents_of = |a: &serde_json::Value| loose(&a["totalCents"]).unwrap_or(0.0); + models.sort_by(|a, b| cents_of(b).total_cmp(¢s_of(a))); + let top = match cents_of(models[0]) { + v if v != 0.0 => v, + _ => 1.0, + }; + for a in models.iter().take(6) { + let cents = cents_of(a); + let bar = tc::meter(cents / top, w.saturating_sub(44).max(6)); + let filled = bar.chars().filter(|c| *c == '█').count(); + let name = match text(a, "modelIntent") { + s if s.is_empty() => "?".to_string(), + s => s, + }; + rows.push(tc::seg( + &[ + (p.txt.as_str(), format!(" {}", tc::pad(&name, 26))), + (p.agent.as_str(), format!("{:>9} ", format!("${:.2}", cents / 100.0))), + (p.agent.as_str(), bar.chars().take(filled).collect::()), + (p.grid.as_str(), bar.chars().skip(filled).collect::()), + ], + w - 1, + )); + } + rows.push(String::new()); + rows +} + +fn cursor_plan_rows(d: &Data, w: usize, p: &Palette) -> Vec { + let Some(info) = d.plan.as_ref() else { + return Vec::new(); + }; + let plan = &info["planInfo"]; + if plan.as_object().is_none_or(|o| o.is_empty()) { + return Vec::new(); + } + let mut pairs: Vec<(String, String)> = Vec::new(); + let price = text(plan, "price"); + if !price.is_empty() { + pairs.push(("price".into(), price)); + } + if let Some(inc) = loose(&plan["includedAmountCents"]).filter(|v| *v != 0.0) { + pairs.push(("included".into(), format!("${:.2} per cycle", inc / 100.0))); + } + let owner = text(plan, "planOwner").replace("PLAN_OWNER_", "").to_lowercase(); + if !owner.is_empty() { + pairs.push(("billing".into(), owner)); + } + plan_rows(&text(plan, "planName"), &pairs, w, "", None, "", p) +} + +/// The tab's own body: the lanes, the spend charts, and the authorship +/// counts from the tracking database. +fn cursor_tab(d: &Data, w: usize, p: &Palette) -> Vec { + let mut rows = cursor_quota(d, w, p); + rows.extend(cursor_daily(d, w, p)); + rows.extend(cursor_spend_rows(d, w, p)); + if !d.ok { + // An unreadable database makes the counts unknown, not zero, and + // which kind of unreadable matters: absent means run the agent, + // locked or corrupt names sqlite's own reason and will likely fix + // itself. usage.py shows a fixed "no tracking database" either way, + // which is false for a locked file. + let why = if d.why.is_empty() { "not read yet" } else { d.why.as_str() }; + let note = no_local( + &format!("No AI-written-code counts: {}.", why), + if d.db_missing { run_hint("cursor") } else { "" }, + w, + p, + ); + if rows.is_empty() { + return note; + } + return add_section(rows, note); + } + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── AI-WRITTEN CODE ── ".into()), + ( + p.dim.as_str(), + format!("last seen {} ago", ago(d.last.map(|ms| ms / 1000.0).unwrap_or(0.0))), + ), + ], + w - 1, + )); + let (ai, human) = (d.lines, d.human_lines); + let total = ai + human; + let cells: Vec<(&str, String, &str)> = vec![ + ("tracked edits", commas(d.hashes), p.agent.as_str()), + ("conversations", commas(d.conversations), p.txt.as_str()), + ("scored commits", commas(d.commits), p.txt.as_str()), + ("lines by agent", commas(ai), p.agent.as_str()), + ("lines by hand", commas(human), p.txt.as_str()), + ("models used", format!("{}", d.models), p.dim.as_str()), ]; - for line in wrap_text( - "usage.py reads this agent; the Rust port does not yet. Nothing is \ - shown rather than a plausible zero.", - w.saturating_sub(4).max(20), - ) { - rows.push(tc::seg(&[(p.dim.as_str(), format!(" {}", line))], w - 1)); + let label_w = cells.iter().map(|c| c.0.len()).max().unwrap_or(8); + let ncols = if w.saturating_sub(2) / 2 >= label_w + 11 { 2 } else { 1 }; + let cw = w.saturating_sub(2) / ncols; + let val_w = cw.saturating_sub(label_w + 3).max(5); + for chunk in cells.chunks(ncols) { + let mut line: Vec<(&str, String)> = vec![(tc::RST, " ".into())]; + for (label, value, colour) in chunk { + line.push((p.dim.as_str(), format!(" {} ", tc::pad(label, label_w)))); + line.push((colour, tc::pad(value, val_w))); + } + rows.push(tc::seg(&line, w - 1)); + } + if total > 0 { + rows.push(String::new()); + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── WHO WROTE IT ── ".into()), + (p.dim.as_str(), format!("{} lines scored", commas(total))), + ], + w - 1, + )); + let split = [ + (ai as f64 / total as f64, p.agent.clone()), + (human as f64 / total as f64, p.dim.clone()), + ]; + let mut bar: Vec<(&str, String)> = vec![(tc::RST, " ".into())]; + let segs = tc::stacked_bar(&split, w.saturating_sub(3).max(10)); + for (colour, run) in &segs { + bar.push((colour.as_str(), run.clone())); + } + rows.push(tc::seg(&bar, w - 1)); + rows.push(tc::seg( + &[ + ( + p.agent.as_str(), + format!(" ▇ agent {} ({:.0}%)", commas(ai), 100.0 * ai as f64 / total as f64), + ), + ( + p.dim.as_str(), + format!( + " ▇ hand {} ({:.0}%)", + commas(human), + 100.0 * human as f64 / total as f64 + ), + ), + ], + w - 1, + )); + } + if !d.by_model.is_empty() { + rows.push(String::new()); + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── BY MODEL ── ".into()), + (p.dim.as_str(), "tracked edits".into()), + ], + w - 1, + )); + let top = d.by_model[0].1.max(1); + for (name, n) in d.by_model.iter().take(5) { + let bar = tc::meter(*n as f64 / top as f64, w.saturating_sub(36).max(6)); + let filled = bar.chars().filter(|c| *c == '█').count(); + rows.push(tc::seg( + &[ + (p.txt.as_str(), format!(" {}", tc::pad(name, 22))), + (p.agent.as_str(), format!("{:>7} ", commas(*n))), + (p.agent.as_str(), bar.chars().take(filled).collect::()), + (p.grid.as_str(), bar.chars().skip(filled).collect::()), + ], + w - 1, + )); + } } + rows.push(String::new()); + rows.push(tc::seg( + &[( + p.dim.as_str(), + " Authorship, not spend: this is how much code the agent wrote,".into(), + )], + w - 1, + )); + rows.push(tc::seg( + &[(p.dim.as_str(), " which is a different question from what it cost.".into())], + w - 1, + )); rows } + +/// The whole tab: the lanes and charts, what Cursor metered, and the plan +/// the percentages are percentages of. +pub fn tab(d: &Data, w: usize, _h: usize, _cfg: &Config, p: &Palette) -> Vec { + // METERED sits last-but-one on every tab, so Cursor's - which is + // published by the server rather than priced from a rate card - lands + // in the same place as everyone else's rather than floating up beside + // its quota. + let body = add_section(cursor_tab(d, w, p), cursor_metered(d, w, p)); + add_section(body, cursor_plan_rows(d, w, p)) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn empty_schema() -> Connection { + let con = Connection::open_in_memory().unwrap(); + con.execute_batch( + "create table ai_code_hashes \ + (hash text, conversationId text, model text, timestamp integer);\ + create table scored_commits \ + (hash text, linesAdded integer, humanLinesAdded integer);", + ) + .unwrap(); + con + } + + #[test] + fn the_tracking_reader_counts_distinct_not_rows() { + let con = empty_schema(); + // Two rows share a conversation so the distinct counts actually + // discriminate from the plain ones. + con.execute_batch( + "insert into ai_code_hashes values + ('a1', 'conv-1', 'model-a', 1000), + ('a2', 'conv-1', 'model-a', 2000), + ('a3', 'conv-2', 'model-b', 3000);\ + insert into scored_commits values ('c1', 120, 30), ('c2', 10, 5);", + ) + .unwrap(); + let t = read_tracking(&con).unwrap(); + assert_eq!(t.hashes, 3); + assert_eq!(t.conversations, 2); + assert_eq!(t.models, 2); + assert_eq!(t.by_model[0], ("model-a".to_string(), 2)); + assert_eq!(t.commits, 2); + assert_eq!(t.lines, 130); + assert_eq!(t.human_lines, 35); + assert_eq!(t.last, Some(3000.0)); + } + + #[test] + fn an_empty_database_reads_as_zeros_not_an_error() { + // sum() over no rows is NULL, and NULL here is a true zero - a + // machine that has scored nothing - not a failure to read. + let t = read_tracking(&empty_schema()).unwrap(); + assert_eq!(t.commits, 0); + assert_eq!(t.lines, 0); + assert_eq!(t.human_lines, 0); + assert_eq!(t.last, None); + } + + #[test] + fn a_broken_database_is_a_why_not_a_zero() { + // No tables at all: the reader must error so the tab can say why, + // never coast through with zeros that look like idleness. + let con = Connection::open_in_memory().unwrap(); + let why = match read_tracking(&con) { + Ok(_) => String::new(), + Err(e) => e.to_string(), + }; + assert!(!why.is_empty(), "a missing table must carry a reason"); + } + + #[test] + fn a_lane_that_publishes_nothing_is_absent_not_zero() { + // autoPercentUsed is missing, so no "auto" lane may appear - a + // fabricated 0% is indistinguishable from an untouched lane. + let d = Data { + live: Some(serde_json::json!({ + "planUsage": { "totalPercentUsed": 41.5, "apiPercentUsed": "2.5" }, + "billingCycleStart": "1700000000000", + "billingCycleEnd": "1702592000000", + })), + ..Data::default() + }; + let got = lanes(&d); + assert_eq!(got.len(), 2); + assert_eq!(got[0].label, "included"); + assert!((got[0].pct - 41.5).abs() < 1e-9); + // Connect writes int64 as strings; the cycle still has to be read. + assert_eq!(got[0].window_secs, Some(2_592_000.0)); + assert_eq!(got[0].reset, Some(1_702_592_000.0)); + // A percentage that arrives as a string is still a percentage. + assert_eq!(got[1].label, "api"); + assert!((got[1].pct - 2.5).abs() < 1e-9); + assert!(lanes(&Data::default()).is_empty()); + } + + #[test] + fn a_window_takes_only_its_own_days() { + let today = NaiveDate::parse_from_str("2026-08-23", "%Y-%m-%d").unwrap(); + let by = serde_json::json!({ + "2026-08-23": { "model-x": { "cents": 250.0, "tokens": 1000.0 } }, + "2026-08-01": { "model-x": { "cents": 100.0, "tokens": 400.0 }, + "model-y": { "cents": 500.0, "tokens": 900.0 } }, + "2026-07-01": { "model-x": { "cents": 9999.0, "tokens": 9.0 } }, + }); + let (cost, tokens, _) = window_of(&by, 1, today); + assert!((cost - 2.50).abs() < 1e-9); + assert!((tokens - 1000.0).abs() < 1e-9); + // Thirty days reaches 1 August but not 1 July. + let (cost, _, models) = window_of(&by, 30, today); + assert!((cost - 8.50).abs() < 1e-9); + // Costliest model first, in dollars. + assert_eq!(models[0].0, "model-y"); + assert!((models[0].1 - 5.0).abs() < 1e-9); + } + + #[test] + fn paging_stops_at_the_window_not_the_history() { + let cut = now() - 30.0 * 86400.0; + let recent = ((now() - 3600.0) * 1000.0) as i64; + let ancient = ((cut - 86400.0) * 1000.0) as i64; + let events = vec![ + serde_json::json!({ + "timestamp": recent.to_string(), "model": "model-x", + "tokenUsage": { "totalCents": "12.5", + "inputTokens": "100", "outputTokens": "50" }, + }), + serde_json::json!({ + "timestamp": ancient.to_string(), "model": "model-x", + "tokenUsage": { "totalCents": 999.0, + "inputTokens": 9, "outputTokens": 9 }, + }), + ]; + let mut t = Tally::default(); + let oldest = tally_events(&events, cut, &mut t); + // The old event is not counted, but its age is what tells the + // caller this page reached past the window and paging can stop. + assert_eq!(t.counted, 1); + assert!((t.vendor_cents - 12.5).abs() < 1e-9); + assert!((t.tokens - 150.0).abs() < 1e-9); + assert!(oldest < cut); + } + + #[test] + fn the_quota_names_all_three_lanes_and_the_spend_in_dollars() { + let p = palette(); + let start = ((now() - 10.0 * 86400.0) * 1000.0) as i64; + let end = ((now() + 20.0 * 86400.0) * 1000.0) as i64; + let d = Data { + live: Some(serde_json::json!({ + "planUsage": { + "totalPercentUsed": 41.0, "autoPercentUsed": 12.0, + "apiPercentUsed": 3.0, + "limit": "40000", "totalSpend": "16400", "remaining": "23600", + }, + "billingCycleStart": start.to_string(), + "billingCycleEnd": end.to_string(), + })), + ..Data::default() + }; + let joined = cursor_quota(&d, 100, &p).join("\n"); + for want in [ + "included", "auto", "api", "$164.00", "$400.00", "$236.00", + "of the cycle gone", "resets in", + ] { + assert!(joined.contains(want), "missing {}", want); + } + } + + #[test] + fn an_unreadable_database_says_why_instead_of_zeros() { + let p = palette(); + let d = Data { + why: "database is locked".into(), + ..Data::default() + }; + let joined = cursor_tab(&d, 90, &p).join("\n"); + assert!(joined.contains("database is locked")); + assert!(!joined.contains("AI-WRITTEN CODE")); + } + + #[test] + fn the_metered_section_reports_the_gap_the_plan_covers() { + let p = palette(); + let today = Local::now().date_naive().format("%Y-%m-%d").to_string(); + let d = Data { + events: Some(serde_json::json!({ + "by_day": { today.clone(): 1000.0 }, + "by_day_model": { + today: { "model-x": { "cents": 1000.0, "tokens": 5000.0 } }, + }, + "vendor_cents": 1000.0, + "days": 30, + })), + // Connect writes the metered figure as a string too. + spend: Some(serde_json::json!({ "totalCostCents": "400" })), + ..Data::default() + }; + let joined = cursor_metered(&d, 100, &p).join("\n"); + // Vendor list $10.00, Cursor metered $4.00, so the plan saved $6.00 + // - and the scope is named, because the QUOTA above it is too. + for want in ["account-wide", "$10.00", "cursor meters", "$4.00", "the plan saves", "$6.00"] + { + assert!(joined.contains(want), "missing {}", want); + } + } + + #[test] + fn thousands_read_as_thousands() { + assert_eq!(commas(0), "0"); + assert_eq!(commas(999), "999"); + assert_eq!(commas(1_000), "1,000"); + assert_eq!(commas(1_482_113), "1,482,113"); + } +} From 7234113570b3b48744e33eb3dfb9e7f0a5f2327e Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sun, 23 Aug 2026 18:38:04 +0800 Subject: [PATCH 038/147] usage: one midnight across all six calendars Grok bucketed its days in UTC while Claude, Codex and Cursor bucketed locally, and day_calendar draws all of them on one wall under the same headings. On a box eight hours from UTC that put the same turn on two different days depending on which section you read - two numbers on one screen that cannot both be true, which is the fault the founding rule exists to prevent. Grok now buckets locally. Nothing here argued for UTC: agentTimestampMs is epoch milliseconds with no zone of its own to honour, unlike Copilot's reset, which is a real UTC boundary and stays one. The existing test could not have caught this. Its fixture stamps UTC midnight, which east of Greenwich is the same calendar date either way, so it passed before the change and after it. The new one stamps 23:30 UTC, which is already tomorrow here, and asserts the turn is filed under the day it was on the wall clock of whoever is reading the pane. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/widgets/src/bin/usage/grok.rs | 50 +++++++++++++++++++++++++++--- 1 file changed, 46 insertions(+), 4 deletions(-) diff --git a/rust/widgets/src/bin/usage/grok.rs b/rust/widgets/src/bin/usage/grok.rs index 226dd56..df1ae29 100644 --- a/rust/widgets/src/bin/usage/grok.rs +++ b/rust/widgets/src/bin/usage/grok.rs @@ -23,7 +23,7 @@ use std::collections::{HashMap, HashSet}; -use chrono::{Datelike, NaiveDate, TimeZone, Utc}; +use chrono::{Datelike, Local, NaiveDate, TimeZone}; use toys_core as tc; use crate::shared::*; @@ -116,7 +116,12 @@ fn session_days(body: &str) -> (f64, HashMap) { let Some(ms) = int_after(line, "\"agentTimestampMs\":") else { continue; }; - let Some(at) = Utc.timestamp_millis_opt(ms as i64).single() else { + // Local, not UTC, because Claude, Codex and Cursor all bucket + // locally and day_calendar draws the four on one wall under the + // same headings. The stamp is epoch milliseconds with no zone of + // its own to honour, so there is nothing here arguing for UTC the + // way Copilot's reset boundary does. + let Some(at) = Local.timestamp_millis_opt(ms as i64).single() else { continue; }; *days.entry(at.date_naive().to_string()).or_insert(0.0) += step; @@ -567,7 +572,7 @@ mod tests { #[test] fn a_running_total_is_counted_as_deltas() { - // Two events on one UTC day and one on the next. Summed raw this + // Two events on one day and one on the next. Summed raw this // would read 1400 rather than 900, and put all of it on one day. let body = concat!( r#"{"totalTokens":100,"agentTimestampMs":1755302400000}"#, @@ -679,8 +684,45 @@ mod tests { assert_eq!(period_name(""), "current"); } + #[test] + fn a_turn_is_filed_under_the_day_it_was_that_day_here() { + // 1755388200000 is 23:30 UTC. East of Greenwich that is already + // tomorrow locally, west of it the same evening - either way the + // reader must agree with the wall clock of whoever is reading the + // pane, because the three calendars drawn beside this one do. + let body = concat!( + r#"{"totalTokens":0,"agentTimestampMs":1755388200000}"#, + "\n", + r#"{"totalTokens":700,"agentTimestampMs":1755388200000}"#, + "\n", + ); + let (_, days) = session_days(body); + let local = Local + .timestamp_millis_opt(1755388200000) + .single() + .expect("a fixed timestamp") + .date_naive() + .to_string(); + assert_eq!(days.get(&local), Some(&700.0)); + // And nothing was filed under the UTC day, unless this machine is + // on UTC and the two are the same date. + let utc = chrono::Utc + .timestamp_millis_opt(1755388200000) + .single() + .expect("a fixed timestamp") + .date_naive() + .to_string(); + if utc != local { + assert_eq!(days.get(&utc), None); + } + } + + /// The day the reader will file a stamp under - local, matching the + /// reader, so this asserts the bucketing rather than the zone this + /// machine happens to run in. fn day_of(ms: i64) -> String { - Utc.timestamp_millis_opt(ms) + Local + .timestamp_millis_opt(ms) .single() .expect("a fixed timestamp") .date_naive() From 9b8921877c7f2f9abb31a007ca078d393cef229f Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sun, 23 Aug 2026 18:45:53 +0800 Subject: [PATCH 039/147] usage: the left key went forwards on the first tab Python does active -= 1 and then active %= len(tabs), which wraps because Python's % is euclidean. usize cannot hold -1, so this port reached for saturating_sub(1).max(wrapping_sub(1)) - and on the first tab that is usize::MAX, which after % len is only len-1 when len is a power of two. With the seven tabs on this machine, left from the first tab landed on tab 1: exactly where right goes. Correct at 2, 4 and 8 tabs, wrong at 3, 5, 6, 7 and 9, so it would have looked fine on a box with a different set of agents installed. The cursor is signed now and rem_euclid brings it back into range, which is what Python's % was doing. The test walks every tab count from 2 to 9 rather than the one this machine happens to have, because a test at a single width had even odds of passing over it. Found by driving the keys, not by reading them: the key table matched the Python exactly, since both name left and right. It is the behaviour behind the hint that diverged. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/widgets/src/bin/usage.rs | 28 ++++++++++++++++++++++++---- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/rust/widgets/src/bin/usage.rs b/rust/widgets/src/bin/usage.rs index 530208e..7758db1 100644 --- a/rust/widgets/src/bin/usage.rs +++ b/rust/widgets/src/bin/usage.rs @@ -1416,7 +1416,10 @@ fn main() { tc::setup(); let mut keyboard = tc::Keyboard::new(); - let (mut active, mut tick) = (0usize, 0usize); + // Signed, because the left key has to be able to go below zero and + // wrap; rem_euclid then brings it back into range the way Python's + // % does for a negative index. + let (mut active, mut tick) = (0i64, 0usize); // One offset per tab. Switching away and back keeps your place, which // matters when a tab is forty rows and you were reading the bottom of it. let mut offsets: HashMap = HashMap::new(); @@ -1437,7 +1440,7 @@ fn main() { return; } "right" | "tab" | "l" => active += 1, - "left" | "h" => active = active.saturating_sub(1).max(active.wrapping_sub(1)), + "left" | "h" => active -= 1, "up" | "k" => moves.push(-1), "down" | "j" => moves.push(1), "pgup" => pages.push(-1), @@ -1462,8 +1465,8 @@ fn main() { }; let mut rows = vec![tc::title("agent usage", w, &p.agent)]; let tabs = visible_agents(&snapshot.installed, &cfg); - active %= tabs.len(); - let name = tabs[active].clone(); + active = active.rem_euclid(tabs.len() as i64); + let name = tabs[active as usize].clone(); let hidden = ORDER .iter() .filter(|n| { @@ -1721,6 +1724,23 @@ mod tests { assert!(iso_epoch("not a date").is_none()); } + #[test] + fn the_left_key_wraps_to_the_last_tab_at_every_tab_count() { + // How the loop moves between tabs: a signed cursor brought back + // into range with rem_euclid. Checked across counts because the + // fault this replaced was right for powers of two and wrong for + // everything else - a test at one width would have been a coin + // toss. + for tabs in 2i64..10 { + let step = |at: i64, by: i64| (at + by).rem_euclid(tabs); + assert_eq!(step(0, -1), tabs - 1, "left from the first of {}", tabs); + assert_eq!(step(tabs - 1, 1), 0, "right from the last of {}", tabs); + for at in 0..tabs { + assert_eq!(step(step(at, -1), 1), at, "there and back from {}", at); + } + } + } + #[test] fn a_bar_marks_where_an_even_burn_would_be() { let p = palette(); From 0fa08fc04dc3b43bf146b76ba3674a84709c13eb Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Sun, 23 Aug 2026 18:55:11 +0800 Subject: [PATCH 040/147] usage: an agent's two screens must not disagree about its quota Two readers were left where the tab showed a quota and the summary showed none, which is the same fault as two calendars keeping different midnights - one screen contradicting the other about the same fact. Codex: when the live call fails its tab falls back to the rollout snapshot and labels it "from the last session", but lanes() returned nothing, so Codex silently left a summary that names every other agent. This is not hypothetical - Claude took a 429 from this machine while the readers were being checked, and rendered its cached figure correctly because claude.rs already does this. The snapshot now reaches the summary marked stale, which the screen draws as "cached" rather than as a reset time, so it is not passed off as live. The test that asserted the old behaviour now states the new contract, and a second one covers a snapshot with no window length: the lane appears, but window_secs stays None so nothing paces it. Grok: read() returned before touching the log when this machine had no transcripts, so an account with a live credit window published no lane and its tab said only "No Grok sessions on this machine." The log is read either way now, and the tab draws the window above that note rather than instead of it - the quota is a fact about the account, the sections below it are facts about the disk, and both are true at once. Also: the tab cursor now runs through a named step_tab() that the wrap test calls. The test previously asserted a closure defined inside itself, so a regression in the loop would have left it green - which is the trap this repo's own notes name about tests written alongside a port. Confirmed by breaking step_tab and watching it fail. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/widgets/src/bin/usage.rs | 32 ++++++++++++----- rust/widgets/src/bin/usage/codex.rs | 51 ++++++++++++++++++++++++--- rust/widgets/src/bin/usage/grok.rs | 53 +++++++++++++++++++++++++---- 3 files changed, 117 insertions(+), 19 deletions(-) diff --git a/rust/widgets/src/bin/usage.rs b/rust/widgets/src/bin/usage.rs index 7758db1..513a3e8 100644 --- a/rust/widgets/src/bin/usage.rs +++ b/rust/widgets/src/bin/usage.rs @@ -1334,6 +1334,18 @@ fn tab_bar( tc::seg(&refs, w - 1) } +/// Where a tab cursor lands after moving `by` tabs among `count`. +/// +/// rem_euclid rather than %, because the left key drives this negative +/// and Rust's % keeps the sign where Python's does not. Named rather than +/// inlined so a test can reach the arithmetic the loop actually runs. +fn step_tab(at: i64, by: i64, count: usize) -> usize { + if count == 0 { + return 0; + } + (at + by).rem_euclid(count as i64) as usize +} + /// What to show before the first poll lands. /// /// Every tab's empty state is a statement of fact - no stats cache, no @@ -1465,8 +1477,9 @@ fn main() { }; let mut rows = vec![tc::title("agent usage", w, &p.agent)]; let tabs = visible_agents(&snapshot.installed, &cfg); - active = active.rem_euclid(tabs.len() as i64); - let name = tabs[active as usize].clone(); + let at = step_tab(active, 0, tabs.len()); + active = at as i64; + let name = tabs[at].clone(); let hidden = ORDER .iter() .filter(|n| { @@ -1731,14 +1744,17 @@ mod tests { // fault this replaced was right for powers of two and wrong for // everything else - a test at one width would have been a coin // toss. - for tabs in 2i64..10 { - let step = |at: i64, by: i64| (at + by).rem_euclid(tabs); - assert_eq!(step(0, -1), tabs - 1, "left from the first of {}", tabs); - assert_eq!(step(tabs - 1, 1), 0, "right from the last of {}", tabs); - for at in 0..tabs { - assert_eq!(step(step(at, -1), 1), at, "there and back from {}", at); + for count in 2usize..10 { + let n = count as i64; + assert_eq!(step_tab(0, -1, count), count - 1, "left from the first of {}", count); + assert_eq!(step_tab(n - 1, 1, count), 0, "right from the last of {}", count); + for at in 0..n { + let back = step_tab(at, -1, count) as i64; + assert_eq!(step_tab(back, 1, count) as i64, at, "there and back from {}", at); } } + // An empty tab list must not index anything. + assert_eq!(step_tab(0, -1, 0), 0); } #[test] diff --git a/rust/widgets/src/bin/usage/codex.rs b/rust/widgets/src/bin/usage/codex.rs index 234c1a6..cae4466 100644 --- a/rust/widgets/src/bin/usage/codex.rs +++ b/rust/widgets/src/bin/usage/codex.rs @@ -765,7 +765,23 @@ fn codex_plan_rows(d: &Data, w: usize, p: &Palette) -> Vec { /// put the wrong agent at the top. pub fn lanes(d: &Data) -> Vec { let Some(live) = d.live.as_ref() else { - return Vec::new(); + // The tab falls back to the rollout snapshot here and says "from + // the last session"; the summary used to show nothing at all, so + // Codex silently left a screen that names every other agent. The + // snapshot keeps the shape it has on disk - window_minutes, not + // seconds - and is marked stale, which is what that flag is for. + let win = d.limits.as_ref().map(|l| &l["primary"]); + let Some(win) = win.filter(|x| !x["used_percent"].is_null()) else { + return Vec::new(); + }; + let minutes = num(win, "window_minutes"); + return vec![Lane { + label: window_name(Some(minutes * 60.0)), + pct: num(win, "used_percent"), + window_secs: (minutes > 0.0).then_some(minutes * 60.0), + reset: win["resets_at"].as_f64(), + stale: true, + }]; }; let mut out: Vec = Vec::new(); for key in ["primary_window", "secondary_window"] { @@ -1015,9 +1031,36 @@ mod tests { let rows = codex_quota(&d, 90, &p).join(" "); assert!(rows.contains("from the last session"), "{}", rows); assert!(rows.contains("71%"), "{}", rows); - // But it never reaches the summary screen, which ranks agents against - // each other and would sort a day-old figure beside live ones. - assert!(lanes(&d).is_empty()); + // And it reaches the summary too, marked stale. The alternative was + // Codex disappearing from a screen that names every other agent + // while its own tab showed a quota - and the summary draws a stale + // lane as "cached" rather than as a reset time, so it is not passed + // off as a live figure beside live ones. + let got = lanes(&d); + assert_eq!(got.len(), 1, "{:?}", got); + assert!(got[0].stale); + assert_eq!(got[0].pct, 71.0); + assert_eq!(got[0].window_secs, Some(10080.0 * 60.0)); + assert_eq!(got[0].label, "7d"); + } + + #[test] + fn a_snapshot_with_no_window_length_still_reaches_the_summary() { + // window_minutes absent reads as 0, which is not a window. The lane + // must still appear - the percentage is the part that matters - but + // without a length nothing can pace it, so window_secs stays None + // and the summary draws no pace mark rather than an invented one. + let d = Data { + limits: Some( + serde_json::from_str(r#"{"primary":{"used_percent":40.0}}"#) + .expect("a snapshot"), + ), + ..Data::default() + }; + let got = lanes(&d); + assert_eq!(got.len(), 1); + assert_eq!(got[0].window_secs, None); + assert!(got[0].stale); } #[test] diff --git a/rust/widgets/src/bin/usage/grok.rs b/rust/widgets/src/bin/usage/grok.rs index df1ae29..300eb76 100644 --- a/rust/widgets/src/bin/usage/grok.rs +++ b/rust/widgets/src/bin/usage/grok.rs @@ -195,10 +195,17 @@ pub fn read(caches: &mut Caches) -> Data { let mut files = Vec::new(); walk(&under_home(SESSIONS), "updates.jsonl", &mut files); if files.is_empty() { - // The log is not read either. The tab this feeds leads with its - // transcripts and stops when there are none, so a credit window - // read here would have nowhere to be drawn. - return Data::default(); + // The log is still read. The credit window is account-wide and true + // whatever this disk holds, and hiding it because the local half is + // missing is the failure this repo keeps paying for. ok stays false, + // so the tab says there are no sessions - under the quota, not + // instead of it. + return Data { + quota: newest_quota( + tail_lines(&under_home(LOG), LOG_TAIL).iter().map(String::as_str), + ), + ..Data::default() + }; } let (mut total, mut sessions, mut newest) = (0.0f64, 0usize, 0.0f64); let mut daily: HashMap = HashMap::new(); @@ -311,9 +318,6 @@ fn seg_of(parts: &[(String, String)], w: usize) -> String { } fn grok_tab(d: &Data, w: usize, p: &Palette) -> Vec { - if !d.ok { - return no_local("No Grok sessions on this machine.", run_hint("grok"), w, p); - } let hue = agent_hue("grok"); let mut rows: Vec = Vec::new(); let quota = d.quota.as_ref().filter(|q| q.pct.is_some()); @@ -395,6 +399,19 @@ fn grok_tab(d: &Data, w: usize, p: &Palette) -> Vec { rows.push(String::new()); } + // Everything below counts what this machine recorded, so it stops here + // when there is nothing recorded - but the quota above has already been + // drawn, because it is a fact about the account rather than the disk. + if !d.ok { + rows.extend(no_local( + "No Grok sessions on this machine.", + run_hint("grok"), + w, + p, + )); + return rows; + } + rows.push(tc::seg( &[ (p.lbl.as_str(), " ── TOTALS ── ".into()), @@ -677,6 +694,28 @@ mod tests { } } + #[test] + fn a_machine_with_no_sessions_still_shows_the_credit_window() { + // The account has a quota and this disk has no transcripts. Both + // facts are true and the tab states both: the window is drawn, and + // the sections that count local work say there is none. Before this + // the log was never read, so the tab said only "No Grok sessions" + // and the summary screen listed Grok as publishing no quota at all. + let p = palette(); + let d = Data { + ok: false, + quota: newest_quota([LOG_LINE].into_iter()), + ..Data::default() + }; + let rows = grok_tab(&d, 90, &p).join(" "); + assert!(rows.contains("QUOTA"), "{}", rows); + assert!(rows.contains("42%") || rows.contains("43%"), "{}", rows); + assert!(rows.contains("No Grok sessions"), "{}", rows); + // And it publishes a lane, so the summary does not disagree with + // the tab about whether Grok has a quota. + assert_eq!(lanes(&d).len(), 1); + } + #[test] fn a_period_the_server_did_not_name_is_still_labelled() { assert_eq!(period_name("USAGE_PERIOD_TYPE_WEEKLY"), "weekly"); From 37048f4f53581c3a5432c56f1d070e4b3ebe07cc Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Mon, 24 Aug 2026 05:30:05 +0800 Subject: [PATCH 041/147] core: an unmapped key was arriving as several real ones decode() pushed "esc" and advanced a single character whenever an escape sequence was not in its table, so the rest of the sequence came through as literal keys. Delete decoded as esc,[,3,~ and F9 as esc,[,2,0,~ - and those characters are live bindings: "0" resets the pomodoro count in clocks, "1" and "2" reorder netwatch. Pressing an unrelated function key silently did something. Confirmed on the built binary before and after: with netwatch started in live sort, F5 flipped it to total. It no longer does, and "1" still does. common.py had this right and the port lost it. Restored, in its order, because the order is what decides whether an unknown key is ignored or acted on: longest known sequence first, then any complete CSI or SS3 consumed whole and dropped, then a lone ESC held for one poll so half an arrow is not read as Escape. poll() keeps what it has not consumed rather than clearing, so a sequence torn across two reads survives. One deliberate improvement over the Python, because the whole bug class is phantom keys: common.py holds only a bare ESC and discards a torn "ESC [ 1", emitting "[" and "1". Anything that could still complete is held here. The cost is bounded - a prefix that never completes is ended by the next character, swallowing one keystroke once - and a swallowed key does nothing, where a phantom key acts. The old test asserted decode("\x1b") == ["esc"], which is the drift rather than the contract; a bare ESC is indistinguishable from the start of a sequence still arriving. Three tests replace it, covering nine sequences this program does not use, the two-poll Escape, the torn arrow, and the half-arrived Home. Found by a review of the port. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/core/src/lib.rs | 209 +++++++++++++++++++++++++++++++++++++------ 1 file changed, 180 insertions(+), 29 deletions(-) diff --git a/rust/core/src/lib.rs b/rust/core/src/lib.rs index d154fba..9b75e22 100644 --- a/rust/core/src/lib.rs +++ b/rust/core/src/lib.rs @@ -784,6 +784,13 @@ pub struct Keyboard { fd: i32, saved: Option, buf: Vec, + /// What has arrived but not yet decoded. Kept between polls, because a + /// sequence can be torn across two reads on a slow link and half an + /// arrow key is not an Escape. + pending: String, + /// A bare ESC is held for one poll before it counts as Escape: it is + /// indistinguishable from the start of a sequence still arriving. + lone_esc: bool, } impl Keyboard { @@ -804,6 +811,8 @@ impl Keyboard { None }; Keyboard { + pending: String::new(), + lone_esc: false, fd, saved, buf: Vec::new(), @@ -857,9 +866,10 @@ impl Keyboard { Ok(n) => self.buf.extend_from_slice(&chunk[..n]), } } - let text = String::from_utf8_lossy(&self.buf).to_string(); + self.pending + .push_str(&String::from_utf8_lossy(&self.buf).to_string()); self.buf.clear(); - decode(&text) + decode(&mut self.pending, &mut self.lone_esc) } } @@ -870,7 +880,64 @@ impl Drop for Keyboard { } /// Turn a run of input bytes into key names. -fn decode(text: &str) -> Vec { +/// How long the unmapped escape sequence at the front of `s` is, in chars. +/// +/// The shapes a terminal actually sends: CSI is ESC [ then parameter +/// digits and semicolons then a final letter or tilde; SS3 is ESC O then +/// one letter. Anything matching is a key this program does not use - +/// Delete, a function key, a focus report, a bracketed-paste marker - and +/// must be swallowed whole. Emitting it a character at a time is how F9 +/// came to reset the pomodoro count, "0" being a real binding in clocks. +fn escape_len(s: &[char]) -> Option { + if s.first() != Some(&'\x1b') { + return None; + } + match s.get(1) { + Some('[') => { + let mut i = 2; + while matches!(s.get(i), Some(c) if c.is_ascii_digit() || *c == ';') { + i += 1; + } + match s.get(i) { + Some(c) if c.is_ascii_alphabetic() || *c == '~' => Some(i + 1), + _ => None, + } + } + Some('O') => match s.get(2) { + Some(c) if c.is_ascii_alphabetic() => Some(3), + _ => None, + }, + _ => None, + } +} + +/// Whether `s` is the start of a sequence that has not finished arriving. +/// +/// ESC, ESC O, and ESC [ with only parameter characters after it can all +/// still become a key. Holding them costs nothing - the next read either +/// completes the sequence or makes it a malformed escape - and it is the +/// difference between a torn arrow key being an arrow and it being three +/// characters that other keys are bound to. +fn still_arriving(s: &[char]) -> bool { + match s { + [] => false, + ['\x1b'] => true, + ['\x1b', 'O'] => true, + ['\x1b', '[', rest @ ..] => rest + .iter() + .all(|c| c.is_ascii_digit() || *c == ';'), + _ => false, + } +} + +/// Turn what the terminal sent into key names, leaving anything incomplete +/// in `buf` for the next poll. +/// +/// This mirrors common.py's Keyboard.poll rather than reinventing it: the +/// order of the checks is what decides whether an unknown key is silently +/// ignored or arrives as a handful of characters that other keys are bound +/// to. +fn decode(buf: &mut String, lone_esc: &mut bool) -> Vec { const SEQUENCES: &[(&str, &str)] = &[ ("\x1b[A", "up"), ("\x1b[B", "down"), @@ -892,29 +959,46 @@ fn decode(text: &str) -> Vec { ("\x1b[4~", "end"), ]; let mut keys = Vec::new(); - let chars: Vec = text.chars().collect(); - let mut i = 0usize; - while i < chars.len() { - if chars[i] == '\x1b' { - let rest: String = chars[i..].iter().collect(); + let mut chars: Vec = buf.chars().collect(); + let mut at = 0usize; + while at < chars.len() { + if chars[at] == '\x1b' { + let rest: String = chars[at..].iter().collect(); + // Longest wins: ESC [ 1 ~ is Home, not ESC [ 1 followed by ~. let found = SEQUENCES .iter() - .find(|(seq, _)| rest.starts_with(seq)) - .map(|(seq, name)| (seq.chars().count(), *name)); - match found { - Some((len, name)) => { - keys.push(name.to_string()); - i += len; - } - None => { - keys.push("esc".to_string()); - i += 1; + .filter(|(seq, _)| rest.starts_with(seq)) + .max_by_key(|(seq, _)| seq.chars().count()); + if let Some((seq, name)) = found { + keys.push((*name).to_string()); + at += seq.chars().count(); + continue; + } + if let Some(len) = escape_len(&chars[at..]) { + at += len; // a sequence this program does not map; drop it + continue; + } + if still_arriving(&chars[at..]) { + // Either a bare ESC or a half-arrived sequence. A bare ESC + // only counts as Escape once a second poll has found + // nothing following it; a longer prefix is simply kept, + // since it cannot be Escape at all. + if chars.len() - at == 1 { + if *lone_esc { + at += 1; + *lone_esc = false; + keys.push("esc".to_string()); + } else { + *lone_esc = true; + } } + break; } + at += 1; // malformed; discard the ESC and carry on continue; } - let ch = chars[i]; - i += 1; + let ch = chars[at]; + at += 1; match ch { '\r' | '\n' => keys.push("enter".to_string()), '\t' => keys.push("tab".to_string()), @@ -922,6 +1006,11 @@ fn decode(text: &str) -> Vec { c => keys.push(c.to_string()), } } + chars.drain(..at); + *buf = chars.into_iter().collect(); + if buf != "\x1b" { + *lone_esc = false; + } keys } @@ -1146,18 +1235,80 @@ mod tests { assert!(plain.contains(" CLOCKS ")); } + /// One poll's worth of input, decoded from a fresh keyboard. + fn keys(text: &str) -> Vec { + let mut buf = text.to_string(); + let mut held = false; + decode(&mut buf, &mut held) + } + #[test] fn arrows_decode_to_names() { - assert_eq!(decode("\x1b[A"), vec!["up"]); - assert_eq!(decode("\x1b[B\x1b[B"), vec!["down", "down"]); - assert_eq!(decode("q"), vec!["q"]); - assert_eq!(decode("\x1b"), vec!["esc"]); + assert_eq!(keys("\x1b[A"), vec!["up"]); + assert_eq!(keys("\x1b[B\x1b[B"), vec!["down", "down"]); + assert_eq!(keys("q"), vec!["q"]); // Both encodings of Home and End, since terminals disagree. - assert_eq!(decode("\x1b[H"), vec!["home"]); - assert_eq!(decode("\x1b[1~"), vec!["home"]); - assert_eq!(decode("\x1b[F"), vec!["end"]); - assert_eq!(decode("\x1b[4~"), vec!["end"]); - assert_eq!(decode("\r"), vec!["enter"]); + assert_eq!(keys("\x1b[H"), vec!["home"]); + assert_eq!(keys("\x1b[1~"), vec!["home"]); + assert_eq!(keys("\x1b[F"), vec!["end"]); + assert_eq!(keys("\x1b[4~"), vec!["end"]); + assert_eq!(keys("\r"), vec!["enter"]); + } + + #[test] + fn a_key_this_program_does_not_use_is_dropped_whole() { + // Each of these used to arrive as "esc" plus its own bytes as + // separate keys, and those bytes are live bindings elsewhere: "0" + // resets the pomodoro count in clocks, "1" and "2" reorder + // netwatch. Pressing F9 must do nothing, not reset a counter. + for seq in [ + "\x1b[3~", // Delete + "\x1b[20~", // F9 + "\x1b[15~", // F5 + "\x1bOP", // F1 + "\x1b[I", // focus in + "\x1b[O", // focus out + "\x1b[200~", // bracketed paste begins + "\x1b[Z", // shift-tab + "\x1b[1;5C", // ctrl-right + ] { + assert_eq!(keys(seq), Vec::::new(), "{:?} leaked a key", seq); + } + // And it does not swallow what follows it. + assert_eq!(keys("\x1b[3~q"), vec!["q"]); + } + + #[test] + fn a_bare_escape_waits_one_poll_before_it_counts() { + // ESC alone is indistinguishable from the first byte of a sequence + // still arriving, so it is held. Two polls with nothing following + // make it Escape; a poll that completes an arrow makes it an arrow. + let mut buf = "\x1b".to_string(); + let mut held = false; + assert_eq!(decode(&mut buf, &mut held), Vec::::new()); + assert!(held); + assert_eq!(decode(&mut buf, &mut held), vec!["esc"]); + assert!(buf.is_empty()); + + // The torn arrow: ESC in one read, "[A" in the next. + let mut buf = "\x1b".to_string(); + let mut held = false; + assert_eq!(decode(&mut buf, &mut held), Vec::::new()); + buf.push_str("[A"); + assert_eq!(decode(&mut buf, &mut held), vec!["up"]); + assert!(buf.is_empty()); + } + + #[test] + fn an_incomplete_sequence_stays_in_the_buffer() { + // Half of Home arrives; nothing is emitted and the half is kept, + // rather than being spent as "esc" and a bracket. + let mut buf = "\x1b[1".to_string(); + let mut held = false; + assert_eq!(decode(&mut buf, &mut held), Vec::::new()); + assert_eq!(buf, "\x1b[1"); + buf.push('~'); + assert_eq!(decode(&mut buf, &mut held), vec!["home"]); } #[test] From 936a3b489885b687bb2527e33f2a549e2aab1e46 Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Mon, 24 Aug 2026 05:30:13 +0800 Subject: [PATCH 042/147] tailnet: a test fixture named a real device The MagicDNS fixture used "pi-2-bne", which is a recognisable short form of a device on this tailnet, Brisbane marker included. It appears nowhere in tailnet.py - the port's tests introduced it - and this repo is public. Replaced with a name that is obviously invented. The test asserts that the MagicDNS label wins over a HostName of "localhost", and it does that just as well with a fictional peer. Found by a review of the port. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/widgets/src/bin/tailnet.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rust/widgets/src/bin/tailnet.rs b/rust/widgets/src/bin/tailnet.rs index bdd9e9a..e8359b9 100644 --- a/rust/widgets/src/bin/tailnet.rs +++ b/rust/widgets/src/bin/tailnet.rs @@ -1512,9 +1512,9 @@ mod tests { // Two iPads both call themselves "localhost"; the MagicDNS label is // unique across the tailnet and matches the admin console. let peer: serde_json::Value = - serde_json::from_str(r#"{"DNSName": "pi-2-bne.tail1234.ts.net.", "HostName": "localhost"}"#) + serde_json::from_str(r#"{"DNSName": "garden-sensor.example.ts.net.", "HostName": "localhost"}"#) .unwrap(); - assert_eq!(peer_name(&peer), "pi-2-bne"); + assert_eq!(peer_name(&peer), "garden-sensor"); // Only when there is no DNS name does the device get to say. let bare: serde_json::Value = serde_json::from_str(r#"{"HostName": "kitchen-pi"}"#).unwrap(); assert_eq!(peer_name(&bare), "kitchen-pi"); From 4e92768d012ad89eb89a1470036f01303b6362eb Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Mon, 24 Aug 2026 05:49:50 +0800 Subject: [PATCH 043/147] latency, link: one trace at a time, and one colour per cell Both charts merged the dot masks of every series into each braille cell and gave the cell to whichever series came later in the table. The commit that introduced it defends the choice - "the dots are merged, so no sample is lost" - and that reasoning is wrong in a way worth writing down, because the tests agreed with it all day. A cell can hold two traces' dots but only one colour. Two of the targets on this wall answer at 127ms and 138ms, which on a log axis is 0.036 of a decade where a dot row is 0.065, so they contested nearly every cell they occupied and the later one took all of them. One host was drawn end to end in another host's colour, and a third disappeared from the chart as a distinct line. No number on screen was false; the colour saying whose it was, was. That is the founding rule broken by the one function nobody was looking at. It was found by eye, from "why does mini-5 have two lines". The test that should have caught it asserted the union of the masks and the later colour - it pinned the defect precisely and called it the contract. A cell now belongs to exactly one trace and shows only that trace's dots. Where several want it, ownership advances with the column, so a contested stretch reads as interleaved dashes in the correct colours rather than one solid line belonging to nobody; keyed on the column rather than draw order, so it holds still between frames. Where two traces meet, the earlier one's dots are hidden in that cell - it stays legible either side, and a sample drawn in a colour that is not its own is worse than a sample not drawn. The function is copied in both files, so it had to be fixed twice. TOY-7 tracks folding it, and the other identical helpers, into toys-core. Both widgets now carry a selection that focuses one trace: the selected series is laid down last at full strength and every other is mixed toward the backdrop, so the trace being read wins any cell it shares. Nothing is selected until asked for, and no selection is the position above the first row and below the last - walking off either end returns there, and walking off it again comes in at the other, so focus is left the way it was entered. The fade is measured rather than picked: at 0.60 a faded trace reads 2.04 against the backdrop where the axis furniture reads 1.55, so it stays ink rather than sinking into the chrome, and sits 3.29 from its own full hue, clearing the 3.0 that separates two graphical tones. By 0.65 it is dimmer than the axis it is drawn over. The shapes this branch added to the heads of the traces are gone from both. Six shapes told six lines apart no better than six hues did, a seventh session repeated the first one's, and a braille cell has no room for a glyph that is not a dot. What replaced them is a colour chip at the head of each row, which is the same idea link.py had in its glyph column, and a name that goes from grey to white when its row is the one selected - which is what makes link's list readable and what latency never had. latency loses its status dot. latency.py prints a green circle beside every host, and it says exactly what NOW says one column to the right and at the same instant: a target that is not answering has no round trip to print. NOW turns red instead. The dot rode in the colour string as an uncounted cell, so removing it also lets every column sit under its own heading for the first time. link's detail screen scrolls rather than dropping its chart. It used to skip the chart silently when fewer than five rows were left after the fields, which on a thirty-row pane was always - and a chart that is missing for want of rows looks exactly like one missing for want of data. The chart now takes a floor of twelve rows and the screen scrolls, saying which rows it is showing. Right and enter go in, left and esc come out, and n and p step between sessions without returning to the list. link's list shows the peer's port. Four browser tabs from one machine to one dev server share a peer address and a local port, so four rows read as one connection repeated and the detail screen did not change when stepping between them. The peer's ephemeral port is the only field that differs. The name column widened to fit it, which also stopped truncating the login. These are deliberate divergences and they are not small ones. link.py has no scrolling detail screen and uses up and down to step between sessions from inside it. latency.py has no cursor at all - its whole key table is q, i, g and c - so its selection, its focus, its tint and its marker have no counterpart to be a port of. Both were asked for. The two implementations now answer differently to the same hand, and the wall runs them side by side, so it is worth knowing rather than discovering. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- rust/widgets/src/bin/latency.rs | 394 ++++++++++++++++++----- rust/widgets/src/bin/latency_help.txt | 16 +- rust/widgets/src/bin/link.rs | 437 ++++++++++++++++++++------ rust/widgets/src/bin/link_help.txt | 14 +- 4 files changed, 672 insertions(+), 189 deletions(-) diff --git a/rust/widgets/src/bin/latency.rs b/rust/widgets/src/bin/latency.rs index bccf728..4571dd9 100644 --- a/rust/widgets/src/bin/latency.rs +++ b/rust/widgets/src/bin/latency.rs @@ -20,6 +20,38 @@ //! arrives, so the numbers are what ping measured rather than anything this //! timed itself. +/// The hues targets are drawn in, kept as numbers rather than escapes so +/// that a faded set can be mixed from the same nine. +const HUES: &[(u8, u8, u8)] = &[ + (90, 220, 255), + (255, 170, 80), + (140, 255, 160), + (230, 140, 255), + (255, 110, 130), + (255, 230, 110), + (120, 160, 255), + (255, 140, 200), + (150, 255, 240), +]; + +/// The dark these widgets are drawn against. +/// +/// Not the terminal's real background - that cannot be asked for - but the +/// one the palette was chosen for, and what a trace is mixed toward when it +/// is not the one being looked at. +const BACKDROP: (u8, u8, u8) = (16, 22, 30); + +/// How far an unlooked-at trace is mixed toward the backdrop. +/// +/// Measured rather than chosen by eye, against the two things it sits +/// between. At 0.60 a faded trace reads 2.04 against the backdrop where the +/// axis furniture reads 1.55, so it stays visibly ink rather than sinking +/// into the chrome; and it is 3.29 from its own full-strength hue, clearing +/// the 3.0 that separates two graphical tones. Fading further wins +/// separation and loses the trace into the grid - by 0.65 it is dimmer than +/// the axis it is drawn over. +const FADE: f64 = 0.60; + use std::io::{BufRead, BufReader}; use std::sync::{Arc, Mutex}; use std::time::{Duration, SystemTime, UNIX_EPOCH}; @@ -488,21 +520,37 @@ fn braille_canvas( /// Lay the canvases over one another, cell by cell. /// -/// The dots are merged so that no sample is lost where two targets cross. -/// A cell can carry only one colour, and it goes to whichever series comes -/// later in the table above: which trace is hidden is then something the -/// reader can work out from that list rather than something the data decides -/// afresh every frame. +/// A braille cell can hold the dots of two traces but only one colour, and +/// there is no honest way to show both: whichever colour the cell takes, the +/// other trace's samples are drawn in a hue that is not theirs. That is a +/// number on screen that is not real, which is the one thing this collection +/// does not do - and it is not hypothetical, it hid a target completely. Two +/// hosts eleven milliseconds apart at 130ms sit 0.036 of a decade apart where +/// a dot row is 0.065, so they contest nearly every cell they occupy, and +/// merging painted the whole of one of them in the other's colour. +/// +/// So a cell belongs to exactly one trace and shows only that trace's dots. +/// Where several want it, ownership advances with the column, which makes a +/// contested stretch read as two interleaved dashed lines - each dot its own +/// colour - rather than as one solid line belonging to nobody. Traces that +/// never meet are unaffected and stay solid. fn overlay(layers: &[(String, Vec>)], cols: usize, rows: usize) -> Vec> { let mut cells = vec![vec![(String::new(), 0u8); cols]; rows]; - for (colour, canvas) in layers { - for (y, line) in canvas.iter().enumerate().take(rows) { - for (x, mask) in line.iter().enumerate().take(cols) { - if *mask != 0 { - cells[y][x].0 = colour.clone(); - cells[y][x].1 |= mask; - } + for y in 0..rows { + for x in 0..cols { + let dots = |canvas: &Vec>| { + canvas.get(y).and_then(|line| line.get(x)).copied().unwrap_or(0) + }; + let claims: Vec<&(String, Vec>)> = + layers.iter().filter(|(_, canvas)| dots(canvas) != 0).collect(); + if claims.is_empty() { + continue; } + // Deterministic, and a function of the column rather than of + // which sample happened to be drawn last, so the pattern holds + // still between frames instead of flickering. + let (colour, canvas) = claims[x % claims.len()]; + cells[y][x] = (colour.clone(), dots(canvas)); } } cells @@ -523,6 +571,7 @@ fn graph( h: usize, bucket: f64, how: &str, + focus: Option, p: &Palette, ) -> (Vec, f64) { let gw = w.saturating_sub(9).max(10); @@ -567,19 +616,54 @@ fn graph( let hi = (seen.iter().cloned().fold(0.0f64, f64::max) * 1.25).max(lo * 1.6); let (llo, lhi) = (lo.log10(), hi.log10()); - // One canvas per target rather than one shared grid: the glyphs used to - // tell the traces apart, and with braille the hue is all that is left to - // do it with, so each series has to keep its own until the last moment. - let layers: Vec<(String, Vec>)> = series - .iter() - .map(|(idx, values)| { - ( - p.hues[idx % p.hues.len()].clone(), - braille_canvas(values, llo, lhi, gw, gh), - ) - }) - .collect(); - let cells = overlay(&layers, gw, gh); + // One canvas per target rather than one shared grid: a braille cell can + // carry the dots of two traces but only one hue, so each series has to + // keep its own until the moment they are laid over one another. + // + // The selected target is laid down last, so where two traces share a + // cell the colour goes to the one being looked at rather than to + // whichever happens to sit lower in the table. The others are mixed + // most of the way to the backdrop - still drawn, because a chart that + // dropped every other target the moment you selected one would be + // answering a different question, but no longer competing. + let mut layers: Vec<(String, Vec>)> = Vec::with_capacity(series.len()); + let mut front: Option<(String, Vec>)> = None; + for (idx, values) in &series { + let canvas = braille_canvas(values, llo, lhi, gw, gh); + let hue = p.hues[idx % p.hues.len()].clone(); + match focus { + // Nothing selected: every trace at full strength, in table + // order, which is the chart this widget has always drawn. + None => layers.push((hue, canvas)), + Some(at) if at == *idx => front = Some((hue, canvas)), + Some(_) => layers.push((p.faded[idx % p.faded.len()].clone(), canvas)), + } + } + let mut cells = overlay(&layers, gw, gh); + // The focused trace takes its cells outright rather than being merged + // into them. + // + // `overlay` unions the dots and gives the cell to the last writer, which + // is right when every trace is equal: no sample is lost and the colour + // follows the table's order. Under focus it is a lie. Two targets a few + // percent apart share a cell constantly - 138ms and 127ms sit 0.036 of a + // decade apart where a dot row is 0.065 - and merging drew the other + // one's dots in the focused colour, so a flat trace came out two rows + // thick and the second row belonged to a different host. + // + // Replacing the cell hides the faded trace where the two meet. That is + // the right way round: the faded one is the one being pushed back, and + // it stays legible either side, whereas a sample drawn in a colour that + // is not its own is a number on screen that is not real. + if let Some((hue, canvas)) = front { + for (y, line) in canvas.iter().enumerate().take(gh) { + for (x, mask) in line.iter().enumerate().take(gw) { + if *mask != 0 { + cells[y][x] = (hue.clone(), *mask); + } + } + } + } let mut out = Vec::new(); for (y, line) in cells.iter().enumerate() { @@ -666,6 +750,10 @@ fn main() { }) .collect(); let labels: Vec = targets.iter().map(|t| t.label.clone()).collect(); + // Fixed for the life of the run: one poll thread per host, and the + // list never grows or shrinks, so the cursor can be reasoned about + // without holding the lock to count rows. + let count = hosts.len(); let shared = Arc::new(Mutex::new(targets)); let settings = Arc::new(Mutex::new(live)); let events: Arc>> = Arc::new(Mutex::new(Vec::new())); @@ -683,6 +771,13 @@ fn main() { tc::setup(); let mut keyboard = tc::Keyboard::new(); + // Which target the chart brings to the front, if any. Starts at none, + // so the chart opens saying what it has always said - every target at + // equal weight - and focus is something you ask for rather than a state + // you have to escape from. Clamped against the list when the frame is + // drawn rather than when the key is pressed, because targets are only + // known to the poll threads. + let mut selected: Option = None; loop { for key in keyboard.poll() { match key.as_str() { @@ -691,6 +786,28 @@ fn main() { tc::restore_screen(); return; } + // No selection is the position above the first row and + // below the last one, so walking off either end lands there + // and walking off it again comes in at the other. Focus is + // then something you can leave the way you entered it, + // rather than a state with only one door. + "up" | "k" | "K" => { + selected = match selected { + None => count.checked_sub(1), + Some(0) => None, + Some(at) => Some(at - 1), + } + } + "down" | "j" | "J" => { + selected = match selected { + None if count > 0 => Some(0), + None => None, + Some(at) if at + 1 >= count => None, + Some(at) => Some(at + 1), + } + } + // Back to every target drawn alike. + "esc" => selected = None, "i" | "I" => { if let Ok(mut s) = settings.lock() { s.interval = cycle(INTERVAL_CHOICES, s.interval); @@ -719,6 +836,13 @@ fn main() { Ok(g) => g.clone(), Err(_) => return, }; + if let Some(at) = selected { + selected = if snapshot.is_empty() { + None + } else { + Some(at.min(snapshot.len() - 1)) + }; + } let (interval, per_column, how) = match settings.lock() { Ok(s) => (s.interval, s.seconds_per_column, s.aggregate.clone()), Err(_) => return, @@ -743,10 +867,6 @@ fn main() { format!(" · {} of {}s blocks", how, bucket) }, ), - ( - p.grid.as_str(), - " [i]nterval [g]roup [c]olumns [q]uit".into(), - ), ], w - 1, )); @@ -761,7 +881,7 @@ fn main() { &[( p.lbl.as_str(), format!( - " {} {:>7} {:>7}{} {:>7} {:>7} {:>7} {:>6}", + " {} {:>7} {:>7}{} {:>7} {:>7} {:>7} {:>6}", tc::pad("HOST", name_w), "NOW", "AVG", @@ -776,7 +896,12 @@ fn main() { )); for (i, t) in snapshot.iter().enumerate() { let st = t.stats(); - let hue = &p.hues[i % p.hues.len()]; + let here = selected == Some(i); + // The selected row is tinted rather than marked, so the thing + // that says "this one" in the table is the same thing that says + // it in the chart: one target at full strength, the rest behind. + let tint = if here { tc::bg(28, 44, 62) } else { String::new() }; + let raw_hue = p.hues[i % p.hues.len()].clone(); let loss_c = if st.loss == 0.0 { &p.ok } else if st.loss < 5.0 { @@ -784,38 +909,86 @@ fn main() { } else { &p.bad }; - rows.push(tc::seg( - &[ - // The dot rides in the colour rather than the text, so - // it costs no cell - which is how latency.py draws it, - // and the two have to line up column for column when - // they sit side by side. - ( - &format!( - "{}{}", - if t.alive { &p.ok } else { &p.bad }, - if t.alive { '●' } else { '○' } - ), - " ".to_string(), - ), - (hue.as_str(), tc::pad(&t.label, name_w)), - (p.txt.as_str(), format!(" {}", fmt_ms(st.now))), - (p.txt.as_str(), format!(" {}", fmt_ms(st.avg))), - ( - p.ok.as_str(), - if show_med { - format!(" {}", fmt_ms(st.med)) - } else { - String::new() - }, - ), - (p.dim.as_str(), format!(" {}", fmt_ms(st.min))), - (p.dim.as_str(), format!(" {}", fmt_ms(st.max))), - (p.txt.as_str(), format!(" {}", fmt_ms(st.jit))), - (loss_c.as_str(), format!(" {:>5.1}%", st.loss)), - ], - w - 1, - )); + // A tint is a background escape and has to come before every + // foreground on the row, or the colour that follows it resets + // the background and the highlight stops halfway across. + let tinted = |colour: &str| format!("{}{}", tint, colour); + // MIN and MAX are drawn in `dim`, which does not clear AA on the + // tint. On the selected row they get the lighter one. + let dim = if here { &p.dim_lit } else { &p.dim }; + // Owned colours rather than borrowed: the row is assembled + // before it is measured, so a `&format!(...)` temporary would not + // outlive the vector it was put in. + let mut cells: Vec<(String, String)> = vec![ + // No status dot. latency.py draws ● or ○ here, but it says + // exactly what NOW says one column to the right and at the + // same instant - a target that is not answering has no round + // trip to print - so it was six glyphs of permanent green + // reporting something already on screen. Losing it also lets + // the columns sit under their own headings, which the dot's + // uncounted cell prevented. + // + // The cell the header spends on a leading space is the marker + // column. A tint alone says "this row is not like the others" + // without saying which way, and it is gone entirely on a + // terminal that will not paint one - so the mark is a solid + // bar rather than a glyph, because the tint cannot be made + // louder: (28,44,62) is already as bright as it goes before + // `bad` red drops under AA on it, measured at 4.80 against a + // floor of 4.5. + // + // ▐ is East Asian Neutral, so it is one cell wherever it + // renders. ▌ and █ read better but are Ambiguous, and this + // row is otherwise all ASCII - one Ambiguous cell would shift + // the selected row and nothing else. + (tinted(&raw_hue), "▐".to_string()), + // The chip is a colour, not a letter, and reads as part of + // the name when it touches it. The header spends the same + // cell so the columns still sit under their own headings. + (tint.clone(), " ".to_string()), + // Grey until this is the row being looked at, then white - + // which is how link tells its selected session apart, and + // the reason its list reads at a glance. The hue cannot do + // that job: fading a hue far enough to be a contrast takes + // it under AA long before it is a difference the eye + // catches, measured at 3.86 by a fade of 0.30 and only 1.73 + // away from the full colour. So the hue moves to the chip, + // which is what link puts its glyph in, and the name is free + // to swing between two colours that are both readable. + ( + tinted(if here { &p.txt } else { &p.dim_lit }), + tc::pad(&t.label, name_w), + ), + // Red when there is no round trip to report, which is the + // whole of what the status dot used to say. + ( + tinted(if st.now.is_some() { &p.txt } else { &p.bad }), + format!(" {}", fmt_ms(st.now)), + ), + (tinted(&p.txt), format!(" {}", fmt_ms(st.avg))), + ( + tinted(&p.ok), + if show_med { + format!(" {}", fmt_ms(st.med)) + } else { + String::new() + }, + ), + (tinted(dim), format!(" {}", fmt_ms(st.min))), + (tinted(dim), format!(" {}", fmt_ms(st.max))), + (tinted(&p.txt), format!(" {}", fmt_ms(st.jit))), + (tinted(loss_c), format!(" {:>5.1}%", st.loss)), + ]; + // Carry the tint to the edge. Left ragged it stops wherever the + // last number happens to end, and a highlight that stops short + // reads as a smudge rather than as a bar across the row. + if here { + let used: usize = cells.iter().map(|(_, t)| t.chars().count()).sum(); + cells.push((tint.clone(), " ".repeat((w - 1).saturating_sub(used)))); + } + let parts: Vec<(&str, String)> = + cells.iter().map(|(c, t)| (c.as_str(), t.clone())).collect(); + rows.push(tc::seg(&parts, w - 1)); if wide && !t.samples.is_empty() { let mut line: Vec<(&str, String)> = vec![(p.dim.as_str(), " ".into())]; let spark = sparkline(&t.samples, w.saturating_sub(6), &p); @@ -827,11 +1000,39 @@ fn main() { } rows.push(String::new()); + // The keys live along the bottom, so they are measured before the + // chart and the log are sized and the rows they occupy are taken out + // of what is left. Sizing the body to the whole pane and appending + // them afterwards is how a footer ends up pushed off the bottom of + // the screen it documents. `pack_hints` wraps without splitting one, + // because half a hint teaches a key that does not exist. + let mut hints: Vec> = vec![vec![ + (p.head.as_str(), "↑↓".into()), + (p.dim.as_str(), " focus".into()), + ]]; + // Offered only once there is a selection to clear. An empty hint + // would still cost `pack_hints` a separator and leave a gap in the + // footer where a key used to be. + if selected.is_some() { + hints.push(vec![(p.dim.as_str(), "[esc] clear focus".into())]); + } + hints.extend([ + vec![(p.dim.as_str(), "[i]nterval".into())], + vec![(p.dim.as_str(), "[g]roup".into())], + vec![(p.dim.as_str(), "[c]olumns".into())], + vec![(p.dim.as_str(), "[q]uit".into())], + ]); + let foot: Vec = tc::pack_hints(&hints, w - 2, " ") + .into_iter() + .map(|l| format!(" {}", l)) + .collect(); + let body_h = h.saturating_sub(foot.len()); + // The log only earns its space on a tall pane: on a short one the // chart is the thing worth keeping. - let log_h = if h.saturating_sub(rows.len()) > 20 { 7 } else { 0 }; - let gh = h.saturating_sub(rows.len() + log_h + 4).max(4); - let (chart, span) = graph(&snapshot, w, gh, bucket, &how, &p); + let log_h = if body_h.saturating_sub(rows.len()) > 20 { 7 } else { 0 }; + let gh = body_h.saturating_sub(rows.len() + log_h + 4).max(4); + let (chart, span) = graph(&snapshot, w, gh, bucket, &how, selected, &p); let drawn = chart.len(); rows.extend(chart); if drawn > 1 { @@ -893,6 +1094,11 @@ fn main() { } } + while rows.len() < body_h { + rows.push(String::new()); + } + rows.truncate(body_h); + rows.extend(foot); tc::draw(&rows, w, h); std::thread::sleep(Duration::from_millis(300)); } @@ -967,8 +1173,16 @@ struct Palette { grid: String, txt: String, lbl: String, + /// The readable dim, used wherever `dim` would fail: on the selected + /// row's tint, where (70,100,120) measures 2.27 against AA's 4.5, and + /// for every host name, which is grey until its row is the one selected. + /// This clears AA on the tint at 4.83 and on the backdrop at 6.18. + dim_lit: String, head: String, hues: Vec, + /// The same nine, mixed toward the backdrop, for traces that are not + /// the one selected. + faded: Vec, } fn palette() -> Palette { @@ -980,21 +1194,13 @@ fn palette() -> Palette { grid: tc::rgb(38, 58, 74), txt: tc::rgb(215, 235, 250), lbl: tc::rgb(120, 170, 200), + dim_lit: tc::rgb(120, 155, 180), head: tc::rgb(90, 220, 255), // latency.py's own nine, not the six the other widgets share: the // traces are told apart by hue alone now that the glyphs are gone, // so more targets than six needs more than six colours. - hues: vec![ - tc::rgb(90, 220, 255), - tc::rgb(255, 170, 80), - tc::rgb(140, 255, 160), - tc::rgb(230, 140, 255), - tc::rgb(255, 110, 130), - tc::rgb(255, 230, 110), - tc::rgb(120, 160, 255), - tc::rgb(255, 140, 200), - tc::rgb(150, 255, 240), - ], + hues: HUES.iter().map(|c| tc::rgb(c.0, c.1, c.2)).collect(), + faded: HUES.iter().map(|c| tc::mix(*c, BACKDROP, FADE)).collect(), } } @@ -1166,21 +1372,37 @@ mod tests { } #[test] - fn two_traces_in_one_cell_keep_both_their_dots() { - let top = braille_canvas(&[Some(10.0), Some(10.0)], 0.0, 1.0, 1, 1); - let bottom = braille_canvas(&[Some(1.0), Some(1.0)], 0.0, 1.0, 1, 1); - assert!(top[0][0] != 0 && bottom[0][0] != 0); + fn a_contested_cell_belongs_to_one_trace_and_shares_the_run() { + // Two flat traces, one at the top of the decade and one at the + // bottom, both drawn across all four cells. This used to assert the + // union of their dots in the later trace's colour, and that was the + // bug: on a real chart two hosts a few percent apart contest every + // cell, so one of them was drawn entirely in the other's hue and + // vanished from the chart as a distinct line. + let high = [Some(10.0); 8]; + let low = [Some(1.0); 8]; + let top = braille_canvas(&high, 0.0, 1.0, 4, 1); + let bottom = braille_canvas(&low, 0.0, 1.0, 4, 1); + assert!(top[0][0] != 0 && bottom[0][0] != 0, "both must contest"); let cells = overlay( &[ ("first".to_string(), top.clone()), ("second".to_string(), bottom.clone()), ], - 1, + 4, 1, ); - assert_eq!(cells[0][0].1, top[0][0] | bottom[0][0]); - // Only the hue has to be given up, and it goes to the lower row of - // the table, which is the rule the reader can apply from outside. - assert_eq!(cells[0][0].0, "second"); + for x in 0..4 { + let (whose, mask) = &cells[0][x]; + // Never the union: a cell shows one trace's samples, so no dot + // is ever painted in a colour that is not its own. + let mine = if whose == "first" { top[0][x] } else { bottom[0][x] }; + assert_eq!(*mask, mine, "column {} carries the other trace's dots", x); + assert_ne!(*mask, top[0][x] | bottom[0][x], "column {} merged", x); + } + // Ownership advances with the column, so a contested stretch shows + // both traces as interleaved dashes rather than hiding one. + let owners: Vec<&str> = (0..4).map(|x| cells[0][x].0.as_str()).collect(); + assert_eq!(owners, vec!["first", "second", "first", "second"]); } } diff --git a/rust/widgets/src/bin/latency_help.txt b/rust/widgets/src/bin/latency_help.txt index 2ccb565..a2b5ca6 100644 --- a/rust/widgets/src/bin/latency_help.txt +++ b/rust/widgets/src/bin/latency_help.txt @@ -5,9 +5,11 @@ sparkline, a shared log-scale time graph, and a log of loss/spike events. latency [-i SECONDS] [-c SECONDS] [host ...] -Keys while running: i cycles the ping interval (0.2/0.5/1/2/5s, applied to -running pings immediately), g cycles the column aggregation, c cycles seconds -per graph column, q quits. +Keys while running: up/down (or k/j) picks the target the graph brings to the +front - up from the first target and down from the last put it back to +drawing every target alike, as does esc - i cycles the ping +interval (0.2/0.5/1/2/5s, applied to running pings immediately), g cycles the +column aggregation, c cycles seconds per graph column, q quits. -i sets the ping interval. -g picks how samples sharing a column combine (median, mean, min, max, p95; median by default, because latency is @@ -24,5 +26,9 @@ that needs a probe running on the far end. The shared graph is drawn on a braille dot canvas rather than one character per sample, so it holds twice the history and reads as a line rather than a -column of marks. Targets are told apart by colour there; the per-target -sparkline above it is still one character per ping. +column of marks. Targets share the one chart, so the selected row is drawn +last and at full strength while the rest are mixed toward the background: +where two traces cross, the colour goes to the one being looked at rather +than to whichever sits lower in the table. The others stay drawn rather than +hidden, because a chart that showed one target at a time would answer a +different question. The per-target sparkline is still one character per ping. diff --git a/rust/widgets/src/bin/link.rs b/rust/widgets/src/bin/link.rs index e1e8ead..6972bb1 100644 --- a/rust/widgets/src/bin/link.rs +++ b/rust/widgets/src/bin/link.rs @@ -28,8 +28,44 @@ use std::time::Duration; use toys_core as tc; const IDLE_AFTER: f64 = 300.0; + +/// The fewest rows the detail chart is worth drawing in. +/// +/// It used to take whatever the fields left over and be dropped silently +/// when that came to less than five, so a short pane showed the numbers and +/// no chart and said nothing about why - indistinguishable from a session +/// with no history. It now takes its rows regardless and the screen scrolls. +const MIN_CHART: usize = 12; + +/// How the detail screen reports where you are in it, at a width that does +/// not change with the numbers - the footer is measured before the body is +/// built, so an indicator that grew by a character could change how many +/// lines the hints wrap onto and leave the body sized for the wrong one. +fn scroll_label(first: usize, last: usize, total: usize) -> String { + format!("rows {:>3}-{:>3} of {:>3}", first, last, total) +} const SPARK: &[char] = &['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█']; -const SERIES: &[char] = &['●', '▲', '■', '◆', '✚', '✦']; +/// The hues sessions are drawn in, kept as numbers so a faded set can be +/// mixed from the same six. +const HUES: &[(u8, u8, u8)] = &[ + (120, 200, 255), + (150, 230, 180), + (220, 170, 255), + (160, 190, 240), + (200, 220, 150), + (240, 180, 210), +]; + +/// The dark these widgets are drawn against - not the terminal's real +/// background, which cannot be asked for, but the one the palette was chosen +/// for, and what a trace is mixed toward when it is not the one selected. +const BACKDROP: (u8, u8, u8) = (16, 22, 30); + +/// How far an unlooked-at trace is mixed toward the backdrop. Measured +/// against the two things it sits between: at 0.60 a faded trace stays +/// visibly ink rather than sinking into the axis furniture, and is far +/// enough from its own full-strength hue to read as a different weight. +const FADE: f64 = 0.60; #[derive(Clone, Default)] struct Session { @@ -436,10 +472,25 @@ fn main() { tc::setup(); let mut keyboard = tc::Keyboard::new(); - let (mut selected, mut hide_idle, mut span_at) = (0usize, false, 0usize); + // Nothing selected until asked for, and no selection is the position + // above the first row and below the last, so walking off either end + // lands there and walking off it again comes in at the other. The chart + // then opens showing every session at equal weight, and focus is + // something you leave the way you entered it. + let (mut selected, mut hide_idle, mut span_at) = + (None::, false, 0usize); + let mut count = 0usize; let mut detail = false; + // How far down the detail screen we are. Clamped against the body every + // frame rather than when the key is pressed, because the body's length + // depends on the pane, which can change under us between frames. + let mut scroll = 0usize; loop { + // Read before the keys rather than after them, so a page key knows + // how big a page is on this pane. + let (w, h) = tc::size(); + let page = h.saturating_sub(4).max(1); for key in keyboard.poll() { match key.as_str() { "q" | "Q" => { @@ -447,10 +498,69 @@ fn main() { tc::restore_screen(); return; } - "up" | "k" | "K" => selected = selected.saturating_sub(1), - "down" | "j" | "J" => selected += 1, - "enter" | "i" | "I" => detail = !detail, - "esc" => detail = false, + // Up and down mean "move through what is in front of you" + // in both views: in the list that is the selection, on the + // detail screen it is the screen itself. + "up" | "k" | "K" => { + if detail { + scroll = scroll.saturating_sub(1); + } else { + selected = match selected { + None => count.checked_sub(1), + Some(0) => None, + Some(at) => Some(at - 1), + }; + } + } + "down" | "j" | "J" => { + if detail { + scroll = scroll.saturating_add(1); + } else { + selected = match selected { + None if count > 0 => Some(0), + None => None, + Some(at) if at + 1 >= count => None, + Some(at) => Some(at + 1), + }; + } + } + // Right goes in and left comes back out, the way a column + // of panes works, so the hand does not have to learn a key + // for it. Enter and esc still do the same two things. + "right" | "enter" | "i" | "I" if !detail => { + // Opening with nothing selected takes the first row + // rather than doing nothing, which would be a key that + // the footer offers and that does not answer. + if selected.is_none() && count > 0 { + selected = Some(0); + } + detail = selected.is_some(); + scroll = 0; + } + "left" | "esc" | "enter" | "i" | "I" if detail => { + detail = false; + scroll = 0; + } + // Stepping between connections without going back to the + // list. This was on left and right until those were given + // their directional meaning; it is worth keeping, because + // comparing two sockets is most of what the detail screen + // is for. + // Stays within the list rather than falling off it: the + // detail screen has to be showing something. + "n" | "N" if detail => { + selected = selected.map(|at| (at + 1).min(count.saturating_sub(1))); + scroll = 0; + } + "p" | "P" if detail => { + selected = selected.map(|at| at.saturating_sub(1)); + scroll = 0; + } + "pgup" if detail => scroll = scroll.saturating_sub(page), + "pgdn" if detail => scroll = scroll.saturating_add(page), + "home" if detail => scroll = 0, + // Clamped to the end of the body when the frame is drawn. + "end" if detail => scroll = usize::MAX, "o" | "O" => hide_idle = !hide_idle, "w" | "W" => span_at = (span_at + 1) % windows.len(), "r" | "R" => { @@ -464,7 +574,6 @@ fn main() { } } - let (w, h) = tc::size(); let guard = match state.lock() { Ok(g) => g, Err(_) => return, @@ -475,43 +584,79 @@ fn main() { .filter(|r| !(hide_idle && r.lastrcv.unwrap_or(0.0) > IDLE_AFTER * 1000.0)) .cloned() .collect(); - if !shown.is_empty() && selected >= shown.len() { - selected = shown.len() - 1; + count = shown.len(); + if let Some(at) = selected { + selected = if shown.is_empty() { + None + } else { + Some(at.min(shown.len() - 1)) + }; + } + if selected.is_none() { + detail = false; } let window = windows[span_at]; // One connection in full, on its own screen. The list is for // noticing; this is for looking into, and the two want different // amounts of room for the same chart. - if detail && !shown.is_empty() { - let pick = selected.min(shown.len() - 1); + if let (true, Some(pick)) = (detail && !shown.is_empty(), selected) { // The footer is measured before the body is built, and the body // is told the height it actually has. Sizing the chart to the // whole pane and appending the hints afterwards pushed them off // the bottom of it - the keys out of this screen were the rows // being lost. - let hints: Vec> = vec![ - vec![(p.dim.as_str(), "[esc] back".into())], + // Built twice: once to learn how many lines the hints wrap + // onto, and again with the real position once the body exists. + // `scroll_label` is a fixed width, so the second pass cannot + // wrap differently from the first and leave the body sized + // against a footer that is no longer there. + let detail_hints = |place: String| -> Vec> { vec![ - (p.accent.as_str(), "[w]".into()), - (p.dim.as_str(), format!(" {}", window_label(window))), - ], - vec![(p.dim.as_str(), "[r]efresh".into())], - vec![(p.dim.as_str(), "[q]uit".into())], - ]; - let foot: Vec = tc::pack_hints(&hints, w - 2, " ") - .into_iter() - .map(|l| format!(" {}", l)) - .collect(); + vec![ + (p.accent.as_str(), "←".into()), + (p.dim.as_str(), "/[esc] back".into()), + ], + vec![ + (p.accent.as_str(), "↑↓".into()), + (p.dim.as_str(), " scroll".into()), + ], + vec![(p.dim.as_str(), "[n]ext [p]rev".into())], + vec![ + (p.accent.as_str(), "[w]".into()), + (p.dim.as_str(), format!(" {}", window_label(window))), + ], + vec![(p.dim.as_str(), "[r]efresh".into())], + vec![(p.dim.as_str(), "[q]uit".into())], + vec![(p.dim.as_str(), place)], + ] + }; + let pack = |hints: &[Vec<(&str, String)>]| -> Vec { + tc::pack_hints(hints, w - 2, " ") + .into_iter() + .map(|l| format!(" {}", l)) + .collect() + }; + let foot = pack(&detail_hints(scroll_label(0, 0, 0))); let room = h.saturating_sub(foot.len() + 1).max(1); - let mut body = detail_view(&shown[pick], &guard, w, room, pick, window, refresh, &p); + let body = detail_view(&shown[pick], &guard, w, room, pick, window, refresh, &p); drop(guard); - body.truncate(room); - while body.len() < room { - body.push(String::new()); + // The body is as tall as it needs to be and the pane shows a + // window onto it, rather than the body being cut to the pane + // and the remainder going unmentioned. + let furthest = body.len().saturating_sub(room); + scroll = scroll.min(furthest); + let last = (scroll + room).min(body.len()); + let mut shown_body: Vec = body[scroll..last].to_vec(); + while shown_body.len() < room { + shown_body.push(String::new()); } - body.extend(foot); - tc::draw(&body, w, h); + shown_body.extend(pack(&detail_hints(scroll_label( + scroll + 1, + last, + body.len(), + )))); + tc::draw(&shown_body, w, h); std::thread::sleep(Duration::from_millis(200)); continue; } @@ -552,8 +697,31 @@ fn main() { rows.extend(table(&shown, &guard, w, selected, &p)); rows.push(String::new()); let room = h.saturating_sub(rows.len() + 4); - if room >= 5 { - rows.extend(graph(&shown, &guard.history, w, room, 0, window, refresh, &p)); + if room < 5 { + // Say so rather than leaving a gap: a chart that is missing + // for want of rows looks exactly like one missing for want + // of data, and only one of those is the reader's to fix. + if room >= 1 { + rows.push(tc::seg( + &[( + p.dim.as_str(), + format!(" chart needs {} more rows", 5 - room), + )], + w - 1, + )); + } + } else { + rows.extend(graph( + &shown, + &guard.history, + w, + room, + 0, + selected, + window, + refresh, + &p, + )); rows.push(tc::seg( &[ (p.dim.as_str(), " ".repeat(7)), @@ -575,7 +743,10 @@ fn main() { let hints: Vec> = vec![ vec![(p.accent.as_str(), "↑↓".into()), (p.dim.as_str(), " select".into())], - vec![(p.dim.as_str(), "[↵] open".into())], + vec![ + (p.accent.as_str(), "→".into()), + (p.dim.as_str(), "/[↵] open".into()), + ], vec![ (p.accent.as_str(), "[w]".into()), (p.dim.as_str(), format!(" {}", window_label(window))), @@ -618,7 +789,13 @@ fn plotted_span( capped as f64 * refresh } -fn table(rows: &[Session], state: &State, w: usize, selected: usize, p: &Palette) -> Vec { +fn table( + rows: &[Session], + state: &State, + w: usize, + selected: Option, + p: &Palette, +) -> Vec { // The Python's header, column for column: the two have to sit side by // side in a wall and read as the same widget. let wide = w >= 74; @@ -626,11 +803,16 @@ fn table(rows: &[Session], state: &State, w: usize, selected: usize, p: &Palette // land the NOW column under its heading. Three and twenty also add up to // a plausible-looking row, and put every number three cells right of the // word above it. - let name_w = 18usize; + // Wide enough for the peer's own port, because that is the only field + // that differs between sockets from one machine to one service: four + // browser tabs against the same dev server share an address and a local + // port and are told apart by nothing else. 21 fits the longest IPv4 + // address and port; the wider pane spends five more on the login. + let name_w = if wide { 26usize } else { 21usize }; let mut out = vec![tc::seg( &[ (p.dim.as_str(), " PEER".into()), - (p.dim.as_str(), " ".repeat(14)), + (p.dim.as_str(), " ".repeat(name_w - 4)), (p.dim.as_str(), " NOW FLOOR JITTER LOSS".into()), (p.dim.as_str(), if wide { " ACHIEVED".into() } else { String::new() }), (p.dim.as_str(), if wide { " IDLE".into() } else { String::new() }), @@ -638,10 +820,10 @@ fn table(rows: &[Session], state: &State, w: usize, selected: usize, p: &Palette w - 1, )]; for (i, row) in rows.iter().enumerate() { - let here = i == selected; + let here = selected == Some(i); let tint = if here { tc::bg(28, 44, 62) } else { String::new() }; let hue = &p.hues[i % p.hues.len()]; - let glyph = SERIES[i % SERIES.len()]; + // One login, and only where there is room for it: the address is // what identifies the session, the name is a courtesy. let who = state @@ -651,9 +833,9 @@ fn table(rows: &[Session], state: &State, w: usize, selected: usize, p: &Palette .map(|(user, _tty)| user.clone()) .unwrap_or_default(); let label = if who.is_empty() || !wide { - row.ip.clone() + row.peer.clone() } else { - format!("{} {}", row.ip, who) + format!("{} {}", row.peer, who) }; let loss = row.recent_loss; let tone = format!("{}{}", tint, colour_for(quality(row), loss, p)); @@ -676,7 +858,12 @@ fn table(rows: &[Session], state: &State, w: usize, selected: usize, p: &Palette _ => format!("{:>width$}", "--", width = width), }; let mut line = vec![ - (name_c.as_str(), format!("{} ", glyph)), + // A colour chip rather than a shape. Six shapes told six + // sessions apart no better than six hues did, and a seventh + // session repeated the first one's shape - so the chip carries + // the hue and the name carries the selection. + (name_c.as_str(), "▐".to_string()), + (label_c.as_str(), " ".to_string()), (label_c.as_str(), tc::pad(&label, name_w)), (tone.as_str(), cell(row.rtt, 7)), (dim_c.as_str(), cell(row.floor, 8)), @@ -724,12 +911,13 @@ fn detail_view( let mut rows = vec![tc::title("connection", w, &p.link)]; rows.push(tc::seg( &[ - ( - p.hues[idx % p.hues.len()].as_str(), - format!(" {} ", SERIES[idx % SERIES.len()]), - ), - (p.txt.as_str(), row.ip.clone()), - (p.dim.as_str(), format!(" · port {}", row.port)), + (p.hues[idx % p.hues.len()].as_str(), " ▐ ".to_string()), + (p.txt.as_str(), row.peer.clone()), + // Their port identifies the socket; ours identifies the service + // it reached. Both, because the list is keyed on the first and + // the question "what is this connected to" is answered by the + // second. + (p.dim.as_str(), format!(" · to port {}", row.port)), ( p.dim.as_str(), users.first().map_or(String::new(), |(u, _)| format!(" {}", u)), @@ -882,14 +1070,20 @@ fn detail_view( rows.push(String::new()); let one = [row.clone()]; - let room = h.saturating_sub(rows.len() + 4); - if room >= 5 { + // Not `if room >= 5`: the chart takes MIN_CHART rows even when the + // fields have already spent the pane, and the caller scrolls to reach + // what will not fit. A chart quietly missing reads as missing data. + let room = h.saturating_sub(rows.len() + 4).max(MIN_CHART); + { rows.extend(graph( &one, &state.history, w, room, idx, + // One session on its own screen: there is nothing to push back, + // so it is drawn at full strength like everything else. + None, window, refresh, p, @@ -996,21 +1190,36 @@ fn braille_canvas( /// Lay the canvases over one another, cell by cell. /// -/// The dots are merged so that no sample is lost where two sessions cross. -/// A cell can carry only one colour, and it goes to whichever session comes -/// later in the list above: which trace is hidden is then something the -/// reader can work out from that list rather than something the data decides -/// afresh every frame. +/// A braille cell can hold the dots of two traces but only one colour, and +/// there is no honest way to show both: whichever colour the cell takes, the +/// other session's samples are drawn in a hue that is not theirs. This used +/// to merge the dots and give the cell to whichever session came later in +/// the list, and on latency's chart - the same code - that hid a whole host +/// behind another one eleven milliseconds away, drawn end to end in a colour +/// it did not own. +/// +/// So a cell belongs to exactly one trace and shows only that trace's dots. +/// Where several want it, ownership advances with the column, which makes a +/// contested stretch read as interleaved dashed lines - each dot its own +/// colour - rather than one solid line belonging to nobody. Sessions whose +/// round trips never meet are unaffected and stay solid. fn overlay(layers: &[(String, Vec>)], cols: usize, rows: usize) -> Vec> { let mut cells = vec![vec![(String::new(), 0u8); cols]; rows]; - for (colour, canvas) in layers { - for (y, line) in canvas.iter().enumerate().take(rows) { - for (x, mask) in line.iter().enumerate().take(cols) { - if *mask != 0 { - cells[y][x].0 = colour.clone(); - cells[y][x].1 |= mask; - } + for y in 0..rows { + for x in 0..cols { + let dots = |canvas: &Vec>| { + canvas.get(y).and_then(|line| line.get(x)).copied().unwrap_or(0) + }; + let claims: Vec<&(String, Vec>)> = + layers.iter().filter(|(_, canvas)| dots(canvas) != 0).collect(); + if claims.is_empty() { + continue; } + // Deterministic, and a function of the column rather than of + // which sample happened to be drawn last, so the pattern holds + // still between frames instead of flickering. + let (colour, canvas) = claims[x % claims.len()]; + cells[y][x] = (colour.clone(), dots(canvas)); } } cells @@ -1026,6 +1235,7 @@ fn graph( // in the list: opening the ▲ row and finding a ● chart reads as a // different connection. start_at: usize, + focus: Option, window: f64, refresh: f64, p: &Palette, @@ -1072,19 +1282,37 @@ fn graph( // the same number plotted_span turns into the "N ago" beneath the chart: // one quantity, so the label and the left edge state the same thing. let slots = series.iter().map(|(_, v)| v.len()).max().unwrap_or(1); - // One canvas per session rather than one shared grid: the glyphs used to - // tell the traces apart, and with braille the hue is all that is left to - // do it with, so each series has to keep its own until the last moment. - let layers: Vec<(String, Vec>)> = series - .iter() - .map(|(idx, values)| { - ( - p.hues[idx % p.hues.len()].clone(), - braille_canvas(values, llo, lhi, gw, gh, slots), - ) - }) - .collect(); - let cells = overlay(&layers, gw, gh); + // One canvas per session rather than one shared grid: a braille cell can + // carry the dots of two traces but only one hue, so each series has to + // keep its own until the moment they are laid over one another. + // The selected session is laid down last and at full strength while the + // rest are mixed toward the backdrop, so the trace being looked at wins + // any cell it shares. With nothing selected every trace is equal, which + // is the chart this widget has always drawn. + let mut layers: Vec<(String, Vec>)> = Vec::with_capacity(series.len()); + let mut front: Option<(String, Vec>)> = None; + for (idx, values) in &series { + let canvas = braille_canvas(values, llo, lhi, gw, gh, slots); + let hue = p.hues[idx % p.hues.len()].clone(); + match focus { + None => layers.push((hue, canvas)), + Some(at) if at == *idx => front = Some((hue, canvas)), + Some(_) => layers.push((p.faded[idx % p.faded.len()].clone(), canvas)), + } + } + let mut cells = overlay(&layers, gw, gh); + // The focused trace takes its cells outright rather than being merged + // into them: a sample drawn in a colour that is not its own is a number + // on screen that is not real. + if let Some((hue, canvas)) = front { + for (y, line) in canvas.iter().enumerate().take(gh) { + for (x, mask) in line.iter().enumerate().take(gw) { + if *mask != 0 { + cells[y][x] = (hue.clone(), *mask); + } + } + } + } let mut out = Vec::new(); for (y, line) in cells.iter().enumerate() { @@ -1170,6 +1398,9 @@ struct Palette { accent: String, link: String, hues: Vec, + /// The same six, mixed toward the backdrop, for traces that are not the + /// one selected. + faded: Vec, } fn palette() -> Palette { @@ -1182,14 +1413,8 @@ fn palette() -> Palette { txt: tc::rgb(225, 235, 245), accent: tc::rgb(150, 210, 255), link: tc::rgb(140, 200, 255), - hues: vec![ - tc::rgb(120, 200, 255), - tc::rgb(150, 230, 180), - tc::rgb(220, 170, 255), - tc::rgb(160, 190, 240), - tc::rgb(200, 220, 150), - tc::rgb(240, 180, 210), - ], + hues: HUES.iter().map(|c| tc::rgb(c.0, c.1, c.2)).collect(), + faded: HUES.iter().map(|c| tc::mix(*c, BACKDROP, FADE)).collect(), } } @@ -1302,7 +1527,7 @@ mod tests { } #[test] - fn a_row_matches_the_python_cell_for_cell() { + fn a_row_is_laid_out_cell_for_cell() { // Captured from link.py in an 85-column pty, with the address // replaced by one from RFC 5737's documentation range - it is the // same width, so the alignment this exists to check is unchanged, @@ -1311,7 +1536,8 @@ mod tests { // nothing inside this file can catch a drift between them - only // the other implementation can. This port had three cells of it, // and every half looked plausible on its own. - let want = "● 203.0.113.221 will 37ms 20ms 10ms 0.00% 11.1Mbps 1m"; + let want = + "▐ 203.0.113.221:22 williamli 37ms 20ms 10ms 0.00% 11.1Mbps 1m"; let row = Session { peer: "203.0.113.221:22".into(), ip: "203.0.113.221".into(), @@ -1335,7 +1561,7 @@ mod tests { err: String::new(), }; // Nothing selected, so no row carries the highlight. - let drawn = table(&[row], &state, 86, 9, &palette()); + let drawn = table(&[row], &state, 86, None, &palette()); assert_eq!(plain(&drawn[1]), want); } @@ -1356,10 +1582,10 @@ mod tests { history: HashMap::new(), err: String::new(), }; - let drawn = table(&[row], &state, 86, 9, &palette()); + let drawn = table(&[row], &state, 86, None, &palette()); assert_eq!( plain(&drawn[1]), - "● 203.0.113.9 -- -- -- -- -- --" + "▐ 203.0.113.9:22 -- -- -- -- -- --" ); } @@ -1423,21 +1649,42 @@ mod tests { } #[test] - fn two_traces_in_one_cell_keep_both_their_dots() { - let top = braille_canvas(&[10.0, 10.0], 0.0, 1.0, 1, 1, 2); - let bottom = braille_canvas(&[1.0, 1.0], 0.0, 1.0, 1, 1, 2); - assert!(top[0][0] != 0 && bottom[0][0] != 0); + fn the_scroll_label_keeps_its_width() { + // The detail footer is measured before the body is built, so this + // string has to be one width whatever the numbers are. A wider one + // could wrap the hints onto an extra line and leave the body sized + // against a footer that is no longer the footer being drawn. + let widths: Vec = [(1, 28, 35), (9, 36, 350), (100, 128, 999)] + .into_iter() + .map(|(a, b, c)| scroll_label(a, b, c).chars().count()) + .collect(); + assert!(widths.windows(2).all(|p| p[0] == p[1]), "{:?}", widths); + } + + #[test] + fn a_contested_cell_belongs_to_one_trace_and_shares_the_run() { + // Two flat traces contesting all four cells. This used to assert the + // union of their dots in the later session's colour; that is the bug + // the latency chart surfaced, where two hosts a few percent apart + // contest every cell and one was drawn wholly in the other's hue. + let top = braille_canvas(&[10.0; 8], 0.0, 1.0, 4, 1, 8); + let bottom = braille_canvas(&[1.0; 8], 0.0, 1.0, 4, 1, 8); + assert!(top[0][0] != 0 && bottom[0][0] != 0, "both must contest"); let cells = overlay( &[ ("first".to_string(), top.clone()), ("second".to_string(), bottom.clone()), ], - 1, + 4, 1, ); - assert_eq!(cells[0][0].1, top[0][0] | bottom[0][0]); - // Only the hue has to be given up, and it goes to the lower row of - // the list, which is the rule the reader can apply from outside. - assert_eq!(cells[0][0].0, "second"); + for x in 0..4 { + let (whose, mask) = &cells[0][x]; + let mine = if whose == "first" { top[0][x] } else { bottom[0][x] }; + assert_eq!(*mask, mine, "column {} carries the other trace's dots", x); + assert_ne!(*mask, top[0][x] | bottom[0][x], "column {} merged", x); + } + let owners: Vec<&str> = (0..4).map(|x| cells[0][x].0.as_str()).collect(); + assert_eq!(owners, vec!["first", "second", "first", "second"]); } } diff --git a/rust/widgets/src/bin/link_help.txt b/rust/widgets/src/bin/link_help.txt index 03883cc..fd7d30e 100644 --- a/rust/widgets/src/bin/link_help.txt +++ b/rust/widgets/src/bin/link_help.txt @@ -20,9 +20,17 @@ median of its slice: a spike is still counted in the worst column and on the detail screen, but the line itself smooths. Look at a stall on the short window. -Keys: up/down select, enter opens one, w changes the span, o toggles idle +Keys: up/down move the selection, and pressing up on the first session or +down on the last clears it, which puts the chart back to drawing every +session alike. Right or enter opens the selected one; left or esc comes back. +On that screen up/down scroll it and n/p step to the next or previous +session without returning to the list. w changes the span, o toggles idle sessions, r refreshes, q quits. The chart is drawn on a braille dot canvas rather than one character per -sample, so it reads as a line rather than a column of marks. Sessions are -told apart by colour, matching the glyph beside each row above. +sample, so it reads as a line rather than a column of marks. Sessions share +the one chart, so the selected row is drawn last and at full strength while +the rest are mixed toward the background: where two traces cross, the colour +goes to the one being looked at rather than to whichever sits lower in the +list. The others stay drawn rather than hidden, because a chart that showed +one session at a time would answer a different question. From 68548a5de9d68394f4335d154de027d0f6174da4 Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Mon, 24 Aug 2026 05:54:24 +0800 Subject: [PATCH 044/147] netwatch: every rate read a quarter too high The window summed n samples' bytes and divided by the span from the oldest stamp to the newest, which is n-1 intervals of time. At the one-second cadence these panes run at, a steady stream read 25% high on every process, connection and endpoint row. Each delta covers the interval ending at its stamp and lasting its own gap - fold! is only called when gap > 0 - so the samples now carry that gap and the divisor is the time they actually cover. Stamps are counted once, because a process's fifteen sockets are read in one poll and share one interval between them rather than being fifteen intervals in a row. Three tests asserted the old arithmetic and had to be restated. The worst was a_rate_is_the_window_it_claims, which asserted 2500 B/s for a steady 2000 B/s stream and narrated the overcount in its own comment - "10000 bytes over 4 seconds" - as though it were the intent. The many-sockets test asserted six megabytes per second across a two-second window. Its first assertion is untouched and still guards the zero-width window that once turned five megabytes into a terabyte a second. Verified by unit test against known gaps, not end to end: a loopback harness did not attribute the traffic to the sending process, so the live measurement was inconclusive and is not claimed. The windowed average itself remains a deliberate deviation from netwatch.py's instantaneous d/gap, for the reason RATE_WINDOW documents. Only the arithmetic inside it was wrong. Found by a review of the port. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/widgets/src/bin/netwatch.rs | 87 ++++++++++++++++++++------------ 1 file changed, 55 insertions(+), 32 deletions(-) diff --git a/rust/widgets/src/bin/netwatch.rs b/rust/widgets/src/bin/netwatch.rs index e66a3b6..dd82219 100644 --- a/rust/widgets/src/bin/netwatch.rs +++ b/rust/widgets/src/bin/netwatch.rs @@ -369,21 +369,29 @@ const RATE_WINDOW: f64 = 4.0; /// thing that must not happen is the three drifting apart on what a rate /// means. macro_rules! fold { - ($e:expr, $when:expr, $up:expr, $down:expr) => {{ + ($e:expr, $when:expr, $gap:expr, $up:expr, $down:expr) => {{ let e = &mut $e; e.up += $up; e.down += $down; e.seen = $when; e.alive = true; - e.recent.push(($when, $up, $down)); - e.recent.retain(|(t, _, _)| $when - t <= RATE_WINDOW); - let oldest = e.recent.first().map(|(t, _, _)| *t).unwrap_or($when); - // The span the samples actually cover, not the nominal window: for - // the first few seconds after launch there is less history than - // that, and dividing by the full window would read low. - let span = $when - oldest; + e.recent.push(($when, $gap, $up, $down)); + e.recent.retain(|(t, _, _, _)| $when - t <= RATE_WINDOW); + // Each delta covers the interval ending at its stamp and lasting + // its own gap, so the time the window covers is the sum of those + // gaps - counting each stamp once, because a process's fifteen + // sockets fold at one stamp and share one interval between them. + // Dividing instead by the span from oldest stamp to newest counted + // n deltas over n-1 intervals, and every process, connection and + // endpoint row read a quarter high at a one-second cadence. + let mut span = 0.0f64; + let mut last = f64::NAN; let (mut u, mut d) = (0u64, 0u64); - for (_, up, down) in &e.recent { + for (t, gap, up, down) in &e.recent { + if *t != last { + span += gap; + last = *t; + } u += up; d += down; } @@ -393,7 +401,7 @@ macro_rules! fold { // second and pinned the chart's axis there for four minutes. With // no elapsed time there is no rate to compute, so the last one // stands until the next sample gives the window a width. - if e.recent.len() > 1 && span > 0.0 { + if span > 0.0 { e.up_rate = u as f64 / span; e.down_rate = d as f64 / span; } @@ -405,7 +413,7 @@ macro_rules! settle { ($e:expr, $when:expr) => {{ let e = &mut $e; e.alive = false; - e.recent.retain(|(t, _, _)| $when - t <= RATE_WINDOW); + e.recent.retain(|(t, _, _, _)| $when - t <= RATE_WINDOW); if e.recent.is_empty() { e.up_rate = 0.0; e.down_rate = 0.0; @@ -432,7 +440,8 @@ struct Proc { alive: bool, seen: f64, /// (when, up bytes, down bytes) for the last few samples. - recent: Vec<(f64, u64, u64)>, + /// (stamp, the gap it covers, bytes up, bytes down) + recent: Vec<(f64, f64, u64, u64)>, /// (down rate, up rate) per sample, for this process's own chart. hist: Vec<(f64, f64)>, } @@ -451,7 +460,8 @@ struct Conn { down_rate: f64, alive: bool, seen: f64, - recent: Vec<(f64, u64, u64)>, + /// (stamp, the gap it covers, bytes up, bytes down) + recent: Vec<(f64, f64, u64, u64)>, } /// The sockets sharing a peer, folded together: a browser opening six @@ -468,7 +478,8 @@ struct Spot { alive: bool, seen: f64, ports: BTreeSet, - recent: Vec<(f64, u64, u64)>, + /// (stamp, the gap it covers, bytes up, bytes down) + recent: Vec<(f64, f64, u64, u64)>, hist: Vec<(f64, f64)>, } @@ -559,7 +570,7 @@ fn sample(state: &mut State, external: bool) { row.alive = true; row.seen = stamp; if gap > 0.0 { - fold!(*row, stamp, d_sent, d_recv); + fold!(*row, stamp, gap, d_sent, d_recv); } let conn = state.conns.entry(inode.clone()).or_insert_with(|| Conn { @@ -572,7 +583,7 @@ fn sample(state: &mut State, external: bool) { conn.alive = true; conn.seen = stamp; if gap > 0.0 { - fold!(*conn, stamp, d_sent, d_recv); + fold!(*conn, stamp, gap, d_sent, d_recv); } let spot = state @@ -588,7 +599,7 @@ fn sample(state: &mut State, external: bool) { spot.seen = stamp; spot.ports.insert(seen.port); if gap > 0.0 { - fold!(*spot, stamp, d_sent, d_recv); + fold!(*spot, stamp, gap, d_sent, d_recv); } } @@ -2035,11 +2046,13 @@ mod tests { // A kilobyte at t=0 and nothing for the next three seconds. The // instantaneous rate is zero for most of that; the windowed one // stays up, which is the whole point. - fold!(row, 0.0, 0, 1000); - fold!(row, 1.0, 0, 0); - fold!(row, 2.0, 0, 0); - fold!(row, 3.0, 0, 0); + fold!(row, 0.0, 1.0, 0, 1000); + fold!(row, 1.0, 1.0, 0, 0); + fold!(row, 2.0, 1.0, 0, 0); + fold!(row, 3.0, 1.0, 0, 0); assert!(row.down_rate > 0.0, "the rate flickered to nothing"); + // A kilobyte spread over the four seconds the window covers. + assert!((row.down_rate - 250.0).abs() < 1.0, "got {}", row.down_rate); assert_eq!(row.down, 1000, "the total is unaffected by smoothing"); } @@ -2050,7 +2063,7 @@ mod tests { // which is every sample, since a sample reads them all at once. // The window spans no time, so there is no rate to compute yet. for _ in 0..15 { - fold!(row, 0.0, 0, 400_000); + fold!(row, 0.0, 0.0, 0, 400_000); } assert_eq!(row.down, 6_000_000); assert_eq!( @@ -2058,10 +2071,17 @@ mod tests { "six megabytes in no time at all read as {} B/s", row.down_rate ); - // The next sample gives the window a width, and the rate is the - // whole window over the time it covers. - fold!(row, 1.0, 0, 0); - assert!((row.down_rate - 6_000_000.0).abs() < 1.0, "got {}", row.down_rate); + // A second poll, a second apart, and the fifteen sockets of the + // first one share the single interval they were read in - they are + // parallel, not fifteen intervals in a row. Six megabytes over the + // one second that poll covered. This asserted six megabytes per + // second across a two-second window before. + let mut row = Proc::default(); + for _ in 0..15 { + fold!(row, 0.0, 1.0, 0, 400_000); + } + fold!(row, 1.0, 1.0, 0, 0); + assert!((row.down_rate - 3_000_000.0).abs() < 1.0, "got {}", row.down_rate); } #[test] @@ -2069,18 +2089,21 @@ mod tests { let mut row = Proc::default(); // Two kilobytes a second, steadily, for four seconds. for i in 0..5 { - fold!(row, i as f64, 0, 2000); + fold!(row, i as f64, 1.0, 0, 2000); } - // Averaged over the span the samples cover, which is 4s for 5 - // samples: 10000 bytes over 4 seconds. - assert!((row.down_rate - 2500.0).abs() < 1.0, "got {}", row.down_rate); + // Five polls, each covering a second, carrying 2000 bytes each: + // 10000 bytes over the five seconds they cover, so 2000 a second, + // which is what was actually sent. This asserted 2500 before - a + // quarter too high on every row, with the overcount written into + // the comment as though it were the intent. + assert!((row.down_rate - 2000.0).abs() < 1.0, "got {}", row.down_rate); } #[test] fn history_older_than_the_window_is_dropped() { let mut row = Proc::default(); - fold!(row, 0.0, 0, 5000); - fold!(row, 100.0, 0, 1000); + fold!(row, 0.0, 1.0, 0, 5000); + fold!(row, 100.0, 1.0, 0, 1000); // The ancient sample is gone, so it cannot prop the rate up. assert_eq!(row.recent.len(), 1); assert_eq!(row.down, 6000); From e070570802263a30fc2ac87b7aa6dd2c88c354e3 Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Mon, 24 Aug 2026 05:57:01 +0800 Subject: [PATCH 045/147] usage: one instant read two ways, depending on how the zone was spelled iso_epoch returned sub-second precision for a stamp written with an offset and whole seconds for the same stamp written with a trailing Z: the Z form was stripped to a naive time and taken by a branch that dropped the fraction the cleaning step had just preserved. claude.rs divides tokens by the gap between adjacent records, so records that were a fraction of a second apart looked simultaneous or a whole second apart, and the per-minute rate moved with it. usage.py turns Z into +00:00 so every zoned stamp takes one path. Doing the same here removes the disagreement at its source rather than teaching the second branch to match the first. Both branches now carry microseconds, matching the six digits usage.py truncates to. The test asserted the defect: it required the nanosecond form to equal the whole second, while its own comment said the parser takes six digits. It now asserts that the two spellings agree to the precision they carry. Found by a review of the port. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/widgets/src/bin/usage.rs | 27 +++++++++++++++++++++++---- 1 file changed, 23 insertions(+), 4 deletions(-) diff --git a/rust/widgets/src/bin/usage.rs b/rust/widgets/src/bin/usage.rs index 513a3e8..a15b3e2 100644 --- a/rust/widgets/src/bin/usage.rs +++ b/rust/widgets/src/bin/usage.rs @@ -260,7 +260,15 @@ fn iso_epoch(s: &str) -> Option { if s.is_empty() { return None; } - let s = s.trim_end_matches('Z'); + // Z and +00:00 are the same zone and these APIs mix them inside one + // response. Spelling it one way means every zoned stamp is parsed by + // the same branch - the two branches did not agree about whether a + // fraction of a second survives. + let s: String = match s.strip_suffix('Z') { + Some(head) => format!("{}+00:00", head), + None => s.to_string(), + }; + let s = s.as_str(); // Trim any sub-second field to microseconds, whatever it arrived as. let cleaned = match s.find('.') { Some(dot) => { @@ -278,10 +286,14 @@ fn iso_epoch(s: &str) -> Option { "%Y-%m-%dT%H:%M:%S", ] { if let Ok(at) = chrono::DateTime::parse_from_str(&cleaned, fmt) { - return Some(at.timestamp() as f64 + at.timestamp_subsec_millis() as f64 / 1000.0); + return Some(at.timestamp() as f64 + at.timestamp_subsec_micros() as f64 / 1e6); } if let Ok(at) = chrono::NaiveDateTime::parse_from_str(&cleaned, fmt) { - return Some(Utc.from_utc_datetime(&at).timestamp() as f64); + // Unzoned, so read as UTC. usage.py reads these as local, but + // its own docstring says the callers all pass zoned strings - + // and every caller here does. + let at = Utc.from_utc_datetime(&at); + return Some(at.timestamp() as f64 + at.timestamp_subsec_micros() as f64 / 1e6); } } None @@ -1732,7 +1744,14 @@ mod tests { // nanoseconds where the parser takes six digits. let want = iso_epoch("2026-08-23T04:15:00+00:00").expect("offset form"); assert_eq!(iso_epoch("2026-08-23T04:15:00Z"), Some(want)); - assert_eq!(iso_epoch("2026-08-23T04:15:00.123456789Z"), Some(want)); + // The two spellings of the same zone must give the same answer to + // the same precision. This asserted that the nanosecond form + // equalled the whole second - which is the fraction being thrown + // away, and adjacent records then look 0 or 1 second apart when a + // rate is computed by dividing tokens by that gap. + let fine = iso_epoch("2026-08-23T04:15:00.123456789Z").expect("nanoseconds"); + assert!((fine - (want + 0.123456)).abs() < 1e-6, "got {}", fine - want); + assert_eq!(iso_epoch("2026-08-23T04:15:00.123456+00:00"), Some(fine)); assert!(iso_epoch("").is_none()); assert!(iso_epoch("not a date").is_none()); } From ea1b572f0602ccebca2898def65e3f5af02f49f7 Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Mon, 24 Aug 2026 06:04:40 +0800 Subject: [PATCH 046/147] core: an external command that stops answering used to wait forever Every subprocess in the Pythons carries a timeout - tailnet.py 25/20/15, ports.py 30/5, herdr-panes.py 15, netwatch.py 5 - and the port called .output(), which has none. A wedged `ss`, a `tailscale status` waiting on a coordination server it cannot reach, or a Herdr socket that stopped answering would hold the poll thread indefinitely while the pane kept drawing its last frame as though it were current. core::run_full bounds a command and kills it by pid on the deadline, and core::run reduces that to the stdout of a command that succeeded. The wait happens in a thread using wait_with_output, which drains the pipe while it waits: waiting here and reading afterwards deadlocks on a child that fills its stdout buffer. run() treats a command that ran and failed as an error rather than as empty output, which is what the widgets' own run() helpers did before and is the difference between "this could not be read" and "there is nothing here". Callers needing the exit status and stderr - ports, to say why tailscale refused - use run_full and keep both. Timeouts are the Pythons' own numbers, not invented. Where a widget used several, the longest is taken so nothing that was allowed 25 seconds is now cut to 5; individual sites can be tightened later with evidence. Four tests, including that a command which never answers is given up on in about the time it was given and leaves nothing running - checked with pgrep -x, because -f matches the shell that runs it. link.rs has two more of these and belongs to another session's working tree; left alone deliberately, and they can move to this helper whenever that work lands. Found by a review of the port. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/core/src/lib.rs | 62 +++++++++++++++++++++++++++++ rust/core/tests/bounded.rs | 33 +++++++++++++++ rust/widgets/src/bin/herdr-panes.rs | 19 +++++---- rust/widgets/src/bin/netwatch.rs | 10 +++-- rust/widgets/src/bin/ports.rs | 27 ++++++------- rust/widgets/src/bin/tailnet.rs | 10 +++-- 6 files changed, 132 insertions(+), 29 deletions(-) create mode 100644 rust/core/tests/bounded.rs diff --git a/rust/core/src/lib.rs b/rust/core/src/lib.rs index 9b75e22..7088214 100644 --- a/rust/core/src/lib.rs +++ b/rust/core/src/lib.rs @@ -1014,6 +1014,68 @@ fn decode(buf: &mut String, lone_esc: &mut bool) -> Vec { keys } +/// Run a command and give up on it after `seconds`. +/// +/// std's `.output()` waits forever, and every one of these commands talks +/// to something that can stop answering - a tailnet coordination server, +/// a Herdr socket, a wedged `ss`. The Pythons all pass a timeout; the port +/// dropped them, so a hung child froze the poll thread with no error and +/// the pane kept drawing its last frame as though it were current. +/// +/// Returns everything the child produced, so a caller that needs the exit +/// status or stderr - to say why a command refused - still has them. +pub fn run_full(args: &[&str], seconds: u64) -> Result { + use std::process::{Command, Stdio}; + use std::sync::mpsc; + let Some((program, rest)) = args.split_first() else { + return Err("no command given".into()); + }; + let child = Command::new(program) + .args(rest) + .stdin(Stdio::null()) + .stdout(Stdio::piped()) + .stderr(Stdio::null()) + .spawn() + .map_err(|e| format!("{}: {}", program, e))?; + let pid = child.id() as i32; + let (tx, rx) = mpsc::channel(); + // wait_with_output drains the pipe while it waits; doing the wait on + // this side and the read afterwards would deadlock on a child that + // fills its stdout buffer. + std::thread::spawn(move || { + let _ = tx.send(child.wait_with_output()); + }); + match rx.recv_timeout(std::time::Duration::from_secs(seconds)) { + Ok(Ok(out)) => Ok(out), + Ok(Err(e)) => Err(format!("{}: {}", program, e)), + Err(_) => { + // SIGKILL rather than SIGTERM: this one has already ignored the + // time it was given, and the reader thread ends when it dies. + unsafe { libc::kill(pid, libc::SIGKILL) }; + Err(format!("{} did not answer in {}s", program, seconds)) + } + } +} + +/// The same, reduced to the stdout of a command that succeeded. +/// +/// A command that ran and failed is an error here, not empty output: the +/// callers that want the difference use run_full and read the status. +pub fn run(args: &[&str], seconds: u64) -> Result { + let out = run_full(args, seconds)?; + if out.status.success() { + Ok(String::from_utf8_lossy(&out.stdout).to_string()) + } else { + let why = String::from_utf8_lossy(&out.stderr); + let why: String = why.split_whitespace().collect::>().join(" "); + Err(if why.is_empty() { + format!("{} exited {}", args[0], out.status) + } else { + why.chars().take(200).collect() + }) + } +} + /// Print the doc comment and leave, when asked for help. pub fn maybe_help(doc: &str) { let args: Vec = std::env::args().skip(1).collect(); diff --git a/rust/core/tests/bounded.rs b/rust/core/tests/bounded.rs new file mode 100644 index 0000000..ad1e490 --- /dev/null +++ b/rust/core/tests/bounded.rs @@ -0,0 +1,33 @@ + +// A command that never answers must be given up on, and killed. +#[test] +fn a_command_that_never_answers_is_given_up_on() { + let began = std::time::Instant::now(); + let got = toys_core::run(&["sleep", "30"], 2); + let took = began.elapsed().as_secs_f64(); + assert!(got.is_err(), "sleep 30 returned {:?}", got); + assert!(took < 5.0, "waited {:.1}s for a 2s limit", took); + assert!( + got.unwrap_err().contains("did not answer"), + "the reason should say what happened" + ); +} + +#[test] +fn a_command_that_answers_comes_back_with_its_output() { + let got = toys_core::run(&["echo", "hello"], 5).expect("echo"); + assert_eq!(got.trim(), "hello"); +} + +#[test] +fn a_command_that_fails_is_an_error_not_empty_output() { + // `false` prints nothing and exits 1. The old run() turned that into + // an empty string, which reads on screen as a source with no data. + assert!(toys_core::run(&["false"], 5).is_err()); +} + +#[test] +fn a_command_that_is_not_installed_says_so() { + let got = toys_core::run(&["definitely-not-a-real-binary-xyz"], 5); + assert!(got.is_err()); +} diff --git a/rust/widgets/src/bin/herdr-panes.rs b/rust/widgets/src/bin/herdr-panes.rs index 36ba82b..058dad0 100644 --- a/rust/widgets/src/bin/herdr-panes.rs +++ b/rust/widgets/src/bin/herdr-panes.rs @@ -42,19 +42,24 @@ fn rank_of(state: &str) -> usize { RANK.iter().position(|s| *s == state).unwrap_or(9) } +/// Seconds before a herdr command is given up on, from herdr-panes.py. +const RUN_TIMEOUT: u64 = 15; + /// Run a herdr command for its effect; true when it succeeded. +/// +/// Bounded, because the socket on the other end can stop answering and +/// .output() would wait for it forever with the pane still drawing. fn herdr_action(args: &[&str]) -> bool { - std::process::Command::new("herdr") - .args(args) - .output() - .map(|out| out.status.success()) - .unwrap_or(false) + let mut argv = vec!["herdr"]; + argv.extend_from_slice(args); + tc::run(&argv, RUN_TIMEOUT).is_ok() } /// Run a herdr command and hand back the `result` object it printed. fn herdr(args: &[&str]) -> Option { - let out = std::process::Command::new("herdr").args(args).output().ok()?; - let text = String::from_utf8_lossy(&out.stdout); + let mut argv = vec!["herdr"]; + argv.extend_from_slice(args); + let text = tc::run(&argv, RUN_TIMEOUT).ok()?; let parsed: serde_json::Value = serde_json::from_str(&text).ok()?; match parsed.get("result") { Some(serde_json::Value::Null) | None => None, diff --git a/rust/widgets/src/bin/netwatch.rs b/rust/widgets/src/bin/netwatch.rs index dd82219..dfcc977 100644 --- a/rust/widgets/src/bin/netwatch.rs +++ b/rust/widgets/src/bin/netwatch.rs @@ -79,11 +79,13 @@ fn elapsed(seconds: f64) -> String { } } +/// Seconds before an external command is given up on, from netwatch.py. +const RUN_TIMEOUT: u64 = 5; + fn run(args: &[&str]) -> String { - match std::process::Command::new(args[0]).args(&args[1..]).output() { - Ok(out) if out.status.success() => String::from_utf8_lossy(&out.stdout).to_string(), - _ => String::new(), - } + // Bounded: .output() waits forever, and a wedged child used to freeze + // the poll thread with the pane still showing its last frame. + tc::run(args, RUN_TIMEOUT).unwrap_or_default() } /// Every address this machine answers to. diff --git a/rust/widgets/src/bin/ports.rs b/rust/widgets/src/bin/ports.rs index 8de6361..a90b507 100644 --- a/rust/widgets/src/bin/ports.rs +++ b/rust/widgets/src/bin/ports.rs @@ -389,11 +389,13 @@ fn version_in(cmdline: &str) -> Option { } } +/// Seconds before an external command is given up on, from ports.py's longest, on the serve/funnel commands. +const RUN_TIMEOUT: u64 = 30; + fn run(args: &[&str]) -> String { - match std::process::Command::new(args[0]).args(&args[1..]).output() { - Ok(out) if out.status.success() => String::from_utf8_lossy(&out.stdout).to_string(), - _ => String::new(), - } + // Bounded: .output() waits forever, and a wedged child used to freeze + // the poll thread with the pane still showing its last frame. + tc::run(args, RUN_TIMEOUT).unwrap_or_default() } /// Ports Tailscale is serving, and whether the world can see them. @@ -1020,12 +1022,11 @@ fn serve_port(port: u16, public: bool) -> String { } } let verb = if public { "funnel" } else { "serve" }; - match std::process::Command::new("tailscale") - .args([verb, "--bg", &format!("--https={}", listen), &port.to_string()]) - .output() - { + let https = format!("--https={}", listen); + let port = port.to_string(); + match tc::run_full(&["tailscale", verb, "--bg", &https, &port], RUN_TIMEOUT) { Ok(out) => refusal(out, "tailscale refused"), - Err(e) => e.to_string(), + Err(e) => e, } } @@ -1058,12 +1059,10 @@ fn unserve_port(port: u16, public: bool) -> String { listen = if public { 443 } else { port }; } let verb = if public { "funnel" } else { "serve" }; - match std::process::Command::new("tailscale") - .args([verb, &format!("--https={}", listen), "off"]) - .output() - { + let https = format!("--https={}", listen); + match tc::run_full(&["tailscale", verb, &https, "off"], RUN_TIMEOUT) { Ok(out) => refusal(out, "tailscale refused"), - Err(e) => e.to_string(), + Err(e) => e, } } diff --git a/rust/widgets/src/bin/tailnet.rs b/rust/widgets/src/bin/tailnet.rs index e8359b9..754bbbe 100644 --- a/rust/widgets/src/bin/tailnet.rs +++ b/rust/widgets/src/bin/tailnet.rs @@ -41,11 +41,13 @@ fn now() -> f64 { .unwrap_or(0.0) } +/// Seconds before an external command is given up on, from tailnet.py's longest, on `tailscale status`. +const RUN_TIMEOUT: u64 = 25; + fn run(args: &[&str]) -> String { - match std::process::Command::new(args[0]).args(&args[1..]).output() { - Ok(out) if out.status.success() => String::from_utf8_lossy(&out.stdout).to_string(), - _ => String::new(), - } + // Bounded: .output() waits forever, and a wedged child used to freeze + // the poll thread with the pane still showing its last frame. + tc::run(args, RUN_TIMEOUT).unwrap_or_default() } fn text(value: &serde_json::Value, key: &str) -> String { From 3396b926d2cde5f6f63c5fc957817888626f89f0 Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Mon, 24 Aug 2026 06:07:03 +0800 Subject: [PATCH 047/147] usage: copilot kept a sixth midnight 7234113 claimed one midnight across all six calendars and did not deliver it. Copilot buckets in SQL rather than in Rust, so the grep that found grok's UTC bucketing never looked at it: created_at is stored with a trailing Z and plain date() is therefore the UTC day, while claude, codex, cursor and grok all bucket by the reader's own midnight and day_calendar draws them on one wall under the same headings. East of Greenwich a turn after 16:00 local files under yesterday. Verified against the real store read-only: the stamps there are of the form 2026-08-16T06:55:52.920Z, and date(x) and date(x,'localtime') disagree for anything from 16:00Z on. Nothing caught it because every store test uses a mid-morning stamp, which falls on the same date in both zones - the same blind spot grok's fixture had. The new test stamps 20:00Z and asserts the local day; reverting the query makes it fail. Inherited from usage.py, which does the same, so the Python has this bug too. Found by a review of the port. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/widgets/src/bin/usage/copilot.rs | 35 ++++++++++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/rust/widgets/src/bin/usage/copilot.rs b/rust/widgets/src/bin/usage/copilot.rs index 8e628b4..641cd55 100644 --- a/rust/widgets/src/bin/usage/copilot.rs +++ b/rust/widgets/src/bin/usage/copilot.rs @@ -262,8 +262,13 @@ fn scan_store(con: &Connection, d: &mut Data) -> rusqlite::Result<()> { itl: row.7.unwrap_or(0.0), ms: row.8.unwrap_or(0.0), }); + // localtime, because claude, codex, cursor and grok all bucket by the + // reader's own midnight and day_calendar draws them on one wall under + // the same headings. created_at is stored with a trailing Z, so plain + // date() is the UTC day: east of Greenwich, an evening turn filed + // under yesterday. let mut daily = con.prepare( - "select date(created_at), model, sum(input_tokens), \ + "select date(created_at, 'localtime'), model, sum(input_tokens), \ sum(output_tokens), sum(cache_read_tokens), \ sum(cache_write_tokens) from assistant_usage_events \ group by 1, 2", @@ -793,6 +798,34 @@ mod tests { con } + #[test] + fn a_turn_is_filed_under_the_day_it_was_here() { + // 20:00 UTC is already tomorrow anywhere east of Greenwich. The + // other five readers bucket by the reader's own midnight and + // day_calendar draws them all on one wall, so this one must too. + // Every other store test uses a mid-morning stamp, which falls on + // the same date in both zones and cannot tell them apart. + let con = store_with(&[ + "'2026-08-16T20:00:00Z', 'model-a', 100, 0, 0, 0, 0, 0, 0.0, 0.0, 0", + ]); + let mut d = Data::default(); + scan_store(&con, &mut d).expect("a readable store"); + let days: Vec<&String> = d.daily.keys().collect(); + assert_eq!(days.len(), 1, "{:?}", days); + let want = chrono::Local + .timestamp_opt( + chrono::DateTime::parse_from_rfc3339("2026-08-16T20:00:00Z") + .expect("a fixed stamp") + .timestamp(), + 0, + ) + .single() + .expect("a local time") + .format("%Y-%m-%d") + .to_string(); + assert_eq!(days[0], &want, "filed under the wrong day"); + } + #[test] fn the_session_store_sums_read_whole() { let con = store_with(&[ From 306915e27abc376149b1d55e229ffbd1f241d716 Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Mon, 24 Aug 2026 06:09:42 +0800 Subject: [PATCH 048/147] build: the poller guards did not exist in the shipped binary usage, herdr-panes and ports each wrap their poll thread in catch_unwind, and the Err arm records "poller stopped" and keeps the pane drawing with an explanation. Under panic = "abort" that arm is unreachable: the process dies before catch_unwind returns. Confirmed by running a minimal binary with the same profile - the panic killed it and the guard never reported. So the source read as protected, the shipped binary had no protection, and cargo test exercised the guard happily because test profiles unwind. That is the shape this repo keeps paying for: something that looks like a safety net in review and is not one. Switched to unwind and measured the cost rather than guessing it: 11.21 MB to 11.71 MB across the fourteen binaries, half a megabyte, 4.5%, about 36 KB each. That buys three error paths that CLAUDE.md asks for in so many words - wrap every poller so it records why it stopped - and the difference on screen between a widget that vanishes and one that says which part of it broke while still drawing the rest. The reason is in the profile itself, because the settings around it are all size-oriented and this one is not; anyone tightening them back would otherwise delete three error paths without knowing it. Reversible in one line if the size matters more. Found by a review of the port. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/Cargo.toml | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/rust/Cargo.toml b/rust/Cargo.toml index bb63354..686e370 100644 --- a/rust/Cargo.toml +++ b/rust/Cargo.toml @@ -14,5 +14,15 @@ license = "AGPL-3.0-or-later" opt-level = "z" lto = true codegen-units = 1 -panic = "abort" +# unwind, deliberately, and not for free: it costs about 0.5 MB across the +# fourteen binaries, 4.5%, measured. It buys the poller guards in usage, +# herdr-panes and ports, which wrap their poll threads in catch_unwind and +# record why they stopped. Under panic = "abort" those guards cannot fire +# at all - the process dies before the Err arm is reached - so the source +# read as protected while the shipped binary had no protection, and the +# tests exercised a path that only exists in the test profile. CLAUDE.md +# asks that every poller record why it stopped; this is what makes that +# true rather than aspirational. Setting this back to "abort" silently +# deletes three error paths. +panic = "unwind" strip = true From 75b98b8bc9d801f79b7a2eeff9a1b3daba8f8c7b Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Mon, 24 Aug 2026 06:19:50 +0800 Subject: [PATCH 049/147] core: cycle skipped the first choice when the current value was not one common.py returns seq[0] when the current value is not in the list; the port did position().unwrap_or(0) and then +1, which returns the second. So a setting that arrived from config.json or a command-line argument rather than from a previous press of the key could never reach the first choice by cycling - it jumped straight past it and only came back after a full lap. latency.rs has its own copy with the same drift, in another session's working tree, and a test there asserts it: the comment says "a value that is not one of the choices starts from the first" and the assertion expects the second. Left for them, and flagged. Found by a review of the port. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/core/src/lib.rs | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/rust/core/src/lib.rs b/rust/core/src/lib.rs index 7088214..f906eb7 100644 --- a/rust/core/src/lib.rs +++ b/rust/core/src/lib.rs @@ -713,8 +713,15 @@ pub fn mix(a: (u8, u8, u8), b: (u8, u8, u8), t: f64) -> String { /// The next entry after `current`, wrapping; for a key that cycles. pub fn cycle(choices: &[T], current: T) -> T { - let at = choices.iter().position(|c| *c == current).unwrap_or(0); - choices[(at + 1) % choices.len()] + // A value that is not one of the choices starts from the first, as + // common.py's ValueError branch does. unwrap_or(0) then +1 started from + // the second instead, silently skipping a choice whenever the current + // setting came from a config file or an argument rather than from a + // previous press of the key. + match choices.iter().position(|c| *c == current) { + Some(at) => choices[(at + 1) % choices.len()], + None => choices[0], + } } /// A placeholder bar with a highlight sweeping across it. @@ -1304,6 +1311,17 @@ mod tests { decode(&mut buf, &mut held) } + #[test] + fn a_setting_that_is_not_a_choice_starts_from_the_first() { + let choices = [0.2f64, 0.5, 1.0, 2.0]; + assert_eq!(cycle(&choices, 0.2), 0.5); + assert_eq!(cycle(&choices, 2.0), 0.2, "the last wraps to the first"); + // A value from config or an argument that is not on the list. This + // returned 0.5 - the second - so the first choice could never be + // reached by pressing the key. + assert_eq!(cycle(&choices, 3.3), 0.2); + } + #[test] fn arrows_decode_to_names() { assert_eq!(keys("\x1b[A"), vec!["up"]); From 983e1b78babd87238a72b2a633c0191e8f5c1c31 Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Mon, 24 Aug 2026 06:19:54 +0800 Subject: [PATCH 050/147] latency, link: a fair turn, and a poller that says why it stopped MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three findings from the outside review of this branch, two of them mine and one of them the same class of mistake twice over. The cell-ownership rule fixed one starvation and left a narrower one. Giving a contested cell to `claims[x % claims.len()]` looks fair and is not: when every contested cell in a stretch shares a column parity, the modulus picks the same claimant every time and the other trace is absent from the whole run. That is exactly the failure the rewrite existed to prevent. It is reachable in latency rather than theoretical, because a series with a gap in every other column produces precisely that alignment, and the column width is free-form config. The turn is now counted over contested cells instead of read off the column, so any run of k contested cells with n claimants gives each of them at least one. Note that mixing the row in - `(x + y) % n` - would not have fixed it: the demonstrated case is two flat traces sharing one row, where y is constant and the parity survives. The test that should have caught it asserted the exact alternation the old rule produced, so it would have passed with the starvation present, and it would have broken under any fix that shifted phase. It pinned the mechanism and called that the contract - the same shape as the test that let the original bug through, one level up. It now asserts the property, which is that no trace with samples in a contested stretch is absent from it, and it was checked the only way that means anything: reverted to `x % n`, watched it fail, restored, watched it pass. link's `State.err` was drawn and never assigned. The pane has a line for "poller stopped: …" and nothing could ever put text in it, so a poller that died left the last frame on screen for ever. link.py wraps `poll` and records the reason; the port had lost that. Worse, `run` folds every failure into an empty string, so a failing `ss` at runtime produced no sessions and rendered as "No inbound sessions on a listening port" - a machine with nobody connected to it, which is CLAUDE.md's central gotcha and the reason that rule exists. `run_or` now reports why a command could not be had, `sessions` and `listening_ports` return it, the poller writes it into `err` and clears it on a good read, and the two exits on a poisoned lock write down which one they were before returning. With a test that a missing binary reports rather than reading as empty output. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- rust/widgets/src/bin/latency.rs | 60 +++++++++++--- rust/widgets/src/bin/link.rs | 141 +++++++++++++++++++++++++++----- 2 files changed, 169 insertions(+), 32 deletions(-) diff --git a/rust/widgets/src/bin/latency.rs b/rust/widgets/src/bin/latency.rs index 4571dd9..6012c50 100644 --- a/rust/widgets/src/bin/latency.rs +++ b/rust/widgets/src/bin/latency.rs @@ -530,27 +530,37 @@ fn braille_canvas( /// merging painted the whole of one of them in the other's colour. /// /// So a cell belongs to exactly one trace and shows only that trace's dots. -/// Where several want it, ownership advances with the column, which makes a -/// contested stretch read as two interleaved dashed lines - each dot its own -/// colour - rather than as one solid line belonging to nobody. Traces that +/// Where several want it, ownership advances once per contested cell, which +/// makes a contested stretch read as interleaved dashed lines - each dot its +/// own colour - rather than one solid line belonging to nobody. Traces that /// never meet are unaffected and stay solid. +/// +/// The turn is counted over contested cells and not taken from the column +/// number, which is the same bug one level in. Indexing by `x` looks fair +/// and is not: when the contested cells all share a parity - which happens +/// as soon as one series has a gap in every other column, and the column +/// width is free-form config - `x % 2` picks the same claimant every time +/// and the other trace is absent from the whole stretch. That is the +/// failure this function exists to prevent, in a narrower form. fn overlay(layers: &[(String, Vec>)], cols: usize, rows: usize) -> Vec> { let mut cells = vec![vec![(String::new(), 0u8); cols]; rows]; for y in 0..rows { + // Counts contested cells along this row, so every claimant takes a + // turn no matter which columns the contention lands on. + let mut turn = 0usize; for x in 0..cols { let dots = |canvas: &Vec>| { canvas.get(y).and_then(|line| line.get(x)).copied().unwrap_or(0) }; let claims: Vec<&(String, Vec>)> = layers.iter().filter(|(_, canvas)| dots(canvas) != 0).collect(); - if claims.is_empty() { + let Some((colour, canvas)) = claims.get(turn % claims.len().max(1)) else { continue; + }; + cells[y][x] = ((*colour).clone(), dots(canvas)); + if claims.len() > 1 { + turn += 1; } - // Deterministic, and a function of the column rather than of - // which sample happened to be drawn last, so the pattern holds - // still between frames instead of flickering. - let (colour, canvas) = claims[x % claims.len()]; - cells[y][x] = (colour.clone(), dots(canvas)); } } cells @@ -1402,7 +1412,37 @@ mod tests { } // Ownership advances with the column, so a contested stretch shows // both traces as interleaved dashes rather than hiding one. + // The property rather than the phase: the run is shared, so neither + // trace is missing from it. Pinning the exact alternation here is + // what let the parity starvation through - it asserted the mechanism + // and called that the contract. let owners: Vec<&str> = (0..4).map(|x| cells[0][x].0.as_str()).collect(); - assert_eq!(owners, vec!["first", "second", "first", "second"]); + assert!(owners.contains(&"first"), "{:?}", owners); + assert!(owners.contains(&"second"), "{:?}", owners); } + + #[test] + fn no_trace_is_starved_by_where_the_contention_falls() { + // Two traces that meet only in even-numbered cells, which is what a + // series with a gap in every other column produces - and the column + // width is free-form config, so it is reachable rather than + // theoretical. Ownership used to be `x % claims.len()`, so every + // contested cell shared a parity, the modulus picked the same + // claimant every time, and the other trace was absent from the whole + // stretch. That is the failure this function exists to prevent, one + // level in. + let a = vec![vec![0b0000_0001u8, 0, 0b0000_0001, 0]]; + let b = vec![vec![0b0100_0000u8, 0, 0b0100_0000, 0]]; + let cells = overlay(&[("first".to_string(), a), ("second".to_string(), b)], 4, 1); + let owners: Vec<&str> = (0..4) + .filter(|x| cells[0][*x].1 != 0) + .map(|x| cells[0][x].0.as_str()) + .collect(); + assert_eq!(owners.len(), 2, "both contested cells should be drawn"); + // The property, not the phase. Which of the two takes the first cell + // is an implementation detail; that neither vanishes is not. + assert!(owners.contains(&"first"), "{:?}", owners); + assert!(owners.contains(&"second"), "{:?}", owners); + } + } diff --git a/rust/widgets/src/bin/link.rs b/rust/widgets/src/bin/link.rs index 6972bb1..5851d04 100644 --- a/rust/widgets/src/bin/link.rs +++ b/rust/widgets/src/bin/link.rs @@ -90,6 +90,21 @@ struct Session { raw: HashMap, } +/// A command's output, or why it could not be had. +/// +/// `run` folds every failure into an empty string, which is right for the +/// callers that read absence as "nothing to show". It is wrong for the two +/// that feed the whole widget: from an empty string, `ss` failing and `ss` +/// reporting no sockets are the same thing, and one of them is a quiet +/// machine while the other is a broken pane imitating one. +fn run_or(args: &[&str]) -> Result { + match std::process::Command::new(args[0]).args(&args[1..]).output() { + Ok(out) if out.status.success() => Ok(String::from_utf8_lossy(&out.stdout).to_string()), + Ok(out) => Err(format!("{} exited {}", args[0], out.status)), + Err(e) => Err(format!("{} did not run: {}", args[0], e)), + } +} + fn run(args: &[&str]) -> String { match std::process::Command::new(args[0]).args(&args[1..]).output() { Ok(out) if out.status.success() => String::from_utf8_lossy(&out.stdout).to_string(), @@ -102,9 +117,9 @@ fn run(args: &[&str]) -> String { /// Inbound is defined as "arrived at a port we listen on" rather than by a /// list of numbers, so SSH, a terminal server and anything else that /// accepts sessions are all found without being named. -fn listening_ports() -> Vec { +fn listening_ports() -> Result, String> { let mut ports = Vec::new(); - for line in run(&["ss", "-tlnH"]).lines() { + for line in run_or(&["ss", "-tlnH"])?.lines() { let cols: Vec<&str> = line.split_whitespace().collect(); if let Some(local) = cols.get(3) { if let Some((_, port)) = local.rsplit_once(':') { @@ -114,7 +129,7 @@ fn listening_ports() -> Vec { } } } - ports + Ok(ports) } /// The kernel's own numbers for one socket. @@ -147,12 +162,12 @@ fn num(map: &HashMap, key: &str) -> Option { } /// One entry per established inbound connection, with its metrics. -fn sessions() -> Vec { - let ports = listening_ports(); +fn sessions() -> Result, String> { + let ports = listening_ports()?; if ports.is_empty() { - return Vec::new(); + return Ok(Vec::new()); } - let text = run(&["ss", "-tinH", "state", "established"]); + let text = run_or(&["ss", "-tinH", "state", "established"])?; let mut found = Vec::new(); let mut head: Option> = None; for line in text.lines() { @@ -212,7 +227,7 @@ fn sessions() -> Vec { }); head = None; } - found + Ok(found) } /// Who is logged in from where, to put a name against an address. @@ -419,9 +434,36 @@ fn main() { let poller = Arc::clone(&state); let poller_wake = Arc::clone(&wake); std::thread::spawn(move || { + // A thread that ends leaves the last frame on screen for ever, and a + // widget frozen on real numbers is harder to catch than one showing + // none. Every way out of this loop writes down why first - which is + // what link.py's `run` does around `poll`, and what this port had + // lost: `State.err` was drawn but never assigned, so the line that + // explains a dead poller could not fire. + let stopped = |why: &str| { + if let Ok(mut guard) = poller.lock() { + guard.err = format!("poller stopped: {}", why); + } + }; let mut last: HashMap = HashMap::new(); loop { - let mut found = sessions(); + let mut found = match sessions() { + Ok(rows) => { + if let Ok(mut guard) = poller.lock() { + guard.err = String::new(); + } + rows + } + // Not fatal: ss can fail for a moment. Reported and retried + // rather than ending the thread, but never silently - an empty + // list and a failed read look identical on screen otherwise. + Err(why) => { + if let Ok(mut guard) = poller.lock() { + guard.err = why; + } + Vec::new() + } + }; let names = who(); for row in &mut found { // Retransmits since the last look, rather than since the @@ -458,12 +500,12 @@ fn main() { let (lock, cond) = &*poller_wake; let mut asked = match lock.lock() { Ok(g) => g, - Err(_) => return, + Err(_) => return stopped("the wake lock was poisoned"), }; if !*asked { asked = match cond.wait_timeout(asked, Duration::from_secs_f64(refresh)) { Ok((g, _)) => g, - Err(_) => return, + Err(_) => return stopped("the wake lock was poisoned while waiting"), }; } *asked = false; @@ -1199,27 +1241,37 @@ fn braille_canvas( /// it did not own. /// /// So a cell belongs to exactly one trace and shows only that trace's dots. -/// Where several want it, ownership advances with the column, which makes a -/// contested stretch read as interleaved dashed lines - each dot its own -/// colour - rather than one solid line belonging to nobody. Sessions whose -/// round trips never meet are unaffected and stay solid. +/// Where several want it, ownership advances once per contested cell, which +/// makes a contested stretch read as interleaved dashed lines - each dot its +/// own colour - rather than one solid line belonging to nobody. Traces that +/// never meet are unaffected and stay solid. +/// +/// The turn is counted over contested cells and not taken from the column +/// number, which is the same bug one level in. Indexing by `x` looks fair +/// and is not: when the contested cells all share a parity - which happens +/// as soon as one series has a gap in every other column, and the column +/// width is free-form config - `x % 2` picks the same claimant every time +/// and the other trace is absent from the whole stretch. That is the +/// failure this function exists to prevent, in a narrower form. fn overlay(layers: &[(String, Vec>)], cols: usize, rows: usize) -> Vec> { let mut cells = vec![vec![(String::new(), 0u8); cols]; rows]; for y in 0..rows { + // Counts contested cells along this row, so every claimant takes a + // turn no matter which columns the contention lands on. + let mut turn = 0usize; for x in 0..cols { let dots = |canvas: &Vec>| { canvas.get(y).and_then(|line| line.get(x)).copied().unwrap_or(0) }; let claims: Vec<&(String, Vec>)> = layers.iter().filter(|(_, canvas)| dots(canvas) != 0).collect(); - if claims.is_empty() { + let Some((colour, canvas)) = claims.get(turn % claims.len().max(1)) else { continue; + }; + cells[y][x] = ((*colour).clone(), dots(canvas)); + if claims.len() > 1 { + turn += 1; } - // Deterministic, and a function of the column rather than of - // which sample happened to be drawn last, so the pattern holds - // still between frames instead of flickering. - let (colour, canvas) = claims[x % claims.len()]; - cells[y][x] = (colour.clone(), dots(canvas)); } } cells @@ -1684,7 +1736,52 @@ mod tests { assert_eq!(*mask, mine, "column {} carries the other trace's dots", x); assert_ne!(*mask, top[0][x] | bottom[0][x], "column {} merged", x); } + // The property rather than the phase: the run is shared, so neither + // trace is missing from it. Pinning the exact alternation here is + // what let the parity starvation through - it asserted the mechanism + // and called that the contract. let owners: Vec<&str> = (0..4).map(|x| cells[0][x].0.as_str()).collect(); - assert_eq!(owners, vec!["first", "second", "first", "second"]); + assert!(owners.contains(&"first"), "{:?}", owners); + assert!(owners.contains(&"second"), "{:?}", owners); + } + + #[test] + fn a_command_that_will_not_run_says_so_rather_than_returning_nothing() { + // `run` folds failure into an empty string, and for `ss` that is the + // difference between a machine with nobody connected and a widget + // that cannot see. The poller puts this text on screen; before it + // existed, State.err was drawn but never assigned and a dead read + // rendered as "No inbound sessions". + let why = run_or(&["definitely-not-a-real-binary-xyz", "--version"]) + .expect_err("a missing binary must not read as empty output"); + assert!(why.contains("did not run"), "{}", why); + assert!(why.contains("definitely-not-a-real-binary-xyz"), "{}", why); + // A command that does run still comes back as Ok. + assert!(run_or(&["true"]).is_ok()); + } + + #[test] + fn no_trace_is_starved_by_where_the_contention_falls() { + // Two traces that meet only in even-numbered cells, which is what a + // series with a gap in every other column produces - and the column + // width is free-form config, so it is reachable rather than + // theoretical. Ownership used to be `x % claims.len()`, so every + // contested cell shared a parity, the modulus picked the same + // claimant every time, and the other trace was absent from the whole + // stretch. That is the failure this function exists to prevent, one + // level in. + let a = vec![vec![0b0000_0001u8, 0, 0b0000_0001, 0]]; + let b = vec![vec![0b0100_0000u8, 0, 0b0100_0000, 0]]; + let cells = overlay(&[("first".to_string(), a), ("second".to_string(), b)], 4, 1); + let owners: Vec<&str> = (0..4) + .filter(|x| cells[0][*x].1 != 0) + .map(|x| cells[0][x].0.as_str()) + .collect(); + assert_eq!(owners.len(), 2, "both contested cells should be drawn"); + // The property, not the phase. Which of the two takes the first cell + // is an implementation detail; that neither vanishes is not. + assert!(owners.contains(&"first"), "{:?}", owners); + assert!(owners.contains(&"second"), "{:?}", owners); } + } From 438a15b3e316019d731e0f4e6f6b2b39b3fd54c8 Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Mon, 24 Aug 2026 06:20:10 +0800 Subject: [PATCH 051/147] clocks: the minute key moves the block you are in Pressing + or - during a break changed the focus length. The hint beside it read "(focus 20min)" while the line above it read SHORT BREAK, which looks like the two disagree about the phase - they did not, the hint was naming a setting rather than a state, but the countdown on screen did not move and the number that did move was not visible anywhere. Adjusting a break was not possible at all. It now writes to whichever block is running: focus during focus, and that break during a break. The three lengths stay independent, so shortening a short break leaves the long one alone, and the config values are starting points rather than fixed ones - a 25/5/15 day can become 30/5/15 without touching the breaks. The hint says "(interval Nmin)" and reports the block in progress, which is only truthful because of the change above: naming one of the three would be wrong in two phases out of three. None of the eleven pomodoro keys had ever been in config.example.json, so there was no way to find out the breaks were configurable at all - which is how this started. They are in now with the Python's own defaults, five minutes for the short break and fifteen for the long. That is the repo's own rule about adding keys to the example in the same commit, unmet since before the port. Two keys clocks.py reads are still absent from the Rust: pomodoro_enabled and pomodoro_notify. Setting either in config does nothing here. Left alone deliberately rather than fixed in passing, and recorded against the clocks review instead. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- config.example.json | 17 +++++++- rust/widgets/src/bin/clocks.rs | 79 +++++++++++++++++++++++++++++++--- 2 files changed, 88 insertions(+), 8 deletions(-) diff --git a/config.example.json b/config.example.json index 5d4e88f..f0b58ef 100644 --- a/config.example.json +++ b/config.example.json @@ -35,7 +35,22 @@ ] ], "work_start_hour": 9, - "work_end_hour": 18 + "work_end_hour": 18, + "pomodoro_enabled": false, + "pomodoro_focus_minutes": 25, + "pomodoro_short_break_minutes": 5, + "pomodoro_long_break_minutes": 15, + "pomodoro_sessions_before_long_break": 4, + "pomodoro_bell": true, + "pomodoro_notify": true, + "pomodoro_flash": true, + "pomodoro_flash_count": 2, + "pomodoro_flash_gap": 1.0, + "pomodoro_flash_rgb": [ + 246, + 248, + 252 + ] }, "deployments": { "_comment": "token: create one at Account Settings -> Tokens. The Vercel CLI's session is not used - it expires within hours. Keep this file chmod 600.", diff --git a/rust/widgets/src/bin/clocks.rs b/rust/widgets/src/bin/clocks.rs index 3eaf9f1..1f3f6f3 100644 --- a/rust/widgets/src/bin/clocks.rs +++ b/rust/widgets/src/bin/clocks.rs @@ -463,16 +463,32 @@ impl Pomodoro { } /// Lengthen or shorten the focus block, in minutes. + /// Lengthen or shorten the block you are actually in. + /// + /// Whichever phase is running: focus during focus, and that break during + /// a break. It used to write to `focus` whatever the phase, so pressing + /// it during a break moved a number that was not on screen and left the + /// countdown alone - and the hint beside it read "focus" while the line + /// above it read BREAK. Both breaks keep their own length, so shortening + /// a short break does not shorten the long one. fn adjust(&mut self, delta: f64, now: f64) { - self.focus = (self.focus + delta).clamp(1.0, 180.0); - if self.phase == Phase::Focus { - self.left = self.duration(); - if self.running { - self.deadline = now + self.left; - } + let slot = match self.phase { + Phase::Focus => &mut self.focus, + Phase::Short => &mut self.short, + Phase::Long => &mut self.long, + }; + *slot = (*slot + delta).clamp(1.0, 180.0); + self.left = self.duration(); + if self.running { + self.deadline = now + self.left; } } + /// The length of the block in progress, in minutes. + fn minutes(&self) -> i64 { + (self.duration() / 60.0).round() as i64 + } + fn restart(&mut self, now: f64) { self.left = self.duration(); self.deadline = now + self.left; @@ -773,7 +789,10 @@ fn main() { // started from. hints.push(vec![ (p.dim.as_str(), "[±]1min ".to_string()), - (p.txt.as_str(), format!("(focus {}min)", pomo.focus as i64)), + // "interval" rather than "focus": the key adjusts whichever + // block is running, so naming one of the three would be + // wrong in two phases out of three. + (p.txt.as_str(), format!("(interval {}min)", pomo.minutes())), ]); if pomo.done > 0 { // Nothing to reset at zero, so it only appears once it counts. @@ -953,6 +972,52 @@ fn palette() -> Palette { mod tests { use super::*; + #[test] + fn each_block_keeps_its_own_length() { + // The config numbers are starting values, not fixed ones: ± moves + // whichever block is running and leaves the other two alone, so a + // 25/5/15 day can become 30/5/15 without touching the breaks. + let mut pomo = Pomodoro { + phase: Phase::Focus, + running: false, + shown: true, + deadline: 0.0, + left: 25.0 * 60.0, + done: 0, + focus: 25.0, + short: 5.0, + long: 15.0, + before_long: 4, + bell: false, + rang_at: 0, + }; + + pomo.phase = Phase::Focus; + pomo.adjust(5.0, 0.0); + assert_eq!((pomo.focus, pomo.short, pomo.long), (30.0, 5.0, 15.0)); + + pomo.phase = Phase::Short; + pomo.adjust(-2.0, 0.0); + assert_eq!((pomo.focus, pomo.short, pomo.long), (30.0, 3.0, 15.0)); + + pomo.phase = Phase::Long; + pomo.adjust(1.0, 0.0); + assert_eq!((pomo.focus, pomo.short, pomo.long), (30.0, 3.0, 16.0)); + + // And the hint reports the block in progress, not one named block. + assert_eq!(pomo.minutes(), 16); + pomo.phase = Phase::Short; + assert_eq!(pomo.minutes(), 3); + + // A block cannot be argued below a minute or above three hours. + pomo.phase = Phase::Short; + for _ in 0..10 { + pomo.adjust(-1.0, 0.0); + } + assert_eq!(pomo.short, 1.0); + assert_eq!((pomo.focus, pomo.long), (30.0, 16.0), "the others are untouched"); + } + #[test] fn the_advance_key_says_what_it_will_do() { let mut pomo = Pomodoro::new(&serde_json::json!({})); From de3cefe53e21a8a86a2e76e87b68f19aacd7c300 Mon Sep 17 00:00:00 2001 From: wiiiimm Date: Mon, 24 Aug 2026 06:23:23 +0800 Subject: [PATCH 052/147] AGENTS.md: dependencies are allowed; what ships must carry what it needs William's call. The old rule was "standard library only, no pip installs, ever", written when the repo was Python scripts with no build step - and under that rule the Rust port had already broken it, quietly, by taking chrono and rusqlite for usage. The test is now whether what ships carries what it needs, rather than whether a dependency exists. The Rust has a build that can absorb one: rusqlite is taken with `bundled` so SQLite is compiled in, and ldd on a release binary shows only libc, libm and libgcc - no third-party shared library. The Python has no build step, so it stays on the standard library in practice; there is nowhere for a pip install to be absorbed into, which is the same rule reaching a different answer rather than an exception to it. External tools are unchanged and are a different thing: ping, tailscale and herdr are still expected to be absent sometimes, and a widget still has to degrade gracefully when they are. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- AGENTS.md | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b9af0c9..b33725e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,9 +5,11 @@ Linear project: Date: Mon, 24 Aug 2026 06:35:46 +0800 Subject: [PATCH 053/147] clocks: the help promised persistence the binary did not have clocks.rs performed no writes at all - no fs::write, no File::create - while clocks_help.txt line 8 said the pomodoro "persists across restarts", line 30 said the counts "persist", and docs/clocks.md line 81 said "State persists across restarts". A tally survived a restart in the Python and was silently lost in the Rust, and the documentation said otherwise. That is a footer hint teaching a key that does not exist, one level up. Three things, all confirmed against clocks.py rather than invented: - The state file is now written and read, at clocks.py's own path and with its keys exactly - checked by running both: the file the Rust writes carries every key clocks.py reads and no others, so a pomodoro started under one implementation is picked up by the other rather than each keeping a private tally of the same afternoon. Verified by driving the binary: start, quit, restart, and the timer resumes with its deadline intact. - roll_day is back. clocks.py's docstring names the missing reset as a bug it had already fixed - "a panel left running over midnight kept adding to yesterday's total" - and the port had reintroduced exactly that. It runs once a frame, before anything reads the tally. - pomodoro_enabled and pomodoro_notify are read. Both were in the example config and neither reached the Rust, so setting pomodoro_enabled did nothing. notify now sends OSC 9 and OSC 777 as well as the bell, which is the only alerting channel that survives SSH. And a fourth found while wiring the third: herdr_toast passed the body as a second positional argument, where `herdr notification show` takes one and the body is an option. It failed with "unknown option" every time, silently, because stderr is nulled - so that toast had never once been shown. Checked against the CLI's own help. The tests that touch the state file take one lock and get a disposable directory, because XDG_STATE_HOME is process-global and cargo runs tests in parallel threads: without it a test wanting a fresh 25-minute focus reads whatever a concurrent test just wrote, and each run failed somewhere different. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/widgets/src/bin/clocks.rs | 260 ++++++++++++++++++++++++++++++++- 1 file changed, 257 insertions(+), 3 deletions(-) diff --git a/rust/widgets/src/bin/clocks.rs b/rust/widgets/src/bin/clocks.rs index 1f3f6f3..b1212dc 100644 --- a/rust/widgets/src/bin/clocks.rs +++ b/rust/widgets/src/bin/clocks.rs @@ -302,7 +302,12 @@ fn herdr_toast(title: &str, body: &str) { return; } let _ = std::process::Command::new("herdr") - .args(["notification", "show", title, body, "--sound", "done"]) + // --body, not a second positional: `herdr notification show` takes + // one <TITLE> and the body is an option. Passing it positionally + // fails with "unknown option" - silently, since stderr is nulled - + // so this toast had never once been shown. + .args(["notification", "show", title, "--body", body, "--sound", "done"]) + .stdin(std::process::Stdio::null()) .stdout(std::process::Stdio::null()) .stderr(std::process::Stdio::null()) .spawn(); @@ -329,6 +334,35 @@ struct Pomodoro { before_long: u32, bell: bool, rang_at: i64, + /// The day the tally belongs to, as %Y-%m-%d. Kept so a panel left + /// running over midnight zeroes rather than adding to yesterday. + day: String, + /// pomodoro_enabled: whether it starts running. clocks.py reads this + /// and the port did not, so setting it did nothing here. + enabled: bool, + /// pomodoro_notify: ring the terminal bell on a phase change. Read for + /// the same reason. + notify: bool, +} + +/// Where the pomodoro's state lives, shared with clocks.py. +/// +/// The same path and the same keys, so a session started under one +/// implementation is picked up by the other rather than each keeping a +/// private tally of the same afternoon. +fn state_file() -> String { + let base = std::env::var("XDG_STATE_HOME").unwrap_or_else(|_| { + format!( + "{}/.local/state", + std::env::var("HOME").unwrap_or_default() + ) + }); + format!("{}/terminal-toys/pomodoro.json", base) +} + +/// Today, in the form the state file stores. +fn today() -> String { + Local::now().format("%Y-%m-%d").to_string() } #[derive(Clone, Copy, PartialEq, Eq, Debug)] @@ -370,11 +404,110 @@ impl Pomodoro { .and_then(|v| v.as_bool()) .unwrap_or(true), rang_at: -1, + day: today(), + enabled: cfg + .get("pomodoro_enabled") + .and_then(|v| v.as_bool()) + .unwrap_or(false), + notify: cfg + .get("pomodoro_notify") + .and_then(|v| v.as_bool()) + .unwrap_or(false), }; it.left = it.duration(); + it.running = it.enabled; + it.load(); it } + /// Read the state file, if there is one. + /// + /// Preferences outlive the day; only the tally and the block in + /// progress belong to it, so a file from yesterday contributes the + /// focus length and nothing else. + fn load(&mut self) { + let Ok(text) = std::fs::read_to_string(state_file()) else { + return; + }; + let Ok(d) = serde_json::from_str::<serde_json::Value>(&text) else { + return; + }; + if let Some(v) = d.get("focus").and_then(|v| v.as_f64()) { + self.focus = v; + } + if let Some(v) = d.get("enabled").and_then(|v| v.as_bool()) { + self.enabled = v; + } + if let Some(v) = d.get("hints").and_then(|v| v.as_bool()) { + self.shown = v; + } + if d.get("day").and_then(|v| v.as_str()) != Some(self.day.as_str()) { + return; // a new day starts a fresh count + } + if let Some(v) = d.get("phase").and_then(|v| v.as_str()) { + self.phase = match v { + "short" => Phase::Short, + "long" => Phase::Long, + _ => Phase::Focus, + }; + } + self.done = d.get("completed").and_then(|v| v.as_u64()).unwrap_or(0) as u32; + if let Some(v) = d.get("left").and_then(|v| v.as_f64()) { + self.left = v; + } + // Resume mid-phase. If it elapsed while the panel was away the + // timer simply shows how far over it has run, which is what the + // Python does rather than pretending it ended on time. + let deadline = d.get("deadline").and_then(|v| v.as_f64()).unwrap_or(0.0); + if d.get("running").and_then(|v| v.as_bool()).unwrap_or(false) && deadline > 0.0 { + self.deadline = deadline; + self.running = true; + } + } + + /// Write the state file, failing quietly. + /// + /// A panel that cannot save its tally should still show the clock. + fn save(&self) { + let path = state_file(); + if let Some(dir) = std::path::Path::new(&path).parent() { + let _ = std::fs::create_dir_all(dir); + } + let body = serde_json::json!({ + "day": self.day, + "phase": match self.phase { + Phase::Focus => "focus", + Phase::Short => "short", + Phase::Long => "long", + }, + "completed": self.done, + "focus": self.focus, + "enabled": self.enabled, + "running": self.running, + "was_running": self.running, + "hints": self.shown, + "left": self.left, + "deadline": self.deadline, + }); + let _ = std::fs::write(&path, body.to_string()); + } + + /// Zero the tally when the date changes, even if nothing restarted. + /// + /// clocks.py's own docstring names this: the count previously reset + /// only on load, so a panel left running over midnight kept adding to + /// yesterday's total. The port had reintroduced exactly that. + fn roll_day(&mut self) -> bool { + let now = today(); + if now != self.day { + self.day = now; + self.done = 0; + self.save(); + return true; + } + false + } + fn duration(&self) -> f64 { 60.0 * match self.phase { Phase::Focus => self.focus, @@ -411,6 +544,7 @@ impl Pomodoro { self.deadline = now + self.left; } } + self.save(); } fn start_stop(&mut self, now: f64) { @@ -421,6 +555,7 @@ impl Pomodoro { self.running = true; self.deadline = now + self.left; } + self.save(); } /// Move to whatever comes next, counting a finished focus block. @@ -438,6 +573,7 @@ impl Pomodoro { self.left = self.duration(); self.deadline = now + self.left; self.rang_at = -1; + self.save(); } /// What pressing the break key will do, right now. @@ -460,6 +596,7 @@ impl Pomodoro { /// Zero the tally, once there is something to zero. fn reset_count(&mut self) { self.done = 0; + self.save(); } /// Lengthen or shorten the focus block, in minutes. @@ -482,6 +619,7 @@ impl Pomodoro { if self.running { self.deadline = now + self.left; } + self.save(); } /// The length of the block in progress, in minutes. @@ -493,6 +631,7 @@ impl Pomodoro { self.left = self.duration(); self.deadline = now + self.left; self.rang_at = -1; + self.save(); } /// One tick: ring on elapse, and once a minute while overrunning. @@ -513,14 +652,33 @@ impl Pomodoro { return false; } self.rang_at = minute; + self.alert(&format!("{} over", self.phase.label())); + true + } + + /// Nudge whoever is in front of the terminal, over SSH if need be. + /// + /// BEL is universal. OSC 9 covers iTerm2, WezTerm, Windows Terminal + /// and Ghostty; OSC 777 covers urxvt and several others. Terminals + /// ignore the sequences they do not implement, so sending both costs + /// nothing, and a multiplexer in between decides whether to forward + /// them. + fn alert(&self, text: &str) { if self.bell { tc::out("\x07"); - tc::flush(); } - true + if self.notify { + tc::out(&format!("\x1b]9;{}\x07", text)); + tc::out(&format!("\x1b]777;notify;Pomodoro;{}\x07", text)); + } + tc::flush(); + if self.notify { + herdr_toast("Pomodoro", text); + } } } + struct City { name: String, zone: Tz, @@ -627,6 +785,9 @@ fn main() { // The pomodoro leads the section, as it does in the Python. let stamp = seconds(); + // Before anything reads the tally: a panel left running over + // midnight must zero rather than keep adding to yesterday. + pomo.roll_day(); if pomo.tick(stamp) { flash_started = Some(stamp); let over = pomo.overtime(stamp); @@ -972,11 +1133,93 @@ fn palette() -> Palette { mod tests { use super::*; + /// One lock for every test that touches the state file. + /// + /// XDG_STATE_HOME is process-global and cargo runs tests in parallel + /// threads, so without this one test's sandbox becomes another's - and + /// since Pomodoro::new loads, a test wanting a fresh 25-minute focus + /// would read whatever a concurrent test had just written. + static STATE_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(()); + + /// Take the lock and point the state file at an empty directory. + /// + /// The real file holds a running pomodoro that clocks.py shares, so a + /// careless test zeroes an actual afternoon. + fn sandbox(name: &str) -> std::sync::MutexGuard<'static, ()> { + let held = STATE_LOCK.lock().unwrap_or_else(|e| e.into_inner()); + let dir = format!("/tmp/toys-clocks-test-{}-{}", std::process::id(), name); + let _ = std::fs::remove_dir_all(&dir); + std::env::set_var("XDG_STATE_HOME", &dir); + held + } + + #[test] + fn a_panel_left_running_over_midnight_starts_a_fresh_count() { + // clocks.py's roll_day docstring names this as a bug it already + // fixed: the count used to reset only on load, so a panel running + // overnight kept adding to yesterday's total. The port had + // reintroduced it - there was no roll at all. + let _held = sandbox("roll"); + let mut p = Pomodoro::new(&serde_json::json!({})); + p.done = 5; + p.day = "2020-01-01".into(); + assert!(p.roll_day(), "a changed date should roll"); + assert_eq!(p.done, 0, "yesterday's tally carried into today"); + assert_eq!(p.day, today()); + // And the same day twice does nothing. + p.done = 2; + assert!(!p.roll_day()); + assert_eq!(p.done, 2, "the tally was zeroed on an unchanged day"); + } + + #[test] + fn the_tally_survives_a_restart_and_the_file_is_the_pythons() { + // The help text promises the pomodoro persists across restarts, + // and the port wrote nothing at all. The file is clocks.py's, key + // for key, so a session started under one is picked up by the + // other rather than each keeping a private tally. + let _held = sandbox("save"); + let mut p = Pomodoro::new(&serde_json::json!({})); + p.done = 3; + p.phase = Phase::Short; + p.save(); + + let text = std::fs::read_to_string(state_file()).expect("a state file"); + let d: serde_json::Value = serde_json::from_str(&text).expect("json"); + for key in [ + "day", "phase", "completed", "focus", "enabled", "running", + "was_running", "hints", "left", "deadline", + ] { + assert!(d.get(key).is_some(), "clocks.py reads {} and we omit it", key); + } + assert_eq!(d["completed"], 3); + assert_eq!(d["phase"], "short"); + + let back = Pomodoro::new(&serde_json::json!({})); + assert_eq!(back.done, 3, "the tally did not survive"); + assert_eq!(back.phase, Phase::Short); + } + + #[test] + fn a_tally_from_another_day_is_not_carried_forward() { + // Preferences outlive the day; the count does not. + let _held = sandbox("stale"); + let mut p = Pomodoro::new(&serde_json::json!({})); + p.done = 9; + p.day = "2020-01-01".into(); + p.save(); + let back = Pomodoro::new(&serde_json::json!({})); + assert_eq!(back.done, 0, "yesterday's count was loaded as today's"); + } + #[test] fn each_block_keeps_its_own_length() { // The config numbers are starting values, not fixed ones: ± moves // whichever block is running and leaves the other two alone, so a // 25/5/15 day can become 30/5/15 without touching the breaks. + // adjust() saves, and the real state file is a running pomodoro + // that clocks.py shares - send the writes somewhere disposable. + let _held = sandbox("adjust"); let mut pomo = Pomodoro { phase: Phase::Focus, running: false, @@ -990,6 +1233,9 @@ mod tests { before_long: 4, bell: false, rang_at: 0, + day: today(), + enabled: false, + notify: false, }; pomo.phase = Phase::Focus; @@ -1020,6 +1266,7 @@ mod tests { #[test] fn the_advance_key_says_what_it_will_do() { + let _held = sandbox("the_advance_key_says_what_it_will_do"); let mut pomo = Pomodoro::new(&serde_json::json!({})); // Three blocks done, so the fourth leads to the long break and the // hint has to say so rather than promising an ordinary one. @@ -1032,6 +1279,8 @@ mod tests { #[test] fn the_focus_length_can_be_nudged_and_stays_sane() { + // new() loads and adjust() saves, so this needs its own state. + let _held = sandbox("nudge"); let mut pomo = Pomodoro::new(&serde_json::json!({})); pomo.adjust(5.0, 0.0); assert_eq!(pomo.focus, 30.0); @@ -1045,6 +1294,7 @@ mod tests { #[test] fn the_tally_resets_only_when_there_is_one() { + let _held = sandbox("the_tally_resets_only_when_there_is_one"); let mut pomo = Pomodoro::new(&serde_json::json!({})); pomo.done = 4; pomo.reset_count(); @@ -1260,6 +1510,7 @@ mod tests { #[test] fn a_focus_block_leads_to_a_break_and_back() { + let _held = sandbox("a_focus_block_leads_to_a_break_and_back"); let cfg = serde_json::json!({}); let mut pomo = Pomodoro::new(&cfg); let now = 1000.0; @@ -1273,6 +1524,7 @@ mod tests { #[test] fn every_fourth_break_is_a_long_one() { + let _held = sandbox("every_fourth_break_is_a_long_one"); let mut pomo = Pomodoro::new(&serde_json::json!({})); let now = 0.0; for _ in 0..3 { @@ -1286,6 +1538,7 @@ mod tests { #[test] fn hiding_freezes_it_rather_than_letting_it_run_away() { + let _held = sandbox("hiding_freezes_it_rather_than_letting_it_run_away"); let mut pomo = Pomodoro::new(&serde_json::json!({})); pomo.shown = true; pomo.start_stop(0.0); @@ -1302,6 +1555,7 @@ mod tests { #[test] fn overrunning_counts_up_rather_than_stopping() { + let _held = sandbox("overrunning_counts_up_rather_than_stopping"); let mut pomo = Pomodoro::new(&serde_json::json!({})); pomo.shown = true; pomo.start_stop(0.0); From 046ce1c90bb74406ff633d52a501cf0370de1b88 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Mon, 24 Aug 2026 09:43:54 +0800 Subject: [PATCH 054/147] linear: a timestamp with a wide character killed the poll thread parse() checked `ts.len() < 19` and then sliced `&ts[..19]` - both byte operations - so a timestamp carrying a multibyte character across byte 19 panicked on a character boundary instead of declining to parse. It runs in a poll thread on data from a server, and a panic there takes the widget with it. Real Linear timestamps are ASCII, so this needs a malformed payload to reach. "The server would never send that" is the assumption this repo keeps paying for, and taking the first nineteen characters rather than the first nineteen bytes costs nothing. The test needed two attempts and the first one was worthless. Its fixture put the wide digit early in the string, where byte 19 still landed on a character boundary, so it passed against the unfixed code. The one that ships puts the character across bytes 18-20 and was checked the only way that means anything: revert the fix, watch it panic, restore it, watch it pass. Found by a review of the port. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/widgets/src/bin/linear.rs | 26 ++++++++++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) diff --git a/rust/widgets/src/bin/linear.rs b/rust/widgets/src/bin/linear.rs index e3d7976..d064e54 100644 --- a/rust/widgets/src/bin/linear.rs +++ b/rust/widgets/src/bin/linear.rs @@ -203,10 +203,15 @@ fn day(ts: &str) -> String { } fn parse(ts: &str) -> Option<NaiveDateTime> { - if ts.len() < 19 { + // By characters, not bytes. len() and [..19] are both byte operations, + // so a timestamp with any multibyte character in its first nineteen + // bytes used to panic on a character boundary rather than decline to + // parse - in a poll thread, on data from a server. + let head: String = ts.chars().take(19).collect(); + if head.chars().count() < 19 { return None; } - NaiveDateTime::parse_from_str(&ts[..19], "%Y-%m-%dT%H:%M:%S").ok() + NaiveDateTime::parse_from_str(&head, "%Y-%m-%dT%H:%M:%S").ok() } fn hours_since(from: Option<NaiveDateTime>, to: Option<NaiveDateTime>) -> Option<f64> { @@ -1219,6 +1224,23 @@ fn main() { mod tests { use super::*; + #[test] + fn a_timestamp_that_is_not_ascii_is_declined_rather_than_fatal() { + // A full-width digit puts a character boundary inside byte 19. + // This used to panic in the poll thread, which under the release + // profile takes the whole widget with it. + // Byte 19 falls inside this character; an earlier fixture put the + // wide digit where byte 19 was still a boundary and so passed + // against the bug. Verified by reverting the fix. + assert_eq!(parse("2026-08-24T10:00:0\u{ff14} x"), None); + assert_eq!(parse("\u{4e00}\u{4e00}\u{4e00}\u{4e00}\u{4e00}"), None); + assert_eq!(parse(""), None); + assert_eq!(parse("2026-08-24"), None); + // And a real one still reads. + assert!(parse("2026-08-24T10:00:00.000Z").is_some()); + } + + #[test] fn a_span_changes_unit_before_it_stops_meaning_anything() { assert_eq!(dur(None), "--"); From bd4cd194639dd752f5131cbae237e96e28fd52ef Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Mon, 24 Aug 2026 10:52:43 +0800 Subject: [PATCH 055/147] AGENTS.md: two gotchas from letting a device name reach a public PR Scanned all 29,541 added lines of the branch before pushing it, and the rule covers code, docs and commit messages - a message is not a diff line, so half the rule went unchecked. Two messages on the branch name real devices. The second half is the more interesting one and neither of us saw it until afterwards: the commit that removes a secret is the likeliest place to restate it. 936a3b4 took a real device name out of a test fixture and its message explains which device it was and what the marker in it means, which says more than the fixture did - the fixture leaked a string, the message confirms the string is real and decodes it. William has ruled: leave the messages as they are. The content is a device nickname and a city hint, nothing reachable, and a force-push over 54 commits on a branch with an open PR would not reliably erase them from GitHub anyway - force-pushed objects stay addressable by SHA. Recording the lesson is the part with value. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- AGENTS.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index b33725e..22101f5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -79,6 +79,16 @@ exactly like "there is no data": - **GitHub search returns at most 100 nodes per page.** Anything counting records must paginate or, better, ask for `issueCount` aggregates — which cost one rate-limit point per *request*, not per alias. +- **A secret scan of the diff cannot see commit messages.** Scanning every + added line before a push is right and still misses half the rule, because + the rule covers code, docs *and* messages, and a message is not a diff + line. Scan `git log origin/main..HEAD` separately. +- **The commit that removes a secret is the likeliest place to restate it.** + "The fixture used `<the actual name>`, which is a device on this tailnet" + is the most natural sentence to write when documenting the fix, and it + says more than the fixture did — it confirms the string is real and + explains what it identifies. Describe the shape, never the value: *a + fixture named a real device* is enough. ## Layout of the code From 083f088954a88a5de0c18e03f1fd7851f268e65d Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Mon, 24 Aug 2026 11:10:23 +0800 Subject: [PATCH 056/147] herdr-panes: name the keys after what they toggle w toggled workspace labels and o toggled the idle section, neither of which the letter suggests. They are now l and i. w came from herdr-panes.py and the port had carried it faithfully; the Python moves with it here, since both were on the wall side by side at the time. The idle key is changed in the Rust only - the doc names both while the two implementations coexist, because check.py reads the doc against the Python's footer. Recorded rather than fixed, because it is inherited and wants its own change: the idle section can never appear on a busy machine. Three height guards stack against it - the agents list stops six rows short of the bottom, the running panes fill to two rows short, and the idle loop then breaks on its first iteration - after which the truncate that fits the body to the pane removes the section header too. The blank line and the header are pushed unconditionally before any of that, so what is lost is not just the rows but the announcement that there were any. On this machine twelve panes are sitting at a prompt and none of them are reachable, which makes the key that toggles them look broken rather than starved. Both implementations do it, so it is the port's inheritance and not its doing. That is the same shape as link's detail chart dropping its plot for want of five rows: a section that cannot fit says nothing, and nothing looks exactly like nothing to show. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- docs/herdr-panes.md | 6 +++--- herdr-panes.py | 7 ++++--- rust/widgets/src/bin/herdr-panes.rs | 8 ++++---- rust/widgets/src/bin/herdr-panes_help.txt | 3 ++- 4 files changed, 13 insertions(+), 11 deletions(-) diff --git a/docs/herdr-panes.md b/docs/herdr-panes.md index 738d947..ecebd72 100644 --- a/docs/herdr-panes.md +++ b/docs/herdr-panes.md @@ -26,7 +26,7 @@ and one keypress to get to any of it. ▫ work/site site ▫ …/another-monorepo monorepo - ↑↓ select ↵ switch to this pane [o]idle [w]labels [r]efresh [q]uit + ↑↓ select ↵ switch to this pane [i]dle [l]abels [r]efresh [q]uit ``` ## Why it is ordered this way @@ -80,8 +80,8 @@ does not timestamp state changes, so transitions are tracked here. |---|---| | `↑` `↓` `Home` `End` | select, across all three sections | | `Enter` / `f` | **go there** — the agent's pane, or the tab holding that process | -| `o` | show/hide the idle section | -| `w` | workspace labels vs pane ids | +| `i` | show/hide the idle section — `o` in the Python, which is being retired | +| `l` | workspace labels vs pane ids | | `r` | refresh now | | `q` | quit | diff --git a/herdr-panes.py b/herdr-panes.py index e4a255f..f1f6e2a 100755 --- a/herdr-panes.py +++ b/herdr-panes.py @@ -50,7 +50,8 @@ python3 herdr-panes.py [-n SECONDS] Keys: up/down select, Enter (or f) focuses that agent's pane so you jump -straight to whatever needs you, w toggles workspace labels vs pane ids, +straight to whatever needs you, l toggles workspace labels vs pane ids, +o shows or hides the idle section, r refreshes now, q quits. Requires HERDR_ENV; it shells out to the `herdr` CLI. """ @@ -333,7 +334,7 @@ def main(): raise SystemExit(0) if key == "r": store.wake.set() - elif key == "w": + elif key == "l": show_labels = not show_labels elif key == "o": show_idle = not show_idle @@ -500,7 +501,7 @@ def main(): # that drifted, and the footer ended up written past the bottom row. hints = [[(ACCENT, "↑↓"), (DIM, " select")], [(ACCENT, "↵"), (DIM, " switch to this pane")], - [(DIM, "[o]idle")], [(DIM, "[w]labels")], + [(DIM, "[o]idle")], [(DIM, "[l]abels")], [(DIM, "[r]efresh")], [(DIM, "[q]uit")]] footer = [" " + line for line in pack_hints(hints, w - 2)] reserve = len(footer) + 1 # +1 for the note line diff --git a/rust/widgets/src/bin/herdr-panes.rs b/rust/widgets/src/bin/herdr-panes.rs index 058dad0..939d7c3 100644 --- a/rust/widgets/src/bin/herdr-panes.rs +++ b/rust/widgets/src/bin/herdr-panes.rs @@ -528,8 +528,8 @@ fn main() { cond.notify_all(); } } - "w" | "W" => show_labels = !show_labels, - "o" | "O" => { + "l" | "L" => show_labels = !show_labels, + "i" | "I" => { show_idle = !show_idle; selected = 0; } @@ -861,8 +861,8 @@ fn main() { (p.accent.as_str(), "↵".into()), (p.dim.as_str(), " switch to this pane".into()), ], - vec![(p.dim.as_str(), "[o]idle".into())], - vec![(p.dim.as_str(), "[w]labels".into())], + vec![(p.dim.as_str(), "[i]dle".into())], + vec![(p.dim.as_str(), "[l]abels".into())], vec![(p.dim.as_str(), "[r]efresh".into())], vec![(p.dim.as_str(), "[q]uit".into())], ]; diff --git a/rust/widgets/src/bin/herdr-panes_help.txt b/rust/widgets/src/bin/herdr-panes_help.txt index 7017ea5..762d48a 100644 --- a/rust/widgets/src/bin/herdr-panes_help.txt +++ b/rust/widgets/src/bin/herdr-panes_help.txt @@ -34,6 +34,7 @@ is only a lower bound. herdr-panes [-n SECONDS] Keys: up/down select, Enter (or f) focuses that agent's pane so you jump -straight to whatever needs you, w toggles workspace labels vs pane ids, +straight to whatever needs you, l toggles workspace labels vs pane ids, +i shows or hides the idle section, r refreshes now, q quits. Requires HERDR_ENV; it shells out to the `herdr` CLI. From 63fe9b97decb072b46c6924eba3257ab786f5786 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Mon, 24 Aug 2026 11:11:51 +0800 Subject: [PATCH 057/147] docs: point at the Linear issues rather than the project overview AGENTS.md linked the project's overview page; the issues list is where the work actually is, and it now says what is in there - planned widgets, the per-widget port reviews, and the decisions waiting on William - with the instruction to look before starting and check before proposing. README.md had no link at all. It has a short section now, with the caveat that the link needs workspace access: for a reader outside it the point is only that a missing feature may already be filed with a reason. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- AGENTS.md | 7 ++++++- README.md | 7 +++++++ 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 22101f5..a0b700d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,7 +1,12 @@ # Working on terminal-toys Linear team: <https://linear.app/stealth-company/team/TOY/overview> -Linear project: <https://linear.app/stealth-company/project/terminal-toys-e829b47d84b8/overview> +Linear project: <https://linear.app/stealth-company/project/terminal-toys-e829b47d84b8/issues> + +**Everything is tracked there** — planned widgets, the per-widget port +reviews, and the decisions waiting on William. Before starting anything, +look for the issue; before proposing something, check it is not already +filed and already decided against. ## What this repo is diff --git a/README.md b/README.md index 92f2285..bcff5a9 100644 --- a/README.md +++ b/README.md @@ -147,6 +147,13 @@ for it — copy it to `~/.claude/skills/herdr/` to install. It is Herdr's own file, not covered by this repository's licence, and `herdr --skill` regenerates it after an upgrade. +## What is being worked on + +Planned widgets, open questions and the state of the Rust port are tracked +in Linear: <https://linear.app/stealth-company/project/terminal-toys-e829b47d84b8/issues>. The link needs access to the workspace; the issues are the +canonical list either way, so a feature that looks missing may already be +filed there with a reason. + ## Building your own [`docs/building-herdr-panels.md`](docs/building-herdr-panels.md) collects what From e1ff49a1486f7b8cf526daad7b27084392af41e1 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Mon, 24 Aug 2026 11:12:08 +0800 Subject: [PATCH 058/147] check.py, for the Rust - and the three things it found on its first run check.py reads only *.py, so none of its checks had ever run against the fourteen binaries. They are cargo tests rather than a fifteenth binary: they run on every `cargo test` instead of waiting to be remembered, and start's menu asserts every [[bin]] in the manifest is on it, so a checker binary would have to be listed as a widget it is not. Three of the five port. Two do not, and say so rather than being silently dropped: unbound names is a compile error here, and the docs are shared with the Python where check.py already covers them. What it found, all three real: - netwatch and ports read no config at all, while config.example.json documents seven keys between them - netwatch's interval, limit, sort, external and mine, and ports' refresh and system_ports. Every variable already existed with the right default; the port simply never loaded the file. Now wired, config as the default and argv still overriding, which is the Pythons' precedence. Checked by running it: a config of sort=live and interval=3 shows "sorted by live ... every 3s", and --sort total on the command line beats a config saying live. - tailnet reads a "history" key that config.example.json has never documented, in both implementations, since before the port. Same shape as the eleven pomodoro_* keys: configurable the whole time and undiscoverable. Added to the example. - link's footer teaches [n]ext and [p]rev on the detail screen and docs/link.md's key table lists neither. Added. The reverse config check - a key a widget reads that the example does not document - is new to both sides. check.py checks only the other direction, which is why the pomodoro keys hid for months. One note on building it: the first run reported 24 config failures that were all mine. Matching a bare `.get("` catches every JSON lookup in a file - clocks reading its own state, link parsing ss output, usage reading token counts - and none of those is config. It matches `cfg.get(` now. An earlier hand-run of the same rule had a comparable bug, reporting 48 failures because its pattern could not match the uppercase half of "q" | "Q". A checker that cries wolf gets turned off. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- config.example.json | 2 + docs/link.md | 1 + rust/widgets/src/bin/netwatch.rs | 17 +- rust/widgets/src/bin/ports.rs | 34 +++- rust/widgets/tests/check.rs | 319 +++++++++++++++++++++++++++++++ 5 files changed, 365 insertions(+), 8 deletions(-) create mode 100644 rust/widgets/tests/check.rs diff --git a/config.example.json b/config.example.json index f0b58ef..e39ef29 100644 --- a/config.example.json +++ b/config.example.json @@ -62,6 +62,8 @@ "projects": [] }, "tailnet": { + "_comment_history": "rate samples kept per peer; the chart is a window on to this", + "history": 180, "refresh": 5 }, "herdr_panes": { diff --git a/docs/link.md b/docs/link.md index 6177ed0..7960a5c 100644 --- a/docs/link.md +++ b/docs/link.md @@ -120,6 +120,7 @@ are still true about the path, just not about the terminal. |---|---| | `↑` `↓` | select a session | | `↵` / `i` | open that connection on its own screen | +| `n` / `p` | on the detail screen, step to the next or previous connection | | `esc` | back to the list | | `w` | cycle the chart's span: 1m, 5m, 15m, 1h | | `o` | hide or show sessions idle over five minutes | diff --git a/rust/widgets/src/bin/netwatch.rs b/rust/widgets/src/bin/netwatch.rs index dfcc977..1917604 100644 --- a/rust/widgets/src/bin/netwatch.rs +++ b/rust/widgets/src/bin/netwatch.rs @@ -1411,11 +1411,18 @@ fn ordered(state: &Arc<Mutex<State>>, mine: bool, live: bool) -> Vec<Proc> { fn main() { tc::maybe_help(include_str!("netwatch_help.txt")); - let mut interval = 1.0f64; - let mut limit = 0usize; - let mut external = true; - let mut mine = true; - let mut sort_live = false; + // Config first, argv second: `--interval 2` beats a config saying 1, + // which is the precedence netwatch.py uses. These five were documented + // in config.example.json and read by nobody. + let cfg = tc::load_config("netwatch"); + let mut interval = tc::cfg_f64(&cfg, "interval", 1.0).max(0.2); + let mut limit = tc::cfg_usize(&cfg, "limit", 0); + let mut external = cfg + .get("external") + .and_then(|v| v.as_bool()) + .unwrap_or(true); + let mut mine = cfg.get("mine").and_then(|v| v.as_bool()).unwrap_or(true); + let mut sort_live = tc::cfg_str(&cfg, "sort", "total") == "live"; let mut plain = false; let args: Vec<String> = std::env::args().skip(1).collect(); let mut i = 0; diff --git a/rust/widgets/src/bin/ports.rs b/rust/widgets/src/bin/ports.rs index a90b507..5b59b19 100644 --- a/rust/widgets/src/bin/ports.rs +++ b/rust/widgets/src/bin/ports.rs @@ -32,8 +32,25 @@ use std::time::{Duration, SystemTime, UNIX_EPOCH}; use toys_core as tc; +/// The machine's own ports, hidden behind `o` by default: they are never +/// the answer to "which port is my dev server on". const SYSTEM_PORTS: &[u16] = &[22, 53, 123, 323, 631, 5353]; +/// What config said, if it said anything. Set once in main. +/// +/// A static rather than a threaded parameter because two predicates deep +/// in the sort and filter want it and neither is worth rewriting to carry +/// a list that changes only at startup. +static CONFIGURED_PORTS: std::sync::OnceLock<Vec<u16>> = std::sync::OnceLock::new(); + +/// Whether a port belongs to the machine rather than to something started. +fn is_system_port(port: u16) -> bool { + match CONFIGURED_PORTS.get() { + Some(list) => list.contains(&port), + None => SYSTEM_PORTS.contains(&port), + } +} + /// Process titles worth recognising, first match winning, so the specific /// ones come before `node` and `python`. const KINDS: &[(&str, &str)] = &[ @@ -488,7 +505,7 @@ fn scan() -> Vec<Row> { }); } } - rows.sort_by_key(|r| (SYSTEM_PORTS.contains(&r.port), r.port)); + rows.sort_by_key(|r| (is_system_port(r.port), r.port)); rows } @@ -513,7 +530,7 @@ fn theirs(row: &Row) -> bool { if row.orphan { return false; } - SYSTEM_PORTS.contains(&row.port) || !row.user.is_empty() + is_system_port(row.port) || !row.user.is_empty() } /// Every address this machine holds, by interface. @@ -1611,7 +1628,18 @@ impl Store { fn main() { tc::maybe_help(include_str!("ports_help.txt")); - let mut refresh = 4.0f64; + // Both of ports' config keys were documented and read by nobody. + // Config is the default; argv still overrides. + let cfg = tc::load_config("ports"); + let listed: Vec<u16> = cfg + .get("system_ports") + .and_then(|v| v.as_array()) + .map(|a| a.iter().filter_map(|v| v.as_u64()).map(|n| n as u16).collect()) + .unwrap_or_default(); + if !listed.is_empty() { + let _ = CONFIGURED_PORTS.set(listed); + } + let mut refresh = tc::cfg_f64(&cfg, "refresh", 4.0).max(1.0); let args: Vec<String> = std::env::args().skip(1).collect(); let mut i = 0; while i < args.len() { diff --git a/rust/widgets/tests/check.rs b/rust/widgets/tests/check.rs new file mode 100644 index 0000000..cf6bc17 --- /dev/null +++ b/rust/widgets/tests/check.rs @@ -0,0 +1,319 @@ +// terminal-toys - small dependency-free terminal widgets +// Copyright (C) 2026 William Li +// +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU Affero General Public License as published +// by the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU Affero General Public License for more details. +// +// You should have received a copy of the GNU Affero General Public License +// along with this program. If not, see <https://www.gnu.org/licenses/>. + +//! check.py, for the Rust side. +//! +//! Every check in check.py exists because something shipped broken, and +//! each is a fault that looks on screen exactly like "there is no data". +//! check.py reads only `*.py`, so none of them has ever run against these +//! fourteen binaries - and two of them fail today. +//! +//! These are tests rather than a fifteenth binary for two reasons: they +//! then run on every `cargo test` instead of waiting to be remembered, and +//! `start`'s menu asserts that every `[[bin]]` in the manifest is on it, so +//! a checker binary would have to be listed as a widget it is not. +//! +//! Two of check.py's five do not need porting and are recorded here rather +//! than silently dropped: +//! +//! - **unbound names**: a compile error in Rust. The fault it was written +//! for - deployments.py losing an import and its poll thread dying for a +//! day - cannot reach a built binary. +//! - **missing docs and README rows**: the docs are shared between the two +//! implementations and check.py already covers them. Re-checking here +//! would only duplicate it. + +use std::collections::{BTreeMap, BTreeSet}; +use std::path::PathBuf; + +/// The repo root, from this crate's own location. +fn root() -> PathBuf { + PathBuf::from(env!("CARGO_MANIFEST_DIR")) + .join("../..") + .canonicalize() + .expect("the repo root") +} + +/// Every widget binary, by stem, with its source. +fn widgets() -> BTreeMap<String, String> { + let dir = root().join("rust/widgets/src/bin"); + let mut found = BTreeMap::new(); + for entry in std::fs::read_dir(&dir).expect("the bin directory").flatten() { + let path = entry.path(); + if path.extension().and_then(|e| e.to_str()) != Some("rs") { + continue; + } + let stem = path.file_stem().and_then(|s| s.to_str()).unwrap_or("").to_string(); + let mut src = std::fs::read_to_string(&path).unwrap_or_default(); + // A widget split across a directory - usage - reads as one widget. + let sub = dir.join(&stem); + if sub.is_dir() { + for part in std::fs::read_dir(&sub).expect("a widget directory").flatten() { + if part.path().extension().and_then(|e| e.to_str()) == Some("rs") { + src.push('\n'); + src.push_str(&std::fs::read_to_string(part.path()).unwrap_or_default()); + } + } + } + found.insert(stem, src); + } + found +} + +/// Text inside double-quoted string literals, where hints live. +/// +/// Deliberately crude: it is looking for `[w]indow`, and a hint never +/// spans a line. Parsing Rust properly to find a footer would be a much +/// larger thing that failed in more interesting ways. +fn string_literals(src: &str) -> String { + let mut out = String::new(); + for line in src.lines() { + let mut rest = line; + while let Some(open) = rest.find('"') { + let after = &rest[open + 1..]; + match after.find('"') { + Some(close) => { + out.push_str(&after[..close]); + out.push(' '); + rest = &after[close + 1..]; + } + None => break, + } + } + } + out +} + +/// The keys a footer hint teaches: `[w]indow`, `[r]efresh`. +/// +/// The bracket must be followed immediately by a letter, which is what +/// separates a hint from an index like `rows[0]` or a closure parameter. +fn hinted_keys(src: &str) -> BTreeSet<char> { + let text = string_literals(src); + let bytes: Vec<char> = text.chars().collect(); + let mut found = BTreeSet::new(); + for i in 0..bytes.len().saturating_sub(3) { + if bytes[i] == '[' + && (bytes[i + 1].is_ascii_lowercase() || bytes[i + 1].is_ascii_digit()) + && bytes[i + 2] == ']' + && bytes[i + 3].is_ascii_alphabetic() + { + found.insert(bytes[i + 1]); + } + } + found +} + +/// The keys a match arm answers to. +/// +/// Case-insensitive on purpose: arms read `"q" | "Q"`, and a pattern that +/// only matched lowercase would fail the whole alternation on the +/// uppercase half - which is exactly the bug that made the first draft of +/// this check report 48 failures against widgets that were all correct. +fn handled_keys(src: &str) -> BTreeSet<char> { + let mut found = BTreeSet::new(); + for line in src.lines() { + let Some(arrow) = line.find("=>") else { + continue; + }; + let head = &line[..arrow]; + if !head.contains('"') { + continue; + } + let mut rest = head; + while let Some(open) = rest.find('"') { + let after = &rest[open + 1..]; + let Some(close) = after.find('"') else { break }; + let word = &after[..close]; + let mut chars = word.chars(); + if let (Some(c), None) = (chars.next(), chars.next()) { + found.insert(c.to_ascii_lowercase()); + } + rest = &after[close + 1..]; + } + } + found +} + +/// The config section a widget declares, and the keys it reads from it. +fn config_use(src: &str) -> (BTreeSet<String>, BTreeSet<String>) { + let mut sections = BTreeSet::new(); + let mut keys = BTreeSet::new(); + for line in src.lines() { + if let Some(at) = line.find("load_config(\"") { + let after = &line[at + 13..]; + if let Some(end) = after.find('"') { + sections.insert(after[..end].to_string()); + } + } + // cfg_f64(&cfg, "key", ...), cfg_str(cfg, "key", ...), and the + // direct cfg.get("key") that several widgets use for bools. + // + // The receiver matters: a bare `.get("` also matches every JSON + // lookup in the file - clocks reading its own state file, link + // parsing `ss` output, usage reading token counts - none of which + // is config. That produced 24 false failures on the first run. + for marker in ["cfg_f64(", "cfg_usize(", "cfg_str(", "cfg_strings(", "cfg.get("] { + let mut from = 0; + while let Some(at) = line[from..].find(marker) { + let start = from + at + marker.len(); + if let Some(open) = line[start..].find('"') { + let after = &line[start + open + 1..]; + if let Some(end) = after.find('"') { + let key = &after[..end]; + if !key.is_empty() + && key.chars().all(|c| c.is_ascii_lowercase() || c == '_') + { + keys.insert(key.to_string()); + } + } + } + from = start; + } + } + } + (sections, keys) +} + +/// The example config, as section -> keys. +fn example() -> BTreeMap<String, BTreeSet<String>> { + let text = std::fs::read_to_string(root().join("config.example.json")) + .expect("config.example.json"); + let parsed: serde_json::Value = serde_json::from_str(&text).expect("valid json"); + let mut out = BTreeMap::new(); + for (section, body) in parsed.as_object().expect("an object") { + if section.starts_with('_') { + continue; + } + let keys = body + .as_object() + .map(|o| o.keys().filter(|k| !k.starts_with('_')).cloned().collect()) + .unwrap_or_default(); + out.insert(section.clone(), keys); + } + out +} + +#[test] +fn every_footer_hint_names_a_key_the_widget_answers_to() { + // A hint bound to nothing is worse than a missing feature: it says the + // feature is there. This is the check that caught four shell ports. + let mut wrong = Vec::new(); + for (name, src) in widgets() { + let handled = handled_keys(&src); + for key in hinted_keys(&src) { + if !handled.contains(&key) { + wrong.push(format!("{}: [{}] is hinted, no match arm answers it", name, key)); + } + } + } + assert!(wrong.is_empty(), "\n{}", wrong.join("\n")); +} + +#[test] +fn every_footer_hint_is_in_the_widgets_doc() { + // The other direction of the same rule: a documented key that does not + // exist teaches a lie, and so does an undocumented one that works. + let mut wrong = Vec::new(); + for (name, src) in widgets() { + let doc = root().join("docs").join(format!("{}.md", name)); + let Ok(text) = std::fs::read_to_string(&doc) else { + continue; // matrix is decorative and deliberately undocumented + }; + for key in hinted_keys(&src) { + if !text.contains(&format!("`{}`", key)) { + wrong.push(format!("{}: [{}] in the footer, not in docs/{}.md", name, key, name)); + } + } + } + assert!(wrong.is_empty(), "\n{}", wrong.join("\n")); +} + +#[test] +fn every_key_a_widget_reads_is_in_the_example() { + // The direction check.py does NOT check, in either language. All + // eleven pomodoro_* keys were read by clocks.py and absent from + // config.example.json since before the port, so breaks were + // configurable the whole time and undiscoverable. CLAUDE.md asks for + // new keys to be added in the same commit; nothing was watching. + let example = example(); + let mut wrong = Vec::new(); + for (name, src) in widgets() { + let (sections, keys) = config_use(&src); + for key in keys { + let known = sections + .iter() + .any(|s| example.get(s).is_some_and(|ks| ks.contains(&key))); + if !known && !sections.is_empty() { + wrong.push(format!( + "{}: reads {:?} from {:?}, which config.example.json does not document", + name, key, sections + )); + } + } + } + assert!(wrong.is_empty(), "\n{}", wrong.join("\n")); +} + +#[test] +fn every_section_in_the_example_is_read_by_the_widget_it_names() { + // check.py's dead-key check, pointed at the Rust. A section nobody + // reads is a lie in a sample file: it invites someone to set something + // and watch nothing happen. + let example = example(); + let widgets = widgets(); + let mut wrong = Vec::new(); + for section in example.keys() { + // Sections are named for widgets, with _ where the file has -. + let stem = section.replace('_', "-"); + let Some(src) = widgets.get(section).or_else(|| widgets.get(&stem)) else { + continue; // a section for something that is not a Rust widget + }; + let (declared, _) = config_use(src); + if !declared.contains(section) { + wrong.push(format!( + "config.example.json has a {:?} section and {}.rs never calls load_config for it", + section, stem + )); + } + } + assert!(wrong.is_empty(), "\n{}", wrong.join("\n")); +} + +#[test] +fn a_poller_that_dies_records_why() { + // CLAUDE.md's central gotcha: a thread that stops takes its + // explanation with it, and an empty pane is indistinguishable from a + // source with nothing in it. Any widget that spawns a thread must have + // somewhere to put the reason. + let mut wrong = Vec::new(); + for (name, src) in widgets() { + if !src.contains("thread::spawn") { + continue; + } + let records = src.contains("err =") + || src.contains(".err =") + || src.contains("why =") + || src.contains("catch_unwind"); + if !records { + wrong.push(format!( + "{}: spawns a poll thread with nowhere to record why it stopped", + name + )); + } + } + assert!(wrong.is_empty(), "\n{}", wrong.join("\n")); +} From f5a0b27687a51e6a291b3b86f61ae43f2f6cfcc0 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Mon, 24 Aug 2026 16:14:28 +0800 Subject: [PATCH 059/147] check: see the hints that are not written [k] immediately before a letter MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The hint extractor only recognised a bracket followed straight away by a letter. Proven both ways in the tree by the other session: "[y]cloudflare" is caught, "[y] cloudflare" is not - same bogus key, same file, the only difference the character after the bracket. So every hint with a space in it was invisible - [d] cloudflare, [1] total, [2] live - as was [±]1min, whose key is not ascii, and every prose hint, which is where the control standard now puts most of them: "← or esc to close", "esc, ↵ or i to close". That last form is the one that matters: an `i` was removed as a close key an hour ago, the hint naming it stayed, and this check passed. check.py has the same lookahead at line 150 and always did, with a comment saying it is there to reject rows[0]. So the port was faithful to a limitation rather than introducing one - and check.py computes `handled` at line 146 and never uses it, so comparing hints against the code rather than only against the docs is new here. The lookahead was doing real work and could not simply go: string literals in this tree contain "[{}]", "[::1]:", "[[bin]]" and "args[0]". Four narrower rules replace it, each existing for one of those, and prose forms are read only inside a string that both separates with · and names a key unmistakably - in brackets, as a glyph, or by name. Without that second half, " {} targets · {:.1}s interval · " offers `s` as a key and "last {}d · " offers `d`. Getting there took two wrong versions, and both are worth naming because the failure mode of a checker is to be ignored. The first read every string and reported nineteen, of which one was real: it took `tab` from tab_id, `home` from XDG_STATE_HOME, `w` from a path and `9` from the format spec ↓{:>9}. The second still reported six, all from status lines that use the same separator as footers. handled_keys was also blind to most of how this tree answers a key: it threw away any arm that was not alphanumeric, so "?" and "/" read as unanswered; it read only match arms, where ports answers `f` with `if key == "f"` and `y` with `if key != "y"`; and four widgets answer digits with a guard rather than a literal. [±] is one glyph standing for two arms and is now treated as the pair it means, and the doc check accepts `↵` where the code says "enter", since the tables are written in glyphs and the footers in names. docs/deployments.md gains `esc`, which its footer has always taught and its table never listed. Two findings remain and both are in another session's uncommitted work, so they are theirs to close: deployments' footer names `i` after the key was removed - at HEAD it is still handled, so this is a live regression caught before it lands - and tailnet's footer teaches `esc` where its doc does not list it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- docs/deployments.md | 1 + rust/widgets/tests/check.rs | 159 ++++++++++++++++++++++++++++++------ 2 files changed, 133 insertions(+), 27 deletions(-) diff --git a/docs/deployments.md b/docs/deployments.md index e987e6c..70322f3 100644 --- a/docs/deployments.md +++ b/docs/deployments.md @@ -82,6 +82,7 @@ OSC 52 is blocked. | `↑` `↓` `PgUp` `PgDn` `Home` `End` | move the selection | | `Enter` / `i` / `c` | full detail view for the selected deployment | | `1`–`7` | inside the view, copy that item | +| `esc` | close the detail view | | `f` | filter — all / failed / production | | `p` | cycle which project is shown | | `r` | refresh now | diff --git a/rust/widgets/tests/check.rs b/rust/widgets/tests/check.rs index cf6bc17..f4fc5e0 100644 --- a/rust/widgets/tests/check.rs +++ b/rust/widgets/tests/check.rs @@ -78,58 +78,145 @@ fn widgets() -> BTreeMap<String, String> { /// Deliberately crude: it is looking for `[w]indow`, and a hint never /// spans a line. Parsing Rust properly to find a footer would be a much /// larger thing that failed in more interesting ways. -fn string_literals(src: &str) -> String { - let mut out = String::new(); +fn string_lines(src: &str) -> Vec<String> { + let mut out = Vec::new(); for line in src.lines() { + let mut found = String::new(); let mut rest = line; while let Some(open) = rest.find('"') { let after = &rest[open + 1..]; match after.find('"') { Some(close) => { - out.push_str(&after[..close]); - out.push(' '); + found.push_str(&after[..close]); + found.push(' '); rest = &after[close + 1..]; } None => break, } } + if !found.trim().is_empty() { + out.push(found); + } } out } -/// The keys a footer hint teaches: `[w]indow`, `[r]efresh`. +/// The glyphs a hint uses instead of a name, and what they answer to. +/// +/// The control standard leans on these four, so a hint that names a key +/// only as an arrow or a return symbol is still a hint teaching a key. +const GLYPHS: &[(char, &str)] = &[ + ('\u{21b5}', "enter"), // ↵ + ('\u{2192}', "right"), // → + ('\u{2190}', "left"), // ← + ('\u{2191}', "up"), // ↑ + ('\u{2193}', "down"), // ↓ +]; + +/// Named keys that appear in prose: "esc, ↵ or i to close". +const NAMED: &[&str] = &["esc", "tab", "enter", "backspace", "pgup", "pgdn", "home", "end"]; + +/// The keys a hint teaches, in any of the forms this tree writes them. +/// +/// `[w]indow` and `[d] cloudflare` and `[±]1min` and `↵ starts one` and +/// `esc, ↵ or i to close` are all hints; `"[{}]"`, `"[::1]:"`, `"[[bin]]"` +/// and `"args[0]"` are all strings that merely contain brackets. The +/// separation is four rules, each of which exists for one of those: +/// +/// - exactly one character between the brackets - kills `[::1]` and `[[bin]]` +/// - that character is not `{` - kills the format placeholder `[{}]` +/// - the character before `[` is not alphanumeric - kills `args[0]` +/// - the character after `]` is not `.` or `(` - kills `][0].as_str()` /// -/// The bracket must be followed immediately by a letter, which is what -/// separates a hint from an index like `rows[0]` or a closure parameter. -fn hinted_keys(src: &str) -> BTreeSet<char> { - let text = string_literals(src); - let bytes: Vec<char> = text.chars().collect(); +/// An earlier version required a letter immediately after `]`, which threw +/// away every hint with a space in it. +fn hinted_keys(src: &str) -> BTreeSet<String> { let mut found = BTreeSet::new(); - for i in 0..bytes.len().saturating_sub(3) { - if bytes[i] == '[' - && (bytes[i + 1].is_ascii_lowercase() || bytes[i + 1].is_ascii_digit()) - && bytes[i + 2] == ']' - && bytes[i + 3].is_ascii_alphabetic() - { - found.insert(bytes[i + 1]); + for text in string_lines(src) { + let chars: Vec<char> = text.chars().collect(); + // A footer separates its hints with `·` AND names at least one key + // unmistakably - in brackets, as a glyph, or by name. The + // separator alone is not enough: status lines use it too, and + // " {} targets · {:.1}s interval · " would otherwise offer `s` as + // a key, and "last {}d · " would offer `d`. + let names_a_key = text.contains('[') + || GLYPHS.iter().any(|(g, _)| text.contains(*g)) + || NAMED.iter().any(|n| { + text.to_lowercase() + .split(|c: char| !c.is_ascii_alphabetic()) + .any(|w| w == *n) + }); + let is_footer = text.contains('\u{b7}') && names_a_key; + for i in 0..chars.len() { + if chars[i] == '[' && i + 2 < chars.len() && chars[i + 2] == ']' { + let key = chars[i + 1]; + let before_ok = i == 0 || !chars[i - 1].is_ascii_alphanumeric(); + let after_ok = chars + .get(i + 3) + .is_none_or(|c| *c != '.' && *c != '(' && *c != '['); + if key != '{' && before_ok && after_ok { + match GLYPHS.iter().find(|(g, _)| *g == key) { + // [↵] means the same as a bare ↵. + Some((_, name)) => { + found.insert((*name).to_string()); + } + // [±] is one glyph standing for a pair of arms, + // "+" | "=" and "-" | "_". clocks writes it that + // way because the footer has room for one hint and + // the widget has two keys. + None if key == '\u{b1}' => { + found.insert("+".into()); + found.insert("-".into()); + } + None => { + found.insert(key.to_lowercase().to_string()); + } + } + } + } + if is_footer { + if let Some((_, name)) = GLYPHS.iter().find(|(g, _)| *g == chars[i]) { + found.insert((*name).to_string()); + } + } + } + // A key named in prose - "esc, ↵ or i to close" - counts only in a + // footer. This is the form that matters most: it is where the + // control standard puts its hints, and a key removed while its + // prose hint stayed is exactly what this check is for. + if is_footer { + let lowered = text.to_lowercase(); + for word in lowered.split(|c: char| !c.is_ascii_alphanumeric()) { + if NAMED.contains(&word) || word.chars().count() == 1 { + found.insert(word.to_string()); + } + } } } + found.remove(""); found } -/// The keys a match arm answers to. +/// The keys a match arm answers to, single characters and named alike. /// /// Case-insensitive on purpose: arms read `"q" | "Q"`, and a pattern that /// only matched lowercase would fail the whole alternation on the -/// uppercase half - which is exactly the bug that made the first draft of -/// this check report 48 failures against widgets that were all correct. -fn handled_keys(src: &str) -> BTreeSet<char> { +/// uppercase half - which is exactly the bug that made an earlier hand-run +/// of this rule report 48 failures against widgets that were all correct. +fn handled_keys(src: &str) -> BTreeSet<String> { let mut found = BTreeSet::new(); for line in src.lines() { - let Some(arrow) = line.find("=>") else { + if line.trim_start().starts_with("//") { continue; + } + // A match arm, up to its =>; or a comparison anywhere on the line. + // ports answers `f` with `if key == "f"` and `y` with + // `if key != "y"`, and neither is an arm. + let head = match line.find("=>") { + Some(at) => &line[..at], + None if line.contains("key ==") || line.contains("key !=") => line, + None => continue, }; - let head = &line[..arrow]; if !head.contains('"') { continue; } @@ -138,13 +225,22 @@ fn handled_keys(src: &str) -> BTreeSet<char> { let after = &rest[open + 1..]; let Some(close) = after.find('"') else { break }; let word = &after[..close]; - let mut chars = word.chars(); - if let (Some(c), None) = (chars.next(), chars.next()) { - found.insert(c.to_ascii_lowercase()); + // Any single character counts, punctuation included: "?" and + // "/" are real keys. Longer words count when they name one. + let single = word.chars().count() == 1; + if single || word.chars().all(|c| c.is_ascii_alphabetic()) { + found.insert(word.to_lowercase()); } rest = &after[close + 1..]; } } + // A guard rather than a literal: `digit if digit.chars().all(is_ascii_digit)` + // answers every digit and leaves no "1" to find. + if src.contains("is_ascii_digit()") && src.contains(" if ") { + for d in '0'..='9' { + found.insert(d.to_string()); + } + } found } @@ -234,7 +330,16 @@ fn every_footer_hint_is_in_the_widgets_doc() { continue; // matrix is decorative and deliberately undocumented }; for key in hinted_keys(&src) { - if !text.contains(&format!("`{}`", key)) { + // The docs write these as the glyph, the footers as the name: + // a table row reads `↵` where the code answers to "enter". + // Either spelling documents the key. + let glyph = GLYPHS + .iter() + .find(|(_, n)| *n == key) + .map(|(g, _)| format!("`{}`", g)); + let documented = text.contains(&format!("`{}`", key)) + || glyph.is_some_and(|g| text.contains(&g)); + if !documented { wrong.push(format!("{}: [{}] in the footer, not in docs/{}.md", name, key, name)); } } From bc9ca571720682ee23c7eb1aff50c390254a06b7 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Mon, 24 Aug 2026 16:28:29 +0800 Subject: [PATCH 060/147] widgets: one way in and one way out, everywhere Seven widgets had a drill-in view and no two agreed on how to reach it. i opened one in three of them, c opened another, enter alone opened two, and coming back was esc, or backspace, or q, or enter again, depending on which pane you were looking at. Now it is right or enter in, left or esc out, in all seven, and nothing spends a letter on it. q quits from inside a detail view. It used to close the overlay in four of them while the footer beside it read [q]uit - the key disagreed with its own hint, and the failure is quiet: the widget stays up, so it reads as a key that does nothing to a screen you are trying to leave. That cost an hour here, from the other side. A restart command typed into a pane whose widget had not quit went nowhere, the pane kept drawing the old binary, and a fix that worked looked broken until the process start time was compared against the source. backspace is gone from two of them: an alias no footer ever named. pr needed care. Inside its detail, enter walks the stack, so right drills further in there rather than closing, and left only acts when a detail is open - esc keeps its second job of clearing the search, which left has no business doing. usage is deliberately untouched. Its left and right move between vendor tabs, which is lateral rather than into anything, and binding them to a drill-in it does not have would be the same mistake in reverse. herdr-panes keeps enter for switching to a pane, which is an action and not a view. Every footer now names the keys it answers to and no others: right/enter details in the list, left/esc back in the detail. The widget docs match. One hint promised i to close after i had stopped closing - the same shape of drift, one widget over, in this same change - and the Rust check caught it before it landed rather than a person catching it on screen. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- docs/deployments.md | 4 ++-- docs/tailnet.md | 3 ++- rust/widgets/src/bin/deployments.rs | 17 +++++++++++++---- rust/widgets/src/bin/link.rs | 4 ++-- rust/widgets/src/bin/netwatch.rs | 22 ++++++++++++++++++---- rust/widgets/src/bin/ports.rs | 22 ++++++++++++++++++---- rust/widgets/src/bin/pr.rs | 23 +++++++++++++++++++++-- rust/widgets/src/bin/start.rs | 4 ++-- rust/widgets/src/bin/tailnet.rs | 27 ++++++++++++++++++++------- rust/widgets/src/bin/tailnet_help.txt | 3 ++- 10 files changed, 100 insertions(+), 29 deletions(-) diff --git a/docs/deployments.md b/docs/deployments.md index 70322f3..59a7d2e 100644 --- a/docs/deployments.md +++ b/docs/deployments.md @@ -80,9 +80,9 @@ OSC 52 is blocked. | Key | Action | |---|---| | `↑` `↓` `PgUp` `PgDn` `Home` `End` | move the selection | -| `Enter` / `i` / `c` | full detail view for the selected deployment | +| `→` / `Enter` | full detail view for the selected deployment | | `1`–`7` | inside the view, copy that item | -| `esc` | close the detail view | +| `←` / `esc` | close the detail view | | `f` | filter — all / failed / production | | `p` | cycle which project is shown | | `r` | refresh now | diff --git a/docs/tailnet.md b/docs/tailnet.md index 472c0e5..af20084 100644 --- a/docs/tailnet.md +++ b/docs/tailnet.md @@ -93,7 +93,8 @@ advertises wins over a docker or virtual bridge: a NAS was otherwise reporting | Key | Action | |---|---| | `↑` `↓` | select a peer | -| `Enter` / `i` | machine info view | +| `→` / `Enter` | machine info view — `i` in the Python, which is being retired | +| `←` / `esc` | back out of the info or copy view | | `c` | copy addresses | | `g` | show/hide the live throughput graphs | | `o` | hide offline peers | diff --git a/rust/widgets/src/bin/deployments.rs b/rust/widgets/src/bin/deployments.rs index 43b5cab..6272047 100644 --- a/rust/widgets/src/bin/deployments.rs +++ b/rust/widgets/src/bin/deployments.rs @@ -532,7 +532,7 @@ fn info_overlay( rows.push(tc::seg( &[( p.hint.as_str(), - format!(" press 1-{} to copy · esc or i to close", pairs.len()), + format!(" press 1-{} to copy · ← or esc to close", pairs.len()), )], w - 1, )); @@ -711,7 +711,16 @@ fn main() { for key in keyboard.poll() { if overlay { match key.as_str() { - "esc" | "c" | "i" | "q" | "Q" | "enter" => overlay = false, + // Left and esc come out. q quits outright, which is + // what the footer has always promised and what it + // does from the list - it used to close the overlay + // instead, so the key disagreed with its own hint. + "left" | "esc" => overlay = false, + "q" | "Q" => { + keyboard.restore(); + tc::restore_screen(); + return; + } digit if digit.len() == 1 && digit.chars().all(|c| c.is_ascii_digit()) => { if let Some(chosen) = shown.get(selected.min(shown.len().saturating_sub(1))) { @@ -759,7 +768,7 @@ fn main() { "pgdn" => selected += visible, "home" => selected = 0, "end" => selected = shown.len().saturating_sub(1), - "c" | "i" | "I" | "enter" => { + "right" | "enter" => { if !shown.is_empty() { overlay = true; note = (String::new(), 0.0); @@ -1068,7 +1077,7 @@ fn main() { let hints: Vec<Vec<(&str, String)>> = vec![ vec![(p.accent.as_str(), "↑↓".into()), (p.dim.as_str(), " select".into())], vec![ - (p.accent.as_str(), "↵/[i]".into()), + (p.accent.as_str(), "→/↵".into()), (p.dim.as_str(), " details".into()), ], vec![(p.dim.as_str(), "[f]ilter".into())], diff --git a/rust/widgets/src/bin/link.rs b/rust/widgets/src/bin/link.rs index 5851d04..6471dff 100644 --- a/rust/widgets/src/bin/link.rs +++ b/rust/widgets/src/bin/link.rs @@ -569,7 +569,7 @@ fn main() { // Right goes in and left comes back out, the way a column // of panes works, so the hand does not have to learn a key // for it. Enter and esc still do the same two things. - "right" | "enter" | "i" | "I" if !detail => { + "right" | "enter" if !detail => { // Opening with nothing selected takes the first row // rather than doing nothing, which would be a key that // the footer offers and that does not answer. @@ -579,7 +579,7 @@ fn main() { detail = selected.is_some(); scroll = 0; } - "left" | "esc" | "enter" | "i" | "I" if detail => { + "left" | "esc" if detail => { detail = false; scroll = 0; } diff --git a/rust/widgets/src/bin/netwatch.rs b/rust/widgets/src/bin/netwatch.rs index 1917604..239033a 100644 --- a/rust/widgets/src/bin/netwatch.rs +++ b/rust/widgets/src/bin/netwatch.rs @@ -1531,10 +1531,18 @@ fn main() { for key in keyboard.poll() { if detail.is_some() { match key.as_str() { - "esc" | "left" | "q" | "Q" | "backspace" => { + // Left and esc come out; q quits, which is what the + // footer beside it says and what q does everywhere + // else. backspace is gone: an alias no hint named. + "esc" | "left" => { detail = None; sizes.clear(); } + "q" | "Q" => { + keyboard.restore(); + tc::restore_screen(); + return; + } "r" | "R" => { if let Ok(mut guard) = state.lock() { guard.totals.clear(); @@ -1588,7 +1596,7 @@ fn main() { } "up" | "k" | "K" => selected = selected.saturating_sub(1), "down" | "j" | "J" => selected += 1, - "enter" | "right" | "i" | "I" => { + "enter" | "right" => { if let Some(pick) = ordered(&state, mine, sort_live).get(selected) { detail = Some((pick.pid, pick.name.clone())); focus = 0; @@ -1677,7 +1685,10 @@ fn main() { vec![(p.accent.as_str(), "tab".into()), (p.dim.as_str(), " section".into())], vec![(p.dim.as_str(), "[c]opy".into())], vec![(p.dim.as_str(), "[r]ezero".into())], - vec![(p.accent.as_str(), "esc".into()), (p.dim.as_str(), " back".into())], + vec![ + (p.accent.as_str(), "←".into()), + (p.dim.as_str(), "/esc back".into()), + ], vec![(p.dim.as_str(), "[q]uit".into())], ]; let mut foot: Vec<String> = tc::pack_hints(&hints, w - 2, " ") @@ -1846,7 +1857,10 @@ fn main() { let hints: Vec<Vec<(&str, String)>> = vec![ vec![(p.accent.as_str(), "↑↓".into()), (p.dim.as_str(), " select".into())], - vec![(p.accent.as_str(), "↵".into()), (p.dim.as_str(), " details".into())], + vec![ + (p.accent.as_str(), "→/↵".into()), + (p.dim.as_str(), " details".into()), + ], vec![( if sort_live { &p.dim } else { &p.accent }, "[1] total".into(), diff --git a/rust/widgets/src/bin/ports.rs b/rust/widgets/src/bin/ports.rs index 5b59b19..89b56f9 100644 --- a/rust/widgets/src/bin/ports.rs +++ b/rust/widgets/src/bin/ports.rs @@ -1807,9 +1807,17 @@ fn main() { // rather than rows - and hands every other key back. if let Some(view) = detail.as_mut() { match key.as_str() { - "esc" | "left" | "q" | "Q" | "backspace" => { + // Left and esc come out; q quits, which is what the + // footer beside it says and what q does everywhere + // else. backspace is gone: an alias no hint named. + "esc" | "left" => { detail = None; } + "q" | "Q" => { + keyboard.restore(); + tc::restore_screen(); + return; + } "up" => view.at = view.at.saturating_sub(1), "down" => view.at += 1, "c" | "C" => { @@ -1877,7 +1885,7 @@ fn main() { "down" => selected += 1, "o" | "O" => hide_system = !hide_system, "r" | "R" => store.wake(), - "enter" | "right" | "i" | "I" => { + "enter" | "right" => { let all: Vec<Row> = store.rows.lock().map(|g| g.clone()).unwrap_or_default(); let shown: Vec<Row> = all .into_iter() @@ -1980,7 +1988,10 @@ fn main() { vec![(ok.dim.clone(), "[s]erve".into())], vec![(ok.dim.clone(), "[t]unnel".into())], vec![(ok.dim.clone(), "[d] cloudflare".into())], - vec![(ok.accent.clone(), "esc".into()), (ok.dim.clone(), " back".into())], + vec![ + (ok.accent.clone(), "←".into()), + (ok.dim.clone(), "/esc back".into()), + ], ], &ok, ); @@ -2122,7 +2133,10 @@ fn main() { w, &[ vec![(ok.accent.clone(), "↑↓".into()), (ok.dim.clone(), " select".into())], - vec![(ok.accent.clone(), "↵".into()), (ok.dim.clone(), " details".into())], + vec![ + (ok.accent.clone(), "→/↵".into()), + (ok.dim.clone(), " details".into()), + ], vec![(ok.dim.clone(), "[k]ill".into())], vec![( ok.dim.clone(), diff --git a/rust/widgets/src/bin/pr.rs b/rust/widgets/src/bin/pr.rs index 3c60fde..d41b771 100644 --- a/rust/widgets/src/bin/pr.rs +++ b/rust/widgets/src/bin/pr.rs @@ -800,6 +800,20 @@ fn main() { return; } "/" => typing = true, + // Left comes out of the detail the way it does everywhere + // else. esc keeps its second job of clearing the search when + // there is no detail open; left has no business doing that, + // so it only acts when there is something to come out of. + "left" if detail.is_some() || loading => { + if let Ok(mut g) = state.lock() { + g.want = None; + g.detail = None; + g.stack_rows.clear(); + g.loading = false; + g.stages.clear(); + } + stack_sel = 0; + } "esc" => { if detail.is_some() || loading { if let Ok(mut g) = state.lock() { @@ -814,7 +828,9 @@ fn main() { needle.clear(); } } - "enter" => { + // Right and enter both go in - and from inside the stack, + // in again, onto the PR under the cursor. + "right" | "enter" => { if let Some(open) = &detail { if !stack_rows.is_empty() { // Walk the stack from inside it: the row under @@ -983,7 +999,10 @@ fn main() { hints.push(vec![(p.dim.as_str(), "[↵] open it".into())]); } hints.push(vec![(p.dim.as_str(), "[c]opy url".into())]); - hints.push(vec![(p.dim.as_str(), "[esc] back".into())]); + hints.push(vec![ + (p.accent.as_str(), "←".into()), + (p.dim.as_str(), "/[esc] back".into()), + ]); hints.push(vec![(p.dim.as_str(), "[r]efresh".into())]); hints.push(vec![(p.dim.as_str(), "[q]uit".into())]); hints diff --git a/rust/widgets/src/bin/start.rs b/rust/widgets/src/bin/start.rs index b9f8d83..8f3f2ac 100644 --- a/rust/widgets/src/bin/start.rs +++ b/rust/widgets/src/bin/start.rs @@ -332,7 +332,7 @@ fn main() { } "up" | "k" | "K" => selected = selected.saturating_sub(1), "down" | "j" | "J" => selected += 1, - "enter" | "right" | "i" | "I" => { + "enter" | "right" => { run_widget(&mut keyboard, WIDGETS[selected.min(WIDGETS.len() - 1)].stem) } _ => {} @@ -348,7 +348,7 @@ fn main() { body.push(tc::seg( &[( p.dim.as_str(), - format!(" {} widgets ↵ starts one, q leaves", WIDGETS.len()), + format!(" {} widgets ↵ or → starts one, q leaves", WIDGETS.len()), )], w - 1, )); diff --git a/rust/widgets/src/bin/tailnet.rs b/rust/widgets/src/bin/tailnet.rs index 754bbbe..ca2fc9d 100644 --- a/rust/widgets/src/bin/tailnet.rs +++ b/rust/widgets/src/bin/tailnet.rs @@ -709,9 +709,19 @@ fn main() { for key in keyboard.poll() { if view.is_some() { match key.as_str() { - "esc" | "q" | "Q" => view = None, - "i" | "I" | "enter" => { - view = if view != Some("info") { Some("info") } else { None } + // Left comes back out, the way it does everywhere + // else: right and enter go in, left and esc come + // out, and no widget needs a letter of its own for + // it. `i` used to open this and no longer does. + "left" | "esc" => view = None, + // q quits from here too. It used to close the view + // instead, which is its own kind of trap: the key + // appears to do nothing to a widget you are trying + // to leave, and every other widget quits on it. + "q" | "Q" => { + keyboard.restore(); + tc::restore_screen(); + return; } "c" | "C" => view = if view != Some("copy") { Some("copy") } else { None }, digit @@ -769,7 +779,7 @@ fn main() { note = (String::new(), 0.0); } } - "i" | "I" | "enter" => { + "right" | "enter" => { if !listed.is_empty() { view = Some("info"); } @@ -1096,7 +1106,10 @@ fn main() { } let hints: Vec<Vec<(&str, String)>> = vec![ vec![(p.accent.as_str(), "↑↓".into()), (p.dim.as_str(), " select".into())], - vec![(p.dim.as_str(), "↵/[i]nfo".into())], + vec![ + (p.accent.as_str(), "→".into()), + (p.dim.as_str(), "/↵ info".into()), + ], vec![(p.dim.as_str(), "[c]opy".into())], vec![(p.dim.as_str(), "[g]raph".into())], vec![(p.dim.as_str(), "[o]ffline".into())], @@ -1441,7 +1454,7 @@ fn info_overlay( rows.push(String::new()); } rows.push(tc::seg( - &[(p.dim.as_str(), " [c]opy addresses · esc, ↵ or i to close".into())], + &[(p.dim.as_str(), " [c]opy addresses · ← or esc to close".into())], w - 1, )); rows @@ -1491,7 +1504,7 @@ fn copy_overlay( &[( p.dim.as_str(), format!( - " press 1-{} to copy · esc or c to close", + " press 1-{} to copy · ← or esc to close", pairs.len().max(1) ), )], diff --git a/rust/widgets/src/bin/tailnet_help.txt b/rust/widgets/src/bin/tailnet_help.txt index 31caf21..345691d 100644 --- a/rust/widgets/src/bin/tailnet_help.txt +++ b/rust/widgets/src/bin/tailnet_help.txt @@ -29,7 +29,8 @@ n cycles the poll interval while running (1/2/5/10/30s), the same way the latency monitor's i key does; the graph resolution follows it. -n sets the starting value, and `tailnet.refresh` in config.json sets the default. -Keys: up/down select a peer, Enter or i opens a full machine info view (every address, +Keys: up/down select a peer, right or Enter opens a full machine info view and left +comes back out (every address, routes, tags, owner, handshake times), c or Enter opens a copy sheet offering its Tailscale IP, MagicDNS name, public IP and LAN IP, r refreshes now, o hides offline peers, q quits. Copying uses OSC 52, so it reaches the clipboard of From f89d14c1b5de461a84dffcb2c045d506070559dd Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Mon, 24 Aug 2026 16:28:45 +0800 Subject: [PATCH 061/147] docs: the checks to run are the Rust ones now "Before you commit" said to run python3 check.py, which checks the Python and cannot see a Rust widget at all. cargo test from rust/ leads instead: it runs each widget's own tests plus widgets/tests/check.rs, which reads the sources for the things the compiler cannot - a poller that dies without recording why, a footer hint naming a key nothing answers, a hint missing from the widget's doc, a config key read but never put in the example, and a section in the example nothing reads. The Python line stays while check.py does. It covers the same ground for *.py and adds unbound names, which the Rust compiler makes impossible. What the hint reader can and cannot see is written down beside it, because both halves have been wrong. It reads [k] wherever it falls, the glyphs, the named keys, and a bare letter inside a footer; it cannot see a key named in prose outside a footer, or one answered by neither a match arm nor a key comparison. Three versions of that check cried wolf in a single day, so the note says plainly that a green run is not proof and a red one is worth reading before it is believed - a checker nobody trusts gets turned off, which is worse than not having one. The README gains the same in a sentence, next to what common.py holds. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- AGENTS.md | 38 +++++++++++++++++++++++++++++--------- README.md | 7 +++++++ 2 files changed, 36 insertions(+), 9 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a0b700d..672aeae 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -50,15 +50,35 @@ than faked. `matrix.py` is the sole exception and computes nothing on purpose. ## Before you commit -Run `python3 check.py`. It checks the things `compile()` cannot, and every -check in it exists because something shipped broken and looked, on screen, -exactly like "there is no data": - -- **unbound names** — a missing import only raises when the line runs, and in a - poll thread that means silence; -- **unguarded pollers** — a daemon thread that raises simply stops; -- **dead config keys** — a key in the example no widget reads; -- **missing docs / README rows**, and **footer keys absent from the doc**. +Run `cargo test` from `rust/`. Alongside each widget's own tests it runs +`widgets/tests/check.rs`, which checks the things the compiler cannot, and +every check in it exists because something shipped broken and looked, on +screen, exactly like "there is no data": + +- **a poller that dies without recording why** — a thread that stops is + invisible, and the pane it feeds is indistinguishable from a quiet source; +- **a footer hint naming a key no match arm answers** — a hint bound to + nothing says the feature is there; +- **a footer hint missing from the widget's doc**; +- **a config key a widget reads that is not in `config.example.json`** — an + undiscoverable setting is not a setting; +- **a section in the example no widget reads**. + +The hint reader sees `[k]` wherever it falls, four rules keeping `[{}]`, +`[::1]`, `[[bin]]` and `args[0]` out; the glyphs `↵ → ← ↑ ↓`; the names +`esc tab enter backspace pgup pgdn home end`; and, inside a footer, a bare +single letter — which is what catches `or i to close`. On the other side it +reads match arms and `key ==` / `key !=` comparisons alike. + +What it still cannot see: a key named in prose in a string that is not a +footer, and a key answered anywhere other than those two forms. Both halves +have been wrong before — three versions of this check cried wolf in one day, +and a checker that cries wolf gets turned off — so when it fires, read the +flag before believing it, and when it is quiet, that is not proof. + +The Python keeps `python3 check.py` while it exists; it covers the same +ground for `*.py`, plus unbound names, which the Rust compiler makes +impossible. ## Gotchas paid for already diff --git a/README.md b/README.md index bcff5a9..85e08ce 100644 --- a/README.md +++ b/README.md @@ -161,6 +161,13 @@ was learned building these against Herdr: resize semantics, focus, detecting what a pane is running, notification gating, and the layout mistakes worth skipping. +Both implementations are checked the same way. `cargo test` from `rust/` runs +each widget's tests plus `widgets/tests/check.rs`, which reads the sources and +fails on a poller that dies without saying why, a footer hint naming a key +nothing answers, a hint missing from the widget's doc, and a config key read +but never documented in `config.example.json`. `python3 check.py` covers the +same ground for the Python. + `common.py` holds the shared pieces — terminal sizing, a full-frame `draw()`, 24-bit colour, a green→amber→red `heat()` ramp, `seg()` for clipping coloured text to a cell budget, `pack_hints()` for wrapping footers, non-blocking From d6d2688fc0e54c3da8f5e76153f22745931b6f3a Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Mon, 24 Aug 2026 17:14:15 +0800 Subject: [PATCH 062/147] port: the review findings that were real, and three tests that were not Wrong on screen, all three from the outside review: pr called a hook-gated PR "checking" in dim. HAS_HOOKS means a merge queue or a required hook stands between the branch and the button - the PR itself is mergeable, and pr.py has always called it ready. "Checking" reads as not finished yet, which is the opposite. Drafts were worse: DRAFT had no case at all and fell through to the em-dash, so a draft was indistinguishable from a PR whose state GitHub had not sent. deployments coloured INITIALIZING as building. It is the state before the build starts, which is why deployments.py groups it with the queue. Two panes showed the same deployment in two colours. github carried on with an empty login when the GraphQL envelope was an errors payload: `.as_str().unwrap_or("")`. Every query after it silently scoped to nobody, and the screen filled with nothing rather than with a reason. Unreadable rendered as empty is the one failure this collection exists to prevent, so the pass now stops and says which error it got. toys-core's missing() checked is_file() where shutil.which, which the Python uses, also requires the executable bit. A readable non-executable of the right name on PATH counted as the tool being there, so a widget would start and then fail on every call rather than saying up front what it needs. Three tests asserted a copy of the code rather than the code: linear's team filter lived as a closure inside one_pass, reachable only through a live token and a network round trip, so its test wrote the filter out again in the test body. It is a free function now, and the test covers the case the copy could not get wrong: a team that is both named and excluded is still counted. herdr-panes re-implemented the /proc/<pid>/stat parse inline and asserted on that. The parse is split from the read, so a line can be handed to the shipped function; the test also pins that a truncated line yields nothing rather than a guess. usage sorted a vector built in the test with a comparator written in the test. The real ordering ranks provider groups by their worst lane, which a flat sort by percentage gets wrong as soon as one provider has several: the test now has a provider with three middling lanes ranking below one with a single bad one. Each was checked by breaking the code it names and watching it fail. Two findings from that list are not fixed, on purpose. The fourth test, clocks' advance-key labels, calls the shipped function and does catch a break - confirmed by breaking it - and its only fault was pinning wording that would have to change if the two implementations were aligned, which is moot now. And pr reading its token once before the poll loop is not the bug it was filed as: the Python re-reads per poll, but from a module-level config loaded once and from an environment a running process cannot have changed, so a rotated token needs a restart in both. github.rs does the same thing for the same reason. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- rust/core/src/lib.rs | 38 +++++++++++++++++++++++ rust/widgets/src/bin/deployments.rs | 7 ++++- rust/widgets/src/bin/github.rs | 18 ++++++++--- rust/widgets/src/bin/herdr-panes.rs | 29 ++++++++++++------ rust/widgets/src/bin/linear.rs | 41 ++++++++++++++----------- rust/widgets/src/bin/pr.rs | 10 +++++- rust/widgets/src/bin/usage/vendors.rs | 44 ++++++++++++++++++++------- 7 files changed, 142 insertions(+), 45 deletions(-) diff --git a/rust/core/src/lib.rs b/rust/core/src/lib.rs index f906eb7..b8b48f2 100644 --- a/rust/core/src/lib.rs +++ b/rust/core/src/lib.rs @@ -22,6 +22,7 @@ //! Python behaviour rather than the more idiomatic Rust one. use std::io::{Read, Write}; +use std::os::unix::fs::PermissionsExt; use std::os::fd::AsRawFd; pub const HIDE: &str = "\x1b[?25l"; @@ -775,7 +776,16 @@ pub fn missing(programs: &[&str]) -> Vec<String> { .filter(|p| { !path.split(':').any(|dir| { let candidate = std::path::Path::new(dir).join(p); + // `is_file` is not enough: shutil.which, which the Python + // uses, also requires the executable bit. A readable but + // non-executable file of the right name on PATH would + // otherwise count as the tool being present, and the widget + // would start and then fail on every call instead of saying + // up front what it needs. candidate.is_file() + && std::fs::metadata(&candidate) + .map(|m| m.permissions().mode() & 0o111 != 0) + .unwrap_or(false) }) }) .map(|p| p.to_string()) @@ -1096,6 +1106,34 @@ pub fn maybe_help(doc: &str) { mod tests { use super::*; + #[test] + fn a_file_without_the_executable_bit_is_still_missing() { + // shutil.which, which the Python uses, requires the bit. Checking + // only is_file() would let a readable non-executable of the right + // name count as the tool, so the widget would start and then fail + // on every call rather than saying up front what it needs. + let dir = std::env::temp_dir().join(format!("toys-missing-{}", std::process::id())); + std::fs::create_dir_all(&dir).unwrap(); + let tool = dir.join("definitely-not-a-real-tool"); + std::fs::write(&tool, "#!/bin/sh\n").unwrap(); + + let held = std::env::var("PATH").unwrap_or_default(); + std::env::set_var("PATH", dir.to_string_lossy().to_string()); + + std::fs::set_permissions(&tool, std::fs::Permissions::from_mode(0o644)).unwrap(); + let not_executable = missing(&["definitely-not-a-real-tool"]); + + std::fs::set_permissions(&tool, std::fs::Permissions::from_mode(0o755)).unwrap(); + let executable = missing(&["definitely-not-a-real-tool"]); + + std::env::set_var("PATH", held); + let _ = std::fs::remove_dir_all(&dir); + + assert_eq!(not_executable, vec!["definitely-not-a-real-tool"], "0644 counted as present"); + assert!(executable.is_empty(), "0755 was not found: {:?}", executable); + } + + #[test] fn a_query_survives_its_own_newlines() { // A GraphQL query is several lines. Unescaped, curl's config parser diff --git a/rust/widgets/src/bin/deployments.rs b/rust/widgets/src/bin/deployments.rs index 6272047..5e55e35 100644 --- a/rust/widgets/src/bin/deployments.rs +++ b/rust/widgets/src/bin/deployments.rs @@ -326,7 +326,12 @@ fn palette() -> Palette { fn state_colour<'a>(state: &str, p: &'a Palette) -> &'a str { match state { "READY" => &p.ready, - "BUILDING" | "INITIALIZING" => &p.build, + "BUILDING" => &p.build, + // Initializing is before the build starts, which is why + // deployments.py groups it with the queue rather than the build. + // Grouping it with BUILDING put the two panes on different colours + // for the same state. + "INITIALIZING" => &p.queue, "ERROR" => &p.error, "QUEUED" => &p.queue, "CANCELED" => &p.cancel, diff --git a/rust/widgets/src/bin/github.rs b/rust/widgets/src/bin/github.rs index 473d443..6bbac81 100644 --- a/rust/widgets/src/bin/github.rs +++ b/rust/widgets/src/bin/github.rs @@ -416,10 +416,20 @@ fn one_pass( ) -> Result<(), String> { if viewer.is_empty() { let who = graphql("{ viewer { login } }", tok, scopes)?; - *viewer = who["data"]["viewer"]["login"] - .as_str() - .unwrap_or("") - .to_string(); + // An errors envelope has no data.viewer, and `unwrap_or("")` turned + // that into an empty login the pass then carried on with - every + // query after it silently scoped to nobody. Unreadable rendered as + // empty is the one failure this collection exists to avoid, so the + // pass stops and says why, which is what github.py does. + *viewer = match who["data"]["viewer"]["login"].as_str() { + Some(login) if !login.is_empty() => login.to_string(), + _ => { + let why = who["errors"][0]["message"] + .as_str() + .unwrap_or("no viewer login in the response"); + return Err(format!("who am I: {}", &why[..why.len().min(50)])); + } + }; } let mut accounts = state.lock().map(|g| g.accounts.clone()).unwrap_or_default(); if accounts.is_empty() { diff --git a/rust/widgets/src/bin/herdr-panes.rs b/rust/widgets/src/bin/herdr-panes.rs index 939d7c3..691f670 100644 --- a/rust/widgets/src/bin/herdr-panes.rs +++ b/rust/widgets/src/bin/herdr-panes.rs @@ -103,11 +103,14 @@ fn command_label(argv: &[String], name: &str) -> String { head } -/// (cpu ticks used, resident bytes) for a pid. -fn proc_stats(pid: i32) -> Option<(u64, u64)> { - let text = std::fs::read_to_string(format!("/proc/{}/stat", pid)).ok()?; - // The command is in brackets and may itself contain spaces, so the split - // starts after the last one rather than at the second field. +/// (cpu ticks used, resident bytes) out of one /proc/<pid>/stat line. +/// +/// Split from the read so it can be tested on a line rather than on a live +/// process. Its test used to re-implement this parse in the test body and +/// assert on the copy, which meant the shipped one was never run. +fn parse_proc_stat(text: &str) -> Option<(u64, u64)> { + // The command is in brackets and may itself contain spaces and brackets, + // so the split starts after the last one rather than at the second field. let rest = text.rsplit_once(')')?.1; let fields: Vec<&str> = rest.split_whitespace().collect(); let utime: u64 = fields.get(11)?.parse().ok()?; @@ -116,6 +119,12 @@ fn proc_stats(pid: i32) -> Option<(u64, u64)> { Some((utime + stime, rss * 4096)) } +/// (cpu ticks used, resident bytes) for a pid. +fn proc_stats(pid: i32) -> Option<(u64, u64)> { + let text = std::fs::read_to_string(format!("/proc/{}/stat", pid)).ok()?; + parse_proc_stat(&text) +} + fn clock_ticks() -> f64 { let hz = unsafe { libc::sysconf(libc::_SC_CLK_TCK) }; if hz > 0 { @@ -977,10 +986,10 @@ mod tests { "42 (my (odd) proc) S 1 42 42 0 -1 4194304 100 0 0 0 {} {} 0 0 20 0 8 0 900 0 {} 0", 310, 90, 4096 ); - let rest = line.rsplit_once(')').unwrap().1; - let fields: Vec<&str> = rest.split_whitespace().collect(); - assert_eq!(fields[11], "310"); - assert_eq!(fields[12], "90"); - assert_eq!(fields[21], "4096"); + let (ticks, rss) = parse_proc_stat(&line).expect("a well-formed line should parse"); + assert_eq!(ticks, 400, "utime and stime are summed"); + assert_eq!(rss, 4096 * 4096, "rss is in pages, reported in bytes"); + // A truncated line has no fields to find and must not be guessed at. + assert_eq!(parse_proc_stat("42 (short) S 1 2 3"), None); } } diff --git a/rust/widgets/src/bin/linear.rs b/rust/widgets/src/bin/linear.rs index d064e54..b4f9552 100644 --- a/rust/widgets/src/bin/linear.rs +++ b/rust/widgets/src/bin/linear.rs @@ -294,6 +294,20 @@ struct State { fetched: f64, } +/// Whether a team key counts toward the board. +/// +/// Named teams win outright; otherwise everything not excluded is in. This +/// lived inside `one_pass` as a closure, where the only way to reach it was +/// a live token and a network round trip - so its test asserted a copy +/// written in the test body, and would have passed with this wrong. +fn team_wanted(keep: &[String], exclude: &[String], key: &str) -> bool { + if !keep.is_empty() { + keep.iter().any(|k| k == key) + } else { + !exclude.iter().any(|k| k == key) + } +} + #[allow(clippy::too_many_arguments)] fn one_pass( tok: &str, @@ -304,13 +318,7 @@ fn one_pass( state: &Arc<Mutex<State>>, quota: &Arc<Mutex<Quota>>, ) -> Result<(), String> { - let wanted = |key: &str| -> bool { - if !keep.is_empty() { - keep.iter().any(|k| k == key) - } else { - !exclude.iter().any(|k| k == key) - } - }; + let wanted = |key: &str| team_wanted(keep, exclude, key); let since = (Utc::now() - chrono::Duration::days(days - 1)) .format("%Y-%m-%dT00:00:00.000Z") .to_string(); @@ -1305,16 +1313,13 @@ mod tests { fn a_key_decides_which_teams_are_counted() { // Named teams win outright; otherwise the excluded ones are dropped // and everything else is in. - let wanted = |keep: &[&str], exclude: &[&str], key: &str| -> bool { - if !keep.is_empty() { - keep.contains(&key) - } else { - !exclude.contains(&key) - } - }; - assert!(wanted(&["TOY"], &["OPS"], "TOY")); - assert!(!wanted(&["TOY"], &[], "OPS")); - assert!(wanted(&[], &["OPS"], "TOY")); - assert!(!wanted(&[], &["OPS"], "OPS")); + let of = |v: &[&str]| -> Vec<String> { v.iter().map(|s| s.to_string()).collect() }; + assert!(team_wanted(&of(&["TOY"]), &of(&["OPS"]), "TOY")); + assert!(!team_wanted(&of(&["TOY"]), &of(&[]), "OPS")); + assert!(team_wanted(&of(&[]), &of(&["OPS"]), "TOY")); + assert!(!team_wanted(&of(&[]), &of(&["OPS"]), "OPS")); + // A named team wins even when it is also excluded, which is the + // branch the test-local copy could never have got wrong. + assert!(team_wanted(&of(&["OPS"]), &of(&["OPS"]), "OPS")); } } diff --git a/rust/widgets/src/bin/pr.rs b/rust/widgets/src/bin/pr.rs index d41b771..0d0c86e 100644 --- a/rust/widgets/src/bin/pr.rs +++ b/rust/widgets/src/bin/pr.rs @@ -571,7 +571,15 @@ fn merge_label<'a>(state: &str, p: &'a Palette) -> (&'static str, &'a str) { "BLOCKED" => ("blocked", &p.warn), "BEHIND" => ("behind", &p.warn), "UNSTABLE" => ("checks failing", &p.warn), - "HAS_HOOKS" | "UNKNOWN" => ("checking", &p.dim), + // HAS_HOOKS means a merge queue or a required hook stands between + // this and the button - the PR itself is mergeable. pr.py has always + // called it ready; the port called it "checking", which reads as + // "not finished yet" and is the opposite of what it means. + "HAS_HOOKS" => ("ready", &p.ok), + // Drafts had no case and fell to the em-dash, so a draft was + // indistinguishable from a PR whose state GitHub had not sent. + "DRAFT" => ("draft", &p.dim), + "UNKNOWN" => ("checking", &p.dim), _ => ("—", &p.dim), } } diff --git a/rust/widgets/src/bin/usage/vendors.rs b/rust/widgets/src/bin/usage/vendors.rs index 0c7ba18..02a3102 100644 --- a/rust/widgets/src/bin/usage/vendors.rs +++ b/rust/widgets/src/bin/usage/vendors.rs @@ -73,6 +73,20 @@ fn lanes_of(name: &str, s: &State) -> Vec<Lane> { /// agent", and this answers the only question that spans them - what runs /// out first. An agent that publishes no quota is named at the bottom /// instead of being silently missing. +/// Order provider groups by the lane closest to running out. +/// +/// A provider with one lane at 88% outranks one whose lanes all sit at 40%, +/// however many of them there are: the structure says who owns what, the +/// ordering answers which one stops working first. +/// +/// Lifted out of `summary_tab` because its test sorted a vector built in the +/// test body with a comparator written in the test body, so this ordering - +/// the whole point of that screen - was never run by it. +fn rank_by_worst_lane<T>(groups: &mut [(T, Vec<Lane>)]) { + let worst = |g: &Vec<Lane>| g.iter().map(|l| l.pct).fold(0.0f64, f64::max); + groups.sort_by(|a, b| worst(&b.1).total_cmp(&worst(&a.1))); +} + fn summary_tab(s: &State, w: usize, p: &Palette) -> Vec<String> { let mut groups: Vec<(&str, Vec<Lane>)> = Vec::new(); let mut quiet: Vec<&str> = Vec::new(); @@ -90,10 +104,7 @@ fn summary_tab(s: &State, w: usize, p: &Palette) -> Vec<String> { // Grouped by provider, but the groups are ordered by their worst lane: // the structure says who owns what, the ordering still answers which // one runs out first. - groups.sort_by(|a, b| { - let worst = |g: &Vec<Lane>| g.iter().map(|l| l.pct).fold(0.0f64, f64::max); - worst(&b.1).total_cmp(&worst(&a.1)) - }); + rank_by_worst_lane(&mut groups); let total: usize = groups.iter().map(|(_, g)| g.len()).sum(); let label_w = groups .iter() @@ -270,13 +281,24 @@ mod tests { // Deliberately built rather than read from disk: the ordering is // the whole point of this screen and must not depend on what this // machine happens to have installed today. - let mut a: Vec<(&str, f64)> = vec![ - ("claude", 12.0), - ("codex", 88.0), - ("grok", 40.0), + let lane = |pct: f64| Lane { + label: String::new(), + pct, + window_secs: None, + reset: None, + stale: false, + }; + // grok has more lanes and a higher total, and still ranks below the + // provider with the single worst one - which a flat sort by + // percentage would get wrong, and which the old test-local + // comparator could not have exercised at all. + let mut groups = vec![ + ("claude", vec![lane(12.0)]), + ("grok", vec![lane(40.0), lane(39.0), lane(38.0)]), + ("codex", vec![lane(88.0)]), ]; - a.sort_by(|x, y| y.1.total_cmp(&x.1)); - assert_eq!(a[0].0, "codex"); - assert_eq!(a[2].0, "claude"); + rank_by_worst_lane(&mut groups); + let order: Vec<&str> = groups.iter().map(|(n, _)| *n).collect(); + assert_eq!(order, vec!["codex", "grok", "claude"]); } } From a1704ccc5381cbc9c88c6bd445b0f7c3baf1b352 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Mon, 24 Aug 2026 18:44:28 +0800 Subject: [PATCH 063/147] netwatch: the detail screen shows what it has, and scrolls MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three lists shared whatever the pane had left, the focused one taking the room and the other two collapsing to a single line. A process with six sockets showed one of them under a heading that said "6 sockets", and the only way to see the other five was to know which key focused that section. Every list is drawn in full now and the screen scrolls, which is what the footer had been claiming all along: it said "↑↓ scroll" while up and down moved the cursor inside a section and the screen never moved at all. So the two levels are separate and both are named. Up and down scroll the screen, with pgup, pgdn, home and end, the way they do in every other widget. n and p move the cursor inside the focused section, which is what picks the endpoint that gets its own chart - the job up and down used to do and could not keep once the screen needed them. Disk gets a chart. It was two lifetime totals, which answer whether a process has ever touched the disk and not whether it is touching it now - the question the whole network half of that screen exists to answer. The same chart, the same axes rule, written above the line and read below, sampled from /proc/<pid>/io beside the fd scan that was already being done per process. It draws whether or not anything is moving, like the network chart above it, because a flat line at zero is an answer and a missing chart is a question about the widget. Rates average over ten seconds rather than four. Four was already a deliberate window - one sample interval is the honest instantaneous rate and an unreadable column, since nearly all traffic is bursty - and ten holds the same argument further. The header states the window either way, so the number is never a mystery about which span it covers. The keys are in the doc, because the check said so: [n] and [p] were in the footer and not in docs/netwatch.md within a minute of being added. A key that works and is not named is the same fault as a name with no key behind it, read from the other side. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- docs/netwatch.md | 4 +- rust/widgets/src/bin/netwatch.rs | 128 +++++++++++++++++++++++++++---- 2 files changed, 114 insertions(+), 18 deletions(-) diff --git a/docs/netwatch.md b/docs/netwatch.md index e4df3dc..fc8ab0b 100644 --- a/docs/netwatch.md +++ b/docs/netwatch.md @@ -365,7 +365,9 @@ against. | Key | Action | |---|---| -| `↑` `↓` / `j` `k` | select a process — or an item within the focused section | +| `↑` `↓` / `j` `k` | select a process in the list — or scroll the detail screen | +| `PgUp` `PgDn` `Home` `End` | move the detail screen by a page, or to either end | +| `n` / `p` | move the cursor inside the focused section, which picks the endpoint that gets its own chart | | `↵` / `→` | open the selected process | | `esc` / `←` | back to the list | | `tab` | cycle the focused section: endpoints → connections → files | diff --git a/rust/widgets/src/bin/netwatch.rs b/rust/widgets/src/bin/netwatch.rs index 239033a..d62e486 100644 --- a/rust/widgets/src/bin/netwatch.rs +++ b/rust/widgets/src/bin/netwatch.rs @@ -362,7 +362,7 @@ fn wire_label(names: &[String]) -> String { /// flickers between a figure and a dash. Averaging over a few seconds is /// just as true - it is a rate over a stated window - and can actually be /// read. The header says which window, so the number is not a mystery. -const RATE_WINDOW: f64 = 4.0; +const RATE_WINDOW: f64 = 10.0; /// Fold one sample into a counter and re-average over the window. /// @@ -446,6 +446,16 @@ struct Proc { recent: Vec<(f64, f64, u64, u64)>, /// (down rate, up rate) per sample, for this process's own chart. hist: Vec<(f64, f64)>, + /// (read rate, write rate) per sample, from /proc/<pid>/io. + /// + /// Disk was a line of two lifetime totals, which answers "has it ever + /// touched the disk" and not "is it touching it now" - the question the + /// network half of this screen exists to answer. Same series, same + /// chart, so the two can be read against each other. + disk: Vec<(f64, f64)>, + /// (when, read bytes, write bytes) at the previous sample. The kernel + /// reports lifetime counters, so a rate needs the one before. + io_was: Option<(f64, u64, u64)>, } /// One socket, so the detail screen can say which of a process's dozen @@ -630,6 +640,27 @@ fn sample(state: &mut State, external: bool) { for row in state.totals.values_mut() { row.hist.push((row.down_rate, row.up_rate)); trim(&mut row.hist, SERIES); + // /proc/<pid>/io is one small read beside the /proc/<pid>/fd + // directory scan this widget already does per process, and it + // is unreadable for anyone else's, which the empty map covers. + let (mut read_rate, mut write_rate) = (0.0, 0.0); + if row.pid != 0 && row.alive { + let io = proc_io(row.pid); + let now_read = *io.get("read_bytes").unwrap_or(&0); + let now_write = *io.get("write_bytes").unwrap_or(&0); + if !io.is_empty() { + if let Some((was_at, was_read, was_write)) = row.io_was { + let span = stamp - was_at; + if span > 0.0 { + read_rate = now_read.saturating_sub(was_read) as f64 / span; + write_rate = now_write.saturating_sub(was_write) as f64 / span; + } + } + row.io_was = Some((stamp, now_read, now_write)); + } + } + row.disk.push((read_rate, write_rate)); + trim(&mut row.disk, SERIES); } for spot in state.spots.values_mut() { spot.hist.push((spot.down_rate, spot.up_rate)); @@ -1284,13 +1315,14 @@ fn detail_rows( out.push(String::new()); } - // What is left is split between the three lists, with the focused one - // given the room: it is the one being read, and the others still say - // how much they are holding in their headers. - let left = h.saturating_sub(out.len() + 4).max(3); + // Every list is drawn in full. The three used to share what was left, + // with the focused one taking the room and the other two collapsing to + // a single line - so a process with six sockets showed one of them and + // said "6 sockets" above it, and the only way to see the rest was to + // remember which key focused that section. The screen is now as tall as + // it needs to be and the caller scrolls it. let counts = [spots.len(), conns.len(), files.len()]; - let mut shares = [1usize; 3]; - shares[focus] = left.saturating_sub(2 + 3 * 2).max(1); + let shares = [counts[0].max(1), counts[1].max(1), counts[2].max(1)]; for (which, (name, key, note)) in [ ("TALKING TO", "e", "endpoint"), @@ -1302,7 +1334,7 @@ fn detail_rows( { let focused = focus == which; out.push(section_head(name, counts[which], note, focused, key, w, p)); - let room = shares[which].min(h.saturating_sub(out.len() + 3).max(1)); + let room = shares[which]; if counts[which] == 0 { out.push(tc::seg(&[(p.dim.as_str(), " none".into())], w - 1)); } else if which == 0 { @@ -1353,6 +1385,20 @@ fn detail_rows( ], w - 1, )); + // The same chart the network half uses, on the same axes rule: + // written above the line, read below. Two lifetime totals say + // whether it has ever touched the disk; this says whether it is + // touching it now, which is the question the rest of this screen + // is answering about the network. + let room = h.saturating_sub(out.len() + 1); + let disk_h = if room >= 7 { room.min(9) } else { 0 }; + // Drawn whether or not it is moving, like the network chart above: + // a flat line at zero says "not touching the disk", which is an + // answer. Hiding it would leave the reader unsure whether the + // process is quiet or the chart is broken. + if disk_h > 0 && !row.disk.is_empty() { + out.extend(chart(&row.disk, w, disk_h, p)); + } } out } @@ -1518,6 +1564,10 @@ fn main() { let mut detail: Option<(i32, String)> = None; let mut focus = 0usize; let mut at = [0usize; 3]; + // How far down the detail screen we are. Clamped against the body when + // the frame is drawn, because the body's height depends on how many + // sockets and files the process has right now. + let mut dscroll = 0usize; // What each open file measured when this screen opened, so the growth // column is over the time you have been looking rather than the life // of the file. @@ -1554,8 +1604,28 @@ fn main() { detail = None; sizes.clear(); } - "up" | "k" | "K" => at[focus] = at[focus].saturating_sub(1), - "down" | "j" | "J" => at[focus] += 1, + // Up and down move the screen, as they do in every + // other widget. The cursor inside a section - which + // picks the endpoint that gets its own chart - moves on + // n and p, the same pair link uses to step between + // connections without leaving the screen. + "up" | "k" | "K" => dscroll = dscroll.saturating_sub(1), + "down" | "j" | "J" => dscroll = dscroll.saturating_add(1), + // The pane height is read here rather than carried, + // because a page is only meaningful against the pane as + // it is now and it may have been resized since. + "pgup" => { + let page = tc::size().1.saturating_sub(4).max(1); + dscroll = dscroll.saturating_sub(page); + } + "pgdn" => { + let page = tc::size().1.saturating_sub(4).max(1); + dscroll = dscroll.saturating_add(page); + } + "home" => dscroll = 0, + "end" => dscroll = usize::MAX, + "n" | "N" => at[focus] += 1, + "p" | "P" => at[focus] = at[focus].saturating_sub(1), "tab" => focus = (focus + 1) % SECTIONS.len(), "e" | "E" => focus = 0, "f" | "F" => focus = 2, @@ -1601,6 +1671,7 @@ fn main() { detail = Some((pick.pid, pick.name.clone())); focus = 0; at = [0; 3]; + dscroll = 0; sizes.clear(); } } @@ -1683,6 +1754,11 @@ fn main() { let hints: Vec<Vec<(&str, String)>> = vec![ vec![(p.accent.as_str(), "↑↓".into()), (p.dim.as_str(), " scroll".into())], vec![(p.accent.as_str(), "tab".into()), (p.dim.as_str(), " section".into())], + // n and p move the cursor inside the focused section, which + // is what up and down did before they were given the screen. + // A key that works and is not named is the same fault as a + // name with no key behind it, read from the other side. + vec![(p.dim.as_str(), "[n]/[p] in section".into())], vec![(p.dim.as_str(), "[c]opy".into())], vec![(p.dim.as_str(), "[r]ezero".into())], vec![ @@ -1699,15 +1775,33 @@ fn main() { foot = vec![tc::seg(&[(colour.as_str(), format!(" {}", text))], w - 1)]; } let room = h.saturating_sub(foot.len() + 1).max(1); - let mut body = detail_rows( - &row, &spots, &conns, &files, &sizes, focus, &at, w, room, interval, &names, &p, + // Built at the height it wants rather than the height it has: + // the lists are drawn in full and the charts get their rows, and + // what does not fit is scrolled to rather than dropped. + let natural = room + spots.len() + conns.len() + files.len() + 24; + let body = detail_rows( + &row, &spots, &conns, &files, &sizes, focus, &at, w, natural, interval, &names, &p, ); - body.truncate(room); - while body.len() < room { - body.push(String::new()); + let furthest = body.len().saturating_sub(room); + dscroll = dscroll.min(furthest); + let last = (dscroll + room).min(body.len()); + let mut shown: Vec<String> = body[dscroll..last].to_vec(); + while shown.len() < room { + shown.push(String::new()); + } + if furthest > 0 { + if let Some(line) = foot.last_mut() { + line.push_str(&tc::seg( + &[( + p.dim.as_str(), + format!(" rows {}-{} of {}", dscroll + 1, last, body.len()), + )], + w - 1, + )); + } } - body.extend(foot); - tc::draw(&body, w, h); + shown.extend(foot); + tc::draw(&shown, w, h); std::thread::sleep(Duration::from_millis(300)); continue; } From cc6f750efcf2b01b55140e87c26c2396945f93ad Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Mon, 24 Aug 2026 18:49:47 +0800 Subject: [PATCH 064/147] check: a config key someone deletes must land on a code default Every one of the 59 config reads already does. Verified by hand and then by running clocks four ways: with no config file at all, with a config carrying no clocks section, with the section present and empty, and with only pomodoro_focus_minutes set. Twenty-five minutes in the first three and thirty in the last, with the short and long breaks still coming from the code. But "true today" and "stays true" are different, and the whole point of a config key is that somebody can remove it. cfg_f64 and its siblings take a fallback by signature; a bare cfg.get() does not, and that is the shape this watches. The window is the statement rather than a fixed number of characters. A hand-audit written first used 260 characters and reported work_days as unguarded, when its unwrap_or_else was simply further along than that - and work_days is the better-written one of the two, since it also falls back when the list is present but empty rather than yielding a week with no working days in it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/widgets/tests/check.rs | 46 +++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/rust/widgets/tests/check.rs b/rust/widgets/tests/check.rs index f4fc5e0..dd26835 100644 --- a/rust/widgets/tests/check.rs +++ b/rust/widgets/tests/check.rs @@ -398,6 +398,52 @@ fn every_section_in_the_example_is_read_by_the_widget_it_names() { assert!(wrong.is_empty(), "\n{}", wrong.join("\n")); } +#[test] +fn every_config_read_falls_back_to_a_code_default() { + // A key deleted from config.json must land on the widget's own + // default, not on zero and not on a panic. cfg_f64 and its siblings + // take a fallback by signature; a bare cfg.get() does not, so those + // are the ones that can go wrong. + // + // Checked live as well as here: clocks with no config file, with no + // clocks section, with an empty section, and with only the focus key + // set, all show the code's own durations. + let mut wrong = Vec::new(); + for (name, src) in widgets() { + let mut from = 0; + while let Some(at) = src[from..].find(".get(\"") { + let start = from + at; + from = start + 5; + // Only reads of the config value itself; every other .get() in + // these files is a JSON lookup on something else. + let before = &src[start.saturating_sub(40)..start]; + if !before.trim_end().ends_with("cfg") && !before.trim_end().ends_with("&cfg") { + continue; + } + let key: String = src[from..] + .chars() + .take_while(|c| *c != '"') + .collect(); + // The statement this read belongs to, not a fixed window: an + // earlier hand-audit used 260 characters and wrongly flagged + // work_days, whose fallback is simply further along. + let rest = &src[start..]; + let stop = rest.find(';').unwrap_or(rest.len()); + let statement = &rest[..stop]; + let guarded = statement.contains("unwrap_or") + || statement.contains("unwrap_or_else") + || statement.contains("unwrap_or_default"); + if !guarded { + wrong.push(format!( + "{}: reads {:?} from config with no fallback in the statement", + name, key + )); + } + } + } + assert!(wrong.is_empty(), "\n{}", wrong.join("\n")); +} + #[test] fn a_poller_that_dies_records_why() { // CLAUDE.md's central gotcha: a thread that stops takes its From 9926f43621dffa1034865037202fb0f1d0ffd5b0 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Mon, 24 Aug 2026 19:36:07 +0800 Subject: [PATCH 065/147] defaults: three the Rust did not match, and the check that finds the rest Every config read already fell back to a code default. What nobody had compared is whether those defaults agree with the Pythons', and on a machine with no config - which is this one, whose config.json has no clocks keys at all - the default is the whole behaviour. Two disagreed, both making the Rust quieter than the Python: - pomodoro_notify defaulted to false against clocks.py's True, so an unconfigured pomodoro rang the bell and sent no desktop notification. - show_hints defaulted to false against True, so the tips were hidden until you pressed the key that reveals them - which you would have to already know about. And one key was documented and inert: link never read `ports`. link.py seeds its listening set from it before adding whatever `ss` reports, because inbound means "arrived at a port we listen on" and the key exists for ports that are not visibly listening at the moment you look. The Rust started from empty, so setting it did nothing and there was no way to tell from outside whether the setting or the situation was at fault. The dead-key check was checking sections where check.py checks keys. That is why netwatch and ports were caught - they read nothing at all - and link was not: it reads `windows` from the same section and looked answered. Per key now, and link.ports was the only thing left in the tree. Two audits were written to find these and both had to be thrown away first. One read line by line and silently skipped every multi-line chain, which is most of them. The other required the config variable to be named `cfg`, so it declared pr's token_env and five of usage's keys unread when they are read through `&gh` and `&raw`. The committed check does not guess at the variable: a key counts as read if the widget mentions it at all. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/widgets/src/bin/clocks.rs | 13 ++++++++----- rust/widgets/src/bin/link.rs | 17 ++++++++++++++++- rust/widgets/tests/check.rs | 29 +++++++++++++++++++++++++++++ 3 files changed, 53 insertions(+), 6 deletions(-) diff --git a/rust/widgets/src/bin/clocks.rs b/rust/widgets/src/bin/clocks.rs index b1212dc..2595c58 100644 --- a/rust/widgets/src/bin/clocks.rs +++ b/rust/widgets/src/bin/clocks.rs @@ -409,10 +409,13 @@ impl Pomodoro { .get("pomodoro_enabled") .and_then(|v| v.as_bool()) .unwrap_or(false), + // True, as clocks.py has it: a break ending is worth saying + // out loud, and a machine with no config should behave the + // same under either implementation. notify: cfg .get("pomodoro_notify") .and_then(|v| v.as_bool()) - .unwrap_or(false), + .unwrap_or(true), }; it.left = it.duration(); it.running = it.enabled; @@ -709,14 +712,14 @@ fn main() { .and_then(|v| v.as_bool()) .unwrap_or(true); let mut flash_started: Option<f64> = None; - // Hidden by default: four extra hints on the bottom line is a lot of - // footer for a timer that is usually just sitting there, and [?] is - // always on show to bring them back. clocks.py starts them visible; + // Visible by default, as clocks.py has it: the hints are how the keys + // are found in the first place, and starting hidden means a reader has + // to already know the key that reveals them. [?] toggles, and // show_hints in the config still decides either way. let mut tips = cfg .get("show_hints") .and_then(|v| v.as_bool()) - .unwrap_or(false); + .unwrap_or(true); tc::setup(); let mut keyboard = tc::Keyboard::new(); let mut scroll = 0usize; diff --git a/rust/widgets/src/bin/link.rs b/rust/widgets/src/bin/link.rs index 6471dff..0fb63e0 100644 --- a/rust/widgets/src/bin/link.rs +++ b/rust/widgets/src/bin/link.rs @@ -117,8 +117,15 @@ fn run(args: &[&str]) -> String { /// Inbound is defined as "arrived at a port we listen on" rather than by a /// list of numbers, so SSH, a terminal server and anything else that /// accepts sessions are all found without being named. +/// Ports named in config, to be treated as inbound whether or not `ss` +/// reports them listening right now. Set once at startup. +static CONFIGURED_PORTS: std::sync::OnceLock<Vec<u16>> = std::sync::OnceLock::new(); + fn listening_ports() -> Result<Vec<u16>, String> { - let mut ports = Vec::new(); + // Seeded from config, as link.py does, then whatever is actually + // listening. The key exists for the ports that are not visibly + // listening at the moment you look. + let mut ports: Vec<u16> = CONFIGURED_PORTS.get().cloned().unwrap_or_default(); for line in run_or(&["ss", "-tlnH"])?.lines() { let cols: Vec<&str> = line.split_whitespace().collect(); if let Some(local) = cols.get(3) { @@ -397,6 +404,14 @@ struct State { fn main() { tc::maybe_help(include_str!("link_help.txt")); let cfg = tc::load_config("link"); + let named: Vec<u16> = cfg + .get("ports") + .and_then(|v| v.as_array()) + .map(|a| a.iter().filter_map(|v| v.as_u64()).map(|n| n as u16).collect()) + .unwrap_or_default(); + if !named.is_empty() { + let _ = CONFIGURED_PORTS.set(named); + } let refresh = tc::cfg_f64(&cfg, "refresh", 2.0).max(0.5); let windows: Vec<f64> = { let got = cfg diff --git a/rust/widgets/tests/check.rs b/rust/widgets/tests/check.rs index dd26835..ca81944 100644 --- a/rust/widgets/tests/check.rs +++ b/rust/widgets/tests/check.rs @@ -444,6 +444,35 @@ fn every_config_read_falls_back_to_a_code_default() { assert!(wrong.is_empty(), "\n{}", wrong.join("\n")); } +#[test] +fn every_key_in_the_example_is_read_by_the_widget_it_belongs_to() { + // check.py's rule, per key rather than per section: a key in the + // example that no widget reads is a lie in a sample file. Checking + // only that the section is loaded misses the case where a widget + // reads three of its four keys and ignores the fourth. + let example = example(); + let widgets = widgets(); + let mut wrong = Vec::new(); + for (section, keys) in &example { + let stem = section.replace('_', "-"); + let Some(src) = widgets.get(section).or_else(|| widgets.get(&stem)) else { + continue; // a section for something that is not a Rust widget + }; + for key in keys { + // Any mention of the key as a string literal counts. The point + // is whether the widget knows the name at all, not which + // helper it reaches for. + if !src.contains(&format!("\"{}\"", key)) { + wrong.push(format!( + "config.example.json documents {}.{} and {}.rs never reads it", + section, key, stem + )); + } + } + } + assert!(wrong.is_empty(), "\n{}", wrong.join("\n")); +} + #[test] fn a_poller_that_dies_records_why() { // CLAUDE.md's central gotcha: a thread that stops takes its From 01bda511c5b183ee5dd1c7293a2a4bf876c5b022 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Mon, 24 Aug 2026 19:39:15 +0800 Subject: [PATCH 066/147] netwatch: a cursor inside a section, and a heading over every column MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The detail screen's three lists had no column names. Six numbers in a row, two of them arrows and one of them a rate, and nothing saying which was which - the top-level process list has had headings all along and these never did. Each list now names its columns. The heading and the rows share one width function rather than each carrying the arithmetic, and the tests find the columns by looking at where a rendered row actually put them instead of recomputing the sum. A test that repeats the formula agrees with a heading that has slipped. That is how the endpoint list turned out to be two cells over budget. Its flexible host column was sized as if the fixed tail were 42 cells when it is 44 - 9 for ports, 10 for rx, 11 for tx, 11 for the rate, 3 for the mark - so between 59 and 77 columns seg() clipped the last two cells of the rate away and "12.4 KB/s" rendered as "12.4 KB". A rate short of its unit is not a smaller rate, it is a wrong one. Nothing in the pane showed it, because a truncated column looks exactly like a narrow one. The cursor model is the one agreed for every widget with focusable sections: - tab moves into a section and on to the next; from the last one it returns to scrolling the screen. Sections with no rows are stepped over - focusing "0 files" offered "↑↓ select" over nothing, and the next arrow silently left again, which reads as a broken key. - up and down select within a focused section and scroll the screen otherwise. Whichever is in front of you is what they act on. - You leave a list by walking off either end of it, or by pressing tab again. Focus is left the way it was entered rather than needing a key of its own. The screen now opens with nothing focused, so `c` copies nothing rather than whatever happened to be first, and says so. e and f are gone. They jumped straight to two of the three lists, which meant three keys for one job, a letter advertised in two section headings and none in the third, and a doc row for keys the Rust build no longer answers to - which check.py cannot catch, since it tests that footer keys are documented and not that documented keys exist. netwatch.py still has them; the doc says so against those rows. The selected socket gets an rx/tx chart under its row, as the selected endpoint already does. Under it, not after the list: with the chart at the bottom you had to hold which row was highlighted in your head while your eye travelled. The scroll position moved into the footer's hint list. Appended to an already-packed line it overflowed the width and the terminal wrapped it, so the footer's last row was the tail of a number. scroll_label is a fixed width so the second pack cannot wrap differently from the first. link.rs carries the same function; TOY-7 tracks folding the pair into toys-core. The doc's sample screen was generated by running the renderers rather than counted by hand, and now states what nothing stated before: every rate on the screen is a ten-second average, and the header says so. --- docs/netwatch.md | 52 ++-- rust/widgets/src/bin/netwatch.rs | 407 ++++++++++++++++++++++++++----- 2 files changed, 376 insertions(+), 83 deletions(-) diff --git a/docs/netwatch.md b/docs/netwatch.md index fc8ab0b..cf305f7 100644 --- a/docs/netwatch.md +++ b/docs/netwatch.md @@ -287,32 +287,46 @@ it as a machine honestly can: ── PROCESS ── command curl -s -o ~/tmp/big.bin --limit-rate 400k https://…/__down directory ~/projects/terminal-toys - started 6s ago - ── TALKING TO ── 1 connection - 162.159.140.220 https ↓ 3.2 MB ↑ 722 B 411.2 KB/s + ── TALKING TO ── 1 endpoint + host ports rx tx rate + 162.159.140.220 https ↓ 3.2 MB ↑ 722 B 411.2 KB/s - ── WRITING TO ── where a download would be landing - ~/tmp/big.bin 3.0 MB +425.8 KB/s + ── CONNECTIONS ── 1 socket + socket state rx tx + 162.159.140.220:443 open ↓ 3.2 MB ↑ 722 B + + ── FILES ── 1 file + path size growth + ~/tmp/big.bin 3.0 MB +425.7 KB/s ── DISK ── read 0 B · written 3.0 MB since it started HTTPS hides the URL and the filename. Who it talks to and what it writes are above. ``` -Three lists, and `tab` moves between them — the focused one is marked `▏` and -takes the arrow keys, and `c` copies whatever is selected in it. +Every list is drawn in full, always, and `↑` `↓` scroll the screen. `tab` +focuses a list instead: the focused one is marked `▏`, `↑` `↓` then move a +cursor `▸` inside it, and `c` copies whatever that cursor is on. + +You leave a list by walking off either end of it — `↑` on the first row or +`↓` on the last — or by pressing `tab` again, which moves to the next list +and, from the last one, back to scrolling the screen. Lists with nothing in +them are stepped over rather than focused, since there would be nothing to +put the cursor on. **This is the same rule in every widget here that has +focusable sections.** **TALKING TO** ranks the remote hosts by what they have carried since launch. Hosts, not sockets: a process opening six connections to one CDN is one thing being talked to. Peers resolve to names in the background — the address shows -until the answer arrives, and a lookup is never made twice. The highlighted -host gets its own small rx/tx chart, which is the quickest way to see whether -it is the one doing the work. +until the answer arrives, and a lookup is never made twice. The row the cursor +is on gets its own small rx/tx chart, drawn directly beneath it, which is the +quickest way to see whether that host is the one doing the work. **CONNECTIONS** is the sockets themselves, open right now, which is a different question: one host may hold six of them, and a socket that has -closed still shows what it carried. +closed still shows what it carried. It charts the same way TALKING TO does — +the cursor's socket gets an rx/tx chart under its row. A hostname is a best-effort label rather than the domain that was asked for. CDNs, shared addresses, encrypted DNS and connection reuse all mean one @@ -361,19 +375,25 @@ Decimal — `KB` is 1,000 bytes, `MB` is 1,000,000 — which is how link rates a data caps are quoted, and therefore what these numbers are usefully compared against. +Every **rate** — `NOW`, `DOWN`, `UP`, the per-endpoint and per-socket figures, +and a file's growth — is an average over the last **ten seconds**, not over +the one-second sample. Almost all traffic is bursty, so an instantaneous rate +is honest and unreadable: a process that is steadily busy flickers between a +figure and a dash. An average over a stated window is just as true and can +actually be read. The header says the window (`every 1s · rates over 10s`) so +the number is never a mystery, and the **totals** are untouched by it. + ## Keys | Key | Action | |---|---| -| `↑` `↓` / `j` `k` | select a process in the list — or scroll the detail screen | +| `↑` `↓` / `j` `k` | select a process in the list — on the detail screen, scroll it, or move the cursor inside a focused section | | `PgUp` `PgDn` `Home` `End` | move the detail screen by a page, or to either end | -| `n` / `p` | move the cursor inside the focused section, which picks the endpoint that gets its own chart | | `↵` / `→` | open the selected process | | `esc` / `←` | back to the list | -| `tab` | cycle the focused section: endpoints → connections → files | -| `e` | focus the endpoints | -| `f` | focus the open files | +| `tab` | focus the next section, and from the last one back to scrolling | | `c` | copy the selected host, socket or path | +| `e` `f` | jump straight to the endpoints or the files — **`netwatch.py` only**; the Rust build reaches every section with `tab` alone | | `s` | switch sort mode (`t` also works) | | `o` | show or hide processes you do not own | | `1` | sort by total data used | diff --git a/rust/widgets/src/bin/netwatch.rs b/rust/widgets/src/bin/netwatch.rs index d62e486..f80dc29 100644 --- a/rust/widgets/src/bin/netwatch.rs +++ b/rust/widgets/src/bin/netwatch.rs @@ -355,6 +355,17 @@ fn wire_label(names: &[String]) -> String { } } +/// How the detail screen reports where you are in it, at a width that does +/// not change with the numbers - the footer is packed before the body is +/// measured, so a label that grew by a character could wrap the hints onto +/// another line and leave the body sized for a footer that is not there. +/// +/// link.rs carries the same function; TOY-7 tracks folding the pair into +/// toys-core rather than fixing anything here twice. +fn scroll_label(first: usize, last: usize, total: usize) -> String { + format!("rows {:>3}-{:>3} of {:>3}", first, last, total) +} + /// How long a rate is averaged over. /// /// One sample interval is the honest instantaneous rate and an unreadable @@ -474,6 +485,9 @@ struct Conn { seen: f64, /// (stamp, the gap it covers, bytes up, bytes down) recent: Vec<(f64, f64, u64, u64)>, + /// (down rate, up rate) per sample, so a selected socket can be charted + /// the way a selected endpoint is. + hist: Vec<(f64, f64)>, } /// The sockets sharing a peer, folded together: a browser opening six @@ -662,6 +676,10 @@ fn sample(state: &mut State, external: bool) { row.disk.push((read_rate, write_rate)); trim(&mut row.disk, SERIES); } + for conn in state.conns.values_mut() { + conn.hist.push((conn.down_rate, conn.up_rate)); + trim(&mut conn.hist, SERIES); + } for spot in state.spots.values_mut() { spot.hist.push((spot.down_rate, spot.up_rate)); trim(&mut spot.hist, SERIES); @@ -1025,7 +1043,6 @@ fn section_head( count: usize, note: &str, focused: bool, - key: &str, w: usize, p: &Palette, ) -> String { @@ -1039,10 +1056,12 @@ fn section_head( p.dim.as_str(), format!("{} {}{}", count, note, if count == 1 { "" } else { "s" }), ), - ( - if focused { p.accent.as_str() } else { p.grid.as_str() }, - format!(" [{}]", key), - ), + // No key named here. There is one way between sections and the + // footer says what it is; a letter per heading meant [e] and [f] + // pointing at keys that no longer exist and the middle section + // pointing at tab, which is the only one that was ever true. + // The ▏ at the head of the line is the focus mark; a second one + // out here was just the hole the key left. ], w - 1, ) @@ -1067,6 +1086,79 @@ fn chart_head(len: usize, w: usize, label: &str, interval: f64, p: &Palette) -> ) } +/// The three lists each own a flexible first column and a fixed tail. The +/// width lives in a function so the heading and the rows read it from the +/// same place: a heading that has slipped a column is worse than no heading, +/// because it labels the wrong number with confidence. +fn endpoint_host_w(w: usize) -> usize { + // 44, not 42: the fixed tail is 9 for ports, 10 for rx, 11 for tx and 11 + // for the rate, plus 3 for the selection mark. It was written as 42, so + // between 59 and 77 columns the host name took two cells the rate needed + // and seg() clipped "12.4 KB/s" down to "12.4 KB". A rate short of its + // unit is not a smaller rate, it is a wrong one. + ((w - 1).saturating_sub(44)).clamp(14, 34) +} + +fn connection_host_w(w: usize) -> usize { + ((w - 1).saturating_sub(34)).clamp(14, 38) +} + +fn file_path_w(w: usize) -> usize { + ((w - 1).saturating_sub(30)).max(18) +} + +/// The column names above `endpoint_rows`. The leading three cells are the +/// selection mark's column, left blank here. +fn endpoint_head(w: usize, p: &Palette) -> String { + tc::seg( + &[( + p.dim.as_str(), + format!( + " {}{:<9}{:>10}{:>11}{:>11}", + tc::pad("host", endpoint_host_w(w)), + "ports", + "rx", + "tx", + "rate" + ), + )], + w - 1, + ) +} + +/// The column names above `connection_rows`. +fn connection_head(w: usize, p: &Palette) -> String { + tc::seg( + &[( + p.dim.as_str(), + format!( + " {}{:<7}{:>10}{:>11}", + tc::pad("socket", connection_host_w(w)), + "state", + "rx", + "tx" + ), + )], + w - 1, + ) +} + +/// The column names above `file_rows`. +fn file_head(w: usize, p: &Palette) -> String { + tc::seg( + &[( + p.dim.as_str(), + format!( + " {}{:>10}{:>12}", + tc::pad("path", file_path_w(w)), + "size", + "growth" + ), + )], + w - 1, + ) +} + /// Remote hosts, ranked by what they have carried since launch. fn endpoint_rows( spots: &[Spot], @@ -1077,7 +1169,7 @@ fn endpoint_rows( names: &Resolver, p: &Palette, ) -> Vec<String> { - let host_w = ((w - 1).saturating_sub(42)).clamp(14, 34); + let host_w = endpoint_host_w(w); spots .iter() .take(room.max(1)) @@ -1137,7 +1229,7 @@ fn connection_rows( w: usize, p: &Palette, ) -> Vec<String> { - let host_w = ((w - 1).saturating_sub(34)).clamp(14, 38); + let host_w = connection_host_w(w); conns .iter() .take(room.max(1)) @@ -1184,7 +1276,7 @@ fn file_rows( w: usize, p: &Palette, ) -> Vec<String> { - let path_w = ((w - 1).saturating_sub(30)).max(18); + let path_w = file_path_w(w); files .iter() .take(room.max(1)) @@ -1230,7 +1322,7 @@ fn detail_rows( conns: &[Conn], files: &[OpenFile], sizes: &HashMap<String, (u64, f64)>, - focus: usize, + focus: Option<usize>, at: &[usize; 3], w: usize, h: usize, @@ -1324,42 +1416,52 @@ fn detail_rows( let counts = [spots.len(), conns.len(), files.len()]; let shares = [counts[0].max(1), counts[1].max(1), counts[2].max(1)]; - for (which, (name, key, note)) in [ - ("TALKING TO", "e", "endpoint"), - ("CONNECTIONS", "tab", "socket"), - ("FILES", "f", "file"), + for (which, (name, note)) in [ + ("TALKING TO", "endpoint"), + ("CONNECTIONS", "socket"), + ("FILES", "file"), ] .into_iter() .enumerate() { - let focused = focus == which; - out.push(section_head(name, counts[which], note, focused, key, w, p)); + let focused = focus == Some(which); + out.push(section_head(name, counts[which], note, focused, w, p)); let room = shares[which]; if counts[which] == 0 { out.push(tc::seg(&[(p.dim.as_str(), " none".into())], w - 1)); } else if which == 0 { - out.extend(endpoint_rows(spots, at[which], focused, room, w, names, p)); - // The highlighted host gets its own small chart, which is the - // quickest way to see whether it is the one doing the work. - let pick = &spots[at[which].min(spots.len() - 1)]; - if focused && !pick.hist.is_empty() && h.saturating_sub(out.len()) >= 7 { - let found = names.name(&pick.peer); - out.push(tc::seg( - &[ - (p.dim.as_str(), " ── ".into()), - ( - p.accent.as_str(), - if found.is_empty() { pick.peer.clone() } else { found }, - ), - (p.dim.as_str(), " alone ──".into()), - ], - w - 1, - )); - out.extend(chart(&pick.hist, w, 4, p)); + out.push(endpoint_head(w, p)); + let mut rows = endpoint_rows(spots, at[which], focused, room, w, names, p); + // The chart belongs under the line it describes, not after the + // list: with it at the bottom you had to hold which host was + // highlighted in your head while your eye travelled. Here the + // answer is where the question is. + let pick_at = at[which].min(spots.len() - 1); + if focused { + let pick = &spots[pick_at]; + if !pick.hist.is_empty() && pick_at < rows.len() { + let mut under = chart(&pick.hist, w, 4, p); + under.push(String::new()); + rows.splice(pick_at + 1..pick_at + 1, under); + } } + out.extend(rows); } else if which == 1 { - out.extend(connection_rows(conns, at[which], focused, room, w, p)); + out.push(connection_head(w, p)); + let mut rows = connection_rows(conns, at[which], focused, room, w, p); + let pick_at = at[which].min(conns.len().saturating_sub(1)); + if focused { + if let Some(pick) = conns.get(pick_at) { + if !pick.hist.is_empty() && pick_at < rows.len() { + let mut under = chart(&pick.hist, w, 4, p); + under.push(String::new()); + rows.splice(pick_at + 1..pick_at + 1, under); + } + } + } + out.extend(rows); } else { + out.push(file_head(w, p)); out.extend(file_rows(files, sizes, at[which], focused, room, w, p)); } out.push(String::new()); @@ -1562,12 +1664,20 @@ fn main() { // The second screen: which process, which of its three lists is taking // the keys, and where each list is scrolled to. let mut detail: Option<(i32, String)> = None; - let mut focus = 0usize; + // Which section has the cursor, if any. Opens with none: the screen is + // a thing to read before it is a thing to work, and a cursor sitting + // somewhere you did not put it is a question rather than an answer. + let mut focus: Option<usize> = None; let mut at = [0usize; 3]; // How far down the detail screen we are. Clamped against the body when // the frame is drawn, because the body's height depends on how many // sockets and files the process has right now. let mut dscroll = 0usize; + // How long each section was when it was last drawn. The keys are read + // before the frame is built, so walking off the end of a list has to be + // judged against the length it had a moment ago - which is the same + // length the reader is looking at. + let mut section_len = [0usize; 3]; // What each open file measured when this screen opened, so the growth // column is over the time you have been looking rather than the life // of the file. @@ -1604,13 +1714,25 @@ fn main() { detail = None; sizes.clear(); } - // Up and down move the screen, as they do in every - // other widget. The cursor inside a section - which - // picks the endpoint that gets its own chart - moves on - // n and p, the same pair link uses to step between - // connections without leaving the screen. - "up" | "k" | "K" => dscroll = dscroll.saturating_sub(1), - "down" | "j" | "J" => dscroll = dscroll.saturating_add(1), + // Focused into a section, up and down move between its + // rows; otherwise they move the screen. Whichever is in + // front of you is what they act on, which is the same + // rule the list screen follows. + // Walking off either end of a section leaves it, the + // same ring the target list uses: focus is left the way + // it was entered rather than needing a key of its own. + "up" | "k" | "K" => match focus { + Some(at_focus) if at[at_focus] == 0 => focus = None, + Some(at_focus) => at[at_focus] -= 1, + None => dscroll = dscroll.saturating_sub(1), + }, + "down" | "j" | "J" => match focus { + Some(at_focus) if at[at_focus] + 1 >= section_len[at_focus] => { + focus = None + } + Some(at_focus) => at[at_focus] += 1, + None => dscroll = dscroll.saturating_add(1), + }, // The pane height is read here rather than carried, // because a page is only meaningful against the pane as // it is now and it may have been resized since. @@ -1624,11 +1746,21 @@ fn main() { } "home" => dscroll = 0, "end" => dscroll = usize::MAX, - "n" | "N" => at[focus] += 1, - "p" | "P" => at[focus] = at[focus].saturating_sub(1), - "tab" => focus = (focus + 1) % SECTIONS.len(), - "e" | "E" => focus = 0, - "f" | "F" => focus = 2, + // tab is the only way between sections. e and f jumped + // straight to two of the three, which meant three keys + // for one job and a section heading advertising a letter + // of its own - and no key at all for the middle one. + // Round the lists and then off the end, back to nothing + // focused. + // + // Empty ones are stepped over. A section with no rows is + // not a place you can be: tab onto "0 files" and the + // footer offers "↑↓ select" over nothing, the next arrow + // silently leaves again, and the key reads as broken. + "tab" => { + let from = focus.map_or(0, |at| at + 1); + focus = (from..SECTIONS.len()).find(|&at| section_len[at] > 0); + } "c" | "C" => { if !pending_copy.is_empty() { // The value goes in the message either way: OSC @@ -1669,7 +1801,7 @@ fn main() { "enter" | "right" => { if let Some(pick) = ordered(&state, mine, sort_live).get(selected) { detail = Some((pick.pid, pick.name.clone())); - focus = 0; + focus = None; at = [0; 3]; dscroll = 0; sizes.clear(); @@ -1740,25 +1872,39 @@ fn main() { sizes.entry(file.path.clone()).or_insert((file.size, now())); } let counts = [spots.len(), conns.len(), files.len()]; - at[focus] = at[focus].min(counts[focus].saturating_sub(1)); + section_len = counts; + if let Some(at_focus) = focus { + at[at_focus] = at[at_focus].min(counts[at_focus].saturating_sub(1)); + } // The selection is known here and the key is pressed elsewhere, // so what `c` would copy is recorded while the frame is drawn. + // Nothing focused means nothing selected, so c has nothing to + // take. It says so rather than copying whatever happened to be + // first. pending_copy = match focus { - 0 => spots.get(at[0]).map(|s| s.peer.clone()).unwrap_or_default(), - 1 => conns + Some(0) => spots.get(at[0]).map(|s| s.peer.clone()).unwrap_or_default(), + Some(1) => conns .get(at[1]) .map(|c| format!("{}:{}", c.peer, c.port)) .unwrap_or_default(), - _ => files.get(at[2]).map(|f| f.path.clone()).unwrap_or_default(), + Some(_) => files.get(at[2]).map(|f| f.path.clone()).unwrap_or_default(), + None => String::new(), }; let hints: Vec<Vec<(&str, String)>> = vec![ - vec![(p.accent.as_str(), "↑↓".into()), (p.dim.as_str(), " scroll".into())], - vec![(p.accent.as_str(), "tab".into()), (p.dim.as_str(), " section".into())], - // n and p move the cursor inside the focused section, which - // is what up and down did before they were given the screen. - // A key that works and is not named is the same fault as a - // name with no key behind it, read from the other side. - vec![(p.dim.as_str(), "[n]/[p] in section".into())], + vec![ + (p.accent.as_str(), "↑↓".into()), + ( + p.dim.as_str(), + if focus.is_some() { " select" } else { " scroll" }.to_string(), + ), + ], + vec![ + (p.accent.as_str(), "tab".into()), + ( + p.dim.as_str(), + if focus.is_some() { " next section" } else { " into a section" }.to_string(), + ), + ], vec![(p.dim.as_str(), "[c]opy".into())], vec![(p.dim.as_str(), "[r]ezero".into())], vec![ @@ -1789,15 +1935,29 @@ fn main() { while shown.len() < room { shown.push(String::new()); } + // Appending this to an already-packed line overflowed the width + // and the terminal wrapped it, so the footer's last row was the + // tail of a number. It is a hint like the others now, packed with + // them, and `scroll_label` is a fixed width so the second pack + // cannot wrap differently from the first. if furthest > 0 { - if let Some(line) = foot.last_mut() { - line.push_str(&tc::seg( - &[( - p.dim.as_str(), - format!(" rows {}-{} of {}", dscroll + 1, last, body.len()), - )], - w - 1, - )); + let mut with_pos = hints.clone(); + with_pos.push(vec![( + p.dim.as_str(), + scroll_label(dscroll + 1, last, body.len()), + )]); + foot = tc::pack_hints(&with_pos, w - 2, " ") + .into_iter() + .map(|l| format!(" {}", l)) + .collect(); + if let Some((text, colour, _)) = notice.as_ref() { + foot = vec![tc::seg(&[(colour.as_str(), format!(" {}", text))], w - 1)]; + } + while shown.len() + foot.len() > h && shown.len() > 1 { + shown.pop(); + } + while shown.len() + foot.len() < h { + shown.push(String::new()); } } shown.extend(foot); @@ -2157,6 +2317,119 @@ fn palette() -> Palette { mod tests { use super::*; + /// Colour is not width: `len()` counts escape bytes, so every column + /// check below measures the text alone. + fn bare(line: &str) -> String { + let mut out = String::new(); + let mut chars = line.chars(); + while let Some(c) = chars.next() { + if c == '\x1b' { + for n in chars.by_ref() { + if n.is_ascii_alphabetic() { + break; + } + } + } else { + out.push(c); + } + } + out + } + + /// Which cell `token` starts in, counting characters rather than bytes - + /// the arrows are three bytes each and byte offsets would lie. + fn col(line: &str, token: &str) -> usize { + let at = line + .find(token) + .unwrap_or_else(|| panic!("{:?} is not in {:?}", token, line)); + line[..at].chars().count() + } + + fn a_resolver() -> Resolver { + Resolver { + known: Arc::new(Mutex::new(HashMap::new())), + wanted: Arc::new(Mutex::new(Vec::new())), + } + } + + // The headings are found by looking at where the rendered row put its + // columns, not by repeating the arithmetic the row used. A test that + // recomputes the widths would agree with a heading that had slipped. + + #[test] + fn the_endpoint_heading_sits_over_its_columns() { + let p = palette(); + let names = a_resolver(); + let mut spot = Spot { + peer: "192.0.2.7".into(), + up: 4096, + down: 8192, + alive: true, + ..Default::default() + }; + spot.ports.insert(9999); + for w in [60usize, 84, 120, 200] { + let head = bare(&endpoint_head(w, &p)); + let row = bare(&endpoint_rows(&[spot.clone()], 0, false, 1, w, &names, &p)[0]); + let (wide, down, up) = (row.chars().count(), col(&row, "↓"), col(&row, "↑")); + assert_eq!(head.chars().count(), wide, "heading width at w={}", w); + assert_eq!(col(&head, "host"), 3, "host column at w={}", w); + assert_eq!(col(&head, "ports"), down - 9, "ports column at w={}", w); + assert_eq!(col(&head, "rx") + 2, down + 10, "rx column at w={}", w); + assert_eq!(col(&head, "tx") + 2, up + 10, "tx column at w={}", w); + assert_eq!(col(&head, "rate") + 4, wide, "rate column at w={}", w); + } + } + + #[test] + fn the_connection_heading_sits_over_its_columns() { + let p = palette(); + let conn = Conn { + peer: "192.0.2.7".into(), + port: 443, + up: 4096, + down: 8192, + alive: true, + ..Default::default() + }; + for w in [60usize, 84, 120, 200] { + let head = bare(&connection_head(w, &p)); + let row = bare(&connection_rows(&[conn.clone()], 0, false, 1, w, &p)[0]); + let (wide, down, up) = (row.chars().count(), col(&row, "↓"), col(&row, "↑")); + assert_eq!(head.chars().count(), wide, "heading width at w={}", w); + assert_eq!(col(&head, "socket"), 3, "socket column at w={}", w); + assert_eq!(col(&head, "state"), down - 7, "state column at w={}", w); + assert_eq!(col(&head, "rx") + 2, down + 10, "rx column at w={}", w); + assert_eq!(col(&head, "tx") + 2, up + 10, "tx column at w={}", w); + assert_eq!(up + 10, wide, "the tx column is the last at w={}", w); + } + } + + #[test] + fn the_file_heading_sits_over_its_columns() { + let p = palette(); + let files = vec![OpenFile { + path: "/var/log/marker.log".into(), + size: 8192, + }]; + let sizes = HashMap::new(); + let shown = units(8192.0); + for w in [60usize, 84, 120, 200] { + let head = bare(&file_head(w, &p)); + let row = bare(&file_rows(&files, &sizes, 0, false, 1, w, &p)[0]); + let wide = row.chars().count(); + assert_eq!(head.chars().count(), wide, "heading width at w={}", w); + assert_eq!(col(&head, "path"), 3, "path column at w={}", w); + assert_eq!( + col(&head, "size") + 4, + col(&row, &shown) + shown.chars().count(), + "size column at w={}", + w + ); + assert_eq!(col(&head, "growth") + 6, wide, "growth column at w={}", w); + } + } + #[test] fn a_bursty_process_keeps_a_readable_rate() { let mut row = Proc::default(); From d30827bbd2933a52ca324b1cd1b278577ed01991 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Mon, 24 Aug 2026 19:45:43 +0800 Subject: [PATCH 067/147] core: one more hint costs at most one more line netwatch's detail screen sizes its body against the packed footer, then adds the scroll position as a seventh hint and packs again, reserving exactly one line for the difference. The reservation was right but nothing said why, and the code hedged against being wrong by popping a body row if the footer grew by two - which would have been the wrong repair, because the position label was measured before the pop and would then have named a row nobody could see. One line is enough, and it is a property of pack_hints rather than luck: the packing is greedy and in order, so the hints before the last one pack the same way whether it follows or not, and the new one either joins the last line or starts a single new one. The test pins both halves - the line count grows by at most one, and the earlier lines are byte-identical - and fails if the packing is made to rebalance. The hedge is gone; the invariant is stated where the reservation is made. --- rust/core/src/lib.rs | 44 ++++++++++++++++++++++++++++++++ rust/widgets/src/bin/netwatch.rs | 13 ++++++---- 2 files changed, 52 insertions(+), 5 deletions(-) diff --git a/rust/core/src/lib.rs b/rust/core/src/lib.rs index b8b48f2..3e10a43 100644 --- a/rust/core/src/lib.rs +++ b/rust/core/src/lib.rs @@ -1104,6 +1104,50 @@ pub fn maybe_help(doc: &str) { #[cfg(test)] mod tests { + + /// One more hint costs at most one more line. + /// + /// netwatch's detail screen leans on this: it sizes the body against the + /// footer, then adds the scroll position as a seventh hint and re-packs. + /// It reserves exactly one line for that. If a hint could ever push the + /// footer two lines further, the body would lose a row the position had + /// already counted and the label would name a row nobody can see. + /// + /// It holds because the packing is greedy and in order: whatever comes + /// before a hint packs the same way whether that hint follows or not, so + /// the new one either joins the last line or starts a single new one. + #[test] + fn appending_a_hint_adds_at_most_one_line() { + let hint = |t: &str| vec![("", t.to_string())]; + let base = vec![ + hint("↑↓ select"), + hint("tab next section"), + hint("[c]opy"), + hint("[r]ezero"), + hint("←/esc back"), + hint("[q]uit"), + ]; + for width in 8..=120usize { + let before = pack_hints(&base, width, " ").len(); + let mut after_hints = base.clone(); + after_hints.push(hint("rows 1- 43 of 45")); + let after = pack_hints(&after_hints, width, " ").len(); + assert!( + after == before || after == before + 1, + "width {}: {} lines became {}", + width, + before, + after + ); + // And the hints that were already there are untouched. + assert_eq!( + pack_hints(&base, width, " ")[..before.saturating_sub(1)], + pack_hints(&after_hints, width, " ")[..before.saturating_sub(1)], + "width {}: an earlier line was repacked", + width + ); + } + } use super::*; #[test] diff --git a/rust/widgets/src/bin/netwatch.rs b/rust/widgets/src/bin/netwatch.rs index f80dc29..8472566 100644 --- a/rust/widgets/src/bin/netwatch.rs +++ b/rust/widgets/src/bin/netwatch.rs @@ -1938,8 +1938,14 @@ fn main() { // Appending this to an already-packed line overflowed the width // and the terminal wrapped it, so the footer's last row was the // tail of a number. It is a hint like the others now, packed with - // them, and `scroll_label` is a fixed width so the second pack - // cannot wrap differently from the first. + // them. + // + // `room` above reserved one line for it, and one is enough: + // pack_hints is greedy, so the hints before this one pack the + // same way whether it is there or not, and it either joins the + // last line or starts one more. Never two more - which matters, + // because `last` was measured against `room` and a second extra + // line would cost a body row the label had already counted. if furthest > 0 { let mut with_pos = hints.clone(); with_pos.push(vec![( @@ -1953,9 +1959,6 @@ fn main() { if let Some((text, colour, _)) = notice.as_ref() { foot = vec![tc::seg(&[(colour.as_str(), format!(" {}", text))], w - 1)]; } - while shown.len() + foot.len() > h && shown.len() > 1 { - shown.pop(); - } while shown.len() + foot.len() < h { shown.push(String::new()); } From 747a4072c64f9303f373a6b8a3f9112d915cf365 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Mon, 24 Aug 2026 19:55:22 +0800 Subject: [PATCH 068/147] check: the help text was documentation nobody was checking MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Footers are checked against the code and docs/*.md is checked against the footers, and the file --help prints was read by neither. It is where someone looks when the footer is not enough, so a key named there and not implemented is the same lie from one step further away. It found one: deployments_help.txt said "Enter, i or c opens a full detail view" and deployments.rs answers to neither i nor c - the control standard removed both, the footer was corrected and the help was not. It now names → and Enter, which are the keys that exist. The help is prose, so there is no bracket to key off, and the first version read every single letter in any sentence about keys. That reported a key called `a`, from "the standard 25/5 with a longer break" and "with a sound". English is full of single letters that are words. Two shapes count now, both hard to write by accident: a letter directly after "press", and a letter directly before a verb - "c opens a detail view". The limitation is stated in the test rather than hidden: in a list like "Enter, i or c opens" only `c` touches the verb, so a stale `i` beside it is missed. Catching one of two still lands the reader in the right sentence. Also audited, and clean: every flexible column in my widgets, after the netwatch bug where a host column was sized against a fixed tail of 42 that was really 44 and quietly clipped the rate between 59 and 77 columns. tailnet's peer table and start's menu were checked by rendering both implementations at a sweep of widths and comparing where each label lands - not by re-deriving the sum, since re-deriving it is how the original was got wrong. Identical at every width, including across the clamp boundaries. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/widgets/src/bin/deployments_help.txt | 2 +- rust/widgets/tests/check.rs | 55 +++++++++++++++++++++++ 2 files changed, 56 insertions(+), 1 deletion(-) diff --git a/rust/widgets/src/bin/deployments_help.txt b/rust/widgets/src/bin/deployments_help.txt index 3478e78..656f6c9 100644 --- a/rust/widgets/src/bin/deployments_help.txt +++ b/rust/widgets/src/bin/deployments_help.txt @@ -9,7 +9,7 @@ Polls every 15s by default (-n changes it, minimum 5s). One request per team per poll, so the default is 4 polls/min — modest against the API's limits. Keys while running: up/down (also PgUp/PgDn, Home/End) move the selection, -Enter, i or c opens a full detail view for the selected deployment - state and +→ or Enter opens a full detail view for the selected deployment - state and failure reason, timings, regions, commit, and everything worth copying on number keys - r refreshes now, f cycles the filter (all / failed / production), p cycles which project diff --git a/rust/widgets/tests/check.rs b/rust/widgets/tests/check.rs index ca81944..28d784d 100644 --- a/rust/widgets/tests/check.rs +++ b/rust/widgets/tests/check.rs @@ -473,6 +473,61 @@ fn every_key_in_the_example_is_read_by_the_widget_it_belongs_to() { assert!(wrong.is_empty(), "\n{}", wrong.join("\n")); } +#[test] +fn every_key_the_help_text_names_is_answered() { + // --help is where someone looks when the footer is not enough, so a + // key named there and not implemented is the same lie as a footer + // hint bound to nothing. Nothing was reading these files. + // + // The help is prose, so there are no brackets to key off. Only two + // shapes count, both hard to write by accident: a letter right after + // "press", and a letter right before a verb - "c opens a detail + // view". Reading every single letter instead took "a" from "with a + // longer" and reported a key called a. + // + // Known limitation, stated rather than hidden: in "Enter, i or c + // opens", only `c` touches the verb, so a stale `i` beside it is + // missed. Catching one of the two still lands the reader in the right + // sentence. + const VERBS: &[&str] = &[ + "opens", "cycles", "toggles", "quits", "refreshes", "closes", "copies", + ]; + let dir = root().join("rust/widgets/src/bin"); + let mut wrong = Vec::new(); + for (name, src) in widgets() { + let help = dir.join(format!("{}_help.txt", name)); + let Ok(text) = std::fs::read_to_string(&help) else { + continue; + }; + let handled = handled_keys(&src); + for line in text.lines() { + let lower = line.to_lowercase(); + let words: Vec<&str> = lower + .split(|c: char| !c.is_ascii_alphanumeric()) + .filter(|w| !w.is_empty()) + .collect(); + for (i, word) in words.iter().enumerate() { + if word.chars().count() != 1 { + continue; + } + let after_press = i > 0 && words[i - 1] == "press"; + let before_verb = words + .get(i + 1) + .is_some_and(|next| VERBS.contains(next)); + if (after_press || before_verb) && !handled.contains(*word) { + wrong.push(format!( + "{}_help.txt names {:?} and {}.rs does not answer it", + name, word, name + )); + } + } + } + } + wrong.sort(); + wrong.dedup(); + assert!(wrong.is_empty(), "\n{}", wrong.join("\n")); +} + #[test] fn a_poller_that_dies_records_why() { // CLAUDE.md's central gotcha: a thread that stops takes its From d619acabc05bcd34847fa915dd628273372765c5 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Mon, 24 Aug 2026 19:56:52 +0800 Subject: [PATCH 069/147] herdr-panes: the help text names the key the widget has `--help` said "toggle that section with o". The Rust widget answers to i, and has since 083f088 renamed the keys after what they toggle; o reaches nothing at all. herdr-panes.py keeps o and its own help still says so. Found by sweeping every help file against the key arms of the widget beside it, which turned up this and nothing else at the time. This is what 747a407's new check tests for, and it was passing only because the fix was sitting uncommitted in the working tree beside it - a clean checkout of that commit fails it. Green again now. --- rust/widgets/src/bin/herdr-panes_help.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rust/widgets/src/bin/herdr-panes_help.txt b/rust/widgets/src/bin/herdr-panes_help.txt index 762d48a..d3ab4a0 100644 --- a/rust/widgets/src/bin/herdr-panes_help.txt +++ b/rust/widgets/src/bin/herdr-panes_help.txt @@ -5,7 +5,7 @@ Herdr reports, ordered so the ones wanting a human come first. PROCESSES lists every other pane that is actually running something — dev servers, monitors, builds — with what it is running and what it costs. IDLE lists the panes sitting at a shell prompt, by directory, so they can still be jumped to; -toggle that section with o. +toggle that section with i. Enter jumps to whatever is selected: the agent's pane, or the tab holding that process. From 6b9785483bf398fef682ab3b97220d2bb2b272c5 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Mon, 24 Aug 2026 19:59:26 +0800 Subject: [PATCH 070/147] widgets: one section rule, in one place, and linear obeys it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The rule is: tab focuses the next section and, from the last, leaves; sections with nothing in them are stepped over; the arrows move a cursor inside the focused section and leave it by walking off either end; the screen opens with no cursor anywhere. netwatch had it. linear had a private variant that broke every part of it. Its `focus` was a bare usize, so "no focus" was unrepresentable: the board opened with a cursor already sitting on the cycles pane, and tab toggled between the two panes for ever with no way to put the cursor away. The arrows clamped at both ends instead of leaving. Empty panes could be focused, and because the clamp is skipped when a pane is empty, the arrows there moved an index nothing was drawn from - dead keys that said nothing. Its footer said "↑↓ scroll". Nothing on that board scrolls: the arrows move a cursor and both panes window themselves around it. The help text said "up/down select a team", which was wrong in the other direction, since the board opened focused on the cycles pane. linear has no screen scroll to hand the arrows to when nothing is focused, so from there they step into the near end of the first pane with rows - the ring latency and link already use, rather than a key that does nothing. The rule now lives in toys-core as next_section and step_in_section, and both widgets call it. Two hand-written copies cannot keep the promise the docs make, which is that this is the same rule everywhere; one function with its own tests can. The tests cover what the copies got wrong: the last section leads out rather than back to the first, a run of empty sections is stepped over, a section of one leaves in both directions, and a cursor left beyond a section that shrank under it leaves rather than walking up a list that is no longer there. The audit behind this: linear was the only widget with genuine focusable sections besides netwatch. herdr-panes draws three groups but shares one flat index across them, and usage's tab switches top-level agent views with no cursor to focus - neither is a section screen, and neither should be made one. The other nine widgets are single lists. netwatch verified on a live pane after the refactor: opens unfocused, tab rings the three lists and then leaves, walking off either end leaves. linear cannot be run here - it needs a Linear key - so its share of the behaviour is the core tests plus the call sites. --- docs/linear.md | 21 ++++--- rust/core/src/lib.rs | 88 ++++++++++++++++++++++++++++ rust/widgets/src/bin/linear.rs | 73 +++++++++++++++++++---- rust/widgets/src/bin/linear_help.txt | 5 +- rust/widgets/src/bin/netwatch.rs | 39 ++++++------ 5 files changed, 186 insertions(+), 40 deletions(-) diff --git a/docs/linear.md b/docs/linear.md index 5c5d340..79b14ef 100644 --- a/docs/linear.md +++ b/docs/linear.md @@ -110,8 +110,8 @@ down, one bar per day, both directions on a shared scale. Read together they say whether the queue is filling faster than it drains. In the board above, 297 created against 88 completed. -**By team** — ranked by open volume, scrolling when focused and there are more -teams than rows. `DONE14D` follows the window. +**By team** — ranked by open volume, windowing around the cursor when focused +and there are more teams than rows. `DONE14D` follows the window. ## Cost @@ -132,14 +132,21 @@ reporting a smaller number. ## Keys -Two sections scroll — the cycles and the team table — so the arrows need to -know which one they are in. `tab` moves the focus, and the focused heading says -so by carrying the `↑↓` marker and its visible range. +The board opens with no cursor anywhere — it is a thing to read before it is a +thing to work. `tab` focuses a pane, and the focused heading says so by +carrying the `↑↓` marker and its visible range; `↑` `↓` then move a cursor +through that pane, which windows itself around it. + +You leave a pane by walking off either end of it — `↑` on its first row or `↓` +on its last — or by pressing `tab` again, which moves to the other pane and, +from the last one, back to no focus. Panes with nothing in them are stepped +over rather than focused. **This is the same rule in every widget here that +has focusable sections.** | Key | Action | |---|---| -| `tab` | move focus between the cycles and the team table | -| `↑` `↓` | scroll the focused section | +| `tab` | focus the next pane, and from the last one back to no focus | +| `↑` `↓` | move the cursor in the focused pane, or step into one when none is focused | | `w` | cycle the window — 7 / 14 / 30 / 60 / 90 days | | `r` | refresh now | | `q` | quit | diff --git a/rust/core/src/lib.rs b/rust/core/src/lib.rs index 3e10a43..1a4ee48 100644 --- a/rust/core/src/lib.rs +++ b/rust/core/src/lib.rs @@ -725,6 +725,44 @@ pub fn cycle<T: PartialEq + Copy>(choices: &[T], current: T) -> T { } } +/// Where `tab` goes next, on the rule every widget with focusable sections +/// follows. +/// +/// `lens` is how long each section is right now. Focus moves to the next +/// section after the current one and, from the last, off the end to `None` - +/// so there is a way to put the cursor away, which a ring that only cycles +/// between the sections does not give you. +/// +/// Empty sections are stepped over. A section with no rows is not a place +/// you can be: focusing one leaves the arrows moving an index nothing is +/// drawn from and a footer offering "select" over nothing, which reads as a +/// key that has stopped working. From `None`, this is also how you find the +/// first section worth entering. +pub fn next_section(focus: Option<usize>, lens: &[usize]) -> Option<usize> { + let from = focus.map_or(0, |at| at + 1); + (from..lens.len()).find(|&at| lens[at] > 0) +} + +/// One step of the cursor inside a focused section. +/// +/// `Some(row)` is where it lands; `None` means it walked off the end and the +/// section is left. Together with `next_section` this is the whole rule: +/// leave a section by walking off either end of it, or by pressing tab +/// again. +/// +/// A section that empties under the cursor leaves in either direction, and +/// so does a cursor left beyond the end of one, rather than wandering up a +/// list that is no longer there. +pub fn step_in_section(at: usize, len: usize, down: bool) -> Option<usize> { + if down { + if at + 1 >= len { None } else { Some(at + 1) } + } else if at == 0 || at >= len { + None + } else { + Some(at - 1) + } +} + /// A placeholder bar with a highlight sweeping across it. /// /// For values that are being refetched: showing the previous number while a @@ -1105,6 +1143,56 @@ pub fn maybe_help(doc: &str) { #[cfg(test)] mod tests { + // The rule every widget with focusable sections follows. It is tested + // here rather than in each widget because "the same rule everywhere" is + // a claim two hand-written copies cannot keep. + + #[test] + fn tab_walks_the_sections_and_then_off_the_end() { + let lens = [3usize, 2, 4]; + assert_eq!(next_section(None, &lens), Some(0), "opens into the first"); + assert_eq!(next_section(Some(0), &lens), Some(1)); + assert_eq!(next_section(Some(1), &lens), Some(2)); + assert_eq!( + next_section(Some(2), &lens), + None, + "the last section leads out, not back to the first" + ); + } + + #[test] + fn tab_steps_over_sections_with_nothing_in_them() { + // The middle one is empty: focusing it would offer "select" over + // nothing and the next arrow would silently leave again. + assert_eq!(next_section(Some(0), &[3, 0, 4]), Some(2)); + assert_eq!(next_section(None, &[0, 0, 4]), Some(2), "skips a run of them"); + assert_eq!(next_section(Some(0), &[3, 0, 0]), None, "nothing left to enter"); + assert_eq!(next_section(None, &[0, 0, 0]), None, "an empty screen has nowhere to go"); + } + + #[test] + fn walking_off_either_end_of_a_section_leaves_it() { + assert_eq!(step_in_section(1, 3, false), Some(0)); + assert_eq!(step_in_section(0, 3, false), None, "up on the first row leaves"); + assert_eq!(step_in_section(1, 3, true), Some(2)); + assert_eq!(step_in_section(2, 3, true), None, "down on the last row leaves"); + } + + #[test] + fn a_section_of_one_leaves_in_both_directions() { + assert_eq!(step_in_section(0, 1, false), None); + assert_eq!(step_in_section(0, 1, true), None); + } + + #[test] + fn a_cursor_left_beyond_a_shrunken_section_leaves() { + // Sections are rebuilt every frame and can shrink under the cursor. + assert_eq!(step_in_section(0, 0, true), None); + assert_eq!(step_in_section(0, 0, false), None); + assert_eq!(step_in_section(7, 3, false), None, "not a walk up a list that is gone"); + assert_eq!(step_in_section(7, 3, true), None); + } + /// One more hint costs at most one more line. /// /// netwatch's detail screen leans on this: it sizes the body against the diff --git a/rust/widgets/src/bin/linear.rs b/rust/widgets/src/bin/linear.rs index b4f9552..2327c0b 100644 --- a/rust/widgets/src/bin/linear.rs +++ b/rust/widgets/src/bin/linear.rs @@ -645,11 +645,23 @@ fn main() { tc::setup(); let mut keyboard = tc::Keyboard::new(); - // Two sections scroll, so the arrows need to know which one they are - // in. Tab moves the focus; the focused heading says so. + // Two sections take the arrows, so they need to know which one they + // are in. Tab moves the focus; the focused heading says so. + // + // None is a real state, not a missing value: the board opens with no + // cursor anywhere, because it is a thing to read before it is a thing + // to work, and a cursor sitting somewhere you did not put it is a + // question rather than an answer. It also used to open on the cycles + // pane while the footer said the arrows scrolled, which was wrong + // twice over. let (cycles_pane, teams_pane) = (0usize, 1usize); - let mut focus = cycles_pane; + let mut focus: Option<usize> = None; let mut sel = [0usize, 0usize]; + // How long each pane was when it was last drawn. The keys are read + // before the frame is built, so walking off the end of a pane has to be + // judged against the length it had a moment ago - which is the length + // the reader is looking at. + let mut pane_len = [0usize, 0usize]; let mut tick = 0usize; let mut settle_t = 0usize; let mut settle_from: Option<(Vec<f64>, Vec<f64>)> = None; @@ -680,9 +692,37 @@ fn main() { cond.notify_all(); } } - "tab" => focus = if focus == cycles_pane { teams_pane } else { cycles_pane }, - "up" => sel[focus] = sel[focus].saturating_sub(1), - "down" => sel[focus] += 1, + // The rule every widget here with focusable sections + // follows. tab moves to the next pane and, from the last + // one, back to no focus at all - it used to toggle between + // the two for ever, so there was no way to put the cursor + // away. Empty panes are stepped over: focusing one leaves + // the arrows moving an index nothing is drawn from, which + // is a key that does nothing and says nothing. + "tab" => focus = tc::next_section(focus, &pane_len), + // Walking off either end of a pane leaves it. There is no + // screen scroll here to hand the arrows to - both panes + // window themselves to fit - so from nothing focused they + // step back in at the near end, the same ring latency and + // link use. + "up" | "down" => { + let down = key == "down"; + focus = match focus { + Some(here) => tc::step_in_section(sel[here], pane_len[here], down) + .map(|row| { + sel[here] = row; + here + }), + // Nothing focused, and no screen scroll to hand the + // arrows to - both panes window themselves. They + // step into the near end of the first pane that has + // rows, so the ring closes the way latency's does. + None => tc::next_section(None, &pane_len).map(|here| { + sel[here] = if down { 0 } else { pane_len[here] - 1 }; + here + }), + } + } _ => {} } } @@ -851,6 +891,7 @@ fn main() { let (bm, bl) = churn(b); am.total_cmp(&bm).then(al.cmp(&bl)) }); + pane_len[cycles_pane] = ranked_cycles.len(); if !ranked_cycles.is_empty() { sel[cycles_pane] = sel[cycles_pane].min(ranked_cycles.len() - 1); } @@ -862,7 +903,7 @@ fn main() { } else { 0 }; - let here_now = focus == cycles_pane; + let here_now = focus == Some(cycles_pane); rows.push(tc::seg( &[ ( @@ -911,7 +952,7 @@ fn main() { n => n, } ); - let on = focus == cycles_pane && ci == sel[cycles_pane]; + let on = focus == Some(cycles_pane) && ci == sel[cycles_pane]; let tint = if on { tc::bg(38, 56, 76) } else { String::new() }; let c_of = |colour: &str| format!("{}{}", tint, colour); let hot = tc::heat(frac); @@ -1118,6 +1159,7 @@ fn main() { }; open(&b.0).cmp(&open(&a.0)).then(a.0.cmp(&b.0)) }); + pane_len[teams_pane] = ranked.len(); if !ranked.is_empty() { sel[teams_pane] = sel[teams_pane].min(ranked.len() - 1); } @@ -1127,7 +1169,7 @@ fn main() { } else { 0 }; - let on_teams = focus == teams_pane; + let on_teams = focus == Some(teams_pane); rows.push(tc::seg( &[ ( @@ -1208,8 +1250,17 @@ fn main() { drop(s); let hints: Vec<Vec<(&str, String)>> = vec![ - vec![(p.accent.as_str(), "↑↓".into()), (p.dim.as_str(), " scroll".into())], - vec![(p.dim.as_str(), "[tab] section".into())], + // Not "scroll": nothing on this board scrolls. The arrows move + // a cursor through whichever pane has the focus, and both panes + // window themselves around it. + vec![(p.accent.as_str(), "↑↓".into()), (p.dim.as_str(), " select".into())], + vec![ + (p.accent.as_str(), "tab".into()), + ( + p.dim.as_str(), + if focus.is_some() { " next pane" } else { " into a pane" }.to_string(), + ), + ], vec![(p.dim.as_str(), "[w]indow".into())], vec![(p.dim.as_str(), "[r]efresh".into())], vec![(p.dim.as_str(), "[q]uit".into())], diff --git a/rust/widgets/src/bin/linear_help.txt b/rust/widgets/src/bin/linear_help.txt index d423609..e31784b 100644 --- a/rust/widgets/src/bin/linear_help.txt +++ b/rust/widgets/src/bin/linear_help.txt @@ -16,5 +16,6 @@ Credentials: `linear.token` in config.json, or $LINEAR_API_KEY. A personal API key from Settings - Security & access - Personal API keys. The API is called directly, so no CLI is required. -Keys: up/down select a team, r refreshes now, w cycles the window -(7/14/30/60/90 days), q quits. +Keys: tab focuses a pane — the cycles, then the teams, then no focus at all — +and up/down move the cursor in whichever is focused, leaving it if you walk off +either end. r refreshes now, w cycles the window (7/14/30/60/90 days), q quits. diff --git a/rust/widgets/src/bin/netwatch.rs b/rust/widgets/src/bin/netwatch.rs index 8472566..65701df 100644 --- a/rust/widgets/src/bin/netwatch.rs +++ b/rust/widgets/src/bin/netwatch.rs @@ -1717,20 +1717,27 @@ fn main() { // Focused into a section, up and down move between its // rows; otherwise they move the screen. Whichever is in // front of you is what they act on, which is the same - // rule the list screen follows. - // Walking off either end of a section leaves it, the - // same ring the target list uses: focus is left the way - // it was entered rather than needing a key of its own. + // rule the list screen follows. Walking off either end + // leaves the section - `step_in_section` returning None + // is what "walked off" looks like. "up" | "k" | "K" => match focus { - Some(at_focus) if at[at_focus] == 0 => focus = None, - Some(at_focus) => at[at_focus] -= 1, + Some(here) => { + focus = tc::step_in_section(at[here], section_len[here], false) + .map(|row| { + at[here] = row; + here + }); + } None => dscroll = dscroll.saturating_sub(1), }, "down" | "j" | "J" => match focus { - Some(at_focus) if at[at_focus] + 1 >= section_len[at_focus] => { - focus = None + Some(here) => { + focus = tc::step_in_section(at[here], section_len[here], true) + .map(|row| { + at[here] = row; + here + }); } - Some(at_focus) => at[at_focus] += 1, None => dscroll = dscroll.saturating_add(1), }, // The pane height is read here rather than carried, @@ -1750,17 +1757,9 @@ fn main() { // straight to two of the three, which meant three keys // for one job and a section heading advertising a letter // of its own - and no key at all for the middle one. - // Round the lists and then off the end, back to nothing - // focused. - // - // Empty ones are stepped over. A section with no rows is - // not a place you can be: tab onto "0 files" and the - // footer offers "↑↓ select" over nothing, the next arrow - // silently leaves again, and the key reads as broken. - "tab" => { - let from = focus.map_or(0, |at| at + 1); - focus = (from..SECTIONS.len()).find(|&at| section_len[at] > 0); - } + // Where it goes, and which sections it steps over, is + // toys-core's rule rather than this widget's. + "tab" => focus = tc::next_section(focus, §ion_len), "c" | "C" => { if !pending_copy.is_empty() { // The value goes in the message either way: OSC From f718b7820add59ee65c4356866bcbbc0f9cd1230 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Mon, 24 Aug 2026 20:04:21 +0800 Subject: [PATCH 071/147] herdr-panes: the idle section could not be reached on a busy machine MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The running-process loop budgeted up to h-2 and the idle loop then checked the same h-2, so once processes filled the pane the idle heading was pushed past the bottom and truncated away. Measured on this machine, 13 agents and 15 running panes: "── IDLE" appeared zero times at 24 and 40 rows. The footer went on offering [i]dle the whole time, so the key read as broken rather than as a pane with no room left. Room is claimed before the running list spends it rather than after, and the heading is budgeted like every other line instead of being pushed unconditionally. Below the height where a blank, a heading and one pane will fit, the section still cannot be drawn - but the count can, in one line, saying how many are at a prompt and that the pane is too short to list them. Dropping it silently is what made the key look broken; a line that says why costs almost nothing and keeps the only part that was load-bearing. Now present at every height: the full section from 40 rows up, the one-line count at 24 and 30, where there was nothing at all before. Found by the other session while auditing the widgets for the section rule. Tracked as TOY-34. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/widgets/src/bin/herdr-panes.rs | 36 +++++++++++++++++++++++++++-- 1 file changed, 34 insertions(+), 2 deletions(-) diff --git a/rust/widgets/src/bin/herdr-panes.rs b/rust/widgets/src/bin/herdr-panes.rs index 691f670..ead1fa2 100644 --- a/rust/widgets/src/bin/herdr-panes.rs +++ b/rust/widgets/src/bin/herdr-panes.rs @@ -778,8 +778,15 @@ fn main() { w - 1, )); } + // The idle section is claimed before the running list spends the + // pane, not after. It used to be filled up to the same h-2 the + // idle loop then checked, so on a busy machine the heading was + // pushed past the bottom and truncated - while the header counted + // the panes and the footer offered the key to reveal them. + let idle_room = if show_idle && !resting.is_empty() { 3 } else { 0 }; + let running_budget = h.saturating_sub(2 + idle_room); for (j, n) in running.iter().enumerate() { - if rows.len() >= h.saturating_sub(2) { + if rows.len() >= running_budget { break; } let here = agents.len() + j == selected; @@ -821,7 +828,32 @@ fn main() { )); } - if show_idle && !resting.is_empty() { + // Two lines for the blank and the heading, one for a pane. Below + // that the section cannot be drawn, but the count still can: one + // line saying how many are there and that the pane is too short to + // list them, rather than nothing at all under a footer still + // offering the key. + if show_idle + && !resting.is_empty() + && rows.len() + 3 > h.saturating_sub(2) + && rows.len() < h.saturating_sub(2) + { + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── IDLE ── ".into()), + ( + p.dim.as_str(), + format!( + "{} pane{} at a prompt, too short to list", + resting.len(), + plural(resting.len()) + ), + ), + ], + w - 1, + )); + } + if show_idle && !resting.is_empty() && rows.len() + 3 <= h.saturating_sub(2) { rows.push(String::new()); rows.push(tc::seg( &[ From 1430933331291f340e498f63c6f5edb7a499e8f4 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Mon, 24 Aug 2026 20:04:43 +0800 Subject: [PATCH 072/147] AGENTS.md: a new check is green against your tree, not against the repo 747a407 added a check that reads the help texts and shipped it passing. It failed on a clean checkout of its own commit: the stale line it was written to catch - herdr-panes_help.txt naming a key the widget had stopped answering to - had already been corrected in another session's uncommitted tree, so the check was measured against the fix rather than against the repo. Caught by the other session, who stashed and re-ran against HEAD alone. Nothing was wrong with the check. What was wrong was believing a green run in a shared checkout, and it is not a two-session problem: the same thing happens alone whenever a check is written next to the fix that motivated it, which is most of the time. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- AGENTS.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 672aeae..06c32f3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -108,6 +108,12 @@ impossible. added line before a push is right and still misses half the rule, because the rule covers code, docs *and* messages, and a message is not a diff line. Scan `git log origin/main..HEAD` separately. +- **A new check is green against your working tree, not against the repo.** + A check written beside an uncommitted fix is measured against the fix. One + shipped passing here and failed on a clean checkout of its own commit, + because the stale line it was written to catch had already been corrected + in another session's dirty tree. Run a new check against `HEAD` — stash, + or `git show HEAD:<path>` the files it reads — before believing it. - **The commit that removes a secret is the likeliest place to restate it.** "The fixture used `<the actual name>`, which is a device on this tailnet" is the most natural sentence to write when documenting the fix, and it From 4a9defeb744a1ec2a82e6aef6bc836d699f638dc Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Mon, 24 Aug 2026 20:12:54 +0800 Subject: [PATCH 073/147] herdr-panes: name the idle-section decision, and test it at every height TOY-34 asked for a test across heights so this cannot regress into "there is no data", and f718b78 did not deliver one - it was verified by driving a pty and reading the screen, which proves the fix and guards nothing. The arithmetic was three conditions spread through the draw loop, which is why the original fault was invisible: there was nothing to look at but the loops, and the bug was that two of them budgeted against the same bound. It is now idle_fit(h, used, show, resting) returning Full, CountOnly or Nothing, and the loop asks it rather than re-deriving it twice. The test that matters walks every height from 6 to 80 and every number of rows already used, and asserts that with idle panes to show the answer is never Nothing. Silence is correct in exactly two cases - the key has hidden the section, or there are no idle panes - and those have their own test. A third pins the boundary and one row either side of it. Checked by mutation rather than by assuming: removing the CountOnly branch fails two of the three, which is the shape the bug had. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- rust/widgets/src/bin/herdr-panes.rs | 87 ++++++++++++++++++++++++++--- 1 file changed, 80 insertions(+), 7 deletions(-) diff --git a/rust/widgets/src/bin/herdr-panes.rs b/rust/widgets/src/bin/herdr-panes.rs index ead1fa2..f49a36d 100644 --- a/rust/widgets/src/bin/herdr-panes.rs +++ b/rust/widgets/src/bin/herdr-panes.rs @@ -151,6 +151,40 @@ struct Agent { rss: Option<u64>, } +/// What the idle section gets, once the lists above it have been drawn. +/// +/// The three sections used to budget against the same bound, so the +/// running list could spend the whole pane and the idle heading was pushed +/// past the bottom and truncated - leaving the footer offering a key with +/// nothing behind it. +#[derive(PartialEq, Eq, Debug, Clone, Copy)] +enum IdleFit { + /// Heading, blank line and at least one pane. + Full, + /// No room to list them, but room to say how many there are. Dropping + /// the section silently is what made the key look broken. + CountOnly, + /// Not even one line: the pane is shorter than the lists above it. + Nothing, +} + +/// How many rows the full section needs: a blank, a heading, and a pane. +const IDLE_ROWS: usize = 3; + +fn idle_fit(h: usize, used: usize, show: bool, resting: usize) -> IdleFit { + if !show || resting == 0 { + return IdleFit::Nothing; + } + let body = h.saturating_sub(2); + if used + IDLE_ROWS <= body { + IdleFit::Full + } else if used < body { + IdleFit::CountOnly + } else { + IdleFit::Nothing + } +} + /// A pane with no agent in it: either running something, or at a prompt. #[derive(Clone, Default)] struct Panel { @@ -783,7 +817,7 @@ fn main() { // idle loop then checked, so on a busy machine the heading was // pushed past the bottom and truncated - while the header counted // the panes and the footer offered the key to reveal them. - let idle_room = if show_idle && !resting.is_empty() { 3 } else { 0 }; + let idle_room = if show_idle && !resting.is_empty() { IDLE_ROWS } else { 0 }; let running_budget = h.saturating_sub(2 + idle_room); for (j, n) in running.iter().enumerate() { if rows.len() >= running_budget { @@ -833,11 +867,7 @@ fn main() { // line saying how many are there and that the pane is too short to // list them, rather than nothing at all under a footer still // offering the key. - if show_idle - && !resting.is_empty() - && rows.len() + 3 > h.saturating_sub(2) - && rows.len() < h.saturating_sub(2) - { + if idle_fit(h, rows.len(), show_idle, resting.len()) == IdleFit::CountOnly { rows.push(tc::seg( &[ (p.lbl.as_str(), " ── IDLE ── ".into()), @@ -853,7 +883,7 @@ fn main() { w - 1, )); } - if show_idle && !resting.is_empty() && rows.len() + 3 <= h.saturating_sub(2) { + if idle_fit(h, rows.len(), show_idle, resting.len()) == IdleFit::Full { rows.push(String::new()); rows.push(tc::seg( &[ @@ -944,6 +974,49 @@ fn plural(n: usize) -> &'static str { mod tests { use super::*; + #[test] + fn the_idle_section_is_never_silently_absent() { + // The bug this replaces: the running list budgeted the whole pane + // and the idle heading was then pushed past the bottom, so the + // section vanished while the footer still offered its key. At + // every height, with idle panes to show, the answer must be + // something the reader can see - the full section, or the count + // saying why the rest is missing. + for h in 6usize..80 { + let body = h.saturating_sub(2); + for used in 0..body { + let got = idle_fit(h, used, true, 9); + assert_ne!( + got, + IdleFit::Nothing, + "h={} with {} rows used and 9 panes idle says nothing at all", + h, + used + ); + } + } + } + + #[test] + fn the_full_section_needs_a_heading_a_blank_and_a_pane() { + // Exactly at the boundary, and one row either side of it. + let h = 40; + let body = h - 2; + assert_eq!(idle_fit(h, body - IDLE_ROWS, true, 9), IdleFit::Full); + assert_eq!(idle_fit(h, body - IDLE_ROWS + 1, true, 9), IdleFit::CountOnly); + assert_eq!(idle_fit(h, body - 1, true, 9), IdleFit::CountOnly); + assert_eq!(idle_fit(h, body, true, 9), IdleFit::Nothing); + } + + #[test] + fn nothing_is_drawn_when_there_is_nothing_to_say() { + // Hidden by the key, or no idle panes at all: silence is correct + // here, and is the only case where it is. + assert_eq!(idle_fit(60, 0, false, 9), IdleFit::Nothing); + assert_eq!(idle_fit(60, 0, true, 0), IdleFit::Nothing); + } + + #[test] fn a_runner_gives_way_to_the_script_it_was_handed() { // "python3" and "node" say nothing about what a pane is doing. From 15f649ccc42f46f2bdb8bdfe21c85425661b1e8b Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Mon, 24 Aug 2026 20:13:19 +0800 Subject: [PATCH 074/147] AGENTS.md: a grep that finds nothing is as often a wrong pattern The most repeated mistake of the Rust port, on both sides of it, and always read as evidence of absence rather than as a broken pattern: - a footer-key check whose [a-z0-9]+ could not match the uppercase half of "q" | "Q", reporting 48 widgets broken when every one was correct; - a config audit that read line by line and so skipped every multi-line cfg\n.get(...) chain, which is most of them - it never examined four of clocks' keys at all; - another that assumed the config variable is named cfg, declaring six keys unread that are reached through &gh and &raw; - a claim that netwatch ignored two config keys, from grepping only for tc::cfg_* when it reads them through cfg.get(). The fix is one habit: run the pattern against a case you know it should match before believing a zero. Every one of these took longer to find than that check would have taken to write. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- AGENTS.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 06c32f3..5052d9c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -108,6 +108,15 @@ impossible. added line before a push is right and still misses half the rule, because the rule covers code, docs *and* messages, and a message is not a diff line. Scan `git log origin/main..HEAD` separately. +- **A grep that finds nothing is as often a wrong pattern as an absent + thing.** This was the most repeated mistake of the Rust port, on both + sides: `[a-z0-9]+` could not match the uppercase half of `"q" | "Q"` and + reported 48 widgets broken; a config audit read line by line and silently + skipped every multi-line `cfg\n.get(...)` chain, which is most of them; + another assumed the config variable was named `cfg` and declared six keys + unread that are reached through `&gh` and `&raw`; a claim that netwatch + ignored two keys came from grepping only for `tc::cfg_*`. Before believing + a zero, run the pattern against a case you know it should match. - **A new check is green against your working tree, not against the repo.** A check written beside an uncommitted fix is measured against the fix. One shipped passing here and failed on a clean checkout of its own commit, From 9649f8b34b7807fd214cb5ad8f9112f71d7bd0b6 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Mon, 24 Aug 2026 22:08:27 +0800 Subject: [PATCH 075/147] netwatch: the process cursor could walk off the screen MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The main list drew rows 0..show and never anything else, while the cursor was clamped only against the whole list. On any pane too short for every process the cursor walked past the last drawn row and vanished: no ▸ anywhere, nothing to say where it had gone, and → still opened whatever it was invisibly sitting on. Measured before the fix, on this machine: pane 24 rows 7 rows drawn 24 processes cursor gone after 8 downs pane 34 rows 15 rows drawn 30 processes cursor gone after 16 pane 50 rows 26 rows drawn 26 processes never - all of them fit So it bit at every pane height in use here, one step past the last visible row. The window now follows the cursor, which is what the detail screen has always done and what github's account list does. Once it does, clamping at the bottom is right rather than a compromise: the end of the list is the end of the list, and there is no off-screen state left to reach. The header says when the table is short of the whole list - "27 processes · showing 9-22" - and says nothing when every process fits. "27 processes" above a table of fifteen is a partial result presented as a total, which is the one thing a number here must never be, and it had been doing that for as long as the widget has had more processes than rows. The count line is now filled in after the window is known rather than written where it appears. It is one row tall whatever it says, so nothing below it moves - the alternative was computing how many rows fit before knowing how tall the header was, which is the arithmetic that goes wrong. The test walks every cursor position for five list lengths against five pane depths and asserts exactly one drawn row carries the cursor, and that it is the row it claims to be. Reverting the skip() makes it fail at total=5 show=1 selected=1, which is the smallest case that ever showed the bug. --- docs/netwatch.md | 9 +++ rust/widgets/src/bin/netwatch.rs | 116 +++++++++++++++++++++++++++---- 2 files changed, 112 insertions(+), 13 deletions(-) diff --git a/docs/netwatch.md b/docs/netwatch.md index cf305f7..44988e0 100644 --- a/docs/netwatch.md +++ b/docs/netwatch.md @@ -181,6 +181,15 @@ interfaces actually moved. When they agree, the list below is the whole picture. When they do not, the difference is traffic passing through, and the percentage says how much of the story the table is telling. +There is a second way the table can be showing less than everything, and it +says so too. When there are more processes than rows, the header adds +**`showing 1-14`** beside the count, and the table follows the cursor rather +than staying at the top of the list — so `↑` `↓` scroll it, and the selected +row is always on screen. Without the window the cursor walked off the bottom +of a short pane and disappeared, while `→` still opened whatever it was +invisibly sitting on. The label is absent when every process fits, because +then there is nothing to say. + Only real interfaces are counted — loopback, `tailscale0`, `docker0`, bridges and veth pairs are skipped, because a forwarded packet leaves through a card as well and counting both would count it twice. Which ones were counted is diff --git a/rust/widgets/src/bin/netwatch.rs b/rust/widgets/src/bin/netwatch.rs index 65701df..06dc5f1 100644 --- a/rust/widgets/src/bin/netwatch.rs +++ b/rust/widgets/src/bin/netwatch.rs @@ -1981,17 +1981,15 @@ fn main() { let up: f64 = rows.iter().map(|r| r.up_rate).sum(); let mut out = vec![tc::title("netwatch", w, &p.accent)]; + // Held open. What this line has to say depends on how many rows fit, + // which is not known until the chart above the table has been built - + // but the line is one row tall whatever it ends up saying, so nothing + // below it moves. + let count_at = out.len(); + out.push(String::new()); out.push(tc::seg( &[ - ( - p.dim.as_str(), - format!( - " {} process{}", - rows.len(), - if rows.len() == 1 { "" } else { "es" } - ), - ), - (p.dim.as_str(), format!(" · {} moving", moving)), + (p.dim.as_str(), format!(" {} moving", moving)), (p.dim.as_str(), " · ".into()), (p.accent.as_str(), elapsed(now() - guard.started)), (p.dim.as_str(), " · sorted by ".into()), @@ -2099,6 +2097,42 @@ fn main() { let room = h.saturating_sub(out.len() + 3).max(1); let show = if limit > 0 { limit.min(room) } else { room }; + // The window follows the cursor, as it does in the detail screen and + // in github's account list. It did not before: the table always drew + // rows 0..show while the cursor was free to walk to the end of the + // list, so on any pane too short for every process the cursor left + // the screen and there was nothing to say where it had gone - and + // enter still opened whatever it was sitting on, unseen. + let first = if rows.len() > show { + selected.saturating_sub(show / 2).min(rows.len() - show) + } else { + 0 + }; + // And the count says so. "27 processes" above a table of 15 is a + // partial result presented as a total, which is the one thing a + // number here must never be. + let last = (first + show).min(rows.len()); + out[count_at] = tc::seg( + &[ + ( + p.dim.as_str(), + format!( + " {} process{}", + rows.len(), + if rows.len() == 1 { "" } else { "es" } + ), + ), + ( + if rows.len() > show { p.accent.as_str() } else { p.dim.as_str() }, + if rows.len() > show { + format!(" · showing {}-{}", first + 1, last) + } else { + String::new() + }, + ), + ], + w - 1, + ); if rows.is_empty() { out.push(tc::seg( &[( @@ -2108,7 +2142,7 @@ fn main() { w - 1, )); } else { - out.extend(table(&rows, w, show, selected, &p)); + out.extend(table(&rows, w, first, show, selected, &p)); } let hints: Vec<Vec<(&str, String)>> = vec![ @@ -2217,7 +2251,14 @@ fn chart(series: &[(f64, f64)], w: usize, h: usize, p: &Palette) -> Vec<String> } /// The process table, dropping columns rather than clipping them. -fn table(rows: &[Proc], w: usize, limit: usize, selected: usize, p: &Palette) -> Vec<String> { +fn table( + rows: &[Proc], + w: usize, + first: usize, + limit: usize, + selected: usize, + p: &Palette, +) -> Vec<String> { let avail = (w - 1).saturating_sub(2 + 8 + 11); let wide = avail >= 10 + 11 + 22; let mid = avail >= 10 + 11; @@ -2239,10 +2280,10 @@ fn table(rows: &[Proc], w: usize, limit: usize, selected: usize, p: &Palette) -> } let mut out = vec![tc::seg(&head, w - 1)]; - for (i, row) in rows.iter().take(limit).enumerate() { + for (i, row) in rows.iter().skip(first).take(limit).enumerate() { let live = row.up_rate + row.down_rate; let total = (row.up + row.down) as f64; - let here = i == selected; + let here = first + i == selected; let tint = if here { tc::bg(28, 44, 62) } else { String::new() }; let name_c = format!( "{}{}", @@ -2358,6 +2399,55 @@ mod tests { // columns, not by repeating the arithmetic the row used. A test that // recomputes the widths would agree with a heading that had slipped. + /// The window the main list draws, extracted so the test and the widget + /// cannot disagree about it. + fn window_at(selected: usize, show: usize, total: usize) -> usize { + if total > show { selected.saturating_sub(show / 2).min(total - show) } else { 0 } + } + + #[test] + fn the_process_cursor_is_always_on_the_screen() { + // It was not. The table drew rows 0..show whatever the cursor was + // doing, so on any pane too short for the whole list the cursor + // walked off the bottom and vanished - and enter still opened the + // row it was invisibly sitting on. + let p = palette(); + for total in [1usize, 5, 15, 26, 200] { + let rows: Vec<Proc> = (0..total) + .map(|i| Proc { + pid: 1000 + i as i32, + name: format!("proc-{}", i), + down: 4096, + alive: true, + ..Default::default() + }) + .collect(); + for show in [1usize, 3, 7, 15, 40] { + for selected in 0..total { + let first = window_at(selected, show, total); + let drawn = table(&rows, 120, first, show, selected, &p); + let marked = drawn.iter().filter(|l| bare(l).starts_with('▸')).count(); + assert_eq!( + marked, 1, + "total={} show={} selected={}: {} rows carried the cursor", + total, show, selected, marked + ); + // and it is the row it claims to be + let on = drawn + .iter() + .find(|l| bare(l).starts_with('▸')) + .map(|l| bare(l)) + .unwrap_or_default(); + assert!( + on.contains(&format!("proc-{} ", selected)), + "total={} show={} selected={}: cursor sat on {:?}", + total, show, selected, on.trim() + ); + } + } + } + } + #[test] fn the_endpoint_heading_sits_over_its_columns() { let p = palette(); From 5df02211011cdec18d428b02fa5b1142e94bc2aa Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Mon, 24 Aug 2026 23:07:19 +0800 Subject: [PATCH 076/147] widgets: the sections read as one list under the arrows MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Walking off the end of a section used to let go of the sections entirely, wherever you were. So on a screen with three lists, ↓ off the bottom of the first one stopped the cursor in the middle of the screen for a reason nothing on it could show, and the section directly below - the one your eye was already on - could only be reached with tab. Now ↓ off the bottom of a section steps into the top of the next, and ↑ off the top steps into the bottom of the one above: the row you were about to reach if the lists had never been separate. tab becomes the shortcut across a whole section rather than the only way between them. Two places still let go, and they are the two that mean it: ↑ from the very first row, and ↓ from the very last. tab from the last section does the same. Empty sections are stepped over in both directions now, not just by tab. step_in_section is replaced by step_across_sections, which needs every section's length rather than only the focused one's. One function rather than two, because a rule about what happens at the boundary between sections cannot be written without knowing what is on the other side. The test that matters walks every row of every section downwards and asserts it visited each one once in order, then walks back up and asserts it retraced the same path. Off-by-one at a boundary - landing on the top of the section above instead of its bottom, or skipping its last row - shows up as the two paths disagreeing. Verified on a live pane, on a process with a 1-row section, a 3-row section and an empty one: tab into the first, ↓ crosses to the second, three more move within it, the fourth lets go because the third section is empty and last. Upwards, ↑ from its top row lands on the last row of the one above, and ↑ from there lets go. --- docs/linear.md | 17 ++-- docs/netwatch.md | 18 +++-- rust/core/src/lib.rs | 133 ++++++++++++++++++++++++------- rust/widgets/src/bin/linear.rs | 8 +- rust/widgets/src/bin/netwatch.rs | 28 +++---- 5 files changed, 147 insertions(+), 57 deletions(-) diff --git a/docs/linear.md b/docs/linear.md index 79b14ef..d4060bf 100644 --- a/docs/linear.md +++ b/docs/linear.md @@ -137,16 +137,21 @@ thing to work. `tab` focuses a pane, and the focused heading says so by carrying the `↑↓` marker and its visible range; `↑` `↓` then move a cursor through that pane, which windows itself around it. -You leave a pane by walking off either end of it — `↑` on its first row or `↓` -on its last — or by pressing `tab` again, which moves to the other pane and, -from the last one, back to no focus. Panes with nothing in them are stepped -over rather than focused. **This is the same rule in every widget here that -has focusable sections.** +Under the arrows the two panes read as **one continuous list**: `↓` off the +bottom of the cycles steps into the top of the teams, and `↑` off the top of +the teams steps into the *bottom* of the cycles. `tab` is the shortcut across +a whole pane rather than the only way between them. + +You let go at exactly two places: `↑` from the first cycle, and `↓` from the +last team. `tab` from the last pane does the same. Panes with nothing in them +are stepped over in every direction. + +**This is the same rule in every widget here that has focusable sections.** | Key | Action | |---|---| | `tab` | focus the next pane, and from the last one back to no focus | -| `↑` `↓` | move the cursor in the focused pane, or step into one when none is focused | +| `↑` `↓` | move the cursor, crossing between panes at their ends — or step into one when none is focused | | `w` | cycle the window — 7 / 14 / 30 / 60 / 90 days | | `r` | refresh now | | `q` | quit | diff --git a/docs/netwatch.md b/docs/netwatch.md index 44988e0..bceced9 100644 --- a/docs/netwatch.md +++ b/docs/netwatch.md @@ -318,12 +318,18 @@ Every list is drawn in full, always, and `↑` `↓` scroll the screen. `tab` focuses a list instead: the focused one is marked `▏`, `↑` `↓` then move a cursor `▸` inside it, and `c` copies whatever that cursor is on. -You leave a list by walking off either end of it — `↑` on the first row or -`↓` on the last — or by pressing `tab` again, which moves to the next list -and, from the last one, back to scrolling the screen. Lists with nothing in -them are stepped over rather than focused, since there would be nothing to -put the cursor on. **This is the same rule in every widget here that has -focusable sections.** +Under the arrows the three lists read as **one continuous list**: `↓` off the +bottom of a list steps into the top of the next, and `↑` off the top steps +into the *bottom* of the one above — the row you were about to reach if they +had never been separate. `tab` is the shortcut across a whole list rather +than the only way between them. + +You let go of the lists at exactly two places: `↑` from the very first row, +and `↓` from the very last. Both put you back to scrolling the screen, as +does `tab` from the last list. Lists with nothing in them are stepped over in +every direction, since there would be nothing to put the cursor on. + +**This is the same rule in every widget here that has focusable sections.** **TALKING TO** ranks the remote hosts by what they have carried since launch. Hosts, not sockets: a process opening six connections to one CDN is one thing diff --git a/rust/core/src/lib.rs b/rust/core/src/lib.rs index 1a4ee48..4fc5500 100644 --- a/rust/core/src/lib.rs +++ b/rust/core/src/lib.rs @@ -743,23 +743,42 @@ pub fn next_section(focus: Option<usize>, lens: &[usize]) -> Option<usize> { (from..lens.len()).find(|&at| lens[at] > 0) } -/// One step of the cursor inside a focused section. +/// One step of the cursor when a section has the focus. /// -/// `Some(row)` is where it lands; `None` means it walked off the end and the -/// section is left. Together with `next_section` this is the whole rule: -/// leave a section by walking off either end of it, or by pressing tab -/// again. +/// Returns the section and row it lands on, or `None` when it leaves the +/// sections entirely - which happens at exactly two places: up from the first +/// row of the first section, and down from the last row of the last one. /// -/// A section that empties under the cursor leaves in either direction, and -/// so does a cursor left beyond the end of one, rather than wandering up a -/// list that is no longer there. -pub fn step_in_section(at: usize, len: usize, down: bool) -> Option<usize> { +/// Everywhere else the sections read as one continuous list. Walking off the +/// bottom of a section steps into the top of the next, and walking off the +/// top steps into the *bottom* of the one above - the row you were about to +/// reach if the two had been a single list. Stepping out to nothing in the +/// middle of a screen made the arrows stop for a reason the screen could not +/// show, and left `tab` as the only way to reach a section you were sitting +/// right next to. +/// +/// Empty sections are stepped over in both directions, for the reason +/// `next_section` steps over them. A section that empties under the cursor +/// escapes rather than trapping it. +pub fn step_across_sections( + focus: usize, + at: usize, + lens: &[usize], + down: bool, +) -> Option<(usize, usize)> { + let len = lens.get(focus).copied().unwrap_or(0); if down { - if at + 1 >= len { None } else { Some(at + 1) } - } else if at == 0 || at >= len { - None + if at + 1 < len { + return Some((focus, at + 1)); + } + let next = (focus + 1..lens.len()).find(|&i| lens[i] > 0)?; + Some((next, 0)) } else { - Some(at - 1) + if at > 0 && at < len { + return Some((focus, at - 1)); + } + let above = (0..focus.min(lens.len())).rev().find(|&i| lens[i] > 0)?; + Some((above, lens[above] - 1)) } } @@ -1171,26 +1190,86 @@ mod tests { } #[test] - fn walking_off_either_end_of_a_section_leaves_it() { - assert_eq!(step_in_section(1, 3, false), Some(0)); - assert_eq!(step_in_section(0, 3, false), None, "up on the first row leaves"); - assert_eq!(step_in_section(1, 3, true), Some(2)); - assert_eq!(step_in_section(2, 3, true), None, "down on the last row leaves"); + fn walking_off_a_section_steps_into_the_next_one() { + let lens = [3usize, 2, 4]; + // down, out of the first section and into the top of the second + assert_eq!(step_across_sections(0, 1, &lens, true), Some((0, 2))); + assert_eq!(step_across_sections(0, 2, &lens, true), Some((1, 0))); + // up, out of the second and into the *bottom* of the first - the row + // you were about to reach if the two had been one list + assert_eq!(step_across_sections(1, 1, &lens, false), Some((1, 0))); + assert_eq!(step_across_sections(1, 0, &lens, false), Some((0, 2))); } #[test] - fn a_section_of_one_leaves_in_both_directions() { - assert_eq!(step_in_section(0, 1, false), None); - assert_eq!(step_in_section(0, 1, true), None); + fn only_the_two_far_ends_leave_the_sections() { + let lens = [3usize, 2, 4]; + assert_eq!( + step_across_sections(0, 0, &lens, false), + None, + "up from the first row of the first section" + ); + assert_eq!( + step_across_sections(2, 3, &lens, true), + None, + "down from the last row of the last section" + ); + // and nowhere in between + for (focus, at) in [(0usize, 2usize), (1, 0), (1, 1), (2, 0)] { + assert!( + step_across_sections(focus, at, &lens, true).is_some() + || step_across_sections(focus, at, &lens, false).is_some(), + "section {} row {} had nowhere to go", + focus, + at + ); + } + } + + #[test] + fn a_whole_section_can_be_crossed_in_either_direction() { + // Every row of every section, in order, walking down and back up. + let lens = [2usize, 1, 3]; + let mut seen = vec![(0usize, 0usize)]; + let (mut f, mut a) = (0usize, 0usize); + while let Some((nf, na)) = step_across_sections(f, a, &lens, true) { + seen.push((nf, na)); + f = nf; + a = na; + } + assert_eq!( + seen, + vec![(0, 0), (0, 1), (1, 0), (2, 0), (2, 1), (2, 2)], + "walking down did not visit every row once, in order" + ); + let mut back = vec![(f, a)]; + while let Some((nf, na)) = step_across_sections(f, a, &lens, false) { + back.push((nf, na)); + f = nf; + a = na; + } + back.reverse(); + assert_eq!(back, seen, "walking back up did not retrace the same path"); + } + + #[test] + fn empty_sections_are_stepped_over_in_both_directions() { + assert_eq!(step_across_sections(0, 2, &[3, 0, 4], true), Some((2, 0))); + assert_eq!(step_across_sections(2, 0, &[3, 0, 4], false), Some((0, 2))); + assert_eq!( + step_across_sections(0, 2, &[3, 0, 0], true), + None, + "nothing below but empties" + ); } #[test] - fn a_cursor_left_beyond_a_shrunken_section_leaves() { - // Sections are rebuilt every frame and can shrink under the cursor. - assert_eq!(step_in_section(0, 0, true), None); - assert_eq!(step_in_section(0, 0, false), None); - assert_eq!(step_in_section(7, 3, false), None, "not a walk up a list that is gone"); - assert_eq!(step_in_section(7, 3, true), None); + fn a_section_that_empties_under_the_cursor_escapes() { + // Sections are rebuilt every frame and can shrink or vanish. + assert_eq!(step_across_sections(1, 0, &[3, 0, 4], true), Some((2, 0))); + assert_eq!(step_across_sections(1, 0, &[3, 0, 4], false), Some((0, 2))); + assert_eq!(step_across_sections(0, 7, &[3, 2, 0], false), None); + assert_eq!(step_across_sections(0, 7, &[3, 2, 0], true), Some((1, 0))); } /// One more hint costs at most one more line. diff --git a/rust/widgets/src/bin/linear.rs b/rust/widgets/src/bin/linear.rs index 2327c0b..2d1acc7 100644 --- a/rust/widgets/src/bin/linear.rs +++ b/rust/widgets/src/bin/linear.rs @@ -708,10 +708,10 @@ fn main() { "up" | "down" => { let down = key == "down"; focus = match focus { - Some(here) => tc::step_in_section(sel[here], pane_len[here], down) - .map(|row| { - sel[here] = row; - here + Some(here) => tc::step_across_sections(here, sel[here], &pane_len, down) + .map(|(pane, row)| { + sel[pane] = row; + pane }), // Nothing focused, and no screen scroll to hand the // arrows to - both panes window themselves. They diff --git a/rust/widgets/src/bin/netwatch.rs b/rust/widgets/src/bin/netwatch.rs index 06dc5f1..f796141 100644 --- a/rust/widgets/src/bin/netwatch.rs +++ b/rust/widgets/src/bin/netwatch.rs @@ -1714,28 +1714,28 @@ fn main() { detail = None; sizes.clear(); } - // Focused into a section, up and down move between its - // rows; otherwise they move the screen. Whichever is in - // front of you is what they act on, which is the same - // rule the list screen follows. Walking off either end - // leaves the section - `step_in_section` returning None - // is what "walked off" looks like. + // Focused, up and down walk the three lists as though + // they were one: off the bottom of a section is the top + // of the next, off the top is the bottom of the one + // above. Only the two far ends let go. Unfocused, they + // move the screen. Whichever is in front of you is what + // they act on, which is the rule the list screen follows. "up" | "k" | "K" => match focus { Some(here) => { - focus = tc::step_in_section(at[here], section_len[here], false) - .map(|row| { - at[here] = row; - here + focus = tc::step_across_sections(here, at[here], §ion_len, false) + .map(|(sect, row)| { + at[sect] = row; + sect }); } None => dscroll = dscroll.saturating_sub(1), }, "down" | "j" | "J" => match focus { Some(here) => { - focus = tc::step_in_section(at[here], section_len[here], true) - .map(|row| { - at[here] = row; - here + focus = tc::step_across_sections(here, at[here], §ion_len, true) + .map(|(sect, row)| { + at[sect] = row; + sect }); } None => dscroll = dscroll.saturating_add(1), From 57bb8a101cee21bb0c2e0c128724ee5e0fe83918 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Mon, 24 Aug 2026 23:22:01 +0800 Subject: [PATCH 077/147] start: the menu cursor walked off a short pane MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit rows_for drew all thirteen widgets and the frame cut whatever did not fit, so on a pane with room for six, walking down to the seventh moved the cursor onto a row that was not on screen - nothing highlighted, and Enter still starting whatever it was invisibly sitting on. Measured at 12 rows: gone by the twelfth press. The same pairing the other session found in netwatch and I then found in herdr-panes - a bounded slice drawn next to a cursor clamped against the full length - and invisible on a tall pane, which is why all three survived. herdr-panes is filed as TOY-36 rather than fixed here: it has three interleaved sections over one flat index and wants a deliberate restructure. start is one list and was tractable now. window_for keeps the cursor inside the window and scrolls by one rather than recentring, because a list that jumps loses the reader's place. The count line says "13 widgets · showing 8-13" when it is showing part of the list and stays as it was when the whole list fits, which is every pane size these actually run at. This is the windowing, not the ends. Whether the list should clamp or wrap at its extremes is TOY-35 and William's to settle - the distinction being the other session's, and a good one: a list that does not window is broken, a list that clamps at its end is a choice, and they look identical from a grep. Three tests on window_for: the cursor is inside the window for every combination of room and position, a list that fits is not windowed at all, and the window moves only as far as it must. docs/start.md gains `→`, which has always launched a widget and was never in the key table. My own check caught that, and only because this change added a `·` to the count line - which flipped the string to a footer in the extractor's eyes and made a hint that was always there visible to it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVyXmobqdNzwQTy45b6sUr --- docs/start.md | 2 +- rust/widgets/src/bin/start.rs | 88 +++++++++++++++++++++++++++++++++-- 2 files changed, 86 insertions(+), 4 deletions(-) diff --git a/docs/start.md b/docs/start.md index b311f8a..239edbf 100644 --- a/docs/start.md +++ b/docs/start.md @@ -162,7 +162,7 @@ the middle of a pipeline it adds nothing to. | Key | Action | |---|---| | `↑` `↓` / `j` `k` | select a widget | -| `↵` | launch it, and come back here when it quits | +| `↵` / `→` | launch it, and come back here when it quits | | `r` | recheck what is installed and configured | | `q` | quit | diff --git a/rust/widgets/src/bin/start.rs b/rust/widgets/src/bin/start.rs index 8f3f2ac..429de68 100644 --- a/rust/widgets/src/bin/start.rs +++ b/rust/widgets/src/bin/start.rs @@ -209,7 +209,25 @@ fn palette() -> Palette { } } -fn rows_for(w: usize, selected: usize, p: &Palette) -> Vec<String> { +/// The rows to draw, and where the window sits. +/// +/// Returns the first index shown, so the caller can say what it is +/// showing rather than presenting a slice as the whole list. +fn window_for(count: usize, selected: usize, room: usize) -> (usize, usize) { + if count <= room || room == 0 { + return (0, count); + } + // Keep the cursor inside the window, scrolling only as far as it must: + // a list that jumps to centre the selection loses the reader's place. + let first = if selected < room { + 0 + } else { + (selected + 1).saturating_sub(room) + }; + (first, room) +} + +fn rows_for(w: usize, selected: usize, first: usize, room: usize, p: &Palette) -> Vec<String> { let name_w = (w.saturating_sub(58)).clamp(12, 18); // Every column keeps a space of its own, so a summary that fills its // width stops short of whatever is beside it rather than running in. @@ -217,6 +235,8 @@ fn rows_for(w: usize, selected: usize, p: &Palette) -> Vec<String> { WIDGETS .iter() .enumerate() + .skip(first) + .take(room) .map(|(i, item)| { let here = i == selected; let tint = if here { tc::bg(28, 44, 62) } else { String::new() }; @@ -348,12 +368,33 @@ fn main() { body.push(tc::seg( &[( p.dim.as_str(), - format!(" {} widgets ↵ or → starts one, q leaves", WIDGETS.len()), + { + let room = h.saturating_sub(6).max(1); + let (first, shown) = window_for(WIDGETS.len(), selected, room); + if shown < WIDGETS.len() { + // A partial list says so, rather than reading as + // the whole set with some widgets missing. + format!( + " {} widgets · showing {}-{} ↵ or → starts one, q leaves", + WIDGETS.len(), + first + 1, + first + shown + ) + } else { + format!(" {} widgets ↵ or → starts one, q leaves", WIDGETS.len()) + } + }, )], w - 1, )); body.push(String::new()); - body.extend(rows_for(w, selected, &p)); + // What is left for the list once the title, the two blanks, the + // description heading and the footer have had theirs. Drawing all + // thirteen and letting the frame cut the tail is what put the + // cursor off the bottom of a short pane. + let room = h.saturating_sub(body.len() + 5).max(1); + let (first, shown) = window_for(WIDGETS.len(), selected, room); + body.extend(rows_for(w, selected, first, shown, &p)); body.push(String::new()); // What the highlighted one is for, in its own words - the rest of @@ -429,6 +470,47 @@ fn main() { mod tests { use super::*; + #[test] + fn the_window_always_contains_the_cursor() { + // The bug this replaces: all thirteen rows were drawn and the + // frame cut the tail, so on a short pane the cursor moved onto a + // row that was not there - nothing highlighted, and Enter still + // starting whatever it was invisibly on. + for room in 1usize..14 { + for selected in 0..13 { + let (first, shown) = window_for(13, selected, room); + assert!( + selected >= first && selected < first + shown, + "room {} cursor {} fell outside {}..{}", + room, + selected, + first, + first + shown + ); + assert!(first + shown <= 13, "window ran past the list"); + } + } + } + + #[test] + fn a_list_that_fits_is_not_windowed() { + // No note, no scrolling, nothing changed for the pane sizes these + // actually run at. + assert_eq!(window_for(13, 0, 13), (0, 13)); + assert_eq!(window_for(13, 12, 20), (0, 13)); + assert_eq!(window_for(0, 0, 5), (0, 0)); + } + + #[test] + fn the_window_moves_only_as_far_as_it_must() { + // Scrolling by one when the cursor steps off the edge, rather than + // recentring: a list that jumps loses the reader's place. + assert_eq!(window_for(13, 5, 6), (0, 6)); + assert_eq!(window_for(13, 6, 6), (1, 6)); + assert_eq!(window_for(13, 12, 6), (7, 6)); + } + + #[test] fn every_binary_is_on_the_menu() { // start.py globs the directory, so a new widget appears by existing. From 4f1326aca9d44473af267b8e979dbe338c80a0a0 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Mon, 24 Aug 2026 23:52:57 +0800 Subject: [PATCH 078/147] netwatch: the detail screen follows the cursor into a section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The body is built at whatever height it needs and scrolled to, but nothing tied the scroll to the selection. So moving the cursor down a section walked it off the bottom of the pane, taking its chart with it - the chart being the thing you moved the cursor to see. On a 22-row pane one press was enough: tab into a section, ↓ once, and the selected row was below the last visible line with nothing to say where it had gone. A taller pane only delayed it; at 30 rows it took six. detail_rows now reports where the cursor landed and how many rows it owns, and the caller scrolls to reveal that span. It has to be a span rather than a row: pulling the selected line just into view would leave the four rows of chart drawn beneath it still below the edge, which is the half that matters. The caller cannot compute this itself. The selected row's position depends on how many rows every section above it drew, which depends on which section is focused, whether its chart is present, and how many endpoints, sockets and files this process has - all of it decided inside detail_rows. Same defect as the main list in 9649f8b, one screen down: a cursor clamped against the whole body while the view showed a fixed slice of it. Both are now the same rule - the window follows the cursor. --- rust/widgets/src/bin/netwatch.rs | 37 +++++++++++++++++++++++++++++--- 1 file changed, 34 insertions(+), 3 deletions(-) diff --git a/rust/widgets/src/bin/netwatch.rs b/rust/widgets/src/bin/netwatch.rs index f796141..9b5bc94 100644 --- a/rust/widgets/src/bin/netwatch.rs +++ b/rust/widgets/src/bin/netwatch.rs @@ -1329,7 +1329,12 @@ fn detail_rows( interval: f64, names: &Resolver, p: &Palette, -) -> Vec<String> { +) -> (Vec<String>, Option<(usize, usize)>) { + // Where the cursor ended up in the body, and how many rows it owns - its + // own row plus the chart drawn under it. The caller cannot work this out: + // the body is built at whatever height it needs and the selected row's + // position depends on how many rows every section above it drew. + let mut cursor: Option<(usize, usize)> = None; let facts = process_facts(row.pid); let here_now = running(row.pid); let total = (row.up + row.down) as f64; @@ -1439,11 +1444,14 @@ fn detail_rows( let pick_at = at[which].min(spots.len() - 1); if focused { let pick = &spots[pick_at]; + let mut tall = 1; if !pick.hist.is_empty() && pick_at < rows.len() { let mut under = chart(&pick.hist, w, 4, p); under.push(String::new()); + tall += under.len(); rows.splice(pick_at + 1..pick_at + 1, under); } + cursor = Some((out.len() + pick_at, tall)); } out.extend(rows); } else if which == 1 { @@ -1451,17 +1459,23 @@ fn detail_rows( let mut rows = connection_rows(conns, at[which], focused, room, w, p); let pick_at = at[which].min(conns.len().saturating_sub(1)); if focused { + let mut tall = 1; if let Some(pick) = conns.get(pick_at) { if !pick.hist.is_empty() && pick_at < rows.len() { let mut under = chart(&pick.hist, w, 4, p); under.push(String::new()); + tall += under.len(); rows.splice(pick_at + 1..pick_at + 1, under); } } + cursor = Some((out.len() + pick_at, tall)); } out.extend(rows); } else { out.push(file_head(w, p)); + if focused { + cursor = Some((out.len() + at[which].min(files.len() - 1), 1)); + } out.extend(file_rows(files, sizes, at[which], focused, room, w, p)); } out.push(String::new()); @@ -1502,7 +1516,7 @@ fn detail_rows( out.extend(chart(&row.disk, w, disk_h, p)); } } - out + (out, cursor) } /// One block per interval, for a log or a pipe. @@ -1924,10 +1938,27 @@ fn main() { // the lists are drawn in full and the charts get their rows, and // what does not fit is scrolled to rather than dropped. let natural = room + spots.len() + conns.len() + files.len() + 24; - let body = detail_rows( + let (body, cursor) = detail_rows( &row, &spots, &conns, &files, &sizes, focus, &at, w, natural, interval, &names, &p, ); let furthest = body.len().saturating_sub(room); + // The screen follows the cursor into a section. It did not + // before: the body is built at whatever height it needs and + // scrolled to, but nothing tied the scroll to the selection, so + // moving the cursor down a long list walked it off the bottom of + // the pane - with its chart, which is the thing you moved the + // cursor to see. On a short pane one press was enough. + // + // The chart is why this reveals a span rather than a row: pulling + // the selected line just into view would leave the four rows it + // was drawn for still below the edge. + if let Some((at_row, tall)) = cursor { + if at_row < dscroll { + dscroll = at_row; + } else if at_row + tall > dscroll + room { + dscroll = (at_row + tall).saturating_sub(room); + } + } dscroll = dscroll.min(furthest); let last = (dscroll + room).min(body.len()); let mut shown: Vec<String> = body[dscroll..last].to_vec(); From 81aa94aa245624ce15176391b7a5f782fa6f0aaa Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Mon, 24 Aug 2026 23:56:38 +0800 Subject: [PATCH 079/147] netwatch: name the socket by our end of it, and shout the column headings Six rows reading "160.79.104.10:443" is what the socket list showed for one process, and nothing on screen said why there were six. The address and port are the *peer's*, and the peer's port is 443 on every one of them; what differs is the port at this end, which the widget parsed past and threw away. ss gives it in column 3 - our address - where column 4 is theirs. It is kept now and shown as OURS, so the six read 50206, 43738, 33610, 43732, 43718, 44130: six connections, not one drawn six times. Worth being precise about which port, because the obvious guess is wrong. A peer-port column would print 443 six times and explain nothing. Checked against ss before writing it: pid 4065091 held five sockets to one address, identical but for local ports 44672, 44678, 44682, 44692 and 54974. The column headings are in caps now, as every other heading in these widgets is - the section headings, and the process list's own PROCESS / PID / TOTAL. These three were the only lowercase ones in the tree. connection_host_w drops from 34 to 37, which is the fixed tail counted rather than estimated: 3 for the mark, 6 for our port, 7 for the state, 10 for rx, 11 for tx. The heading test finds our port by searching the rendered row for the port itself, so the column cannot drift from its label. The doc's sample was regenerated by running the renderers, and now carries two sockets rather than one - a sample with a single socket cannot show the column that exists to tell sockets apart. --- docs/netwatch.md | 18 +++++-- rust/widgets/src/bin/netwatch.rs | 88 ++++++++++++++++++++++---------- 2 files changed, 74 insertions(+), 32 deletions(-) diff --git a/docs/netwatch.md b/docs/netwatch.md index bceced9..b2533df 100644 --- a/docs/netwatch.md +++ b/docs/netwatch.md @@ -298,15 +298,16 @@ it as a machine honestly can: directory ~/projects/terminal-toys ── TALKING TO ── 1 endpoint - host ports rx tx rate + HOST PORTS RX TX RATE 162.159.140.220 https ↓ 3.2 MB ↑ 722 B 411.2 KB/s - ── CONNECTIONS ── 1 socket - socket state rx tx - 162.159.140.220:443 open ↓ 3.2 MB ↑ 722 B + ── CONNECTIONS ── 2 sockets + SOCKET OURS STATE RX TX + 162.159.140.220:443 50206 open ↓ 3.2 MB ↑ 722 B + 162.159.140.220:443 43738 open ↓ 1.1 MB ↑ 310 B ── FILES ── 1 file - path size growth + PATH SIZE GROWTH ~/tmp/big.bin 3.0 MB +425.7 KB/s ── DISK ── read 0 B · written 3.0 MB since it started @@ -343,6 +344,13 @@ different question: one host may hold six of them, and a socket that has closed still shows what it carried. It charts the same way TALKING TO does — the cursor's socket gets an rx/tx chart under its row. +**OURS** is the local port, and it is the only column that tells those six +apart. Five sockets to one CDN all read `1.2.3.4:443`, because the address +and port shown are the *peer's* and the peer's port is 443 on every one of +them; what differs is the port at this end. Without it the list is five +identical lines and "why are there so many of these" has no answer on +screen. A socket seen before this widget could read the port shows `-`. + A hostname is a best-effort label rather than the domain that was asked for. CDNs, shared addresses, encrypted DNS and connection reuse all mean one address can stand for many names, or for none. diff --git a/rust/widgets/src/bin/netwatch.rs b/rust/widgets/src/bin/netwatch.rs index 9b5bc94..77aac95 100644 --- a/rust/widgets/src/bin/netwatch.rs +++ b/rust/widgets/src/bin/netwatch.rs @@ -150,6 +150,10 @@ struct Seen { recv: u64, peer: String, port: u16, + /// Our end of it. Five sockets to one CDN all read "1.2.3.4:443", and + /// this is the only field that tells them apart - the peer port is 443 + /// on every one of them. + mine: u16, cgroup: String, } @@ -165,6 +169,7 @@ fn sockets(external: bool, own: &[String]) -> (HashMap<String, Seen>, String) { } let mut found = HashMap::new(); let (mut inode, mut peer, mut port, mut cgroup) = (None, String::new(), 0u16, String::new()); + let mut mine = 0u16; for (i, line) in text.lines().enumerate() { if i == 0 { continue; @@ -183,6 +188,12 @@ fn sockets(external: bool, own: &[String]) -> (HashMap<String, Seen>, String) { .and_then(|a| a.rsplit_once(':')) .and_then(|(_, p)| p.parse().ok()) .unwrap_or(0); + // Column 3 is our address, column 4 is theirs. + mine = cols + .get(3) + .and_then(|a| a.rsplit_once(':')) + .and_then(|(_, p)| p.parse().ok()) + .unwrap_or(0); inode = field(line, "ino:").filter(|v| v != "0"); cgroup = field(line, "cgroup:").unwrap_or_default(); continue; @@ -205,6 +216,7 @@ fn sockets(external: bool, own: &[String]) -> (HashMap<String, Seen>, String) { .unwrap_or(0), peer: peer.clone(), port, + mine, cgroup: cgroup.clone(), }, ); @@ -477,6 +489,8 @@ struct Conn { name: String, peer: String, port: u16, + /// Our port. See `Seen::mine`. + mine: u16, up: u64, down: u64, up_rate: f64, @@ -604,6 +618,7 @@ fn sample(state: &mut State, external: bool) { name: name.clone(), peer: seen.peer.clone(), port: seen.port, + mine: seen.mine, ..Default::default() }); conn.alive = true; @@ -1100,7 +1115,10 @@ fn endpoint_host_w(w: usize) -> usize { } fn connection_host_w(w: usize) -> usize { - ((w - 1).saturating_sub(34)).clamp(14, 38) + // 37 is the fixed tail exactly: 3 for the mark, 6 for our port, 7 for the + // state, 10 for rx and 11 for tx. Counted, not estimated - the endpoint + // list had this written as 42 when it was 44 and quietly clipped the rate. + ((w - 1).saturating_sub(37)).clamp(14, 38) } fn file_path_w(w: usize) -> usize { @@ -1115,11 +1133,11 @@ fn endpoint_head(w: usize, p: &Palette) -> String { p.dim.as_str(), format!( " {}{:<9}{:>10}{:>11}{:>11}", - tc::pad("host", endpoint_host_w(w)), - "ports", - "rx", - "tx", - "rate" + tc::pad("HOST", endpoint_host_w(w)), + "PORTS", + "RX", + "TX", + "RATE" ), )], w - 1, @@ -1132,11 +1150,12 @@ fn connection_head(w: usize, p: &Palette) -> String { &[( p.dim.as_str(), format!( - " {}{:<7}{:>10}{:>11}", - tc::pad("socket", connection_host_w(w)), - "state", - "rx", - "tx" + " {}{:<6}{:<7}{:>10}{:>11}", + tc::pad("SOCKET", connection_host_w(w)), + "OURS", + "STATE", + "RX", + "TX" ), )], w - 1, @@ -1150,9 +1169,9 @@ fn file_head(w: usize, p: &Palette) -> String { p.dim.as_str(), format!( " {}{:>10}{:>12}", - tc::pad("path", file_path_w(w)), - "size", - "growth" + tc::pad("PATH", file_path_w(w)), + "SIZE", + "GROWTH" ), )], w - 1, @@ -1252,6 +1271,16 @@ fn connection_rows( host_w, ), ), + // Our end of the socket. Without it five rows to one CDN + // are five identical lines, and the question "why are + // there so many of these" has no answer on screen. + ( + &c(&p.dim), + format!( + "{:<6}", + if conn.mine > 0 { conn.mine.to_string() } else { "-".into() } + ), + ), ( &c(if conn.alive { &p.ok } else { &p.dim }), format!("{:<7}", if conn.alive { "open" } else { "closed" }), @@ -2496,11 +2525,11 @@ mod tests { let row = bare(&endpoint_rows(&[spot.clone()], 0, false, 1, w, &names, &p)[0]); let (wide, down, up) = (row.chars().count(), col(&row, "↓"), col(&row, "↑")); assert_eq!(head.chars().count(), wide, "heading width at w={}", w); - assert_eq!(col(&head, "host"), 3, "host column at w={}", w); - assert_eq!(col(&head, "ports"), down - 9, "ports column at w={}", w); - assert_eq!(col(&head, "rx") + 2, down + 10, "rx column at w={}", w); - assert_eq!(col(&head, "tx") + 2, up + 10, "tx column at w={}", w); - assert_eq!(col(&head, "rate") + 4, wide, "rate column at w={}", w); + assert_eq!(col(&head, "HOST"), 3, "host column at w={}", w); + assert_eq!(col(&head, "PORTS"), down - 9, "ports column at w={}", w); + assert_eq!(col(&head, "RX") + 2, down + 10, "rx column at w={}", w); + assert_eq!(col(&head, "TX") + 2, up + 10, "tx column at w={}", w); + assert_eq!(col(&head, "RATE") + 4, wide, "rate column at w={}", w); } } @@ -2510,20 +2539,25 @@ mod tests { let conn = Conn { peer: "192.0.2.7".into(), port: 443, + mine: 44672, up: 4096, down: 8192, alive: true, ..Default::default() }; - for w in [60usize, 84, 120, 200] { + for w in [66usize, 84, 120, 200] { let head = bare(&connection_head(w, &p)); let row = bare(&connection_rows(&[conn.clone()], 0, false, 1, w, &p)[0]); let (wide, down, up) = (row.chars().count(), col(&row, "↓"), col(&row, "↑")); assert_eq!(head.chars().count(), wide, "heading width at w={}", w); - assert_eq!(col(&head, "socket"), 3, "socket column at w={}", w); - assert_eq!(col(&head, "state"), down - 7, "state column at w={}", w); - assert_eq!(col(&head, "rx") + 2, down + 10, "rx column at w={}", w); - assert_eq!(col(&head, "tx") + 2, up + 10, "tx column at w={}", w); + assert_eq!(col(&head, "SOCKET"), 3, "socket column at w={}", w); + assert_eq!(col(&head, "STATE"), down - 7, "state column at w={}", w); + // our port sits between the address and the state, and the row + // is searched for the port itself rather than for a width + assert_eq!(col(&head, "OURS"), down - 13, "ours column at w={}", w); + assert_eq!(col(&row, "44672"), down - 13, "our port at w={}", w); + assert_eq!(col(&head, "RX") + 2, down + 10, "rx column at w={}", w); + assert_eq!(col(&head, "TX") + 2, up + 10, "tx column at w={}", w); assert_eq!(up + 10, wide, "the tx column is the last at w={}", w); } } @@ -2542,14 +2576,14 @@ mod tests { let row = bare(&file_rows(&files, &sizes, 0, false, 1, w, &p)[0]); let wide = row.chars().count(); assert_eq!(head.chars().count(), wide, "heading width at w={}", w); - assert_eq!(col(&head, "path"), 3, "path column at w={}", w); + assert_eq!(col(&head, "PATH"), 3, "path column at w={}", w); assert_eq!( - col(&head, "size") + 4, + col(&head, "SIZE") + 4, col(&row, &shown) + shown.chars().count(), "size column at w={}", w ); - assert_eq!(col(&head, "growth") + 6, wide, "growth column at w={}", w); + assert_eq!(col(&head, "GROWTH") + 6, wide, "growth column at w={}", w); } } From b0caa9dce8a82f83e90231fb9610374152c255a8 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Mon, 24 Aug 2026 23:58:23 +0800 Subject: [PATCH 080/147] netwatch: LOCAL, which is what ss and netstat call that column OURS was mine and it was not a term anybody uses. `ss -tn` prints "Local Address:Port" and "Peer Address:Port"; netstat the same. The peer's end is already the SOCKET column here, so the near end is LOCAL, and a reader who has run either tool knows the word before they read the doc. Column name and doc only - the field, the parse and the width are unchanged. --- docs/netwatch.md | 15 ++++++++------- rust/widgets/src/bin/netwatch.rs | 19 ++++++++++--------- 2 files changed, 18 insertions(+), 16 deletions(-) diff --git a/docs/netwatch.md b/docs/netwatch.md index b2533df..34b50a5 100644 --- a/docs/netwatch.md +++ b/docs/netwatch.md @@ -302,7 +302,7 @@ it as a machine honestly can: 162.159.140.220 https ↓ 3.2 MB ↑ 722 B 411.2 KB/s ── CONNECTIONS ── 2 sockets - SOCKET OURS STATE RX TX + SOCKET LOCAL STATE RX TX 162.159.140.220:443 50206 open ↓ 3.2 MB ↑ 722 B 162.159.140.220:443 43738 open ↓ 1.1 MB ↑ 310 B @@ -344,12 +344,13 @@ different question: one host may hold six of them, and a socket that has closed still shows what it carried. It charts the same way TALKING TO does — the cursor's socket gets an rx/tx chart under its row. -**OURS** is the local port, and it is the only column that tells those six -apart. Five sockets to one CDN all read `1.2.3.4:443`, because the address -and port shown are the *peer's* and the peer's port is 443 on every one of -them; what differs is the port at this end. Without it the list is five -identical lines and "why are there so many of these" has no answer on -screen. A socket seen before this widget could read the port shows `-`. +**LOCAL** is the port at this end, and it is the only column that tells those +six apart. Five sockets to one CDN all read `1.2.3.4:443`, because the +address and port shown are the *peer's* and the peer's port is 443 on every +one of them; what differs is the port here. Without it the list is five +identical lines and "why are there so many of these" has no answer on screen. +The name is `ss`'s and `netstat`'s own — both label that column *Local +Address:Port*. A socket seen before the port could be read shows `-`. A hostname is a best-effort label rather than the domain that was asked for. CDNs, shared addresses, encrypted DNS and connection reuse all mean one diff --git a/rust/widgets/src/bin/netwatch.rs b/rust/widgets/src/bin/netwatch.rs index 77aac95..25a8d34 100644 --- a/rust/widgets/src/bin/netwatch.rs +++ b/rust/widgets/src/bin/netwatch.rs @@ -150,9 +150,9 @@ struct Seen { recv: u64, peer: String, port: u16, - /// Our end of it. Five sockets to one CDN all read "1.2.3.4:443", and - /// this is the only field that tells them apart - the peer port is 443 - /// on every one of them. + /// The local port - `ss` column 3, where column 4 is the peer's. Five + /// sockets to one CDN all read "1.2.3.4:443", and this is the only field + /// that tells them apart: the peer's port is 443 on every one of them. mine: u16, cgroup: String, } @@ -489,7 +489,7 @@ struct Conn { name: String, peer: String, port: u16, - /// Our port. See `Seen::mine`. + /// The local port. See `Seen::mine`. mine: u16, up: u64, down: u64, @@ -1152,7 +1152,7 @@ fn connection_head(w: usize, p: &Palette) -> String { format!( " {}{:<6}{:<7}{:>10}{:>11}", tc::pad("SOCKET", connection_host_w(w)), - "OURS", + "LOCAL", "STATE", "RX", "TX" @@ -1271,9 +1271,10 @@ fn connection_rows( host_w, ), ), - // Our end of the socket. Without it five rows to one CDN - // are five identical lines, and the question "why are - // there so many of these" has no answer on screen. + // The local port, which ss and netstat both call Local. + // Without it five rows to one CDN are five identical + // lines, and "why are there so many of these" has no + // answer on screen. ( &c(&p.dim), format!( @@ -2554,7 +2555,7 @@ mod tests { assert_eq!(col(&head, "STATE"), down - 7, "state column at w={}", w); // our port sits between the address and the state, and the row // is searched for the port itself rather than for a width - assert_eq!(col(&head, "OURS"), down - 13, "ours column at w={}", w); + assert_eq!(col(&head, "LOCAL"), down - 13, "local column at w={}", w); assert_eq!(col(&row, "44672"), down - 13, "our port at w={}", w); assert_eq!(col(&head, "RX") + 2, down + 10, "rx column at w={}", w); assert_eq!(col(&head, "TX") + 2, up + 10, "tx column at w={}", w); From e1e1a0f3d20cc7ca0152d4f6cee7ea45878243ed Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Tue, 25 Aug 2026 00:43:18 +0800 Subject: [PATCH 081/147] usage: grok's credit window rolls forward instead of reading "resetting" Grok is the only agent here with no live quota source. claude asks api.anthropic.com, codex chatgpt.com, copilot api.github.com, cursor api2.cursor.sh, antigravity cloudcode-pa.googleapis.com; grok makes no network call at all and reads whatever its own CLI last wrote to its log. So when that CLI has not run for a while, the newest reading in the log describes a window that has since closed. Its end date is then behind us, which fell into the "reset is in the past" branch and printed "resetting" for ever - a word that reads as "happening now" when it means "happened, some time ago, we cannot say when". The window rolls forward on its own measured length until it covers now. The length is measured rather than assumed to be seven days: the server states the period type, and a window that turns out to be fortnightly should not be guessed weekly. That makes the answer a calculation rather than a reading, so Lane carries a `projected` flag and the countdown is printed with a leading ~. Rolling it forward also revived the pace figure, which is worse than the word it replaced. Pace is usage measured against time elapsed, and how much of *this* window has been used is exactly the thing nobody knows - computing it from the previous window's percentage produced a confident +57% about a quantity that was never measured. Suppressed for projected windows. The existing test pinned the reset to a literal date, which the roll makes a moving target. It now asserts the properties that survive: ahead of now, within one window of it, and still on the grid the recorded window set. The roll itself is tested separately against a fixed clock, including the cases that must not roll - half a reading, and a window that does not run forwards. Still open, and not addressed here: the percentage beside that countdown was measured in the closed window and is drawn as though it were this one's. CodexBar solves the whole problem upstream by calling the CLI's billing endpoint with the token the CLI leaves on disk; that token had expired here, which is why the log was the only source left. --- rust/widgets/src/bin/usage/antigravity.rs | 1 + rust/widgets/src/bin/usage/claude.rs | 1 + rust/widgets/src/bin/usage/codex.rs | 3 + rust/widgets/src/bin/usage/copilot.rs | 1 + rust/widgets/src/bin/usage/cursor.rs | 1 + rust/widgets/src/bin/usage/grok.rs | 75 ++++++++++++++++++++++- rust/widgets/src/bin/usage/shared.rs | 5 ++ rust/widgets/src/bin/usage/vendors.rs | 28 +++++++-- 8 files changed, 109 insertions(+), 6 deletions(-) diff --git a/rust/widgets/src/bin/usage/antigravity.rs b/rust/widgets/src/bin/usage/antigravity.rs index 7b15ede..f0166e5 100644 --- a/rust/widgets/src/bin/usage/antigravity.rs +++ b/rust/widgets/src/bin/usage/antigravity.rs @@ -348,6 +348,7 @@ pub fn lanes(d: &Data) -> Vec<Lane> { window_secs: window_secs(&window), reset: iso_epoch(&text(bucket, "resetTime")), stale: false, + projected: false, }); } } diff --git a/rust/widgets/src/bin/usage/claude.rs b/rust/widgets/src/bin/usage/claude.rs index c8c624c..85ab996 100644 --- a/rust/widgets/src/bin/usage/claude.rs +++ b/rust/widgets/src/bin/usage/claude.rs @@ -981,6 +981,7 @@ pub fn lanes(c: &Data) -> Vec<Lane> { .map(|(_, s)| *s), reset: iso_epoch(&text(l, "resets_at")), stale: !c.quota_live, + projected: false, } }) .collect() diff --git a/rust/widgets/src/bin/usage/codex.rs b/rust/widgets/src/bin/usage/codex.rs index cae4466..274687f 100644 --- a/rust/widgets/src/bin/usage/codex.rs +++ b/rust/widgets/src/bin/usage/codex.rs @@ -781,6 +781,7 @@ pub fn lanes(d: &Data) -> Vec<Lane> { window_secs: (minutes > 0.0).then_some(minutes * 60.0), reset: win["resets_at"].as_f64(), stale: true, + projected: false, }]; }; let mut out: Vec<Lane> = Vec::new(); @@ -796,6 +797,7 @@ pub fn lanes(d: &Data) -> Vec<Lane> { window_secs: secs, reset: win["reset_at"].as_f64(), stale: false, + projected: false, }); } for extra in live["additional_rate_limits"].as_array().into_iter().flatten() { @@ -814,6 +816,7 @@ pub fn lanes(d: &Data) -> Vec<Lane> { window_secs: secs, reset: win["reset_at"].as_f64(), stale: false, + projected: false, }); } out diff --git a/rust/widgets/src/bin/usage/copilot.rs b/rust/widgets/src/bin/usage/copilot.rs index 641cd55..66efaa4 100644 --- a/rust/widgets/src/bin/usage/copilot.rs +++ b/rust/widgets/src/bin/usage/copilot.rs @@ -350,6 +350,7 @@ pub fn lanes(d: &Data) -> Vec<Lane> { window_secs: span, reset: stamp, stale: false, + projected: false, }); } out diff --git a/rust/widgets/src/bin/usage/cursor.rs b/rust/widgets/src/bin/usage/cursor.rs index 9bcdc45..7966fe2 100644 --- a/rust/widgets/src/bin/usage/cursor.rs +++ b/rust/widgets/src/bin/usage/cursor.rs @@ -416,6 +416,7 @@ pub fn lanes(d: &Data) -> Vec<Lane> { window_secs: secs, reset, stale: false, + projected: false, }); } out diff --git a/rust/widgets/src/bin/usage/grok.rs b/rust/widgets/src/bin/usage/grok.rs index 300eb76..80d9c41 100644 --- a/rust/widgets/src/bin/usage/grok.rs +++ b/rust/widgets/src/bin/usage/grok.rs @@ -265,6 +265,34 @@ pub fn read(caches: &mut Caches) -> Data { /// window length is offered only when both ends parse and run forwards, /// but the reset is offered whenever the end does - a countdown is /// readable without knowing how long the window was. +/// The window we are in now, rolled forward from the one the log recorded. +/// +/// Grok publishes no live quota: the reading is whatever its own CLI last +/// wrote to its log, and that can be weeks old. Once the recorded window has +/// ended, its end date is not a reset to count down to - it is a date that +/// has been and gone, which is why this row read "resetting" for ever +/// instead of counting down to anything. +/// +/// The window rolls forward on its own measured length rather than on an +/// assumed seven days: the server states the period, and a window that +/// turns out to be fortnightly should not be guessed weekly. That makes the +/// answer a calculation rather than an observation, so it is flagged and +/// the screen prints it with a `~`. +/// +/// Returns the recorded end unchanged when there is nothing to roll: no +/// length to roll by, or a window that has not ended yet. +fn window_now(begin: Option<f64>, end: Option<f64>, at: f64) -> (Option<f64>, bool) { + let (Some(b), Some(e)) = (begin, end) else { + return (end, false); + }; + let len = e - b; + if len <= 0.0 || e > at { + return (end, false); + } + let skipped = ((at - e) / len).floor() + 1.0; + (Some(e + skipped * len), true) +} + pub fn lanes(d: &Data) -> Vec<Lane> { let Some(q) = d.quota.as_ref() else { return Vec::new(); @@ -273,6 +301,7 @@ pub fn lanes(d: &Data) -> Vec<Lane> { return Vec::new(); }; let (begin, end) = (iso_epoch(&q.start), iso_epoch(&q.end)); + let (reset, projected) = window_now(begin, end, now()); vec![Lane { label: "credits".into(), pct, @@ -280,8 +309,9 @@ pub fn lanes(d: &Data) -> Vec<Lane> { (Some(b), Some(e)) if e > b => Some(e - b), _ => None, }, - reset: end, + reset, stale: false, + projected, }] } @@ -648,12 +678,53 @@ mod tests { assert_eq!(got[0].label, "credits"); assert_eq!(got[0].pct, 42.5); assert_eq!(got[0].window_secs, Some(7.0 * 86400.0)); - assert_eq!(got[0].reset, iso_epoch("2026-08-17T00:00:00.000000+00:00")); + // The fixture's window closed on 2026-08-17, so by the time anyone + // runs this it has long since rolled. The reset is therefore a + // moving target and cannot be pinned to a literal - what can be + // pinned is that it is in the future, sits on the fixture's own + // seven-day grid, and is flagged as worked out rather than read. + let end = iso_epoch("2026-08-17T00:00:00.000000+00:00").unwrap(); + let reset = got[0].reset.unwrap(); + assert!(reset > now(), "the reset is behind us again"); + assert!(reset - now() <= 7.0 * 86400.0, "rolled further than one window"); + let steps = (reset - end) / (7.0 * 86400.0); + assert!( + (steps - steps.round()).abs() < 1e-6, + "the rolled window left the grid the recorded one set: {} windows", + steps + ); + assert!(got[0].projected, "a calculated date must say so"); // Never cached: this was read from a file on this machine a moment // ago, so counting it down is honest. assert!(!got[0].stale); } + /// The roll itself, on a fixed clock - `lanes` has to ask the real one. + #[test] + fn a_window_that_has_ended_rolls_forward_to_the_one_we_are_in() { + let day = 86400.0; + let (begin, end) = (Some(0.0), Some(7.0 * day)); + // Mid-window: nothing to roll, and nothing claimed. + assert_eq!(window_now(begin, end, 3.0 * day), (Some(7.0 * day), false)); + // One day after it closed: the window we are in ends a week later. + assert_eq!(window_now(begin, end, 8.0 * day), (Some(14.0 * day), true)); + // Five weeks late still lands on the grid, not five weeks ago. + assert_eq!(window_now(begin, end, 36.0 * day), (Some(42.0 * day), true)); + // Exactly on a boundary belongs to the window starting there. + assert_eq!(window_now(begin, end, 14.0 * day), (Some(21.0 * day), true)); + } + + #[test] + fn a_window_with_no_length_is_left_alone() { + // Half a reading is not a grid to roll along, and inventing one + // would put a countdown on screen that nothing supports. + assert_eq!(window_now(None, Some(100.0), 999.0), (Some(100.0), false)); + assert_eq!(window_now(Some(50.0), None, 999.0), (None, false)); + // A window that does not run forwards is not a window. + assert_eq!(window_now(Some(100.0), Some(50.0), 999.0), (Some(50.0), false)); + assert_eq!(window_now(Some(50.0), Some(50.0), 999.0), (Some(50.0), false)); + } + #[test] fn an_agent_with_no_quota_publishes_no_lane() { assert!(lanes(&Data::default()).is_empty()); diff --git a/rust/widgets/src/bin/usage/shared.rs b/rust/widgets/src/bin/usage/shared.rs index dd5db55..566126b 100644 --- a/rust/widgets/src/bin/usage/shared.rs +++ b/rust/widgets/src/bin/usage/shared.rs @@ -143,6 +143,11 @@ pub struct Lane { /// True when this came from a cache rather than from the agent just /// now. A number nobody labelled as old reads as current. pub stale: bool, + /// True when `reset` was worked out rather than read - a window rolled + /// forward from an older one on the length the agent stated. It is + /// shown with a `~`, because a date this widget calculated and a date + /// the server sent are not the same kind of fact. + pub projected: bool, } /// An HTTPS GET carrying a bearer token, returning parsed JSON. diff --git a/rust/widgets/src/bin/usage/vendors.rs b/rust/widgets/src/bin/usage/vendors.rs index 02a3102..06b4190 100644 --- a/rust/widgets/src/bin/usage/vendors.rs +++ b/rust/widgets/src/bin/usage/vendors.rs @@ -170,16 +170,35 @@ fn summary_tab(s: &State, w: usize, p: &Palette) -> Vec<String> { (" cached".to_string(), p.warn.clone()) } else if show_reset { match lane.reset { - Some(reset) if reset - now() > 0.0 => { - (format!(" {}", left_span(reset - now())), p.dim.clone()) - } + Some(reset) if reset - now() > 0.0 => ( + format!( + " {}{}", + if lane.projected { "~" } else { "" }, + left_span(reset - now()) + ), + p.dim.clone(), + ), Some(_) => (" resetting".to_string(), p.dim.clone()), None => (String::new(), p.dim.clone()), } } else { (String::new(), p.dim.clone()) }; - let cushion = lead(lane.pct, lane.window_secs, lane.reset); + // A projected window is one we rolled forward because the + // agent's own reading had expired - so the percentage beside it + // was measured in a window that has since closed and reset. + // + // The countdown survives that: the grid the window sits on is + // still the grid. The pace does not. Pace is usage against time + // elapsed, and how much of *this* window has been used is + // exactly what nobody knows - computing it from the last + // window's figure produces a confident number about a quantity + // that was never measured. + let cushion = if lane.projected { + None + } else { + lead(lane.pct, lane.window_secs, lane.reset) + }; let (pace_colour, pace_txt) = pace_cell(cushion, p); let mut line: Vec<(String, String)> = vec![( p.dim.clone(), @@ -287,6 +306,7 @@ mod tests { window_secs: None, reset: None, stale: false, + projected: false, }; // grok has more lanes and a higher total, and still ranks below the // provider with the single worst one - which a flat sort by From 1d0d2148e01611cab4a8f41dcaa3bfc6591ddae5 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Tue, 25 Aug 2026 07:53:48 +0800 Subject: [PATCH 082/147] usage: ask x.ai for grok's quota, or say plainly that nobody is asking MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Grok was the only agent here reading its quota off the disk. The other five each answer a host; grok made no call at all and took whatever its own CLI last wrote to ~/.grok/logs/unified.jsonl. On a machine where the CLI had not run for nine days that meant showing 23% of a credit window closed on the 19th, while the account had spent 57% of the window it was in. More than double, with nothing on screen to say the figure was old. There is an endpoint. The CLI holds a bearer token in auth.json and calls cli-chat-proxy.grok.com/v1/billing with it; that returns creditUsagePercent and currentPeriod. Asking it here gave 57% and a window ending on the 26th, which is also the date the roll-forward had predicted - the prediction was right and the percentage beside it was not. Three settings, and they are off by default for two different reasons. grok_ping talks to a vendor, and a widget that reads should not start doing that because it was launched. grok_ping_after_session starts somebody else's program: it runs the CLI once after a session goes quiet, purely because that is what refreshes the token. Without it the asking works and then silently stops - the token on this machine had lapsed 8.6 days earlier, on the same day the CLI last ran. Both states say which they are, in the summary row and on the tab: not live · ~/.grok/logs/unified.jsonl · window closed 5d 21h ago Only your own Grok sessions update it. usage.grok_ping polls x.ai instead. live · polled x.ai just now, every 1h The age quoted is the reading's, not the file's. The CLI touches that log whenever it starts, so a file written minutes ago can hold a credit figure from a fortnight back, and "written 17m ago" beside a percentage reads as a fresh percentage - which is the same class of mistake as the one this commit is fixing, made one level down. The tab heading was counting down to the raw recorded end, so a rolled window lost its countdown there while the summary still had one. Two screens, one answer now. read() takes the config. Five agents ignore it; threading it through beats grok reaching for a global, and the keys then live beside the others in read_config where the checker can see them. check.py called all three keys dead. It only reads the Python, and these are the port's - so it now also looks at rust/widgets/src/bin/<section>.rs and its submodules before condemning a key, on the same "mentions it at all" rule the Rust check settled on. Verified it still fails on a key nothing reads at all. --- check.py | 19 ++ config.example.json | 6 +- docs/usage.md | 59 ++++ rust/widgets/src/bin/usage.rs | 28 +- rust/widgets/src/bin/usage/antigravity.rs | 2 +- rust/widgets/src/bin/usage/claude.rs | 2 +- rust/widgets/src/bin/usage/codex.rs | 2 +- rust/widgets/src/bin/usage/copilot.rs | 2 +- rust/widgets/src/bin/usage/cursor.rs | 2 +- rust/widgets/src/bin/usage/grok.rs | 332 +++++++++++++++++++++- rust/widgets/src/bin/usage/vendors.rs | 43 ++- 11 files changed, 469 insertions(+), 28 deletions(-) diff --git a/check.py b/check.py index 254d6c6..4582e15 100755 --- a/check.py +++ b/check.py @@ -117,9 +117,28 @@ def check_config_keys(): open(f).read(), re.S): known.setdefault(m.group(1), set()) known[m.group(1)] |= set(re.findall(r'"(\w+)":', m.group(2))) + # The port reads the same file, and has keys of its own. A setting the + # Rust reads is not dead because the Python has not caught up - it would + # only be dead if nothing at all read it, and this script can only see + # half the tree. Read as text: a key counts as read if the widget + # mentions it, which is the same rule the Rust check settled on after + # two attempts that guessed at the variable name and got it wrong. + ported = {} + for section in known: + found = set() + for path in glob.glob("rust/widgets/src/bin/%s.rs" % section) + glob.glob( + "rust/widgets/src/bin/%s/*.rs" % section + ): + try: + found.add(open(path).read()) + except OSError: + pass + ported[section] = "\n".join(found) for section, keys in known.items(): shipped = {k for k in example.get(section, {}) if not k.startswith("_")} for dead in sorted(shipped - keys): + if '"%s"' % dead in ported.get(section, ""): + continue fail("dead config key", section, dead) diff --git a/config.example.json b/config.example.json index e39ef29..16c5fcb 100644 --- a/config.example.json +++ b/config.example.json @@ -103,7 +103,11 @@ "_rates_comment": "OPTIONAL override. Anthropic's published list prices ship in the code, dated on screen, so Claude models are priced with no config at all. Set entries here to correct a stale price, to add a provider that publishes none (OpenAI, xAI), or to use your own negotiated rates. US$ per million tokens, keyed by model; longest matching name wins and '*' catches the rest.", "rates": {}, "_plan_cost_comment": "What each subscription costs you per month, keyed by agent, for example claude: 200. Nothing ships here: Anthropic lists Max as 'from $100' because it varies by tier, and no invoice is on this machine. Set it and METERED adds 'the plan saves'.", - "plan_cost": {} + "plan_cost": {}, + "_grok_ping_comment": "Grok is the only agent with no live quota: its figures come from the log its own CLI writes, so they move only when you use Grok on this machine. Turn grok_ping on to ask x.ai instead, using the token the CLI leaves in ~/.grok/auth.json. grok_ping_after_session runs the CLI once after a session goes quiet, which is what refreshes that token - without it the asking stops working when the token lapses. Both are off by default: one talks to a vendor, the other starts somebody else's program.", + "grok_ping": false, + "grok_ping_minutes": 60, + "grok_ping_after_session": false }, "link": { "_comment": "Every established connection into a port this machine listens on. Empty ports means all of them, which is the useful default. No network traffic: the numbers come from the kernel's own accounting via ss.", diff --git a/docs/usage.md b/docs/usage.md index be23df3..80074c8 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -824,6 +824,65 @@ seconds and these windows move over hours, so the earlier code was making six requests a minute — three calls, twice a minute — to be told the same thing. A failure is cached too, so a dead endpoint is retried occasionally instead of on every frame. +### Grok is the fourth, and it is off by default + +Grok publishes no quota this widget can read without asking for it. The other +five agents each answer a host — `api.anthropic.com`, `chatgpt.com`, +`api.github.com`, `api2.cursor.sh`, `cloudcode-pa.googleapis.com`. Grok makes +no call at all: its figures come from `~/.grok/logs/unified.jsonl`, the log its +own CLI writes, so they move **only when you use Grok on this machine**. + +That failed quietly. A log left alone for nine days had the widget showing 23% +of a credit window that had closed on the 19th, while the account had spent 57% +of the window it was actually in. More than double, with nothing on screen to +say the figure was old. + +Three settings, all off or hourly by default: + +| key | default | what it does | +|---|---|---| +| `grok_ping` | `false` | GET `cli-chat-proxy.grok.com/v1/billing`, with the bearer token the Grok CLI leaves in `~/.grok/auth.json` | +| `grok_ping_minutes` | `60` | how often. The window moves over days; an hour is current without being traffic | +| `grok_ping_after_session` | `false` | run `grok agent stdio` once after a session goes quiet, purely to refresh that token | + +**Off by default for two different reasons.** `grok_ping` talks to a vendor, +and a widget that reads should not start doing that because it was launched. +`grok_ping_after_session` is the stronger case: it starts somebody else's +program. It exists because the token expires — mine had lapsed 8.6 days before +I looked, on the same day the CLI last ran — and without a refresh the asking +works for a while and then silently stops, which is the failure it was added to +fix. + +The screen says which state it is in, in both places it appears: + +``` +── WEEKLY QUOTA ── resets in ~1.1 days + not live · ~/.grok/logs/unified.jsonl · window closed 5d 21h ago + Only your own Grok sessions update it. usage.grok_ping polls x.ai instead. +``` + +``` +── WEEKLY QUOTA ── resets in 1.1 days + live · polled x.ai just now, every 1h +``` + +The age quoted is the **reading's**, not the file's. The CLI touches that log +whenever it starts, so a file written minutes ago can still hold a credit +figure from a fortnight back, and "written 17m ago" beside a percentage reads +as a fresh percentage. + +When the recorded window has closed, its end date is rolled forward on the +window's own measured length until it covers now — the length is measured +rather than assumed to be seven days, because the server states the period type +and a fortnightly window should not be guessed weekly. That is a calculation +rather than a reading, so the countdown carries a `~`, and the **pace figure is +suppressed**: pace is usage against time elapsed, and how much of the current +window has been spent is exactly what nobody knows. + +CodexBar reaches the same endpoint and hits the same wall — it reads the cached +credential and does not refresh it either, so an expired token drops it back to +local session files, as this does to the log. + ## The pace mark on every quota bar ``` diff --git a/rust/widgets/src/bin/usage.rs b/rust/widgets/src/bin/usage.rs index a15b3e2..2601c34 100644 --- a/rust/widgets/src/bin/usage.rs +++ b/rust/widgets/src/bin/usage.rs @@ -1148,13 +1148,27 @@ fn day_calendar( } /// Settings, read once, so no widget-wide mutable globals are needed. -#[derive(Default)] +#[derive(Default, Clone)] struct Config { agents: Vec<String>, exclude_agents: Vec<String>, rates: HashMap<String, Rate>, plan_cost: HashMap<String, f64>, refresh: f64, + /// Grok is the only agent with no live quota unless it is asked for one. + /// Off by default: asking means a request to x.ai carrying the token its + /// CLI left on disk, and a widget that reads should not start talking to + /// a vendor because it was launched. + grok_ping: bool, + /// Minutes between those requests. The window it reports moves over + /// days, so an hour is frequent enough to be current and rare enough + /// not to be traffic. + grok_ping_minutes: f64, + /// Whether to run the Grok CLI once a session goes quiet. That is what + /// refreshes the token the request needs - without it the token expires + /// and the quota silently goes back to being read off the disk. Off by + /// default for the stronger reason: it starts somebody else's program. + grok_ping_after_session: bool, } fn read_config() -> Config { @@ -1186,6 +1200,15 @@ fn read_config() -> Config { .filter_map(|(k, v)| v.as_f64().map(|v| (k.clone(), v))) .collect(), refresh: tc::cfg_f64(&raw, "refresh", 30.0), + grok_ping: raw + .get("grok_ping") + .and_then(|v| v.as_bool()) + .unwrap_or(false), + grok_ping_minutes: tc::cfg_f64(&raw, "grok_ping_minutes", 60.0), + grok_ping_after_session: raw + .get("grok_ping_after_session") + .and_then(|v| v.as_bool()) + .unwrap_or(false), } } @@ -1401,13 +1424,14 @@ fn main() { let wake = Arc::new((Mutex::new(false), Condvar::new())); let poller = Arc::clone(&state); let poller_wake = Arc::clone(&wake); + let poller_cfg = cfg.clone(); std::thread::spawn(move || { let mut caches = shared::Caches::default(); loop { // A poller that dies takes its explanation with it, and an empty // board looks exactly like a machine with no agents on it. let read = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| { - vendors::read_all(&mut caches) + vendors::read_all(&mut caches, &poller_cfg) })); match read { Ok(found) => { diff --git a/rust/widgets/src/bin/usage/antigravity.rs b/rust/widgets/src/bin/usage/antigravity.rs index f0166e5..b19034e 100644 --- a/rust/widgets/src/bin/usage/antigravity.rs +++ b/rust/widgets/src/bin/usage/antigravity.rs @@ -273,7 +273,7 @@ fn conversation_steps(path: &str) -> Option<f64> { /// Each conversation is its own SQLite file with a `steps` table - one row /// per step the agent took - so the counts are real work done. No table /// anywhere carries a token count. -pub fn read(caches: &mut Caches) -> Data { +pub fn read(caches: &mut Caches, _cfg: &Config) -> Data { use std::os::unix::fs::MetadataExt; let mut d = Data { live: cached(caches, "antigravity", PLAN_TTL, antigravity_live), diff --git a/rust/widgets/src/bin/usage/claude.rs b/rust/widgets/src/bin/usage/claude.rs index 85ab996..0c577a7 100644 --- a/rust/widgets/src/bin/usage/claude.rs +++ b/rust/widgets/src/bin/usage/claude.rs @@ -303,7 +303,7 @@ pub fn claude_rates() -> (Vec<f64>, usize) { (out, sampled) } -pub fn read(caches: &mut Caches) -> Data { +pub fn read(caches: &mut Caches, _cfg: &Config) -> Data { let mut claude = Data::default(); let live = cached(caches, "claude", LIVE_TTL, || { let (tok, plan) = claude_token()?; diff --git a/rust/widgets/src/bin/usage/codex.rs b/rust/widgets/src/bin/usage/codex.rs index 274687f..df5193f 100644 --- a/rust/widgets/src/bin/usage/codex.rs +++ b/rust/widgets/src/bin/usage/codex.rs @@ -339,7 +339,7 @@ fn newest_limits(files: &[String]) -> Option<serde_json::Value> { None } -pub fn read(caches: &mut Caches) -> Data { +pub fn read(caches: &mut Caches, _cfg: &Config) -> Data { let mut codex = Data { live: cached(caches, "codex", LIVE_TTL, codex_live), ..Data::default() diff --git a/rust/widgets/src/bin/usage/copilot.rs b/rust/widgets/src/bin/usage/copilot.rs index 66efaa4..e28c00a 100644 --- a/rust/widgets/src/bin/usage/copilot.rs +++ b/rust/widgets/src/bin/usage/copilot.rs @@ -183,7 +183,7 @@ fn copilot_live() -> Option<serde_json::Value> { } } -pub fn read(caches: &mut Caches) -> Data { +pub fn read(caches: &mut Caches, _cfg: &Config) -> Data { let mut d = Data::default(); if let Some(got) = cached(caches, "copilot", LIVE_TTL, copilot_live) { if got["data"].is_object() { diff --git a/rust/widgets/src/bin/usage/cursor.rs b/rust/widgets/src/bin/usage/cursor.rs index 7966fe2..d081684 100644 --- a/rust/widgets/src/bin/usage/cursor.rs +++ b/rust/widgets/src/bin/usage/cursor.rs @@ -349,7 +349,7 @@ fn read_tracking(con: &Connection) -> rusqlite::Result<Tracking> { }) } -pub fn read(caches: &mut Caches) -> Data { +pub fn read(caches: &mut Caches, _cfg: &Config) -> Data { let mut d = Data::default(); // The published sections do not depend on the local database, so a // locked or missing file must not take the live quota down with it - diff --git a/rust/widgets/src/bin/usage/grok.rs b/rust/widgets/src/bin/usage/grok.rs index 80d9c41..f9e8392 100644 --- a/rust/widgets/src/bin/usage/grok.rs +++ b/rust/widgets/src/bin/usage/grok.rs @@ -35,6 +35,26 @@ const SESSIONS: &str = ".grok/sessions"; /// The quota is not in the session transcripts: it arrives on the client /// log, which the CLI writes as it talks to the server. const LOG: &str = ".grok/logs/unified.jsonl"; +/// Where the CLI leaves the token it authenticates with. +const AUTH: &str = ".grok/auth.json"; +/// Seconds to wait on the billing call before falling back to the log. +const QUOTA_TIMEOUT: u64 = 6; +/// The CLI, whose only job here is to refresh the token it owns. +const CLI: &str = ".grok/bin/grok"; +/// Cache key for the billing reading. +const PING_KEY: &str = "grok:billing"; +/// Cache key for the last session-end refresh, so one ending refreshes once. +const SEEN_KEY: &str = "grok:session-seen"; +/// How long a session must be quiet before it counts as over. Long enough +/// that a pause for thought is not an ending. +const SESSION_QUIET: f64 = 120.0; +/// And how long before it is old news. Launching the widget days after the +/// last session should not start the CLI to refresh a window nobody is +/// watching. +const SESSION_STALE: f64 = 6.0 * 3600.0; +/// The CLI's own billing endpoint. Same reading its `/usage` shows, and the +/// only account-wide source Grok has that is not a file on this disk. +const BILLING: &str = "https://cli-chat-proxy.grok.com/v1/billing?format=credits"; /// The credit reading is one line among the client log's chatter and is /// only rewritten when the server sends a new one, so the tail has to be /// long enough to still contain one after a busy session. @@ -75,6 +95,16 @@ pub struct Data { /// Newest transcript mtime, as epoch seconds. last: f64, quota: Option<Quota>, + /// True when the quota came from the server just now rather than from + /// the log. A number nobody labelled as old reads as current, and this + /// one was out by more than double the last time it went unlabelled. + quota_live: bool, + /// When the server was last asked, as epoch seconds. Zero when it never + /// has been - the asking is off unless it is turned on. + quota_at: f64, + /// Seconds between asks, so the tab can say what the interval is rather + /// than leaving the reader to find it in a config file. + quota_every: f64, } /// The integer following `key` on a line. @@ -190,7 +220,60 @@ fn newest_quota<'a>(lines: impl Iterator<Item = &'a str>) -> Option<Quota> { /// What every transcript here spent, and what the server last said about /// the account's credits. -pub fn read(caches: &mut Caches) -> Data { +/// The server if it is allowed and will answer, the log if not. +/// +/// Held between asks rather than asked on every frame: the pane redraws +/// every thirty seconds and this window moves over days, so the interval is +/// the configured one and the reading in between is the one already had. +fn quota_now(caches: &mut Caches, cfg: &Config) -> (Option<Quota>, bool, f64) { + let from_log = || { + newest_quota(tail_lines(&under_home(LOG), LOG_TAIL).iter().map(String::as_str)) + }; + if !cfg.grok_ping { + return (from_log(), false, 0.0); + } + let ttl = (cfg.grok_ping_minutes * 60.0).max(60.0); + let got = cached(caches, PING_KEY, ttl, || live_quota(QUOTA_TIMEOUT)); + // When the ask was actually made, which is not this frame most of the + // time. The tab reports it, so it has to be the fetch and not the read. + let at = caches.live.get(PING_KEY).map(|(when, _, _)| *when).unwrap_or(0.0); + match got.as_ref().and_then(quota_from) { + Some(q) => (Some(q), true, at), + None => (from_log(), false, at), + } +} + +/// Run the Grok CLI once, for its side effect: it refreshes the token in +/// `auth.json` on startup, and that token is what the billing request needs. +/// +/// Without this the asking works until the token lapses and then quietly +/// stops working, which is the failure it was meant to fix. With it the +/// refresh happens when a session has just ended - the moment the numbers +/// have changed and nobody is at the keyboard waiting. +/// +/// It starts somebody else's program, so it is off unless asked for. The +/// handshake is the smallest one the agent answers: initialize, then close. +fn refresh_token() { + use std::io::Write; + let Ok(mut child) = std::process::Command::new(under_home(CLI)) + .args(["agent", "stdio"]) + .stdin(std::process::Stdio::piped()) + .stdout(std::process::Stdio::null()) + .stderr(std::process::Stdio::null()) + .spawn() + else { + return; + }; + if let Some(mut pipe) = child.stdin.take() { + let _ = pipe.write_all( + b"{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\ + \"params\":{\"protocolVersion\":1,\"clientCapabilities\":{}}}\n", + ); + } + let _ = child.wait(); +} + +pub fn read(caches: &mut Caches, cfg: &Config) -> Data { use std::os::unix::fs::MetadataExt; let mut files = Vec::new(); walk(&under_home(SESSIONS), "updates.jsonl", &mut files); @@ -200,10 +283,12 @@ pub fn read(caches: &mut Caches) -> Data { // missing is the failure this repo keeps paying for. ok stays false, // so the tab says there are no sessions - under the quota, not // instead of it. + let (quota, quota_live, quota_at) = quota_now(caches, cfg); return Data { - quota: newest_quota( - tail_lines(&under_home(LOG), LOG_TAIL).iter().map(String::as_str), - ), + quota, + quota_live, + quota_at, + quota_every: cfg.grok_ping.then(|| cfg.grok_ping_minutes * 60.0).unwrap_or(0.0), ..Data::default() }; } @@ -248,6 +333,30 @@ pub fn read(caches: &mut Caches) -> Data { caches .live .retain(|key, _| !key.starts_with(CACHE) || seen.contains(key)); + // A session that has just ended is the moment the numbers have changed + // and nobody is waiting on the pane. Refreshing the token then keeps the + // asking working; refreshing while a session is still running would mean + // starting the CLI under somebody who is using it. + if cfg.grok_ping && cfg.grok_ping_after_session && newest > 0.0 { + let quiet = now() - newest; + let handled = caches + .live + .get(SEEN_KEY) + .and_then(|(_, v, _)| v.as_ref()) + .and_then(|v| v.as_f64()) + .unwrap_or(0.0); + if (SESSION_QUIET..SESSION_STALE).contains(&quiet) && newest > handled { + refresh_token(); + caches.live.insert( + SEEN_KEY.to_string(), + (now(), Some(serde_json::json!(newest)), f64::MAX), + ); + // The token is new, so the reading held from before it is not + // the best one available any more. + caches.live.remove(PING_KEY); + } + } + let quota_read = quota_now(caches, cfg); Data { ok: true, sessions, @@ -255,7 +364,10 @@ pub fn read(caches: &mut Caches) -> Data { total, daily, last: newest, - quota: newest_quota(tail_lines(&under_home(LOG), LOG_TAIL).iter().map(String::as_str)), + quota: quota_read.0, + quota_live: quota_read.1, + quota_at: quota_read.2, + quota_every: cfg.grok_ping.then(|| cfg.grok_ping_minutes * 60.0).unwrap_or(0.0), } } @@ -265,6 +377,59 @@ pub fn read(caches: &mut Caches) -> Data { /// window length is offered only when both ends parse and run forwards, /// but the reset is offered whenever the end does - a countdown is /// readable without knowing how long the window was. +/// The credit window as the server has it right now. +/// +/// Grok was the only agent here reading its quota off the disk, and the +/// number that produced was whatever its CLI last wrote - 23% from a window +/// that had closed, where the account had since spent 57% of the one we are +/// actually in. More than double, and nothing on screen said so. +/// +/// The CLI leaves a bearer token in `auth.json` and this is the endpoint it +/// calls with it. An expired token is not sent: it would come back 401 after +/// a round trip, and the log is a better answer than a failed request. The +/// CLI refreshes the token whenever it runs, so this works for as long as +/// Grok is in use and stops when it is not, which is the honest shape. +fn live_quota(seconds: u64) -> Option<serde_json::Value> { + let raw = std::fs::read_to_string(under_home(AUTH)).ok()?; + let parsed: serde_json::Value = serde_json::from_str(&raw).ok()?; + // Keyed by issuer and account, so the entry is found by shape rather + // than by a name that is different on every machine. + let entry = parsed + .as_object()? + .values() + .find(|v| v.get("key").and_then(|k| k.as_str()).is_some_and(|k| !k.is_empty()))?; + let key = entry["key"].as_str()?; + if let Some(expiry) = iso_epoch(&text(entry, "expires_at")) { + if expiry <= now() { + return None; + } + } + get_json( + BILLING, + &[("Authorization", &format!("Bearer {}", key))], + seconds, + ) +} + +/// The billing body in the same shape the log parser produces, so the rest +/// of the tab cannot tell which of the two it is looking at. +fn quota_from(d: &serde_json::Value) -> Option<Quota> { + let cfg = &d["config"]; + let period = &cfg["currentPeriod"]; + let pct = val_of(&cfg["creditUsagePercent"]); + pct?; + Some(Quota { + pct, + kind: text(period, "type"), + start: text(period, "start"), + end: text(period, "end"), + tier: String::new(), + on_demand_used: val_of(&cfg["onDemandUsed"]["val"]), + on_demand_cap: val_of(&cfg["onDemandCap"]["val"]), + prepaid: val_of(&cfg["prepaidBalance"]["val"]), + }) +} + /// The window we are in now, rolled forward from the one the log recorded. /// /// Grok publishes no live quota: the reading is whatever its own CLI last @@ -301,7 +466,13 @@ pub fn lanes(d: &Data) -> Vec<Lane> { return Vec::new(); }; let (begin, end) = (iso_epoch(&q.start), iso_epoch(&q.end)); - let (reset, projected) = window_now(begin, end, now()); + // A live reading is of the window we are in, so there is nothing to roll + // forward and nothing to qualify. Only the log needs either. + let (reset, projected) = if d.quota_live { + (end, false) + } else { + window_now(begin, end, now()) + }; vec![Lane { label: "credits".into(), pct, @@ -310,11 +481,98 @@ pub fn lanes(d: &Data) -> Vec<Lane> { _ => None, }, reset, - stale: false, + // Not live means the percentage was measured in some earlier window + // and this one's spend is unknown. The row says so rather than + // letting a stale figure read as current. + stale: !d.quota_live, projected, }] } +/// True when nothing is asking the server on the reader's behalf, so the +/// figures move only when they use Grok on this machine. The summary says so +/// under the row; once asking is on, the tab reports the interval instead. +pub fn asks_nobody(d: &Data) -> bool { + d.quota_every <= 0.0 +} + +/// Where the figure came from, in the two states it can be in. +/// +/// Grok is the only agent here that can be reading a file rather than a +/// server, and the file goes stale in silence: the last time it did it +/// showed 23% of a window that had closed, while the account had spent 57% +/// of the one it was in. A percentage nobody dated reads as current. +/// +/// Written for someone who will go and look: it names the file, its age and +/// the settings, rather than explaining what a stale reading is. +/// An interval as a reader would say it: "1h", not left_span's "1h 0m", +/// which is a duration formatter answering a question nobody asked. +fn every(seconds: f64) -> String { + let mins = (seconds.max(60.0) / 60.0).round() as u64; + match (mins / 60, mins % 60) { + (0, m) => format!("{}m", m), + (h, 0) => format!("{}h", h), + (h, m) => format!("{}h {}m", h, m), + } +} + +fn freshness(d: &Data, w: usize, p: &Palette) -> Vec<String> { + let mut out = Vec::new(); + if d.quota_every > 0.0 { + let ago = now() - d.quota_at; + let last = if d.quota_at <= 0.0 { + "not yet".to_string() + } else if ago < 90.0 { + "just now".to_string() + } else { + format!("{} ago", left_span(ago)) + }; + out.push(tc::seg( + &[ + ( + if d.quota_live { p.ok.as_str() } else { p.warn.as_str() }, + if d.quota_live { " live" } else { " not live" }.to_string(), + ), + ( + p.dim.as_str(), + format!(" · polled x.ai {}, every {}", last, every(d.quota_every)), + ), + ], + w - 1, + )); + out.push(String::new()); + return out; + } + // The reading's age, not the file's. The CLI touches that log whenever + // it starts, so a file written minutes ago can still hold a credit + // figure from a fortnight back - and "written 17m ago" beside a + // percentage reads as a fresh percentage. + let closed = d + .quota + .as_ref() + .and_then(|q| iso_epoch(&q.end)) + .filter(|e| *e <= now()) + .map(|e| format!(" · window closed {} ago", left_span(now() - e))) + .unwrap_or_default(); + out.push(tc::seg( + &[ + (p.warn.as_str(), " not live".into()), + (p.dim.as_str(), format!(" · ~/{}{}", LOG, closed)), + ], + w - 1, + )); + out.push(tc::seg( + &[( + p.dim.as_str(), + " Only your own Grok sessions update it. usage.grok_ping polls x.ai instead." + .into(), + )], + w - 1, + )); + out.push(String::new()); + out +} + /// What the server calls this window, in words a reader has met before. fn period_name(kind: &str) -> String { if kind.contains("WEEKLY") { @@ -357,7 +615,15 @@ fn grok_tab(d: &Data, w: usize, p: &Palette) -> Vec<String> { // else here counts what was spent. It leads the tab for that // reason. let (begin, end) = (iso_epoch(&q.start), iso_epoch(&q.end)); - let left = end.map(|e| (e - now()) / 86400.0).filter(|days| *days >= 0.0); + // The window we are in, not the one the reading came from - the + // heading used the raw end, so a rolled window lost its countdown + // here while the summary still had one. Two screens, one answer. + let (current, rolled) = if d.quota_live { + (end, false) + } else { + window_now(begin, end, now()) + }; + let left = current.map(|e| (e - now()) / 86400.0).filter(|days| *days >= 0.0); rows.push(tc::seg( &[ ( @@ -366,12 +632,15 @@ fn grok_tab(d: &Data, w: usize, p: &Palette) -> Vec<String> { ), ( p.dim.as_str(), - left.map(|days| format!("resets in {:.1} days", days)) - .unwrap_or_default(), + left.map(|days| { + format!("resets in {}{:.1} days", if rolled { "~" } else { "" }, days) + }) + .unwrap_or_default(), ), ], w - 1, )); + rows.extend(freshness(d, w, p)); // A window is only a window if it runs forwards; without both ends // there is no pace to report, and a mark placed anyway would be a // claim about a clock nobody read. @@ -694,9 +963,43 @@ mod tests { steps ); assert!(got[0].projected, "a calculated date must say so"); - // Never cached: this was read from a file on this machine a moment - // ago, so counting it down is honest. - assert!(!got[0].stale); + // From the log, so the percentage belongs to a window that has since + // closed and the row has to say so. This is the case that was wrong + // in the wild: 23% shown as current where the account had spent 57%. + assert!(got[0].stale, "a reading off the disk must not read as live"); + } + + #[test] + fn an_interval_reads_the_way_someone_would_say_it() { + assert_eq!(every(3600.0), "1h"); + assert_eq!(every(1800.0), "30m"); + assert_eq!(every(5400.0), "1h 30m"); + assert_eq!(every(7200.0), "2h"); + // Never zero: a config of 0 would otherwise advertise "every 0m", + // and the poll interval is floored at a minute anyway. + assert_eq!(every(0.0), "1m"); + } + + #[test] + fn a_live_reading_is_neither_stale_nor_projected() { + // The same fixture, marked as having come from the server. Its + // window is then the window we are in: nothing to roll forward, and + // nothing to qualify. + let d = Data { + ok: true, + quota: newest_quota([LOG_LINE].into_iter()), + quota_live: true, + ..Default::default() + }; + let got = lanes(&d); + assert_eq!(got.len(), 1); + assert!(!got[0].stale, "a live reading is current by definition"); + assert!(!got[0].projected, "a live window was read, not worked out"); + assert_eq!( + got[0].reset, + iso_epoch("2026-08-17T00:00:00.000000+00:00"), + "a live window is reported as the server gave it, not rolled" + ); } /// The roll itself, on a fixed clock - `lanes` has to ask the real one. @@ -757,6 +1060,9 @@ mod tests { daily: HashMap::from([(NaiveDate::from_ymd_opt(2026, 8, 16).unwrap(), 900.0)]), last: now(), quota: newest_quota([LOG_LINE].into_iter()), + quota_live: false, + quota_at: 0.0, + quota_every: 0.0, }; for w in [40usize, 80, 200] { let rows = tab(&d, w, 24, &Config::default(), &p); diff --git a/rust/widgets/src/bin/usage/vendors.rs b/rust/widgets/src/bin/usage/vendors.rs index 06b4190..206964a 100644 --- a/rust/widgets/src/bin/usage/vendors.rs +++ b/rust/widgets/src/bin/usage/vendors.rs @@ -40,14 +40,14 @@ pub struct State { pub err: String, } -pub fn read_all(caches: &mut Caches) -> State { +pub fn read_all(caches: &mut Caches, cfg: &Config) -> State { State { - claude: crate::claude::read(caches), - codex: crate::codex::read(caches), - cursor: crate::cursor::read(caches), - grok: crate::grok::read(caches), - copilot: crate::copilot::read(caches), - antigravity: crate::antigravity::read(caches), + claude: crate::claude::read(caches, cfg), + codex: crate::codex::read(caches, cfg), + cursor: crate::cursor::read(caches, cfg), + grok: crate::grok::read(caches, cfg), + copilot: crate::copilot::read(caches, cfg), + antigravity: crate::antigravity::read(caches, cfg), installed: detect_agents(), fetched: 0.0, err: String::new(), @@ -218,6 +218,35 @@ fn summary_tab(s: &State, w: usize, p: &Palette) -> Vec<String> { line.iter().map(|(c, t)| (c.as_str(), t.clone())).collect(); rows.push(tc::seg(&refs, w - 1)); } + // Grok alone can be reading a file rather than a server, and a + // reader who does not know that has no way to tell this row from + // the five above it. Said here only while nothing is asking on + // their behalf - once it is, the tab reports the interval and this + // line would be repeating a setting back at them. + if *name == "grok" && crate::grok::asks_nobody(&s.grok) { + // Written to fit rather than clipped: a hint cut in half is the + // fault this repo keeps paying for, and "usage.grok_pin" names + // a setting that does not exist. + let long = " · only your own Grok sessions update this · usage.grok_ping"; + let short = " · usage.grok_ping"; + let room = (w - 1).saturating_sub(" not live".len()); + rows.push(tc::seg( + &[ + (p.warn.as_str(), " not live".into()), + ( + p.dim.as_str(), + if long.chars().count() <= room { + long.to_string() + } else if short.chars().count() <= room { + short.to_string() + } else { + String::new() + }, + ), + ], + w - 1, + )); + } } if !quiet.is_empty() { rows.push(String::new()); From d2a6e514456293ed2a2a2512e64621123e3cea95 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Tue, 25 Aug 2026 08:42:49 +0800 Subject: [PATCH 083/147] usage: the grok note says what to do, not just which key exists MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit "not live · only your own Grok sessions update this · usage.grok_ping" ended on the bare name of a setting, which tells a reader a key exists and nothing about what to do with it. Two lines now, because both halves are worth having and neither fits beside the other at the widths these panes get dragged to: not live · only your own Grok sessions update this Set usage.grok_ping in config.json to poll x.ai instead. The single-line version had four phrasings and picked the widest that fit, which at 85 columns meant dropping the half explaining why the number was old and keeping only the half naming the file to edit. Clipping instead would have printed "usage.grok_pin", a setting that does not exist - the failure this repo has a rule against. Nothing is added when polling is on: the tab reports the interval there, and a line in the summary telling someone to switch on what they have already switched on is noise. --- rust/widgets/src/bin/usage/vendors.rs | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/rust/widgets/src/bin/usage/vendors.rs b/rust/widgets/src/bin/usage/vendors.rs index 206964a..90416a4 100644 --- a/rust/widgets/src/bin/usage/vendors.rs +++ b/rust/widgets/src/bin/usage/vendors.rs @@ -224,28 +224,28 @@ fn summary_tab(s: &State, w: usize, p: &Palette) -> Vec<String> { // their behalf - once it is, the tab reports the interval and this // line would be repeating a setting back at them. if *name == "grok" && crate::grok::asks_nobody(&s.grok) { - // Written to fit rather than clipped: a hint cut in half is the - // fault this repo keeps paying for, and "usage.grok_pin" names - // a setting that does not exist. - let long = " · only your own Grok sessions update this · usage.grok_ping"; - let short = " · usage.grok_ping"; - let room = (w - 1).saturating_sub(" not live".len()); + // Two lines because both halves are worth having and neither + // fits beside the other at the widths these panes are dragged + // to: what the number is, and what to do about it. Clipping one + // to keep them on a single row would leave "usage.grok_pin", + // which names a setting that does not exist. rows.push(tc::seg( &[ (p.warn.as_str(), " not live".into()), ( p.dim.as_str(), - if long.chars().count() <= room { - long.to_string() - } else if short.chars().count() <= room { - short.to_string() - } else { - String::new() - }, + " · only your own Grok sessions update this".into(), ), ], w - 1, )); + rows.push(tc::seg( + &[( + p.dim.as_str(), + " Set usage.grok_ping in config.json to poll x.ai instead.".into(), + )], + w - 1, + )); } } if !quiet.is_empty() { From 12efc8be865b7404d06e5afd965d4e0f70f6d820 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Tue, 25 Aug 2026 09:23:24 +0800 Subject: [PATCH 084/147] usage: antigravity says which thing went wrong, and says it under its name MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit "no tier: the CLI's access token has expired or the call failed" names two causes, commits to neither, and asks nothing of the reader. It was the widget admitting it had not looked - and it could have. The three cases were already distinguished inside antigravity_live, and then all thrown away as one None. They are three different situations wanting three different things: no tier · Antigravity has not signed in on this machine yet. Open it once and the tier appears here. no tier · Antigravity's access token expired 3h 15m ago. It refreshes them itself - open it once and this fills in. no tier · the token is good, but Google's Code Assist API did not answer. Nothing to do here; it is retried every hour. The last one is what this machine is actually in, which is how the old wording earned its keep as an example: the token here is valid for another 58 minutes, so "has expired" was the wrong half of the sentence it offered. The reason is read fresh rather than cached with the call. The call is held for an hour, and a token lapsing inside that hour would otherwise be reported as an endpoint that would not answer - the same mistake in the other direction. Second half: when antigravity publishes nothing at all it was folded into "No quota published by: antigravity." and that was the end of it. That line says the same thing about a machine that has never signed in as about one whose token lapsed an hour ago. It now gets a heading of its own underneath, with the sentence under that, so the explanation has something to belong to. The test that pinned the old copy asserted `contains("no tier")` on a default Data - whose reason is "nothing is missing", so nothing was printed and nothing needed to be. It names the case it is exercising now, and a new test checks all three: each starts the same way, ends as a sentence, differs from the other two, and the lapsed one carries the age, which is the part worth reading. --- rust/widgets/src/bin/usage/antigravity.rs | 126 ++++++++++++++++++++-- rust/widgets/src/bin/usage/vendors.rs | 20 ++++ 2 files changed, 137 insertions(+), 9 deletions(-) diff --git a/rust/widgets/src/bin/usage/antigravity.rs b/rust/widgets/src/bin/usage/antigravity.rs index b19034e..eecd157 100644 --- a/rust/widgets/src/bin/usage/antigravity.rs +++ b/rust/widgets/src/bin/usage/antigravity.rs @@ -65,6 +65,11 @@ pub struct Data { /// Which Code Assist tier the account is on. `None` means the call did /// not happen or did not answer, which the tab says out loud. live: Option<serde_json::Value>, + /// Why there is no tier, when there is none. The three reasons want + /// three different things from the reader - sign in, run the CLI, or + /// wait - and the old line offered "expired or the call failed", which + /// is the widget admitting it never looked. + tier_why: Missing, /// The quota groups, empty when the language server is not running. quota: Vec<serde_json::Value>, /// How the CLI authenticated. Read once here rather than per frame: @@ -218,6 +223,75 @@ fn antigravity_quota() -> Option<serde_json::Value> { /// Which Code Assist tier the account is on. /// +impl Data { + /// The reason the tier is missing, for callers outside this module - + /// the summary says it too, under a heading of Antigravity's own. + pub fn why_no_tier(&self) -> Missing { + if self.live.is_some() { Missing::Nothing } else { self.tier_why } + } +} + +/// Why the tier is missing, in the three ways it can be. +#[derive(Clone, Copy, Default, PartialEq)] +pub enum Missing { + /// There is a tier; nothing is missing. + #[default] + Nothing, + /// No token file, or one with no access token in it. + NotSignedIn, + /// A token that has lapsed, with how long ago in seconds. + Expired(f64), + /// A good token and no answer. Google's, not ours. + NoAnswer, +} + +/// The missing tier in one sentence, ending in what to do about it. +/// +/// The line this replaces read "no tier: the CLI's access token has expired +/// or the call failed", which names two causes, commits to neither, and asks +/// nothing of the reader. Each of these commits, because the widget can tell +/// them apart - it just was not looking. +pub fn tier_note(why: Missing) -> String { + match why { + Missing::Nothing => String::new(), + Missing::NotSignedIn => { + "no tier · Antigravity has not signed in on this machine yet. \ + Open it once and the tier appears here." + .into() + } + Missing::Expired(ago) => format!( + "no tier · Antigravity's access token expired {} ago. \ + It refreshes them itself - open it once and this fills in.", + left_span(ago) + ), + Missing::NoAnswer => { + "no tier · the token is good, but Google's Code Assist API did not \ + answer. Nothing to do here; it is retried every hour." + .into() + } + } +} + +/// What is wrong with the credential, read from the same file the call uses. +/// +/// Cheap enough to do every frame - it is a small JSON file - and it must +/// not be cached with the call: the call is held for an hour, and a token +/// that lapses inside that hour would otherwise be reported as an endpoint +/// that would not answer. +fn why_no_tier() -> Missing { + let Some(file) = read_json(&token_path()) else { + return Missing::NotSignedIn; + }; + let tok = &file["token"]; + if text(tok, "access_token").is_empty() { + return Missing::NotSignedIn; + } + match iso_epoch(&text(tok, "expiry")) { + Some(at) if at <= now() => Missing::Expired(now() - at), + _ => Missing::NoAnswer, + } +} + /// Antigravity keeps no quota and no token counts on disk - its language /// server refreshes a quota into memory and is not even installed between /// runs - so this endpoint is the only thing that can answer anything, and @@ -275,8 +349,10 @@ fn conversation_steps(path: &str) -> Option<f64> { /// anywhere carries a token count. pub fn read(caches: &mut Caches, _cfg: &Config) -> Data { use std::os::unix::fs::MetadataExt; + let live = cached(caches, "antigravity", PLAN_TTL, antigravity_live); let mut d = Data { - live: cached(caches, "antigravity", PLAN_TTL, antigravity_live), + tier_why: if live.is_some() { Missing::Nothing } else { why_no_tier() }, + live, quota: cached(caches, "antigravity-quota", LIVE_TTL, antigravity_quota) .and_then(|got| got.as_array().cloned()) .unwrap_or_default(), @@ -568,13 +644,11 @@ fn antigravity_activity(d: &Data, w: usize, p: &Palette) -> Vec<String> { fn antigravity_body(d: &Data, w: usize, p: &Palette) -> Vec<String> { let mut rows = antigravity_quota_rows(&d.quota, w, p); if d.live.is_none() { - rows.push(tc::seg( - &[( - p.warn.as_str(), - " no tier: the CLI's access token has expired or the call failed".into(), - )], - w - 1, - )); + rows.extend( + wrap_text(&tier_note(d.tier_why), w.saturating_sub(4).max(20)) + .into_iter() + .map(|line| tc::seg(&[(p.warn.as_str(), format!(" {}", line))], w - 1)), + ); rows.push(String::new()); } rows.extend(antigravity_activity(d, w, p)); @@ -854,7 +928,18 @@ mod tests { #[test] fn no_quota_is_explained_and_a_quota_is_not_contradicted() { let p = palette(); - let empty = antigravity_body(&Data::default(), 90, &p).join(" "); + // A reason has to be named: the tab says which of the three it is, + // so a fixture that leaves it at "nothing is missing" is asking for + // a sentence there is no cause to print. + let empty = antigravity_body( + &Data { + tier_why: Missing::NoAnswer, + ..Data::default() + }, + 90, + &p, + ) + .join(" "); assert!(empty.contains("no quota either")); assert!(empty.contains("no tier")); let with = antigravity_body( @@ -872,6 +957,28 @@ mod tests { assert!(!with.contains("no tier")); } + #[test] + fn each_missing_tier_asks_for_something_different() { + // The line this replaced offered "expired or the call failed" for + // all three, which is two causes, no commitment and nothing to do. + let signed_out = tier_note(Missing::NotSignedIn); + let lapsed = tier_note(Missing::Expired(3.0 * 3600.0)); + let silent = tier_note(Missing::NoAnswer); + for note in [&signed_out, &lapsed, &silent] { + assert!(note.starts_with("no tier · "), "{:?}", note); + assert!(note.trim_end().ends_with('.'), "not a sentence: {:?}", note); + } + assert!(signed_out.contains("not signed in"), "{}", signed_out); + assert!(lapsed.contains("3h"), "the age is the useful part: {}", lapsed); + assert!(silent.contains("Google"), "{}", silent); + // and each is a different sentence, which is the whole point + assert_ne!(signed_out, lapsed); + assert_ne!(lapsed, silent); + assert_ne!(signed_out, silent); + // nothing missing says nothing + assert!(tier_note(Missing::Nothing).is_empty()); + } + #[test] fn the_subscription_states_both_tiers_when_they_disagree() { let p = palette(); @@ -955,6 +1062,7 @@ mod tests { steps: 1234.0, prompts: 42, last: now() - 3600.0, + tier_why: Missing::Nothing, }; for w in [20usize, 40, 80, 200] { let plain = tab(&d, w, 40, &cfg, &p).join("\n"); diff --git a/rust/widgets/src/bin/usage/vendors.rs b/rust/widgets/src/bin/usage/vendors.rs index 90416a4..12cbc94 100644 --- a/rust/widgets/src/bin/usage/vendors.rs +++ b/rust/widgets/src/bin/usage/vendors.rs @@ -256,6 +256,26 @@ fn summary_tab(s: &State, w: usize, p: &Palette) -> Vec<String> { w, p, )); + // Antigravity is quiet for a reason it can name, and the reason is + // the useful part - "no quota published" says the same thing about a + // machine that has never signed in and one whose token lapsed an + // hour ago. Its own heading, under that line, so the sentence has + // something to belong to. + if quiet.contains(&"antigravity") { + let note = crate::antigravity::tier_note(s.antigravity.why_no_tier()); + if !note.is_empty() { + rows.push(String::new()); + rows.push(tc::seg( + &[(p.lbl.as_str(), " ANTIGRAVITY".into())], + w - 1, + )); + rows.extend( + wrap_text(¬e, w.saturating_sub(5).max(20)) + .into_iter() + .map(|l| tc::seg(&[(p.warn.as_str(), format!(" {}", l))], w - 1)), + ); + } + } } rows } From e8fb2fb7df68654056f218c097b37b478a4ad687 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Tue, 25 Aug 2026 09:54:41 +0800 Subject: [PATCH 085/147] usage: a star for cached, and the numbers a cached reading can still support "cached" was written where the countdown goes, so marking a reading as old cost the reader the reset time - and a reading a few minutes old describes the window we are in perfectly well. Its percentage is real, its reset is real, and the burn between them is worth having. Cached is a note about those numbers, not a replacement for them. A star beside the bar now, one line at the foot saying what it means, and the cell goes back to reporting the clock. The column is held for every lane so the percentages stay aligned whether the row beside them is cached or not. Claude's cached reading turned out to be the other case, and it is worth naming because it is what "cached" was hiding. The blob in ~/.claude.json was fetched nine and a half days ago and names windows that closed on the 15th and 16th. Its windows are fixed lengths, so the one we are in now is that one rolled forward - the same treatment grok's gets, marked with the same ~. The percentage is not rolled with it: that belonged to the closed window, and what has been spent in the current one was never measured. Which is the honest answer to "can we show the burn anyway": for a cache of minutes, yes, and it now does. For a cache whose window has closed, no - pace is spend against time elapsed and the spend is the unmeasured half. The pace mark on the bar goes with the figure for the same reason: a mark at 40% beside a bar at 11% reads as "well under pace", which is a claim about a window nobody measured. Why Claude was cached at all: HTTP 429. Three usage widgets were running on this machine, one since the 21st, each polling api.anthropic.com every two minutes with the same token. Stopping all of them returned 200 immediately; two running returned 429 again. Nothing was wrong with the credential - it had three hours left - and nothing was wrong with either implementation, which is why the Python showed exactly the same thing. Running the two side by side to compare them is itself enough to rate-limit both. That the screen said "cached" and not "rate limited" is the next thing to fix: claude_get discards curl's message, which names the status. --- rust/widgets/src/bin/usage/claude.rs | 24 ++++++- rust/widgets/src/bin/usage/vendors.rs | 91 +++++++++++++++++++++------ 2 files changed, 93 insertions(+), 22 deletions(-) diff --git a/rust/widgets/src/bin/usage/claude.rs b/rust/widgets/src/bin/usage/claude.rs index 0c577a7..1c6e453 100644 --- a/rust/widgets/src/bin/usage/claude.rs +++ b/rust/widgets/src/bin/usage/claude.rs @@ -972,6 +972,26 @@ pub fn lanes(c: &Data) -> Vec<Lane> { "weekly" => "7d", _ => "", }; + // A cached reading can be old enough that the window it names has + // closed - this machine's was nine days back, naming windows that + // ended on the sixteenth. Claude's windows are fixed lengths, so + // the one we are in now is that one rolled forward, and a + // countdown to it is worth more than the blank a past date left. + // + // The percentage is not rolled with it. That belonged to the + // closed window and the current one's spend is unmeasured, which + // is why `projected` also suppresses the pace. + let secs = CLAUDE_WINDOW_SECS + .iter() + .find(|(g, _)| *g == group) + .map(|(_, s)| *s); + let rolled = match (iso_epoch(&text(l, "resets_at")), secs) { + (Some(at), Some(len)) if at <= now() && len > 0.0 => { + let skipped = ((now() - at) / len).floor() + 1.0; + (Some(at + skipped * len), true) + } + (at, _) => (at, false), + }; Lane { label: format!("{} {}", name, window).trim().to_string(), pct: num(l, "percent"), @@ -979,9 +999,9 @@ pub fn lanes(c: &Data) -> Vec<Lane> { .iter() .find(|(g, _)| *g == group) .map(|(_, s)| *s), - reset: iso_epoch(&text(l, "resets_at")), + reset: rolled.0, stale: !c.quota_live, - projected: false, + projected: rolled.1, } }) .collect() diff --git a/rust/widgets/src/bin/usage/vendors.rs b/rust/widgets/src/bin/usage/vendors.rs index 12cbc94..950b836 100644 --- a/rust/widgets/src/bin/usage/vendors.rs +++ b/rust/widgets/src/bin/usage/vendors.rs @@ -131,16 +131,15 @@ fn summary_tab(s: &State, w: usize, p: &Palette) -> Vec<String> { // the first thing dropped, being the only part a reader can infer from // the bar beside it - but a stale marker is not droppable, since a // number nobody labelled as old reads as current. - let fixed = 15 + label_w; - let show_reset = (w - 1).saturating_sub(fixed + 8) >= 16; + // + // Staleness is a mark beside the bar rather than words in this cell: + // spelling it out cost the countdown, and a cached reading of a window + // still open has a real countdown worth keeping. One cell for the star, + // one line at the foot saying what it means. let any_stale = groups.iter().flat_map(|(_, g)| g.iter()).any(|l| l.stale); - let tail = if show_reset { - 16 - } else if any_stale { - 8 - } else { - 0 - }; + let fixed = 15 + label_w + usize::from(any_stale) * 2; + let show_reset = (w - 1).saturating_sub(fixed + 8) >= 16; + let tail = if show_reset { 16 } else { 0 }; let bar_room = (w - 1).saturating_sub(fixed + tail).max(8); for (i, (name, lanes)) in groups.iter().enumerate() { if i > 0 { @@ -166,23 +165,33 @@ fn summary_tab(s: &State, w: usize, p: &Palette) -> Vec<String> { } for lane in &inner { let used = (lane.pct / 100.0).clamp(0.0, 1.0); - let (when, tone) = if lane.stale { - (" cached".to_string(), p.warn.clone()) - } else if show_reset { - match lane.reset { - Some(reset) if reset - now() > 0.0 => ( + // "cached" used to replace the countdown outright, which threw + // away a fact to report an adjective. A reading a few minutes old + // still describes the window we are in: its percentage is real, + // its reset is real, and the burn between them is worth having. + // Cached is a note on the end of that, not a substitute for it. + // + // A cached reading whose window has *closed* is the other case, + // and it is the one Claude was in - a figure fetched nine days + // ago, for a window that ended on the sixteenth. There is no + // countdown there to keep, and no burn either: what has been + // spent in the current window is exactly what nobody knows. + let ahead = lane.reset.map(|r| r - now()); + let (when, tone) = if !show_reset { + (String::new(), p.dim.clone()) + } else { + match ahead { + Some(left) if left > 0.0 => ( format!( " {}{}", if lane.projected { "~" } else { "" }, - left_span(reset - now()) + left_span(left) ), - p.dim.clone(), + if lane.stale { p.warn.clone() } else { p.dim.clone() }, ), Some(_) => (" resetting".to_string(), p.dim.clone()), None => (String::new(), p.dim.clone()), } - } else { - (String::new(), p.dim.clone()) }; // A projected window is one we rolled forward because the // agent's own reading had expired - so the percentage beside it @@ -194,7 +203,12 @@ fn summary_tab(s: &State, w: usize, p: &Palette) -> Vec<String> { // exactly what nobody knows - computing it from the last // window's figure produces a confident number about a quantity // that was never measured. - let cushion = if lane.projected { + // Suppressed for a window that is not the one we are in - rolled + // forward, or cached from one that has closed. Pace is spend + // against time elapsed, and the spend in the current window is + // the unmeasured half. + let closed = ahead.is_some_and(|left| left <= 0.0); + let cushion = if lane.projected || closed { None } else { lead(lane.pct, lane.window_secs, lane.reset) @@ -206,11 +220,27 @@ fn summary_tab(s: &State, w: usize, p: &Palette) -> Vec<String> { )]; line.extend(paced_bar( used, - elapsed_of(lane.window_secs, lane.reset), + // Dropped with the pace figure and for the same reason: the + // mark says how far through the window we are, and putting + // it beside a percentage from a different window is the + // "well under pace" reading nobody measured. + if cushion.is_none() && (lane.projected || closed) { + None + } else { + elapsed_of(lane.window_secs, lane.reset) + }, bar_room, hue, p, )); + if any_stale { + // Held for every lane, so the percentages stay in one + // column whether the row beside them is cached or not. + line.push(( + p.warn.clone(), + if lane.stale { " *".into() } else { " ".to_string() }, + )); + } line.push((pct_colour(lane.pct, hue, p), pct_text(lane.pct))); line.push((pace_colour, pace_txt)); line.push((tone, when)); @@ -248,6 +278,27 @@ fn summary_tab(s: &State, w: usize, p: &Palette) -> Vec<String> { )); } } + if any_stale { + rows.push(String::new()); + rows.extend( + wrap_text( + "cached - the agent's own last reading rather than one fetched just \ + now. Its own tab says when it was taken, and why.", + w.saturating_sub(6).max(20), + ) + .into_iter() + .enumerate() + .map(|(i, line)| { + tc::seg( + &[ + (p.warn.as_str(), if i == 0 { " * " } else { " " }.into()), + (p.dim.as_str(), line), + ], + w - 1, + ) + }), + ); + } if !quiet.is_empty() { rows.push(String::new()); rows.extend(no_local( From 064071e4d56018f5b399a61ed03d02993a49b01d Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Tue, 25 Aug 2026 09:59:50 +0800 Subject: [PATCH 086/147] usage: a cached lane keeps its bar mark, its pace and its countdown, tilded Withholding them told the reader nothing. The percentage is on the row either way with a star beside it, so the figures derived from it are better shown and marked than left blank - "~+63%" and "~1d 0h" say worked-out where "+63%" and "1d 0h" would have said measured. The tilde covers two different distances from the truth and it is worth being honest about which. Where the cached window is still open the reading is minutes stale and the pace is very nearly right. Where that window has closed, the percentage is the previous window's final one and the counter has since reset, so the figure is carried forward rather than extrapolated. The star says cached, the tilde says derived, and the agent's own tab says how old - claude's already prints "cached 9d ago". pace_cell_of takes the flag; pace_cell keeps its old signature for the callers that never have one. The pace cell grows a column when anything on screen is cached, counted rather than guessed: four wide for "+40%" and five for "~+40%", plus two for the star's column. The bar's own mark comes back with them. It was dropped for the same reason the figure was, and the same answer applies - it is the window's progress, which is true, next to a percentage the star has already qualified. --- rust/widgets/src/bin/usage.rs | 24 +++++++++++++++++++-- rust/widgets/src/bin/usage/vendors.rs | 31 ++++++++++----------------- 2 files changed, 33 insertions(+), 22 deletions(-) diff --git a/rust/widgets/src/bin/usage.rs b/rust/widgets/src/bin/usage.rs index 2601c34..8edc849 100644 --- a/rust/widgets/src/bin/usage.rs +++ b/rust/widgets/src/bin/usage.rs @@ -474,11 +474,31 @@ fn pct_colour(pct: f64, hue: Option<(u8, u8, u8)>, p: &Palette) -> String { /// The signed cushion, coloured by whether it is one. fn pace_cell(value: Option<f64>, p: &Palette) -> (String, String) { + pace_cell_of(value, false, p) +} + +/// The pace figure, with `~` when it rests on a cached percentage rather +/// than one fetched just now. +/// +/// The tilde is doing real work here and it is worth being clear what it +/// covers. Where the cached window is still open the figure is a few +/// minutes stale and the mark is honest. Where that window has closed, the +/// percentage is the *previous* window's final one and the counter has since +/// reset - so the figure is carried forward rather than extrapolated, and +/// the `~` is the only thing saying so. The star beside the bar says the +/// reading is cached; the agent's own tab says how old. +fn pace_cell_of(value: Option<f64>, guessed: bool, p: &Palette) -> (String, String) { match value { None => (p.dim.clone(), String::new()), Some(v) => ( - if v >= 0.0 { p.ok.clone() } else { p.warn.clone() }, - format!(" {:+.0}%", v), + if guessed { + p.dim.clone() + } else if v >= 0.0 { + p.ok.clone() + } else { + p.warn.clone() + }, + format!(" {}{:+.0}%", if guessed { "~" } else { "" }, v), ), } } diff --git a/rust/widgets/src/bin/usage/vendors.rs b/rust/widgets/src/bin/usage/vendors.rs index 950b836..81913d4 100644 --- a/rust/widgets/src/bin/usage/vendors.rs +++ b/rust/widgets/src/bin/usage/vendors.rs @@ -137,7 +137,10 @@ fn summary_tab(s: &State, w: usize, p: &Palette) -> Vec<String> { // still open has a real countdown worth keeping. One cell for the star, // one line at the foot saying what it means. let any_stale = groups.iter().flat_map(|(_, g)| g.iter()).any(|l| l.stale); - let fixed = 15 + label_w + usize::from(any_stale) * 2; + // Three more when anything is cached: two for the star's column and one + // for the tilde the pace figure grows. Counted rather than guessed - the + // pace cell is four wide for "+40%" and five for "~+40%". + let fixed = 15 + label_w + usize::from(any_stale) * 3; let show_reset = (w - 1).saturating_sub(fixed + 8) >= 16; let tail = if show_reset { 16 } else { 0 }; let bar_room = (w - 1).saturating_sub(fixed + tail).max(8); @@ -203,32 +206,20 @@ fn summary_tab(s: &State, w: usize, p: &Palette) -> Vec<String> { // exactly what nobody knows - computing it from the last // window's figure produces a confident number about a quantity // that was never measured. - // Suppressed for a window that is not the one we are in - rolled - // forward, or cached from one that has closed. Pace is spend - // against time elapsed, and the spend in the current window is - // the unmeasured half. + // Shown for a cached reading too, marked rather than withheld: a + // blank cell tells the reader nothing, and the percentage it + // rests on is on the same row with a star beside it. let closed = ahead.is_some_and(|left| left <= 0.0); - let cushion = if lane.projected || closed { - None - } else { - lead(lane.pct, lane.window_secs, lane.reset) - }; - let (pace_colour, pace_txt) = pace_cell(cushion, p); + let guessed = lane.stale || lane.projected || closed; + let cushion = lead(lane.pct, lane.window_secs, lane.reset); + let (pace_colour, pace_txt) = pace_cell_of(cushion, guessed, p); let mut line: Vec<(String, String)> = vec![( p.dim.clone(), format!(" {} ", tc::pad(&lane.label, label_w)), )]; line.extend(paced_bar( used, - // Dropped with the pace figure and for the same reason: the - // mark says how far through the window we are, and putting - // it beside a percentage from a different window is the - // "well under pace" reading nobody measured. - if cushion.is_none() && (lane.projected || closed) { - None - } else { - elapsed_of(lane.window_secs, lane.reset) - }, + elapsed_of(lane.window_secs, lane.reset), bar_room, hue, p, From 1f4cb0cf2c998bbcccbb7f8ada851d95dd5241e2 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Tue, 25 Aug 2026 11:31:53 +0800 Subject: [PATCH 087/147] usage: keep our own claude reading, and stop trusting a cache its owner drops The fallback read cachedUsageUtilization out of ~/.claude.json with no age check. Claude Code's own reader has one: let r = Date.now() - n.data.fetchedAtMs; if (r < 0 || r > zNo) return null; // zNo = 3600000 An hour. It writes at most every five minutes and discards the entry past sixty. The one on this machine was 9.6 days old, so Claude Code had been ignoring its own cache for nine days while this widget drew it as a current percentage - 11% of a window that closed on the 16th, where the account had since spent a third of the one it was in. Not dropped and not a regression: the key is in every installed version, 2.1.243 references it more than the older builds, and the reader is the same logic in 2.1.233 - the build that wrote our last entry - with the same constant. The block is byte-identical in a backup saved on the 16th, so it froze on the 15th and has not moved since, while the file around it is rewritten every few seconds. Why the writer stopped is unestablished; it is gated on an account match and fed from response data, and finding out would mean instrumenting Claude Code rather than reading it. Two fallbacks now, newest wins: our own snapshot, and Claude Code's while it is still inside the hour. Ours is written whenever the live call answers, so on a machine in use it is minutes old rather than days, and it does not depend on another program's cache still being maintained. CodexBar arrived at the same shape from the other end - its Claude sources are the API and the CLI, never that file, with its own history file shown by capture age when they all fail. The snapshot borrows Claude Code's accountUuid as its marker, because the usage response carries no account of its own. No marker means the guard is not applied rather than the reading being refused. claude.rs had no tests at all - the only agent module without any. It has three now. The picking is a function rather than a match arm inside claude_stale so the test exercises the real thing: inverting its comparison fails it. The round trip goes through the real save and read against a temporary path, so it does not rewrite the environment other tests read, and dropping the timestamp fails it. --- docs/usage.md | 43 +++++++ rust/widgets/src/bin/usage/claude.rs | 164 ++++++++++++++++++++++++++- 2 files changed, 205 insertions(+), 2 deletions(-) diff --git a/docs/usage.md b/docs/usage.md index 80074c8..f435bcc 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -824,6 +824,49 @@ seconds and these windows move over hours, so the earlier code was making six requests a minute — three calls, twice a minute — to be told the same thing. A failure is cached too, so a dead endpoint is retried occasionally instead of on every frame. +### Claude's fallback is our own snapshot, not Claude Code's + +Claude Code keeps a usage cache in `~/.claude.json` under +`cachedUsageUtilization`, and this widget read it whenever the live call +failed. With no age check at all — which turned out to matter, because +Claude Code's own reader has one: + +```js +let r = Date.now() - n.data.fetchedAtMs; +if (r < 0 || r > zNo) return null; // zNo = 3600000 +``` + +**It trusts that cache for one hour.** It writes it at most every five +minutes (`BNo = 300000`) and discards it past sixty. On the machine this was +found on, the entry was **9.6 days old** — Claude Code had been ignoring its +own cache for nine days while this widget drew it as a current percentage. +The block was byte-identical in a backup from the 16th, so it had not moved +since the 15th, while `~/.claude.json` itself is rewritten every few seconds. + +Not a removal and not a regression: the key is present in every installed +version, `2.1.243` references it more than the older ones, and the reader is +the same logic in `2.1.233` and `2.1.243` with the same constant. Why the +writer stopped firing on the 15th is unestablished — it is gated on an +account match and fed from API response data, and finding out would mean +instrumenting Claude Code. + +So there are two fallbacks now, newest wins: + +1. **Our own snapshot**, written to `$XDG_STATE_HOME/terminal-toys/claude-usage.json` + every time the live call answers — minutes old on a machine in use, and + not dependent on another program's cache still being maintained. +2. **Claude Code's**, but only inside the hour it trusts it for. + +CodexBar reached the same conclusion from the other end: its Claude sources +are the API and the CLI, never that file, and when they all fail it keeps +its own `history/claude.json` and shows the capture age rather than blanking +the bars. + +The snapshot carries the `accountUuid` Claude Code records, so switching +accounts does not show the old one's figures — the usage response itself +carries no account, so the marker is borrowed. A machine whose Claude Code +never wrote the key has no marker, and then the guard is simply not applied. + ### Grok is the fourth, and it is off by default Grok publishes no quota this widget can read without asking for it. The other diff --git a/rust/widgets/src/bin/usage/claude.rs b/rust/widgets/src/bin/usage/claude.rs index 1c6e453..feb2f55 100644 --- a/rust/widgets/src/bin/usage/claude.rs +++ b/rust/widgets/src/bin/usage/claude.rs @@ -91,14 +91,114 @@ pub fn claude_get(url: &str, tok: &str) -> Option<serde_json::Value> { /// window whose reset has already gone by is said to have passed rather /// than counted down to, because a stale five-hour window describes a /// period that has ended. -pub fn claude_stale() -> Option<(serde_json::Value, f64)> { +/// How long Claude Code trusts its own cache, taken from its own reader: +/// `let r = Date.now() - n.data.fetchedAtMs; if (r < 0 || r > zNo) return null` +/// with `zNo = 3600000`. Identical in 2.1.233 and 2.1.243, so it is the +/// contract rather than a detail of one build. +const CLAUDE_CACHE_TTL: f64 = 3600.0; + +/// Where our own last good reading lives. +/// +/// Claude Code keeps one in ~/.claude.json and expires it after an hour. +/// This widget was reading that file with no age check at all, and on this +/// machine it had been showing a reading from nine days after Claude Code +/// stopped refreshing it - a percentage its own author discards, presented +/// as today's. +/// +/// So we keep our own, written whenever the live call answers. On a machine +/// where Claude is in use that is most refreshes, which makes it minutes old +/// rather than days, and it does not depend on another program's cache still +/// being maintained. CodexBar does the same and for the same reason: its +/// Claude sources are the API and the CLI, never that file, with its own +/// snapshot shown by capture age when they all fail. +fn snapshot_path() -> String { + let base = std::env::var("XDG_STATE_HOME").unwrap_or_else(|_| { + format!("{}/.local/state", std::env::var("HOME").unwrap_or_default()) + }); + format!("{}/terminal-toys/claude-usage.json", base) +} + +/// The account the reading belongs to, so switching accounts does not show +/// the old one's figures. Claude Code guards its cache the same way; we +/// borrow its marker because the usage response carries no account of its +/// own. Absent on a machine whose Claude Code has never written the key, and +/// then the guard is simply not applied - a missing marker is not a mismatch. +fn account_marker() -> Option<String> { + let config = read_json(&under_home(".claude.json"))?; + let uuid = text(&config["cachedUsageUtilization"], "accountUuid"); + (!uuid.is_empty()).then_some(uuid) +} + +fn save_snapshot(utilization: &serde_json::Value) { + save_snapshot_at(&snapshot_path(), utilization) +} + +/// The write, against a named path so it can be tested without reaching for +/// the real one or rewriting the environment out from under other tests. +fn save_snapshot_at(path: &str, utilization: &serde_json::Value) { + if let Some(dir) = std::path::Path::new(path).parent() { + let _ = std::fs::create_dir_all(dir); + } + let mut body = serde_json::json!({ + "fetchedAtMs": now() * 1000.0, + "utilization": utilization, + }); + if let Some(uuid) = account_marker() { + body["accountUuid"] = serde_json::json!(uuid); + } + let _ = std::fs::write(path, body.to_string()); +} + +fn read_snapshot() -> Option<(serde_json::Value, f64)> { + read_snapshot_at(&snapshot_path()) +} + +fn read_snapshot_at(path: &str) -> Option<(serde_json::Value, f64)> { + let saved = read_json(path)?; + let u = saved["utilization"].clone(); + if u.is_null() { + return None; + } + let held = text(&saved, "accountUuid"); + if let (false, Some(now_uuid)) = (held.is_empty(), account_marker()) { + if held != now_uuid { + return None; + } + } + Some((u, num(&saved, "fetchedAtMs") / 1000.0)) +} + +/// Claude Code's own cache, and only while Claude Code would still use it. +fn claude_code_cache() -> Option<(serde_json::Value, f64)> { let config = read_json(&under_home(".claude.json"))?; let c = &config["cachedUsageUtilization"]; let u = c["utilization"].clone(); if u.is_null() { return None; } - Some((u, num(c, "fetchedAtMs") / 1000.0)) + let at = num(c, "fetchedAtMs") / 1000.0; + let age = now() - at; + if !(0.0..=CLAUDE_CACHE_TTL).contains(&age) { + return None; + } + Some((u, at)) +} + +/// The best reading we have that is not live: ours if we have one, Claude +/// Code's while it is still within the hour it trusts it for, whichever was +/// taken more recently. +pub fn claude_stale() -> Option<(serde_json::Value, f64)> { + fresher(read_snapshot(), claude_code_cache()) +} + +/// Whichever reading was taken later, and neither being present is not an +/// error - it is a machine that has never had a live one. A tie goes to the +/// first, which is ours: the one whose provenance we know. +fn fresher<T>(ours: Option<(T, f64)>, theirs: Option<(T, f64)>) -> Option<(T, f64)> { + match (ours, theirs) { + (Some(a), Some(b)) => Some(if a.1 >= b.1 { a } else { b }), + (a, b) => a.or(b), + } } /// Token counts from one transcript usage block, by priced kind. @@ -316,6 +416,10 @@ pub fn read(caches: &mut Caches, _cfg: &Config) -> Data { claude.quota_live = true; claude.quota_at = num(&got, "at"); claude.quota_plan = text(&got, "plan"); + // Kept for the next refresh that cannot reach the endpoint. The + // reading is held for LIVE_TTL either way, so this writes about + // once every two minutes rather than on every frame. + save_snapshot(&got["u"]); } None => { if let Some((u, at)) = claude_stale() { @@ -1016,3 +1120,59 @@ pub fn tab(c: &Data, w: usize, _h: usize, cfg: &Config, p: &Palette) -> Vec<Stri None => body, } } + +#[cfg(test)] +mod tests { + use super::*; + + /// The rule the fossil taught: Claude Code's cache is worth reading only + /// while Claude Code itself would read it. + #[test] + fn claude_codes_cache_is_dropped_at_the_age_it_drops_it() { + // From its own reader, identical in 2.1.233 and 2.1.243: + // let r = Date.now() - n.data.fetchedAtMs; + // if (r < 0 || r > zNo) return null; // zNo = 3600000 + assert_eq!(CLAUDE_CACHE_TTL, 3600.0); + // The machine this was written on had one 9.6 days old, drawn as a + // current percentage because nothing here checked the age at all. + assert!(9.6 * 86400.0 > CLAUDE_CACHE_TTL); + assert!(59.0 * 60.0 <= CLAUDE_CACHE_TTL); + assert!(61.0 * 60.0 > CLAUDE_CACHE_TTL); + } + + #[test] + fn a_saved_reading_comes_back_the_way_it_went_in() { + let dir = std::env::temp_dir().join(format!("tt-claude-{}", std::process::id())); + let path = dir.join("claude-usage.json"); + let path = path.to_string_lossy().to_string(); + let _ = std::fs::remove_file(&path); + // Nothing saved is not a failure - it is a machine that has never + // had a live reading. + assert!(read_snapshot_at(&path).is_none()); + + let u = serde_json::json!({ + "limits": [{"group": "session", "kind": "session", "percent": 42, + "resets_at": "2026-08-25T03:39:59.750751+00:00"}] + }); + save_snapshot_at(&path, &u); + let (back, at) = read_snapshot_at(&path).expect("saved and not read back"); + assert_eq!(back, u, "the reading changed shape crossing the disk"); + assert!( + (now() - at).abs() < 60.0, + "the stamp is the moment it was taken, not the epoch: {}", + at + ); + let _ = std::fs::remove_dir_all(&dir); + } + + #[test] + fn the_later_reading_wins_and_neither_is_not_a_failure() { + assert_eq!(fresher(Some(("ours", 100.0)), Some(("theirs", 50.0))), Some(("ours", 100.0))); + assert_eq!(fresher(Some(("ours", 50.0)), Some(("theirs", 100.0))), Some(("theirs", 100.0))); + assert_eq!(fresher(Some(("ours", 10.0)), None), Some(("ours", 10.0))); + assert_eq!(fresher(None, Some(("theirs", 10.0))), Some(("theirs", 10.0))); + assert_eq!(fresher::<&str>(None, None), None); + // A tie goes to ours - we know when and how it was taken. + assert_eq!(fresher(Some(("ours", 42.0)), Some(("theirs", 42.0))), Some(("ours", 42.0))); + } +} From e756a80d4e27b98cc1710a0289e993e1216102b5 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Tue, 25 Aug 2026 11:46:36 +0800 Subject: [PATCH 088/147] usage: pin the fossil on disk, so it cannot come back as a reading The gap left last time: the fallback was covered by unit tests on its parts but never observed choosing between two real files, because provoking the 429 that triggers it is not something I can do on demand - the instance started to force one got a live reading instead. So the choice is testable now instead. claude_stale is stale_from against two named paths, and the test writes both: a Claude Code cache of a given age in the shape it writes them, and one of ours. What it pins: - A cache 9.6 days old and nothing of ours comes back as nothing. That is the bug in one line, at the age this machine actually had. - Half an hour old is still theirs to offer, and is taken. - An hour and a minute is not. The boundary is theirs, from their reader. - With both present the fresher wins, which is the reason for keeping ours. - With ours fresh and theirs a fossil, ours answers - the state this machine is in right now. - With neither, nothing. Not an error: a machine that has never had a live reading. Both were run against the defects they exist for. Removing the age check fails the first with "a cache its own owner discards was offered as a reading". Inverting fresher fails the second with "the older reading won". One mutation I tried proved nothing and is worth naming: swapping the argument order to fresher changes only the tie-break, and the two readings in that test are a minute and half an hour old, so it passed either way. A mutation that does not change behaviour is not evidence about a test. --- rust/widgets/src/bin/usage/claude.rs | 90 +++++++++++++++++++++++++++- 1 file changed, 88 insertions(+), 2 deletions(-) diff --git a/rust/widgets/src/bin/usage/claude.rs b/rust/widgets/src/bin/usage/claude.rs index feb2f55..d0618a5 100644 --- a/rust/widgets/src/bin/usage/claude.rs +++ b/rust/widgets/src/bin/usage/claude.rs @@ -170,7 +170,11 @@ fn read_snapshot_at(path: &str) -> Option<(serde_json::Value, f64)> { /// Claude Code's own cache, and only while Claude Code would still use it. fn claude_code_cache() -> Option<(serde_json::Value, f64)> { - let config = read_json(&under_home(".claude.json"))?; + claude_code_cache_at(&under_home(".claude.json")) +} + +fn claude_code_cache_at(path: &str) -> Option<(serde_json::Value, f64)> { + let config = read_json(path)?; let c = &config["cachedUsageUtilization"]; let u = c["utilization"].clone(); if u.is_null() { @@ -188,7 +192,13 @@ fn claude_code_cache() -> Option<(serde_json::Value, f64)> { /// Code's while it is still within the hour it trusts it for, whichever was /// taken more recently. pub fn claude_stale() -> Option<(serde_json::Value, f64)> { - fresher(read_snapshot(), claude_code_cache()) + stale_from(&snapshot_path(), &under_home(".claude.json")) +} + +/// The whole fallback against two named files, so a test can put a fossil +/// and a fresh reading on disk and check which one comes back. +fn stale_from(ours: &str, theirs: &str) -> Option<(serde_json::Value, f64)> { + fresher(read_snapshot_at(ours), claude_code_cache_at(theirs)) } /// Whichever reading was taken later, and neither being present is not an @@ -1140,6 +1150,82 @@ mod tests { assert!(61.0 * 60.0 > CLAUDE_CACHE_TTL); } + /// A Claude Code cache file of a given age, as it writes them. + fn their_cache(dir: &std::path::Path, name: &str, age_secs: f64, pct: i64) -> String { + let path = dir.join(name); + let body = serde_json::json!({ + "cachedUsageUtilization": { + "fetchedAtMs": (now() - age_secs) * 1000.0, + "utilization": {"limits": [{"group": "session", "kind": "session", + "percent": pct, + "resets_at": "2026-08-16T13:59:59.851930+00:00"}]}, + } + }); + std::fs::write(&path, body.to_string()).unwrap(); + path.to_string_lossy().to_string() + } + + /// The bug this whole thing was written for, pinned on disk. + /// + /// A 9.6-day-old Claude Code cache and nothing of our own used to come + /// back as a percentage and get drawn as today's. Claude Code's own + /// reader returns null for it, and now so does this. + #[test] + fn a_fossil_of_theirs_is_not_a_reading() { + let dir = std::env::temp_dir().join(format!("tt-fossil-{}", std::process::id())); + std::fs::create_dir_all(&dir).unwrap(); + let ours = dir.join("none.json").to_string_lossy().to_string(); + + let fossil = their_cache(&dir, "fossil.json", 9.6 * 86400.0, 11); + assert!( + stale_from(&ours, &fossil).is_none(), + "a cache its own owner discards was offered as a reading" + ); + + // Inside the hour it is still theirs to offer, and we take it. + let recent = their_cache(&dir, "recent.json", 30.0 * 60.0, 22); + let (got, at) = stale_from(&ours, &recent).expect("a half-hour-old reading is good"); + assert_eq!(got["limits"][0]["percent"], 22); + assert!(now() - at < 3600.0); + + // The boundary is theirs, not ours: an hour and a minute is out. + let edge = their_cache(&dir, "edge.json", 61.0 * 60.0, 33); + assert!(stale_from(&ours, &edge).is_none()); + + let _ = std::fs::remove_dir_all(&dir); + } + + /// And with both on disk, the fresher one wins - which is the point of + /// keeping our own at all. + #[test] + fn our_snapshot_beats_their_cache_when_it_is_newer() { + let dir = std::env::temp_dir().join(format!("tt-both-{}", std::process::id())); + std::fs::create_dir_all(&dir).unwrap(); + let ours = dir.join("ours.json").to_string_lossy().to_string(); + + // Ours taken just now, theirs half an hour ago and still valid. + save_snapshot_at(&ours, &serde_json::json!({ + "limits": [{"group": "session", "kind": "session", "percent": 77, + "resets_at": "2026-08-25T03:39:59.750751+00:00"}] + })); + let theirs = their_cache(&dir, "theirs.json", 30.0 * 60.0, 22); + let (got, _) = stale_from(&ours, &theirs).expect("something should come back"); + assert_eq!(got["limits"][0]["percent"], 77, "the older reading won"); + + // With theirs expired, ours is the only one left - which is the + // state this machine is actually in. + let fossil = their_cache(&dir, "fossil.json", 9.6 * 86400.0, 11); + let (got, _) = stale_from(&ours, &fossil).expect("ours should still answer"); + assert_eq!(got["limits"][0]["percent"], 77); + + // And with neither, nothing - not an error, just a machine that has + // never had a live reading. + let nowhere = dir.join("nothing.json").to_string_lossy().to_string(); + assert!(stale_from(&nowhere, &nowhere).is_none()); + + let _ = std::fs::remove_dir_all(&dir); + } + #[test] fn a_saved_reading_comes_back_the_way_it_went_in() { let dir = std::env::temp_dir().join(format!("tt-claude-{}", std::process::id())); From d7f07d93e02355e9637388e51db8bc7a551f3e85 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Tue, 25 Aug 2026 12:02:05 +0800 Subject: [PATCH 089/147] usage: ask claude every five minutes, and judge a reading by its age Three changes that only make sense together. **The interval.** claude's live read moves from the shared two minutes to five. api.anthropic.com/api/oauth/usage rate-limits the token, and the limit is shared with everything holding it - every running copy of this widget and Claude Code itself. Three copies on the two-minute hold came to a call every forty seconds between them: 429 consistently with three running, intermittently with two, 200 with none. Five minutes is what Claude Code chose for the same data - its own refresh is throttled to BNo = 300000 - and there is no argument for asking more often than the client that owns the number. **The failure hold, which the interval broke.** cached() held a failure for ttl.min(LIVE_TTL), which was the same as ttl while every caller asked every two minutes, and stopped being once claude asked every five. A failure held two minutes beside a success held five means a rate-limited poller asks *more* often than a healthy one, which is the opposite of what a 429 wants. It is FAILURE_CAP now, a ceiling rather than a fixed value: a failure waits as long as a success would have, up to five minutes. The hourly plan read still recovers in five rather than being blanked for an hour, which is what the cap was for. **What the star means.** It marked provenance - did this process fetch it - and put a star on a reading thirty-five seconds old while a live one four minutes old carried none. The fresher of the two flagged as the doubtful one. It marks age now: older than twice the fetch interval, which is the oldest a live reading can be in normal running anyway. On two pollers sharing a token, both panes now show claude's figures in full with no star, where one of them is certainly serving a cached reading. The only star left on screen is grok's, whose reading is genuinely days old. Tested, and each against the defect it exists for. The refusal-hold invariant fails if the cap goes back to a fixed two minutes. The freshness rule is tested twice: once on the rule, and once on the lane it feeds - because reverting the call site to !quota_live passed the first and failed the second, which is the only reason the second exists. --- rust/widgets/src/bin/usage/claude.rs | 95 +++++++++++++++++++++++++++- rust/widgets/src/bin/usage/shared.rs | 64 ++++++++++++++++++- 2 files changed, 154 insertions(+), 5 deletions(-) diff --git a/rust/widgets/src/bin/usage/claude.rs b/rust/widgets/src/bin/usage/claude.rs index d0618a5..d327320 100644 --- a/rust/widgets/src/bin/usage/claude.rs +++ b/rust/widgets/src/bin/usage/claude.rs @@ -97,6 +97,41 @@ pub fn claude_get(url: &str, tok: &str) -> Option<serde_json::Value> { /// contract rather than a detail of one build. const CLAUDE_CACHE_TTL: f64 = 3600.0; +/// How often this endpoint is actually asked, where the other agents use +/// the shared two minutes. +/// +/// api.anthropic.com/api/oauth/usage rate-limits this token, and the limit +/// is shared with everything else holding it: every running copy of this +/// widget, and Claude Code itself. Three copies on the two-minute hold came +/// to a call every forty seconds between them and the endpoint answered 429 +/// - consistently with three running, intermittently with two, and 200 with +/// none, which is as clear as that gets. +/// +/// Five minutes because that is the cadence Claude Code chose for the same +/// data: its own refresh is throttled to BNo = 300000. There is no argument +/// for asking more often than the client that owns the number. +const CLAUDE_LIVE_TTL: f64 = 300.0; + +/// How old a reading may be and still be shown as current. +/// +/// Twice the interval it is fetched on, because a reading is that old +/// anyway in normal running: a live one is held for CLAUDE_LIVE_TTL, so the +/// figure on screen is anywhere from nought to five minutes behind the +/// server whether it came from the endpoint or from the last copy of it. +/// +/// Marking by where a reading came from rather than by how old it is put a +/// star on a figure thirty-five seconds old while a live one four minutes +/// old carried none - the fresher of the two flagged as the doubtful one. +/// The mark is worth having when it means "older than this widget's own +/// cycle"; it is noise when it means "another process fetched it". +const CLAUDE_FRESH_FOR: f64 = 2.0 * CLAUDE_LIVE_TTL; + +/// True when the reading is old enough to be worth flagging, whatever its +/// source. `quota_at` is when it was taken, not when it was read. +fn reading_is_old(taken_at: f64) -> bool { + now() - taken_at > CLAUDE_FRESH_FOR +} + /// Where our own last good reading lives. /// /// Claude Code keeps one in ~/.claude.json and expires it after an hour. @@ -415,7 +450,7 @@ pub fn claude_rates() -> (Vec<f64>, usize) { pub fn read(caches: &mut Caches, _cfg: &Config) -> Data { let mut claude = Data::default(); - let live = cached(caches, "claude", LIVE_TTL, || { + let live = cached(caches, "claude", CLAUDE_LIVE_TTL, || { let (tok, plan) = claude_token()?; let u = claude_get("https://api.anthropic.com/api/oauth/usage", &tok)?; Some(serde_json::json!({ "u": u, "at": now(), "plan": plan })) @@ -1114,7 +1149,7 @@ pub fn lanes(c: &Data) -> Vec<Lane> { .find(|(g, _)| *g == group) .map(|(_, s)| *s), reset: rolled.0, - stale: !c.quota_live, + stale: reading_is_old(c.quota_at), projected: rolled.1, } }) @@ -1170,6 +1205,62 @@ mod tests { /// A 9.6-day-old Claude Code cache and nothing of our own used to come /// back as a percentage and get drawn as today's. Claude Code's own /// reader returns null for it, and now so does this. + #[test] + fn the_lane_takes_its_star_from_the_age_and_not_from_quota_live() { + // The wiring, not just the rule. A cached reading taken a moment ago + // must come through unflagged, and a live-flagged one taken days ago + // must not - which is the pair the old `!quota_live` got backwards. + let with = |live: bool, taken: f64| { + let d = Data { + quota: Some(serde_json::json!({ + "limits": [{"group": "session", "kind": "session", "percent": 20, + "resets_at": "2126-01-01T00:00:00.000000+00:00"}] + })), + quota_live: live, + quota_at: taken, + ..Data::default() + }; + let got = lanes(&d); + assert_eq!(got.len(), 1, "the fixture should make exactly one lane"); + got[0].stale + }; + assert!(!with(false, now() - 35.0), "a 35s cached reading is not old"); + assert!( + !with(false, now() - (CLAUDE_FRESH_FOR - 30.0)), + "just inside the window is not old" + ); + assert!( + with(false, now() - (CLAUDE_FRESH_FOR + 30.0)), + "past the window it has to be flagged" + ); + assert!( + with(true, now() - 9.6 * 86400.0), + "calling a nine-day-old reading live does not make it current" + ); + assert!(with(false, now() - 9.6 * 86400.0)); + } + + #[test] + fn a_reading_is_flagged_by_its_age_not_by_who_fetched_it() { + // The case that prompted this: a cached reading 35 seconds old sat + // under a star while a live one four minutes old carried none. Both + // are current; only one was being doubted. + assert!(!reading_is_old(now() - 35.0), "35s is fresher than most live reads"); + assert!(!reading_is_old(now() - CLAUDE_LIVE_TTL), "a live read may be this old"); + assert!( + !reading_is_old(now() - (CLAUDE_FRESH_FOR - 30.0)), + "just inside the window is still current" + ); + assert!( + reading_is_old(now() - (CLAUDE_FRESH_FOR + 30.0)), + "past twice the fetch interval it has to say so" + ); + // The one this all started with. + assert!(reading_is_old(now() - 9.6 * 86400.0)); + // A reading with no timestamp at all is not to be trusted quietly. + assert!(reading_is_old(0.0)); + } + #[test] fn a_fossil_of_theirs_is_not_a_reading() { let dir = std::env::temp_dir().join(format!("tt-fossil-{}", std::process::id())); diff --git a/rust/widgets/src/bin/usage/shared.rs b/rust/widgets/src/bin/usage/shared.rs index 566126b..104b6a5 100644 --- a/rust/widgets/src/bin/usage/shared.rs +++ b/rust/widgets/src/bin/usage/shared.rs @@ -36,6 +36,18 @@ pub struct Caches { } pub const LIVE_TTL: f64 = 120.0; +/// The longest a failure is held, whatever the success interval is. +/// +/// It exists so an hourly reading does not blank a section for an hour +/// after one transient failure. It used to be LIVE_TTL, which was the same +/// thing while every caller asked every two minutes - and stopped being +/// once claude moved to five. A failure held for two minutes beside a +/// success held for five means a rate-limited poller asks *more* often than +/// a healthy one, which is the opposite of what a 429 is asking for. +/// +/// So it is a ceiling now rather than a fixed value: a failure waits as +/// long as a success would have, up to five minutes. +pub const FAILURE_CAP: f64 = 300.0; /// A plan does not change between refreshes; the windows do. pub const PLAN_TTL: f64 = 3600.0; @@ -43,8 +55,9 @@ pub const PLAN_TTL: f64 = 3600.0; /// /// The pane redraws every thirty seconds; these windows move over hours. A /// failure is cached too, so a dead endpoint is retried occasionally rather -/// than on every frame - but only ever for the short interval, never the -/// long one. One transient 429 should not blank a section for an hour. +/// than on every frame - but never for longer than FAILURE_CAP, so one +/// transient 429 does not blank an hourly section for an hour. Nor is it +/// ever retried sooner than a success would have been asked for. pub fn cached<F>(caches: &mut Caches, key: &str, ttl: f64, fetch: F) -> Option<serde_json::Value> where F: FnOnce() -> Option<serde_json::Value>, @@ -56,7 +69,7 @@ where } } let value = fetch(); - let held = if value.is_some() { ttl } else { ttl.min(LIVE_TTL) }; + let held = if value.is_some() { ttl } else { ttl.min(FAILURE_CAP) }; caches.live.insert(key.to_string(), (at, value.clone(), held)); value } @@ -169,3 +182,48 @@ pub fn post_json( let (text, _) = tc::post_json(url, headers, body, seconds).ok()?; serde_json::from_str(&text).ok() } + +#[cfg(test)] +mod tests { + use super::*; + + /// The rule a five-minute reading broke when the cap was a fixed two + /// minutes: being refused must never make us ask *sooner* than being + /// answered would have. + #[test] + fn a_refusal_is_never_retried_sooner_than_a_success_would_be_asked() { + for ttl in [30.0, 120.0, 300.0, 900.0, 3600.0] { + let mut caches = Caches::default(); + let key = format!("probe-{}", ttl); + assert!(cached(&mut caches, &key, ttl, || None).is_none()); + let (_, _, held) = caches.live.get(&key).expect("the failure was not held"); + assert!( + *held <= ttl, + "ttl {}: a failure held {}s would be retried before a success was due", + ttl, + held + ); + assert!( + *held <= FAILURE_CAP, + "ttl {}: a failure held {}s blanks the section for too long", + ttl, + held + ); + } + } + + #[test] + fn a_good_reading_is_held_for_its_full_interval() { + let mut caches = Caches::default(); + let one = cached(&mut caches, "probe", 300.0, || Some(serde_json::json!(1))); + assert_eq!(one, Some(serde_json::json!(1))); + // The second call must not reach the fetcher at all - that is the + // whole point of the hold, and what keeps the endpoint's rate down. + let two = cached(&mut caches, "probe", 300.0, || { + panic!("asked again inside the hold") + }); + assert_eq!(two, Some(serde_json::json!(1))); + let (_, _, held) = caches.live.get("probe").unwrap(); + assert_eq!(*held, 300.0); + } +} From 03d9bcc95aaa9a38faf20bda35698095fba964a8 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Tue, 25 Aug 2026 12:05:48 +0800 Subject: [PATCH 090/147] usage: say hours when the reset is inside a day "resets in ~0.9 days" is most of a day away stated in the least useful unit. Someone reading that heading is deciding whether they can finish something before the window turns over, and nine tenths of a day does not answer it. It reads "resets in 22h 4m" now. Three headings were rounding the same span three different ways and all three lost the hours: - grok printed a decimal of a day, so anything under one read as "~0.9". - cursor truncated to whole days, so the entire last day of a cycle read "resets in 0d" - worst exactly when the number matters most. - copilot guarded against that and said "resets today", which is true and still throws away the hours it was holding. All three use left_span now, which is the formatter the rest of the widget already uses for exactly this - "5d 12h" above a day, "22h 6m" below one, "45m" below an hour. The test pins the boundary the old code fell off: a minute under a day is "23h 59m" and does not begin with a zero. grok's tilde survives the change: a rolled-forward window still says "resets in ~22h 4m", because the span being readable does not make it measured. --- rust/widgets/src/bin/usage.rs | 18 ++++++++++++++++++ rust/widgets/src/bin/usage/copilot.rs | 10 ++++++++-- rust/widgets/src/bin/usage/cursor.rs | 4 +++- rust/widgets/src/bin/usage/grok.rs | 10 +++++++--- 4 files changed, 36 insertions(+), 6 deletions(-) diff --git a/rust/widgets/src/bin/usage.rs b/rust/widgets/src/bin/usage.rs index 8edc849..9aaef73 100644 --- a/rust/widgets/src/bin/usage.rs +++ b/rust/widgets/src/bin/usage.rs @@ -1674,6 +1674,24 @@ mod vendors; #[cfg(test)] mod tests { + + /// Under a day, say the hours. The quota headings used to render this + /// span three different ways - "~0.9 days", a truncated "0d", and + /// "resets today" - and all three round away the part a reader is + /// asking for when the reset is close. + #[test] + fn a_span_under_a_day_is_hours_and_minutes() { + assert_eq!(left_span(22.0 * 3600.0 + 6.0 * 60.0), "22h 6m"); + assert_eq!(left_span(45.0 * 60.0), "45m"); + assert_eq!(left_span(3600.0), "1h 0m"); + // A day or more keeps days, which is what that range wants. + assert_eq!(left_span(5.0 * 86400.0 + 12.0 * 3600.0), "5d 12h"); + assert_eq!(left_span(86400.0), "1d 0h"); + // The boundary the old code fell off: just under a day is not "0d". + let almost = 86400.0 - 60.0; + assert_eq!(left_span(almost), "23h 59m"); + assert!(!left_span(almost).starts_with('0')); + } use super::*; #[test] diff --git a/rust/widgets/src/bin/usage/copilot.rs b/rust/widgets/src/bin/usage/copilot.rs index e28c00a..71d8795 100644 --- a/rust/widgets/src/bin/usage/copilot.rs +++ b/rust/widgets/src/bin/usage/copilot.rs @@ -455,8 +455,14 @@ fn copilot_tab(d: &Data, w: usize, p: &Palette) -> Vec<String> { let stamp = iso_epoch(&text(live, "quota_reset_date_utc")); let mut when = String::new(); if let Some(stamp) = stamp { - let days = ((stamp - now()) / 86400.0).floor() as i64; - when = if days > 0 { format!("resets in {}d", days) } else { "resets today".into() }; + let left = stamp - now(); + // "resets today" was already better than a truncated 0d, and + // the hours it was rounding away are better still. + when = if left > 0.0 { + format!("resets in {}", left_span(left)) + } else { + "resetting".into() + }; } rows.push(tc::seg( &[ diff --git a/rust/widgets/src/bin/usage/cursor.rs b/rust/widgets/src/bin/usage/cursor.rs index d081684..677edf1 100644 --- a/rust/widgets/src/bin/usage/cursor.rs +++ b/rust/widgets/src/bin/usage/cursor.rs @@ -435,7 +435,9 @@ fn cursor_quota(d: &Data, w: usize, p: &Palette) -> Vec<String> { Some(ends) => { let left = ends / 1000.0 - now(); if left > 0.0 { - format!("resets in {}d", (left / 86400.0) as i64) + // Truncated days read "resets in 0d" for the whole of the + // last day of a cycle, which is when it matters most. + format!("resets in {}", left_span(left)) } else { "resetting".to_string() } diff --git a/rust/widgets/src/bin/usage/grok.rs b/rust/widgets/src/bin/usage/grok.rs index f9e8392..cfc2e75 100644 --- a/rust/widgets/src/bin/usage/grok.rs +++ b/rust/widgets/src/bin/usage/grok.rs @@ -623,7 +623,7 @@ fn grok_tab(d: &Data, w: usize, p: &Palette) -> Vec<String> { } else { window_now(begin, end, now()) }; - let left = current.map(|e| (e - now()) / 86400.0).filter(|days| *days >= 0.0); + let left = current.map(|e| e - now()).filter(|secs| *secs >= 0.0); rows.push(tc::seg( &[ ( @@ -632,8 +632,12 @@ fn grok_tab(d: &Data, w: usize, p: &Palette) -> Vec<String> { ), ( p.dim.as_str(), - left.map(|days| { - format!("resets in {}{:.1} days", if rolled { "~" } else { "" }, days) + // left_span, not a decimal of a day: "~0.9 days" is + // most of a day away stated in the least useful unit, + // and the reader wanting to know if they can finish + // something before the reset needs hours and minutes. + left.map(|secs| { + format!("resets in {}{}", if rolled { "~" } else { "" }, left_span(secs)) }) .unwrap_or_default(), ), From 703e7ab7b1f04193c4c4eeadbf2b0abe30a68f84 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Tue, 25 Aug 2026 12:26:32 +0800 Subject: [PATCH 091/147] usage: one grok setting, because nobody wants half of it grok_ping_after_session was a separate key for one release. It should not have been: the refresh is not an option alongside the polling, it is what keeps the polling working. The token expires, and asking without refreshing works for a while and then silently stops - which is the failure the refresh was added to prevent. Anyone turning the first on wants the second. So grok_ping now means both: ask x.ai on the interval, and run the CLI once after a session goes quiet to refresh the token that asking needs. Still off by default, and still for the two reasons it was - it talks to a vendor and it starts somebody else's program - but those are now one decision rather than two, which is what they always were. --- config.example.json | 5 ++--- docs/usage.md | 22 ++++++++++++---------- rust/widgets/src/bin/usage.rs | 16 +++++++--------- rust/widgets/src/bin/usage/grok.rs | 8 +++++--- 4 files changed, 26 insertions(+), 25 deletions(-) diff --git a/config.example.json b/config.example.json index 16c5fcb..6f0ab03 100644 --- a/config.example.json +++ b/config.example.json @@ -104,10 +104,9 @@ "rates": {}, "_plan_cost_comment": "What each subscription costs you per month, keyed by agent, for example claude: 200. Nothing ships here: Anthropic lists Max as 'from $100' because it varies by tier, and no invoice is on this machine. Set it and METERED adds 'the plan saves'.", "plan_cost": {}, - "_grok_ping_comment": "Grok is the only agent with no live quota: its figures come from the log its own CLI writes, so they move only when you use Grok on this machine. Turn grok_ping on to ask x.ai instead, using the token the CLI leaves in ~/.grok/auth.json. grok_ping_after_session runs the CLI once after a session goes quiet, which is what refreshes that token - without it the asking stops working when the token lapses. Both are off by default: one talks to a vendor, the other starts somebody else's program.", + "_grok_ping_comment": "Grok is the only agent with no live quota: its figures come from the log its own CLI writes, so they move only when you use Grok on this machine. Turn grok_ping on to ask x.ai instead, using the token the CLI leaves in ~/.grok/auth.json. That also runs the Grok CLI once after a session goes quiet, which is what refreshes the token - without it the asking works until the token lapses and then silently stops. Off by default: a widget that reads should not start talking to a vendor, or starting somebody else's program, because it was launched.", "grok_ping": false, - "grok_ping_minutes": 60, - "grok_ping_after_session": false + "grok_ping_minutes": 60 }, "link": { "_comment": "Every established connection into a port this machine listens on. Empty ports means all of them, which is the useful default. No network traffic: the numbers come from the kernel's own accounting via ss.", diff --git a/docs/usage.md b/docs/usage.md index f435bcc..763cdc9 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -884,17 +884,19 @@ Three settings, all off or hourly by default: | key | default | what it does | |---|---|---| -| `grok_ping` | `false` | GET `cli-chat-proxy.grok.com/v1/billing`, with the bearer token the Grok CLI leaves in `~/.grok/auth.json` | +| `grok_ping` | `false` | GET `cli-chat-proxy.grok.com/v1/billing` with the bearer token the Grok CLI leaves in `~/.grok/auth.json`, **and** run `grok agent stdio` once after a session goes quiet to refresh that token | | `grok_ping_minutes` | `60` | how often. The window moves over days; an hour is current without being traffic | -| `grok_ping_after_session` | `false` | run `grok agent stdio` once after a session goes quiet, purely to refresh that token | - -**Off by default for two different reasons.** `grok_ping` talks to a vendor, -and a widget that reads should not start doing that because it was launched. -`grok_ping_after_session` is the stronger case: it starts somebody else's -program. It exists because the token expires — mine had lapsed 8.6 days before -I looked, on the same day the CLI last ran — and without a refresh the asking -works for a while and then silently stops, which is the failure it was added to -fix. + +**One setting, not two.** The refresh was a second key for one release and +should not have been. The token expires — mine had lapsed 8.6 days before I +looked, on the same day the CLI last ran — so asking without refreshing works +for a while and then silently stops, which is the failure the refresh exists to +prevent. Nobody wants the first without the second, so turning on `grok_ping` +turns on both. + +**Off by default**, because it does two things a widget that reads has no +business doing unasked: it talks to a vendor, and it starts somebody else's +program. The screen says which state it is in, in both places it appears: diff --git a/rust/widgets/src/bin/usage.rs b/rust/widgets/src/bin/usage.rs index 9aaef73..85ead7a 100644 --- a/rust/widgets/src/bin/usage.rs +++ b/rust/widgets/src/bin/usage.rs @@ -1179,16 +1179,18 @@ struct Config { /// Off by default: asking means a request to x.ai carrying the token its /// CLI left on disk, and a widget that reads should not start talking to /// a vendor because it was launched. + /// + /// Turning it on also permits running the Grok CLI once after a session + /// goes quiet, because that is what refreshes the token the request + /// needs. The two were separate settings for one release and should not + /// have been: asking without refreshing works until the token lapses and + /// then stops, silently, which is the failure the refresh exists to + /// prevent. Nobody wants the first without the second. grok_ping: bool, /// Minutes between those requests. The window it reports moves over /// days, so an hour is frequent enough to be current and rare enough /// not to be traffic. grok_ping_minutes: f64, - /// Whether to run the Grok CLI once a session goes quiet. That is what - /// refreshes the token the request needs - without it the token expires - /// and the quota silently goes back to being read off the disk. Off by - /// default for the stronger reason: it starts somebody else's program. - grok_ping_after_session: bool, } fn read_config() -> Config { @@ -1225,10 +1227,6 @@ fn read_config() -> Config { .and_then(|v| v.as_bool()) .unwrap_or(false), grok_ping_minutes: tc::cfg_f64(&raw, "grok_ping_minutes", 60.0), - grok_ping_after_session: raw - .get("grok_ping_after_session") - .and_then(|v| v.as_bool()) - .unwrap_or(false), } } diff --git a/rust/widgets/src/bin/usage/grok.rs b/rust/widgets/src/bin/usage/grok.rs index cfc2e75..14c50f1 100644 --- a/rust/widgets/src/bin/usage/grok.rs +++ b/rust/widgets/src/bin/usage/grok.rs @@ -251,8 +251,10 @@ fn quota_now(caches: &mut Caches, cfg: &Config) -> (Option<Quota>, bool, f64) { /// refresh happens when a session has just ended - the moment the numbers /// have changed and nobody is at the keyboard waiting. /// -/// It starts somebody else's program, so it is off unless asked for. The -/// handshake is the smallest one the agent answers: initialize, then close. +/// It starts somebody else's program, which is part of what grok_ping asks +/// for rather than a setting of its own - polling that stops working the +/// moment the token lapses is not what anybody turned on. The handshake is +/// the smallest one the agent answers: initialize, then close. fn refresh_token() { use std::io::Write; let Ok(mut child) = std::process::Command::new(under_home(CLI)) @@ -337,7 +339,7 @@ pub fn read(caches: &mut Caches, cfg: &Config) -> Data { // and nobody is waiting on the pane. Refreshing the token then keeps the // asking working; refreshing while a session is still running would mean // starting the CLI under somebody who is using it. - if cfg.grok_ping && cfg.grok_ping_after_session && newest > 0.0 { + if cfg.grok_ping && newest > 0.0 { let quiet = now() - newest; let handled = caches .live From 7651a458f642abd17687615862ac1a2f5092a07f Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Tue, 25 Aug 2026 12:57:21 +0800 Subject: [PATCH 092/147] usage: back off when refused, and say what the refusal was MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three things, and the last is the one that was overdue. **The backoff.** A refusal was held for a flat interval, so a poller turned away walked back in at exactly the rate that provoked it. It doubles now: 120s, 240, 480, 960, then 1800 and no further. Two minutes for the first because one failure is usually nothing - a dropped connection, a server having a moment - and waiting five for it would make a blip look like an outage. The ceiling is thirty minutes because that is where the screen starts calling a reading old; backing off past the point where the reader is told something is wrong would leave the widget quietly not trying. **The freshness window.** Thirty minutes rather than twice the poll. A weekly quota does not move enough in half an hour to mislead anyone, and it lines the two up: the screen starts saying "old" at the same moment the backoff has given up asking quickly. **The reason, which was being thrown away.** tc::get returns curl's own message and every caller here discarded it with .ok()?. So the tab could say a reading was old and never why - and this morning that cost an hour on a credential with three hours left on it, while the server had already said "too many requests". refusal() turns curl's message into something to act on: 429 into "too many requests - something else is polling the same token", 401 and 403 into a token that wants signing in again, a timeout into a timeout, and anything unrecognised into itself rather than into nothing. The string the test is built on is the one curl actually produced against api.anthropic.com while three widgets shared a token. claude's tab reads "cached 4m ago · too many requests - something else is polling the same token". antigravity's note gains the same, appended to whichever of its three sentences applies. Both hold the reason in the cache beside the failure, so it is shown for as long as the failure lasts rather than only on the frame the request was made. Two things worth recording about getting here. The first version of the tab test asserted the line contained no "·" when there was nothing to say - but the heading has one of its own, so it failed for a reason that was not the one it was testing. And a sed anchored on a line that appears twice clobbered the branch beside the one it meant to change, then a restore anchored on a comment failed silently and left neither. Both were caught by running rather than by reading; the edits are line-indexed with their neighbours asserted now, which is what this repo's own notes say to do. --- rust/widgets/src/bin/usage/antigravity.rs | 56 +++++-- rust/widgets/src/bin/usage/claude.rs | 135 ++++++++++++--- rust/widgets/src/bin/usage/shared.rs | 193 ++++++++++++++++++---- 3 files changed, 319 insertions(+), 65 deletions(-) diff --git a/rust/widgets/src/bin/usage/antigravity.rs b/rust/widgets/src/bin/usage/antigravity.rs index eecd157..4189ebd 100644 --- a/rust/widgets/src/bin/usage/antigravity.rs +++ b/rust/widgets/src/bin/usage/antigravity.rs @@ -70,6 +70,8 @@ pub struct Data { /// wait - and the old line offered "expired or the call failed", which /// is the widget admitting it never looked. tier_why: Missing, + /// What the endpoint said, when it said anything. Empty otherwise. + tier_said: String, /// The quota groups, empty when the language server is not running. quota: Vec<serde_json::Value>, /// How the CLI authenticated. Read once here rather than per frame: @@ -245,6 +247,7 @@ pub enum Missing { NoAnswer, } + /// The missing tier in one sentence, ending in what to do about it. /// /// The line this replaces read "no tier: the CLI's access token has expired @@ -272,6 +275,16 @@ pub fn tier_note(why: Missing) -> String { } } +/// The same, with the server's own words when there are any. +pub fn tier_note_said(why: Missing, said: &str) -> String { + let base = tier_note(why); + match (base.is_empty(), said.is_empty()) { + (true, _) => String::new(), + (false, true) => base, + (false, false) => format!("{} It said: {}.", base, said), + } +} + /// What is wrong with the credential, read from the same file the call uses. /// /// Cheap enough to do every frame - it is a small JSON file - and it must @@ -292,24 +305,23 @@ fn why_no_tier() -> Missing { } } -/// Antigravity keeps no quota and no token counts on disk - its language -/// server refreshes a quota into memory and is not even installed between -/// runs - so this endpoint is the only thing that can answer anything, and -/// what it answers is the subscription rather than the spend. -/// -/// The access token expires hourly and Antigravity refreshes it; an expired -/// one is skipped rather than refreshed here, for the same reason Claude's -/// is: that is the CLI's job and racing it would be rude. -fn antigravity_live() -> Option<serde_json::Value> { - let file = read_json(&token_path())?; +fn antigravity_said() -> Result<serde_json::Value, String> { + let Some(file) = read_json(&token_path()) else { + return Err(String::new()); + }; let tok = &file["token"]; let access = text(tok, "access_token"); let expiry = iso_epoch(&text(tok, "expiry")); if access.is_empty() || expiry.is_some_and(|at| at <= now()) { - return None; + return Err(String::new()); } - post_json( - CODE_ASSIST_API, + post_try(CODE_ASSIST_API, &access) +} + +/// The same call, keeping why it failed. +fn post_try(url: &str, access: &str) -> Result<serde_json::Value, String> { + post_json_said( + url, &[ ("Authorization", &format!("Bearer {}", access)), ("Content-Type", "application/json"), @@ -349,9 +361,22 @@ fn conversation_steps(path: &str) -> Option<f64> { /// anywhere carries a token count. pub fn read(caches: &mut Caches, _cfg: &Config) -> Data { use std::os::unix::fs::MetadataExt; - let live = cached(caches, "antigravity", PLAN_TTL, antigravity_live); + // The refusal is cached with the failure, so it is shown for as long as + // the failure lasts rather than only on the frame the call was made. + let live = cached(caches, "antigravity", PLAN_TTL, || { + match antigravity_said() { + Ok(v) => Some(v), + Err(why) => Some(serde_json::json!({ "terminal_toys_refusal": why })), + } + }); + let said = live + .as_ref() + .map(|v| text(v, "terminal_toys_refusal")) + .unwrap_or_default(); + let live = if said.is_empty() { live } else { None }; let mut d = Data { tier_why: if live.is_some() { Missing::Nothing } else { why_no_tier() }, + tier_said: said, live, quota: cached(caches, "antigravity-quota", LIVE_TTL, antigravity_quota) .and_then(|got| got.as_array().cloned()) @@ -645,7 +670,7 @@ fn antigravity_body(d: &Data, w: usize, p: &Palette) -> Vec<String> { let mut rows = antigravity_quota_rows(&d.quota, w, p); if d.live.is_none() { rows.extend( - wrap_text(&tier_note(d.tier_why), w.saturating_sub(4).max(20)) + wrap_text(&tier_note_said(d.tier_why, &d.tier_said), w.saturating_sub(4).max(20)) .into_iter() .map(|line| tc::seg(&[(p.warn.as_str(), format!(" {}", line))], w - 1)), ); @@ -1063,6 +1088,7 @@ mod tests { prompts: 42, last: now() - 3600.0, tier_why: Missing::Nothing, + tier_said: String::new(), }; for w in [20usize, 40, 80, 200] { let plain = tab(&d, w, 40, &cfg, &p).join("\n"); diff --git a/rust/widgets/src/bin/usage/claude.rs b/rust/widgets/src/bin/usage/claude.rs index d327320..2d4c020 100644 --- a/rust/widgets/src/bin/usage/claude.rs +++ b/rust/widgets/src/bin/usage/claude.rs @@ -46,6 +46,9 @@ pub struct Data { quota: Option<serde_json::Value>, quota_live: bool, quota_at: f64, + /// Why the last attempt did not answer, when it did not. Empty while it + /// is answering. + quota_why: String, quota_plan: String, profile: Option<serde_json::Value>, /// Output tokens per second, sorted, and how many transcripts it came @@ -73,6 +76,16 @@ pub fn claude_token() -> Option<(String, String)> { } pub fn claude_get(url: &str, tok: &str) -> Option<serde_json::Value> { + claude_try(url, tok).ok() +} + +/// The same request, keeping why it failed. +/// +/// `.ok()?` threw that away, so the tab could say a reading was old and +/// never why. The server had been answering "too many requests" for an hour +/// while the screen said "cached" and a credential with three hours left on +/// it got the blame. +fn claude_try(url: &str, tok: &str) -> Result<serde_json::Value, String> { let body = tc::get( url, &[ @@ -81,8 +94,8 @@ pub fn claude_get(url: &str, tok: &str) -> Option<serde_json::Value> { ], 20, ) - .ok()?; - serde_json::from_str(&body).ok() + .map_err(|said| refusal(&said))?; + serde_json::from_str(&body).map_err(|e| format!("unreadable answer: {}", e)) } /// What Claude Code last fetched, for when the live call cannot run. @@ -114,17 +127,19 @@ const CLAUDE_LIVE_TTL: f64 = 300.0; /// How old a reading may be and still be shown as current. /// -/// Twice the interval it is fetched on, because a reading is that old -/// anyway in normal running: a live one is held for CLAUDE_LIVE_TTL, so the -/// figure on screen is anywhere from nought to five minutes behind the -/// server whether it came from the endpoint or from the last copy of it. +/// Half an hour. A reading is already up to five minutes behind the server +/// in normal running - a live one is held for CLAUDE_LIVE_TTL - and a quota +/// window that turns over weekly does not move enough in half an hour to +/// mislead anyone. It is also where the backoff stops doubling, so the +/// screen starts saying "old" at the same moment the widget has given up +/// trying quickly. /// /// Marking by where a reading came from rather than by how old it is put a /// star on a figure thirty-five seconds old while a live one four minutes /// old carried none - the fresher of the two flagged as the doubtful one. /// The mark is worth having when it means "older than this widget's own /// cycle"; it is noise when it means "another process fetched it". -const CLAUDE_FRESH_FOR: f64 = 2.0 * CLAUDE_LIVE_TTL; +const CLAUDE_FRESH_FOR: f64 = 1800.0; /// True when the reading is old enough to be worth flagging, whatever its /// source. `quota_at` is when it was taken, not when it was read. @@ -184,10 +199,6 @@ fn save_snapshot_at(path: &str, utilization: &serde_json::Value) { let _ = std::fs::write(path, body.to_string()); } -fn read_snapshot() -> Option<(serde_json::Value, f64)> { - read_snapshot_at(&snapshot_path()) -} - fn read_snapshot_at(path: &str) -> Option<(serde_json::Value, f64)> { let saved = read_json(path)?; let u = saved["utilization"].clone(); @@ -203,11 +214,6 @@ fn read_snapshot_at(path: &str) -> Option<(serde_json::Value, f64)> { Some((u, num(&saved, "fetchedAtMs") / 1000.0)) } -/// Claude Code's own cache, and only while Claude Code would still use it. -fn claude_code_cache() -> Option<(serde_json::Value, f64)> { - claude_code_cache_at(&under_home(".claude.json")) -} - fn claude_code_cache_at(path: &str) -> Option<(serde_json::Value, f64)> { let config = read_json(path)?; let c = &config["cachedUsageUtilization"]; @@ -450,11 +456,26 @@ pub fn claude_rates() -> (Vec<f64>, usize) { pub fn read(caches: &mut Caches, _cfg: &Config) -> Data { let mut claude = Data::default(); + // The reason rides along in the cached value, so it is held and shown + // for as long as the failure it describes rather than only on the frame + // the request happened to be made. let live = cached(caches, "claude", CLAUDE_LIVE_TTL, || { - let (tok, plan) = claude_token()?; - let u = claude_get("https://api.anthropic.com/api/oauth/usage", &tok)?; - Some(serde_json::json!({ "u": u, "at": now(), "plan": plan })) + let Some((tok, plan)) = claude_token() else { + return Some(serde_json::json!({ "why": "no token - Claude Code has not signed in here" })); + }; + match claude_try("https://api.anthropic.com/api/oauth/usage", &tok) { + Ok(u) => Some(serde_json::json!({ "u": u, "at": now(), "plan": plan })), + Err(why) => Some(serde_json::json!({ "why": why })), + } }); + // A cached entry carrying only a reason is a refusal, not a reading. + let live = match live { + Some(got) if !text(&got, "why").is_empty() => { + claude.quota_why = text(&got, "why"); + None + } + other => other, + }; match live { Some(got) => { claude.quota = Some(got["u"].clone()); @@ -564,8 +585,14 @@ pub fn claude_quota(c: &Data, w: usize, p: &Palette) -> Vec<String> { lanes.sort_by_key(|l| claude_lane_rank(l)); let src = if c.quota_live { "live".to_string() - } else { + } else if c.quota_why.is_empty() { format!("cached {} ago", ago(c.quota_at)) + } else { + // Why, not just how old. "cached 4m ago" tells a reader the number + // is behind and leaves them to guess whether their login has + // lapsed; naming the refusal is the difference between closing a + // spare pane and going through a credential that was never wrong. + format!("cached {} ago · {}", ago(c.quota_at), c.quota_why) }; let hue = agent_hue("claude"); let mut rows = vec![tc::seg( @@ -1205,6 +1232,74 @@ mod tests { /// A 9.6-day-old Claude Code cache and nothing of our own used to come /// back as a percentage and get drawn as today's. Claude Code's own /// reader returns null for it, and now so does this. + #[test] + fn the_tab_says_why_it_is_on_a_cached_reading() { + // The whole point of keeping curl's message. "cached 4m ago" leaves + // a reader to guess whether their login lapsed; this morning that + // guess cost an hour on a credential with three hours left on it. + let p = palette(); + let bare = |rows: Vec<String>| { + rows.iter() + .map(|r| { + let mut out = String::new(); + let mut cs = r.chars(); + while let Some(c) = cs.next() { + if c == '\x1b' { + for n in cs.by_ref() { + if n.is_ascii_alphabetic() { + break; + } + } + } else { + out.push(c) + } + } + out + }) + .collect::<Vec<_>>() + .join(" ") + }; + let with = |live: bool, why: &str| { + let d = Data { + quota: Some(serde_json::json!({ + "limits": [{"group": "session", "kind": "session", "percent": 20, + "resets_at": "2026-08-26T00:00:00.000000+00:00"}] + })), + quota_live: live, + quota_at: now() - 240.0, + quota_why: why.to_string(), + ..Data::default() + }; + bare(claude_quota(&d, 100, &p)) + }; + + let refused = with(false, "too many requests - something else is polling the same token"); + assert!(refused.contains("cached"), "{}", refused); + assert!( + refused.contains("too many requests"), + "the reason was dropped again: {}", + refused + ); + + // No reason recorded is the old wording, unchanged. + // The heading carries a · of its own, so the check is for the + // reason's words rather than for the separator - which is what the + // first version of this test got wrong, and why it was run before + // being believed. + let quiet = with(false, ""); + assert!(quiet.contains("cached"), "{}", quiet); + assert!( + !quiet.contains("too many requests"), + "a reason appeared from nowhere: {}", + quiet + ); + + // And a live reading says nothing about refusals at all. + let good = with(true, ""); + assert!(good.contains("live"), "{}", good); + assert!(!good.contains("cached"), "{}", good); + } + #[test] fn the_lane_takes_its_star_from_the_age_and_not_from_quota_live() { // The wiring, not just the rule. A cached reading taken a moment ago diff --git a/rust/widgets/src/bin/usage/shared.rs b/rust/widgets/src/bin/usage/shared.rs index 104b6a5..b82bb31 100644 --- a/rust/widgets/src/bin/usage/shared.rs +++ b/rust/widgets/src/bin/usage/shared.rs @@ -33,31 +33,43 @@ pub struct Caches { pub transcripts: HashMap<String, ((u64, u64), HashMap<String, (String, String, Tokens)>)>, /// key -> (when, value, ttl) pub live: HashMap<String, (f64, Option<serde_json::Value>, f64)>, + /// key -> refusals in a row, which is what the backoff doubles on. + /// Cleared the moment one gets through. + pub fails: HashMap<String, u32>, } pub const LIVE_TTL: f64 = 120.0; -/// The longest a failure is held, whatever the success interval is. +/// Where a refusal starts waiting, and where it stops. /// -/// It exists so an hourly reading does not blank a section for an hour -/// after one transient failure. It used to be LIVE_TTL, which was the same -/// thing while every caller asked every two minutes - and stopped being -/// once claude moved to five. A failure held for two minutes beside a -/// success held for five means a rate-limited poller asks *more* often than -/// a healthy one, which is the opposite of what a 429 is asking for. +/// Two minutes for the first, because one failure is usually nothing - a +/// dropped connection, a server having a moment - and waiting five for it +/// would make a blip look like an outage. Doubling after that, because a +/// refusal that keeps coming is not a blip, and the flat hold this replaced +/// walked back in at the same rate however many times it was turned away. +/// That is what sustains a rate limit rather than clearing it. /// -/// So it is a ceiling now rather than a fixed value: a failure waits as -/// long as a success would have, up to five minutes. -pub const FAILURE_CAP: f64 = 300.0; +/// 120, 240, 480, 960, then 1800 and no further. The ceiling is thirty +/// minutes because that is when the screen starts calling a reading old: +/// backing off past the point where the reader is told something is wrong +/// would leave the widget quietly not trying. +pub const BACKOFF_FROM: f64 = 120.0; +pub const BACKOFF_MAX: f64 = 1800.0; + +/// How long to wait after `n` refusals in a row. +pub fn backoff(n: u32) -> f64 { + let doubled = BACKOFF_FROM * 2f64.powi(n.saturating_sub(1).min(16) as i32); + doubled.min(BACKOFF_MAX) +} /// A plan does not change between refreshes; the windows do. pub const PLAN_TTL: f64 = 3600.0; /// Hold a reading for a while, but never hold a failure that long. /// /// The pane redraws every thirty seconds; these windows move over hours. A -/// failure is cached too, so a dead endpoint is retried occasionally rather -/// than on every frame - but never for longer than FAILURE_CAP, so one -/// transient 429 does not blank an hourly section for an hour. Nor is it -/// ever retried sooner than a success would have been asked for. +/// refusal is held too, so a dead endpoint is retried occasionally rather +/// than on every frame - and held longer each time it is refused again, so +/// an endpoint saying "too often" is not answered at the same rate that +/// provoked it. pub fn cached<F>(caches: &mut Caches, key: &str, ttl: f64, fetch: F) -> Option<serde_json::Value> where F: FnOnce() -> Option<serde_json::Value>, @@ -69,7 +81,17 @@ where } } let value = fetch(); - let held = if value.is_some() { ttl } else { ttl.min(FAILURE_CAP) }; + let held = if value.is_some() { + caches.fails.remove(key); + ttl + } else { + let n = caches.fails.entry(key.to_string()).or_insert(0); + *n += 1; + // Never longer than the interval itself would have been, for a + // reading asked for hourly: backing an hourly plan read off to + // thirty minutes is fine, but it must not exceed the hour. + backoff(*n).min(ttl.max(BACKOFF_FROM)) + }; caches.live.insert(key.to_string(), (at, value.clone(), held)); value } @@ -163,6 +185,39 @@ pub struct Lane { pub projected: bool, } +/// What a refused request said, in words a reader can act on. +/// +/// `tc::get` returns curl's own message, which for `--fail` names the status +/// - "curl: (22) The requested URL returned error: 429". Every caller here +/// threw that away with `.ok()?`, so the screen could say a reading was old +/// but never why, and an hour went into checking a credential that was fine +/// while the server had already said "too many requests". +/// +/// The code is read out of that message rather than guessed at. Anything +/// unrecognised is passed through as the reason it was, which is still more +/// than nothing. +pub fn refusal(said: &str) -> String { + let code = said + .rsplit_once("error: ") + .and_then(|(_, tail)| tail.split_whitespace().next()) + .and_then(|c| c.parse::<u16>().ok()); + match code { + Some(429) => "too many requests - something else is polling the same token".into(), + Some(401) | Some(403) => "the token was refused - the agent may need signing in again".into(), + Some(404) => "the endpoint is gone".into(), + Some(c) if (500..600).contains(&c) => format!("the server answered {}", c), + Some(c) => format!("the server answered {}", c), + // A timeout or a dead network never reaches a status at all. + None if said.contains("timed out") || said.contains("Timeout") => { + "the request timed out".into() + } + None if said.contains("Could not resolve") || said.contains("Failed to connect") => { + "could not reach it".into() + } + None => said.trim_start_matches("curl: ").to_string(), + } +} + /// An HTTPS GET carrying a bearer token, returning parsed JSON. /// /// The token goes to curl on its standard input, never in its arguments: @@ -179,36 +234,114 @@ pub fn post_json( body: &str, seconds: u64, ) -> Option<serde_json::Value> { - let (text, _) = tc::post_json(url, headers, body, seconds).ok()?; - serde_json::from_str(&text).ok() + post_json_said(url, headers, body, seconds).ok() +} + +/// The same POST, keeping why it failed rather than discarding it. +pub fn post_json_said( + url: &str, + headers: &[(&str, &str)], + body: &str, + seconds: u64, +) -> Result<serde_json::Value, String> { + let (text, _) = tc::post_json(url, headers, body, seconds).map_err(|said| refusal(&said))?; + serde_json::from_str(&text).map_err(|e| format!("unreadable answer: {}", e)) } #[cfg(test)] mod tests { use super::*; - /// The rule a five-minute reading broke when the cap was a fixed two - /// minutes: being refused must never make us ask *sooner* than being - /// answered would have. + /// The string this was built from is the one curl actually produced + /// against api.anthropic.com while three widgets shared a token. + #[test] + fn a_refusal_says_which_refusal_it_was() { + let real = "curl: (22) The requested URL returned error: 429"; + assert!( + refusal(real).contains("too many requests"), + "the message that cost an hour: {:?}", + refusal(real) + ); + assert!(refusal(real).contains("same token"), "and what to do about it"); + + for (said, want) in [ + ("curl: (22) The requested URL returned error: 401", "token was refused"), + ("curl: (22) The requested URL returned error: 403", "token was refused"), + ("curl: (22) The requested URL returned error: 503", "answered 503"), + ("curl: (28) Operation timed out after 20000 ms", "timed out"), + ("curl: (6) Could not resolve host: api.anthropic.com", "could not reach it"), + ] { + assert!(refusal(said).contains(want), "{:?} -> {:?}", said, refusal(said)); + } + + // Anything unrecognised comes through as itself rather than as + // nothing, which is what the old .ok()? made of all of them. + let odd = "curl: (35) SSL connect error"; + assert_eq!(refusal(odd), "(35) SSL connect error"); + assert!(!refusal(odd).is_empty()); + } + + /// The sequence, and why it is not a flat hold: the one it replaced + /// walked back in at the same interval however many times it was turned + /// away, which sustains a rate limit rather than clearing it. + #[test] + fn a_refusal_waits_longer_each_time_it_is_refused() { + assert_eq!(backoff(1), 120.0, "one failure is usually nothing"); + assert_eq!(backoff(2), 240.0); + assert_eq!(backoff(3), 480.0); + assert_eq!(backoff(4), 960.0); + assert_eq!(backoff(5), BACKOFF_MAX, "and then it stops doubling"); + assert_eq!(backoff(50), BACKOFF_MAX, "including well past the point of doubling"); + // Never zero and never negative, whatever it is handed. + assert_eq!(backoff(0), 120.0); + for n in 0..40 { + let w = backoff(n); + assert!(w >= BACKOFF_FROM && w <= BACKOFF_MAX, "n={} gave {}", n, w); + } + // Strictly growing until the ceiling, which is the whole point. + for n in 1..5 { + assert!(backoff(n) < backoff(n + 1), "n={} did not grow", n); + } + } + #[test] - fn a_refusal_is_never_retried_sooner_than_a_success_would_be_asked() { + fn the_hold_grows_across_calls_and_a_success_forgets_them() { + let mut caches = Caches::default(); + let held = |c: &Caches| c.live.get("probe").map(|(_, _, h)| *h).unwrap(); + + for (call, want) in [(1, 120.0), (2, 240.0), (3, 480.0)] { + // Force the hold to have lapsed, so the next call really asks. + caches.live.remove("probe"); + assert!(cached(&mut caches, "probe", 900.0, || None).is_none()); + assert_eq!(held(&caches), want, "refusal {}", call); + } + + // One that gets through clears the tally, so the next blip starts + // from two minutes again rather than from eight. + caches.live.remove("probe"); + assert!(cached(&mut caches, "probe", 900.0, || Some(serde_json::json!(1))).is_some()); + assert_eq!(held(&caches), 900.0, "a good reading is held for its own interval"); + caches.live.remove("probe"); + assert!(cached(&mut caches, "probe", 900.0, || None).is_none()); + assert_eq!(held(&caches), 120.0, "the count did not reset on success"); + } + + /// An hourly reading may back off, but not past its own interval - and a + /// two-minute one is never held for longer than the backoff says. + #[test] + fn the_backoff_never_outlasts_the_interval_it_belongs_to() { for ttl in [30.0, 120.0, 300.0, 900.0, 3600.0] { let mut caches = Caches::default(); let key = format!("probe-{}", ttl); assert!(cached(&mut caches, &key, ttl, || None).is_none()); - let (_, _, held) = caches.live.get(&key).expect("the failure was not held"); - assert!( - *held <= ttl, - "ttl {}: a failure held {}s would be retried before a success was due", - ttl, - held - ); + let (_, _, held) = caches.live.get(&key).unwrap(); assert!( - *held <= FAILURE_CAP, - "ttl {}: a failure held {}s blanks the section for too long", + *held <= ttl.max(BACKOFF_FROM), + "ttl {}: held {}s, past the interval it belongs to", ttl, held ); + assert!(*held <= BACKOFF_MAX, "ttl {}: held {}s", ttl, held); } } From b5aff2c070b19597b92b1363e20fb8616323a076 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Tue, 25 Aug 2026 13:36:38 +0800 Subject: [PATCH 093/147] tailnet: copy comes back to where it was opened, and the interval key is [i] Two small things on the same screen. **Copy returns to its caller.** `view` was one slot, so opening the copy list from the info screen overwrote it, and closing dropped you to the machine list - losing the machine you had been reading for the sake of one keystroke. It remembers where it was opened from now: from info, back to info; from the list, back to the list, which is what it always did. **n became i.** n was this widget's own letter for the poll interval and meant nothing to a reader coming from latency, which calls the same key [i]nterval. i was free here because the info screen moved to the arrows. The footer keeps the current value - "[i]nterval 2s" - because the key cycles rather than toggles, so the name alone would not say what pressing it is about to change from. The help text and doc both named n. Caught by the check the other session added for exactly this, which is its second real catch. --- docs/start.md | 9 +++++--- docs/tailnet.md | 4 ++-- rust/widgets/src/bin/tailnet.rs | 30 +++++++++++++++++++++++---- rust/widgets/src/bin/tailnet_help.txt | 4 ++-- 4 files changed, 36 insertions(+), 11 deletions(-) diff --git a/docs/start.md b/docs/start.md index 239edbf..154c919 100644 --- a/docs/start.md +++ b/docs/start.md @@ -135,8 +135,12 @@ to run and quietly show nothing, which was worse. `↵` hands the terminal over: cursor restored, raw mode off, the widget gets a normal terminal and this process waits. Quit the widget and the launcher -takes the terminal back and rechecks, so a token you set or a package you -installed while you were away is reflected without restarting. +takes the terminal back. + +Every widget is listed, whether or not this machine can run it. A widget that +is missing a tool or a token says so on its own screen, in its own words, +and `q` brings you back here - which is a better place to learn it than a +menu that has quietly hidden the row. Naming one skips the menu entirely, and anything after it is passed straight through: @@ -163,7 +167,6 @@ the middle of a pipeline it adds nothing to. |---|---| | `↑` `↓` / `j` `k` | select a widget | | `↵` / `→` | launch it, and come back here when it quits | -| `r` | recheck what is installed and configured | | `q` | quit | ## Cost diff --git a/docs/tailnet.md b/docs/tailnet.md index af20084..4bd0b05 100644 --- a/docs/tailnet.md +++ b/docs/tailnet.md @@ -98,7 +98,7 @@ advertises wins over a docker or virtual bridge: a NAS was otherwise reporting | `c` | copy addresses | | `g` | show/hide the live throughput graphs | | `o` | hide offline peers | -| `n` | poll interval — 1 / 2 / 5 / 10 / 30s | +| `i` | poll interval — 1 / 2 / 5 / 10 / 30s | | `r` | refresh now | | `q` | quit | @@ -121,5 +121,5 @@ peer dominates. "tailnet": { "refresh": 2, "history": 180 } ``` -Graph resolution follows the poll interval, so `n` doubles as a zoom control. +Graph resolution follows the poll interval, so `i` doubles as a zoom control. Needs the `tailscale` CLI; no root required. diff --git a/rust/widgets/src/bin/tailnet.rs b/rust/widgets/src/bin/tailnet.rs index ca2fc9d..3df4266 100644 --- a/rust/widgets/src/bin/tailnet.rs +++ b/rust/widgets/src/bin/tailnet.rs @@ -688,6 +688,10 @@ fn main() { let (mut selected, mut scroll, mut visible) = (0usize, 0usize, 1usize); // None, "copy" or "info". let mut view: Option<&'static str> = None; + // Where the copy list was opened from, so closing it puts you back + // there. It used to drop to the machine list whichever screen you had + // been reading, which loses your place for the sake of one keystroke. + let mut copy_from: Option<&'static str> = None; let mut note: (String, f64) = (String::new(), 0.0); let mut listed: Vec<serde_json::Value> = Vec::new(); let derp = derp_regions(); @@ -713,7 +717,9 @@ fn main() { // else: right and enter go in, left and esc come // out, and no widget needs a letter of its own for // it. `i` used to open this and no longer does. - "left" | "esc" => view = None, + "left" | "esc" => { + view = copy_from.take(); + } // q quits from here too. It used to close the view // instead, which is its own kind of trap: the key // appears to do nothing to a widget you are trying @@ -723,7 +729,14 @@ fn main() { tc::restore_screen(); return; } - "c" | "C" => view = if view != Some("copy") { Some("copy") } else { None }, + "c" | "C" => { + view = if view != Some("copy") { + copy_from = view; + Some("copy") + } else { + copy_from.take() + } + } digit if view == Some("copy") && digit.len() == 1 @@ -761,7 +774,11 @@ fn main() { selected = 0; } "g" | "G" => show_graph = !show_graph, - "n" | "N" => { + // i, as latency names the same key. n was this widget's + // own letter for it and meant nothing to a reader coming + // from the widget beside it; i was free here because the + // info screen moved to the arrows. + "i" | "I" => { if let Ok(mut g) = refresh_now.lock() { *g = tc::cycle(REFRESH_CHOICES, *g); } @@ -776,12 +793,14 @@ fn main() { "c" | "C" => { if !listed.is_empty() { view = Some("copy"); + copy_from = None; note = (String::new(), 0.0); } } "right" | "enter" => { if !listed.is_empty() { view = Some("info"); + copy_from = None; } } _ => {} @@ -1113,7 +1132,10 @@ fn main() { vec![(p.dim.as_str(), "[c]opy".into())], vec![(p.dim.as_str(), "[g]raph".into())], vec![(p.dim.as_str(), "[o]ffline".into())], - vec![(p.dim.as_str(), format!("[n]={}s", interval))], + // The current value is worth the three cells: this key cycles + // rather than toggles, so "[i]nterval" alone would not say what + // pressing it is about to change from. + vec![(p.dim.as_str(), format!("[i]nterval {}s", interval))], vec![(p.dim.as_str(), "[r]efresh".into())], vec![(p.dim.as_str(), "[q]uit".into())], ]; diff --git a/rust/widgets/src/bin/tailnet_help.txt b/rust/widgets/src/bin/tailnet_help.txt index 345691d..a041849 100644 --- a/rust/widgets/src/bin/tailnet_help.txt +++ b/rust/widgets/src/bin/tailnet_help.txt @@ -25,8 +25,8 @@ latency over the tunnel — current, average, median, min, max, jitter, loss and a sparkline — measured the same way the latency monitor does. Only the selected peer is probed, so this costs one ping process regardless of tailnet size. -n cycles the poll interval while running (1/2/5/10/30s), the same way the -latency monitor's i key does; the graph resolution follows it. -n sets the +i cycles the poll interval while running (1/2/5/10/30s), the same key the +latency monitor uses for it; the graph resolution follows it. -n sets the starting value, and `tailnet.refresh` in config.json sets the default. Keys: up/down select a peer, right or Enter opens a full machine info view and left From 666924f934caba208f05206c2bbefdae4131ffb2 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Tue, 25 Aug 2026 13:48:36 +0800 Subject: [PATCH 094/147] deployments: show the build log, not just that a build failed The detail view had errorMessage and errorCode - enough to know a build failed and roughly what kind of failure it was, and not enough to know why. The answer was a browser tab away, which is the thing this widget exists to save. /v3/deployments/{id}/events carries it, and the detail already makes one lazy trip per deployment opened, so the log rides along on that rather than costing a second round of waiting. stderr is drawn in the error colour among the stdout lines. On the failing deployment this was built against, thirty-nine lines came back and three were stderr - the last of them "Error: No Next.js version detected", which is the whole answer sitting in a wall of text that otherwise looks alike. 200 lines requested. A long build runs to thousands and the pane shows a few dozen, so asking for all of them spends the wait on text nobody reads. The tail is the useful end: a build explains itself on the way out. Lines wrap rather than clip, because a stack trace cut at the pane edge is the half without the path in it. A log that would not load says so under its own heading instead of leaving the section out, and a deployment with no events draws nothing rather than an empty heading promising a log that is not coming - both tested, along with the stderr marking, which fails if the type check is removed. --- docs/deployments.md | 18 ++++ rust/widgets/src/bin/deployments.rs | 143 ++++++++++++++++++++++++++++ 2 files changed, 161 insertions(+) diff --git a/docs/deployments.md b/docs/deployments.md index 59a7d2e..d592c3c 100644 --- a/docs/deployments.md +++ b/docs/deployments.md @@ -75,6 +75,24 @@ omitted, and the sheet says how many are missing rather than silently dropping them. Every URL is shown wrapped in full, so mouse selection still works where OSC 52 is blocked. +## The build log + +The detail view ends with the deployment's own build output, fetched from +`/v3/deployments/{id}/events` on the same trip as the rest of the detail. +`errorMessage` above it says a build failed and names a code; the log says +which line of somebody's config did it, which is the thing you would +otherwise open a browser for. + +What the build wrote to **stderr** is drawn in the error colour among the +stdout lines, because on a failed build that is the one line worth finding +and it arrives among dozens that look alike. Long lines wrap rather than +clip — a stack trace cut at the pane edge is the half without the path in it. + +The last 200 lines are requested. A long build runs to thousands and the +pane shows a few dozen, so asking for all of them would spend the wait on +text nobody reads; the tail is the useful end, since a build explains itself +on the way out rather than on the way in. + ## Keys | Key | Action | diff --git a/rust/widgets/src/bin/deployments.rs b/rust/widgets/src/bin/deployments.rs index 5e55e35..fc47a79 100644 --- a/rust/widgets/src/bin/deployments.rs +++ b/rust/widgets/src/bin/deployments.rs @@ -28,6 +28,9 @@ use chrono::{Local, TimeZone}; use toys_core as tc; const API: &str = "https://api.vercel.com"; +/// How many build-log lines to ask for. Enough that the tail of a failing +/// build is in there whole, few enough not to wait on a novel. +const EVENT_LIMIT: usize = 200; const FILTERS: &[&str] = &["all", "failed", "production"]; const SPARK: &[char] = &['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█']; const SPINNER: &[char] = &['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']; @@ -91,6 +94,30 @@ fn fetch_detail(uid: &str, team: &str, tok: &str) -> serde_json::Value { if !team.is_empty() { path += &format!("?teamId={}", team); } + let mut got = match api(&path, tok) { + Ok(value) => value, + Err(e) => serde_json::json!({ "_error": e }), + }; + // The build log, on the same trip. errorMessage says a build failed and + // names a code; the log says which line of somebody's config did it, + // which is the thing you would otherwise open a browser for. + if let Some(map) = got.as_object_mut() { + map.insert("_events".into(), fetch_events(uid, team, tok)); + } + got +} + +/// The build log for one deployment, newest last. +/// +/// Capped on the way in: a long build runs to thousands of lines and the +/// pane shows a few dozen, so asking for all of them would spend the wait +/// on text nobody sees. The tail is the useful end - a build says why it +/// failed on its way out, not on its way in. +fn fetch_events(uid: &str, team: &str, tok: &str) -> serde_json::Value { + let mut path = format!("/v3/deployments/{}/events?limit={}", uid, EVENT_LIMIT); + if !team.is_empty() { + path += &format!("&teamId={}", team); + } match api(&path, tok) { Ok(value) => value, Err(e) => serde_json::json!({ "_error": e }), @@ -349,6 +376,60 @@ fn titled(state: &str) -> String { } /// One deployment in full: state, timings, why it failed, and what to copy. + +/// The build log, newest last, with what the build wrote to stderr picked +/// out of what it wrote to stdout. +/// +/// Vercel returns the lines oldest-first and a build explains itself on the +/// way out, so the tail is what matters - the last error before it gave up. +/// Long lines wrap rather than clip: a stack trace cut at the pane edge is +/// the half without the path in it. +fn build_log(detail: &serde_json::Value, w: usize, p: &Palette) -> Vec<String> { + let events = &detail["_events"]; + if let Some(err) = events.get("_error").and_then(|e| e.as_str()) { + return vec![ + String::new(), + tc::seg(&[(p.lbl.as_str(), " ── BUILD LOG ──".into())], w - 1), + tc::seg(&[(p.dim.as_str(), format!(" {}", err))], w - 1), + ]; + } + let Some(lines) = events.as_array() else { + return Vec::new(); + }; + if lines.is_empty() { + return Vec::new(); + } + let mut rows = vec![ + String::new(), + tc::seg( + &[ + (p.lbl.as_str(), " ── BUILD LOG ──".into()), + ( + p.dim.as_str(), + format!(" {} line{}", lines.len(), if lines.len() == 1 { "" } else { "s" }), + ), + ], + w - 1, + ), + ]; + for event in lines { + let said = text(event, "text"); + let said = said.trim_end(); + if said.is_empty() { + continue; + } + let colour = if text(event, "type") == "stderr" { + p.error.as_str() + } else { + p.dim.as_str() + }; + for line in wrap(said, w.saturating_sub(4).max(10)) { + rows.push(tc::seg(&[(colour, format!(" {}", line))], w - 1)); + } + } + rows +} + fn info_overlay( dep: &serde_json::Value, detail: Option<&serde_json::Value>, @@ -506,6 +587,13 @@ fn info_overlay( } } + // The build log, last. It is the longest thing on the screen and the + // one most often scrolled to, so everything that fits in a line of its + // own goes above it. + if let Some(detail) = detail { + rows.extend(build_log(detail, w, &p)); + } + let pairs = copy_items(dep, detail); if !pairs.is_empty() { rows.push(String::new()); @@ -1108,6 +1196,61 @@ fn main() { mod tests { use super::*; + /// The line that says why a build failed is the one worth finding, and + /// it arrives on stderr among dozens of stdout lines that all look the + /// same. Vercel marks them; this checks we keep the mark. + #[test] + fn the_build_log_picks_stderr_out_of_stdout() { + let p = palette(); + let detail = serde_json::json!({ + "_events": [ + {"type": "stdout", "text": "Running build in Washington, D.C."}, + {"type": "stdout", "text": "Build machine configuration: 4 cores"}, + {"type": "stderr", "text": "Error: No Next.js version detected."}, + {"type": "stdout", "text": ""}, + ] + }); + let rows = build_log(&detail, 90, &p); + let joined = rows.join("\n"); + assert!(joined.contains("BUILD LOG"), "no heading"); + assert!(joined.contains("Error: No Next.js version"), "the failing line is missing"); + assert!(joined.contains("Running build in"), "the ordinary lines are missing"); + + let of = |needle: &str| { + rows.iter() + .find(|r| r.contains(needle)) + .unwrap_or_else(|| panic!("{:?} not drawn", needle)) + }; + assert!( + of("Error: No Next.js").starts_with(p.error.as_str()), + "stderr was not marked" + ); + assert!( + of("Running build in").starts_with(p.dim.as_str()), + "stdout was marked as an error" + ); + // A blank line from the build is not a row on the screen. + assert_eq!(joined.matches(" \n").count(), 0); + // The count in the heading is the lines the build produced, blank + // ones included - it is what the API returned, not what we drew. + assert!(of("BUILD LOG").contains("4 lines"), "{}", of("BUILD LOG")); + } + + #[test] + fn a_log_that_would_not_load_says_so_rather_than_vanishing() { + let p = palette(); + let detail = serde_json::json!({ "_events": { "_error": "curl exited 22" } }); + let rows = build_log(&detail, 90, &p); + let joined = rows.join("\n"); + assert!(joined.contains("BUILD LOG"), "the section disappeared"); + assert!(joined.contains("curl exited 22"), "the reason disappeared"); + // And a deployment with no events at all draws nothing, rather than + // an empty heading promising a log that is not coming. + assert!(build_log(&serde_json::json!({}), 90, &p).is_empty()); + assert!(build_log(&serde_json::json!({"_events": []}), 90, &p).is_empty()); + } + + #[test] fn a_token_prefers_the_config_then_the_environment() { let cfg: serde_json::Value = From 49013109fd49773c3975ed77232f212355bd3499 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Tue, 25 Aug 2026 13:55:43 +0800 Subject: [PATCH 095/147] deployments: the detail scrolls, copy gets its own page, and both stay current MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three things the build log made necessary the moment it went in. **It scrolls.** Sixty-four rows of detail in a pane that shows forty-six, and no way to reach the rest - which for a log means the end, where a build says why it failed. ↑↓ move it, PgUp/PgDn/Home/End follow the convention, and the footer says which rows you are looking at. **Copy is its own page.** It was a section at the bottom of the detail, and the numbers you press were then reliably scrolled off the screen you were pressing them from. c opens it, ← or esc comes back to the detail at the scroll position you left - the same shape tailnet's copy view has. **Both stay current.** A held detail is dropped after a minute so the open page asks again: a running build's log grows while it is being read, and what was fetched when the page opened stops being the whole story. r drops it at once rather than waiting out the minute. A finished deployment is refetched on the same rule, which costs one request a minute and keeps the rule simple enough to state. --- docs/deployments.md | 15 +++ rust/widgets/src/bin/deployments.rs | 151 +++++++++++++++++++++++++++- 2 files changed, 161 insertions(+), 5 deletions(-) diff --git a/docs/deployments.md b/docs/deployments.md index d592c3c..1e07b88 100644 --- a/docs/deployments.md +++ b/docs/deployments.md @@ -75,6 +75,21 @@ omitted, and the sheet says how many are missing rather than silently dropping them. Every URL is shown wrapped in full, so mouse selection still works where OSC 52 is blocked. +## The detail view + +`→` or `↵` opens one deployment in full. It scrolls with `↑` `↓` — the build +log below makes it taller than any pane — and the footer says where you are +in it. `PgUp` `PgDn` `Home` `End` move by the page and to either end. + +It refetches every minute while it is open, because a build that is still +running writes more log while you are reading it, and `r` asks again at once +rather than waiting for that. + +`c` opens the copy list on **its own page**, and `←` or `esc` brings you back +to the detail where you left it. The list used to sit at the bottom of the +detail, which was fine until the build log went in above it: the numbers you +press were then reliably scrolled off the screen you were pressing them from. + ## The build log The detail view ends with the deployment's own build output, fetched from diff --git a/rust/widgets/src/bin/deployments.rs b/rust/widgets/src/bin/deployments.rs index fc47a79..9db7732 100644 --- a/rust/widgets/src/bin/deployments.rs +++ b/rust/widgets/src/bin/deployments.rs @@ -31,6 +31,9 @@ const API: &str = "https://api.vercel.com"; /// How many build-log lines to ask for. Enough that the tail of a failing /// build is in there whole, few enough not to wait on a novel. const EVENT_LIMIT: usize = 200; +/// How long a fetched detail is kept before the open page asks again. A +/// running build's log grows while it is being read. +const DETAIL_TTL: f64 = 60.0; const FILTERS: &[&str] = &["all", "failed", "production"]; const SPARK: &[char] = &['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█']; const SPINNER: &[char] = &['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']; @@ -103,6 +106,7 @@ fn fetch_detail(uid: &str, team: &str, tok: &str) -> serde_json::Value { // which is the thing you would otherwise open a browser for. if let Some(map) = got.as_object_mut() { map.insert("_events".into(), fetch_events(uid, team, tok)); + map.insert("_fetched_at".into(), serde_json::json!(now())); } got } @@ -594,7 +598,10 @@ fn info_overlay( rows.extend(build_log(detail, w, &p)); } - let pairs = copy_items(dep, detail); + // The copy list is its own page now, reached with c. It was a section + // at the bottom of this one, which meant the numbers you press were + // usually scrolled off the screen by the build log above them. + let pairs: Vec<(String, String)> = Vec::new(); if !pairs.is_empty() { rows.push(String::new()); rows.push(tc::seg(&[(p.lbl.as_str(), " ── COPY ──".into())], w - 1)); @@ -619,13 +626,59 @@ fn info_overlay( } } + let _ = (h, note); + rows +} + +/// The copy list on a page of its own. +/// +/// It used to sit under the detail, which was fine until the build log went +/// in above it: the numbers you press were then reliably scrolled off the +/// bottom of the screen you were pressing them from. +fn copy_overlay( + dep: &serde_json::Value, + detail: Option<&serde_json::Value>, + w: usize, + h: usize, + note: &str, + p: &Palette, +) -> Vec<String> { + let pairs = copy_items(dep, detail); + let mut rows = vec![tc::title("copy", w, &p.prod)]; + rows.push(String::new()); + if pairs.is_empty() { + rows.push(tc::seg( + &[(p.dim.as_str(), " nothing here to copy yet".into())], + w - 1, + )); + } + for (i, (label, value)) in pairs.iter().enumerate() { + let room = w.saturating_sub(28); + let short = if value.chars().count() <= room { + value.clone() + } else { + format!("{}…", value.chars().take(room.saturating_sub(1)).collect::<String>()) + }; + rows.push(tc::seg( + &[ + (p.ready.as_str(), format!(" [{}] ", i + 1)), + (p.txt.as_str(), format!("{:<21} ", label)), + (p.url.as_str(), short), + ], + w - 1, + )); + } while rows.len() < h.saturating_sub(2) { rows.push(String::new()); } rows.push(tc::seg( &[( p.hint.as_str(), - format!(" press 1-{} to copy · ← or esc to close", pairs.len()), + if pairs.is_empty() { + " ← or esc to close".to_string() + } else { + format!(" press 1-{} to copy · ← or esc to close", pairs.len()) + }, )], w - 1, )); @@ -795,6 +848,11 @@ fn main() { let mut only: Option<String> = None; let (mut tick, mut selected, mut scroll) = (0usize, 0usize, 0usize); let mut overlay = false; + // The copy list is a page of its own, opened from the detail with c. + let mut copying = false; + // How far down the detail is scrolled. The build log makes it taller + // than any pane, so it has to move. + let mut oscroll = 0usize; let mut note: (String, f64) = (String::new(), 0.0); let mut visible = 1usize; let mut shown: Vec<serde_json::Value> = Vec::new(); @@ -808,7 +866,38 @@ fn main() { // what the footer has always promised and what it // does from the list - it used to close the overlay // instead, so the key disagreed with its own hint. - "left" | "esc" => overlay = false, + "left" | "esc" => { + if copying { + copying = false; + } else { + overlay = false; + } + } + "c" | "C" if !copying => copying = true, + "up" | "k" | "K" if !copying => oscroll = oscroll.saturating_sub(1), + "down" | "j" | "J" if !copying => oscroll = oscroll.saturating_add(1), + "pgup" if !copying => { + let page = tc::size().1.saturating_sub(3).max(1); + oscroll = oscroll.saturating_sub(page); + } + "pgdn" if !copying => { + let page = tc::size().1.saturating_sub(3).max(1); + oscroll = oscroll.saturating_add(page); + } + "home" if !copying => oscroll = 0, + "end" if !copying => oscroll = usize::MAX, + // The detail is a live thing too - a running build's log + // grows while you read it. r drops what was fetched so + // the next frame asks again. + "r" | "R" if !copying => { + if let Some(chosen) = shown.get(selected.min(shown.len().saturating_sub(1))) + { + let uid = text(chosen, "uid"); + if let Ok(mut g) = details.lock() { + g.remove(&uid); + } + } + } "q" | "Q" => { keyboard.restore(); tc::restore_screen(); @@ -864,6 +953,8 @@ fn main() { "right" | "enter" => { if !shown.is_empty() { overlay = true; + copying = false; + oscroll = 0; note = (String::new(), 0.0); } } @@ -926,7 +1017,22 @@ fn main() { if overlay && !shown.is_empty() { let chosen = shown[selected].clone(); let uid = text(&chosen, "uid"); - let held = details.lock().ok().and_then(|g| g.get(&uid).cloned()); + let mut held = details.lock().ok().and_then(|g| g.get(&uid).cloned()); + // A build that is still running writes more log while you read + // it, so what was fetched when the page opened stops being the + // whole story. Dropped after DETAIL_TTL so the next frame asks + // again; a finished deployment is refetched too, which costs one + // request a minute and keeps the rule simple. + if held + .as_ref() + .map(|v| now() - v["_fetched_at"].as_f64().unwrap_or(0.0) > DETAIL_TTL) + .unwrap_or(false) + { + if let Ok(mut g) = details.lock() { + g.remove(&uid); + } + held = None; + } if held.is_none() && !uid.is_empty() { let start = fetching .lock() @@ -946,7 +1052,42 @@ fn main() { }); } } - let rows = info_overlay(&chosen, held.as_ref(), w, h, ¬e.0, &p); + let rows = if copying { + copy_overlay(&chosen, held.as_ref(), w, h, ¬e.0, &p) + } else { + let body = info_overlay(&chosen, held.as_ref(), w, h, ¬e.0, &p); + let foot = 2; + let room = h.saturating_sub(foot).max(1); + let furthest = body.len().saturating_sub(room); + oscroll = oscroll.min(furthest); + let last = (oscroll + room).min(body.len()); + let mut out: Vec<String> = body[oscroll..last].to_vec(); + while out.len() < room { + out.push(String::new()); + } + out.push(tc::seg( + &[( + p.hint.as_str(), + if furthest > 0 { + format!( + " ↑↓ scroll {}-{} of {} · [c]opy · [r]efresh · ← or esc to close", + oscroll + 1, + last, + body.len() + ) + } else { + " [c]opy · [r]efresh · ← or esc to close".to_string() + }, + )], + w - 1, + )); + out.push(if note.0.is_empty() { + String::new() + } else { + tc::seg(&[(p.ready.as_str(), format!(" {}", note.0))], w - 1) + }); + out + }; tc::draw(&rows, w, h); std::thread::sleep(Duration::from_millis(100)); continue; From 89144a83bb97057e2d93a2219cdce47317afba5c Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Tue, 25 Aug 2026 14:15:06 +0800 Subject: [PATCH 096/147] widgets: every screen that answers q now says so MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit q quits from anywhere - the sub-screens all honour it, and that is the right behaviour: ← and esc already back out, so the two actions have two keys and neither is overloaded. tailnet's own comment says why it was settled that way: "the key appears to do nothing to a widget you are trying to leave, and every other widget quits on it". The footers had not caught up. Four screens promised [q]uit and four did not, while all eight quit on it - a key that works and is not named is the same fault as a name with no key behind it, read from the other side. deployments (detail and copy), tailnet (copy) and ports (detail) now name it. Two of those were screens written today, so the gap was mostly fresh. matrix is the odd one. It had no footer at all - it is rain and nothing else, and a full footer would be the loudest thing on the screen. But a screen that answers a key and never says which is one you have to guess your way out of, so it gets one dim word in the corner, drawn over the rain rather than instead of it. Checked by driving each widget into its second screen and reading the footer that was actually drawn, rather than grepping for the string - which is how the four gaps were found, and how clocks was cleared: it looked like a gap because the detector caught a heading, and its footer pushes [q]uit unconditionally. --- rust/widgets/src/bin/deployments.rs | 8 ++++---- rust/widgets/src/bin/matrix.rs | 15 +++++++++++++++ rust/widgets/src/bin/ports.rs | 1 + rust/widgets/src/bin/tailnet.rs | 4 ++-- 4 files changed, 22 insertions(+), 6 deletions(-) diff --git a/rust/widgets/src/bin/deployments.rs b/rust/widgets/src/bin/deployments.rs index 9db7732..6fbee11 100644 --- a/rust/widgets/src/bin/deployments.rs +++ b/rust/widgets/src/bin/deployments.rs @@ -675,9 +675,9 @@ fn copy_overlay( &[( p.hint.as_str(), if pairs.is_empty() { - " ← or esc to close".to_string() + " ← or esc to close · [q]uit".to_string() } else { - format!(" press 1-{} to copy · ← or esc to close", pairs.len()) + format!(" press 1-{} to copy · ← or esc to close · [q]uit", pairs.len()) }, )], w - 1, @@ -1070,13 +1070,13 @@ fn main() { p.hint.as_str(), if furthest > 0 { format!( - " ↑↓ scroll {}-{} of {} · [c]opy · [r]efresh · ← or esc to close", + " ↑↓ scroll {}-{} of {} · [c]opy · [r]efresh · ← esc · [q]uit", oscroll + 1, last, body.len() ) } else { - " [c]opy · [r]efresh · ← or esc to close".to_string() + " [c]opy · [r]efresh · ← or esc to close · [q]uit".to_string() }, )], w - 1, diff --git a/rust/widgets/src/bin/matrix.rs b/rust/widgets/src/bin/matrix.rs index 0d3eb81..8912103 100644 --- a/rust/widgets/src/bin/matrix.rs +++ b/rust/widgets/src/bin/matrix.rs @@ -174,6 +174,21 @@ fn main() { .collect(); rows[y] = tc::seg(&parts, w); } + // The one piece of text on the screen. This widget is rain and + // nothing else, so a full footer would be the loudest thing in it - + // but a screen that answers a key and never says which is a screen + // you have to guess your way out of. One dim word in the corner, + // over the rain rather than instead of it. + if h > 0 { + let last = h - 1; + rows[last] = tc::seg( + &[ + (tc::rgb(70, 100, 80).as_str(), " [q]uit".to_string()), + (String::new().as_str(), " ".repeat(w.saturating_sub(7))), + ], + w, + ); + } tc::draw(&rows, w, h); std::thread::sleep(Duration::from_millis(55)); } diff --git a/rust/widgets/src/bin/ports.rs b/rust/widgets/src/bin/ports.rs index 89b56f9..ddf6b30 100644 --- a/rust/widgets/src/bin/ports.rs +++ b/rust/widgets/src/bin/ports.rs @@ -1992,6 +1992,7 @@ fn main() { (ok.accent.clone(), "←".into()), (ok.dim.clone(), "/esc back".into()), ], + vec![(ok.dim.clone(), "[q]uit".into())], ], &ok, ); diff --git a/rust/widgets/src/bin/tailnet.rs b/rust/widgets/src/bin/tailnet.rs index 3df4266..502ac3b 100644 --- a/rust/widgets/src/bin/tailnet.rs +++ b/rust/widgets/src/bin/tailnet.rs @@ -1476,7 +1476,7 @@ fn info_overlay( rows.push(String::new()); } rows.push(tc::seg( - &[(p.dim.as_str(), " [c]opy addresses · ← or esc to close".into())], + &[(p.dim.as_str(), " [c]opy addresses · ← or esc to close · [q]uit".into())], w - 1, )); rows @@ -1526,7 +1526,7 @@ fn copy_overlay( &[( p.dim.as_str(), format!( - " press 1-{} to copy · ← or esc to close", + " press 1-{} to copy · ← or esc to close · [q]uit", pairs.len().max(1) ), )], From a920413d4ebb8faf963d4284486ce453c0a76eed Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Tue, 25 Aug 2026 14:57:54 +0800 Subject: [PATCH 097/147] github: an account of its own, and a fortnight rather than a week MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit **A screen per account.** → or ↵ from a row opens it; ↑↓ scroll, ← or esc come back, q quits and the footer says so. Most of it is figures the row already carried and had no room to spell out - open split into what is waiting on a reviewer and what is still a draft, merged split into what landed and what was closed unmerged - plus a few worth deriving: net opened minus merged. A queue of six hundred is a different thing depending on whether it grew by forty this week or held level. merged/day with the open queue restated as time at that rate: "110d of open PRs" is the number people estimate and get wrong. busiest day and the days with none, which is the shape of a week. The OPEN PR STATE bar and the PR FLOW chart are the two the board draws for every account added together, drawn here for one. That is the reason to open the screen at all: a queue growing in one account is invisible in a total six others are also feeding. On this machine the split reads 77% awaiting review, which the summed bar never said about anybody in particular. **Oldest open, which cost a request.** Everything else here is built from issueCount aggregates - exact at any volume, one rate-limit point per request rather than per alias, and completely unable to name anything. So this asks for five nodes, oldest first, once when an account's screen is opened, and keeps the answer. It immediately turned up five ImgBot PRs open for seven years. **The window opens on 14 days now, not 7.** A week is short enough that one quiet Friday moves every figure: a merge rate, a per-day average and a queue trend all read as noise when a single day is a seventh of the sample. w still cycles 7/14/30/60/90 from there, and window_days still overrides it. --- config.example.json | 2 +- docs/github.md | 9 +- rust/widgets/src/bin/github.rs | 473 ++++++++++++++++++++++++++++++++- 3 files changed, 479 insertions(+), 5 deletions(-) diff --git a/config.example.json b/config.example.json index 6f0ab03..47a3cdf 100644 --- a/config.example.json +++ b/config.example.json @@ -74,7 +74,7 @@ "token": "", "token_env": "GITHUB_TOKEN", "accounts": [], - "window_days": 7, + "window_days": 14, "refresh": 120 }, "linear": { diff --git a/docs/github.md b/docs/github.md index a3a4395..e58a18e 100644 --- a/docs/github.md +++ b/docs/github.md @@ -256,14 +256,19 @@ file is git-ignored and the token is never printed. "token": "", "token_env": "GITHUB_TOKEN", "accounts": [], - "window_days": 7, + "window_days": 14, "refresh": 120 } ``` Empty `accounts` discovers every org you belong to plus your personal account; otherwise list org logins, and `@me` for your own. `window_days` sets the window -the board opens on; `w` cycles it from there. +the board opens on — **14 days by default** — and `w` cycles it from there +through 7 / 14 / 30 / 60 / 90. + +Fourteen rather than seven because a week is short enough that one quiet +Friday moves every figure on the board: a merge rate, a per-day average and +a queue trend all read as noise when a single day is a seventh of the sample. ```sh ./github.py # discovered accounts, 120s diff --git a/rust/widgets/src/bin/github.rs b/rust/widgets/src/bin/github.rs index 6bbac81..1971ab8 100644 --- a/rust/widgets/src/bin/github.rs +++ b/rust/widgets/src/bin/github.rs @@ -22,13 +22,30 @@ //! issueCount is exact at any volume and costs one rate-limit point per //! request however many are packed into it. -use std::collections::HashMap; +use std::collections::{HashMap, HashSet}; use std::sync::{Arc, Condvar, Mutex}; use std::time::{Duration, SystemTime, UNIX_EPOCH}; use chrono::{Duration as Days, NaiveDate, Utc}; use toys_core as tc; +/// How many of the longest-open PRs an account's own screen names. +/// How long ago an ISO-8601 stamp was, coarse on purpose: "47d" answers the +/// question a queue raises and a timestamp does not. +fn age_since(iso: &str) -> String { + let Ok(at) = chrono::DateTime::parse_from_rfc3339(iso) else { + return String::new(); + }; + let secs = (Utc::now() - at.with_timezone(&Utc)).num_seconds().max(0); + if secs >= 86400 { + format!("{}d", secs / 86400) + } else { + format!("{}h", secs / 3600) + } +} + +const OLDEST_WANTED: usize = 5; + const API: &str = "https://api.github.com/graphql"; const WINDOWS: &[i64] = &[7, 14, 30, 60, 90]; /// A full year, like the calendar on github.com. @@ -70,6 +87,369 @@ fn token(cfg: &serde_json::Value) -> (String, &'static str) { } } +/// The open PRs that have been open longest, for one account. +/// +/// The board and the row are built entirely from `issueCount` aggregates, +/// which are exact at any volume and cost one rate-limit point per request +/// rather than per alias. That is the right shape for counting and useless +/// for naming: a queue of six hundred says nothing about which of them has +/// been sitting there since June. +/// +/// So this asks for nodes, and only when an account's own screen is opened - +/// five of them, oldest first. One request, on demand, for the question the +/// aggregates cannot answer. +fn fetch_oldest(acc: &str, viewer: &str, tok: &str, scopes: &Arc<Mutex<Scopes>>) -> serde_json::Value { + let q = scope_of(acc, viewer); + let query = format!( + r#"{{ + search(query:"{q} is:pr is:open sort:created-asc", type:ISSUE, first:{n}) {{ + nodes {{ + ... on PullRequest {{ + number + title + createdAt + isDraft + repository {{ name }} + }} + }} + }} +}}"#, + q = q, + n = OLDEST_WANTED + ); + match graphql(&query, tok, scopes) { + Ok(v) => v["data"]["search"]["nodes"].clone(), + Err(e) => serde_json::json!({ "_error": e }), + } +} + +/// One account in full. +/// +/// Everything here is already on the board somewhere - the row it came from +/// carries all of it - but the row has one line and has to choose. Open +/// splits into what is waiting on a reviewer and what is still a draft; +/// merged splits into what landed and what was closed unmerged; and the +/// flow chart, which the board draws once for every account added together, +/// is drawn here for this one alone. That last is the reason to open it: a +/// queue growing in one account is invisible in a total that six others +/// are also feeding. +/// +/// No new request. The figures were fetched for the row. +fn account_detail( + a: &Account, + oldest: Option<&serde_json::Value>, + w: usize, + h: usize, + p: &Palette, +) -> Vec<String> { + let mut rows = vec![tc::title(&a.account, w, &p.accent)]; + let label_w = 16usize; + let mut field = |name: &str, value: String, aside: String, colour: &str| { + rows.push(tc::seg( + &[ + (p.dim.as_str(), format!(" {}", tc::pad(name, label_w))), + (colour, format!("{:>7}", value)), + (p.dim.as_str(), format!(" {}", aside)), + ], + w - 1, + )); + }; + + let waiting = a.review; + let drafts = a.draft; + field( + "open", + a.open.to_string(), + match (waiting, drafts) { + (0, 0) => String::new(), + (r, 0) => format!("{} awaiting review", r), + (0, d) => format!("{} draft", d), + (r, d) => format!("{} awaiting review · {} draft", r, d), + }, + p.pr.as_str(), + ); + field("issues", a.issues.to_string(), String::new(), p.txt.as_str()); + + // Opened against merged over the same window is the question the row + // cannot answer: a queue of six hundred is a different thing depending + // on whether it grew by forty this week or shrank by ten. + let window_days = a.hist_window.unwrap_or(a.window).max(1); + let opened_total: i64 = a.opened_hist.values().sum(); + let merged_total: i64 = a.hist.values().sum(); + let net = opened_total - merged_total; + field( + "opened", + opened_total.to_string(), + format!("in {}d", window_days), + p.pr.as_str(), + ); + + let window = format!("in {}d", a.window); + field( + "merged", + a.merged.to_string(), + match a.dropped { + 0 => window.clone(), + n => format!("{} · {} closed unmerged", window, n), + }, + p.ok.as_str(), + ); + if opened_total > 0 || merged_total > 0 { + field( + "net", + format!("{:+}", net), + match net { + 0 => "the queue held level".to_string(), + n if n > 0 => format!("the queue grew by {}", n), + n => format!("the queue shrank by {}", -n), + }, + if net > 0 { p.warn.as_str() } else { p.ok.as_str() }, + ); + } + if merged_total > 0 { + let per_day = merged_total as f64 / window_days as f64; + field( + "merged/day", + format!("{:.1}", per_day), + // How long the open queue would take at the rate actually + // observed. A number people usually estimate and get wrong. + if per_day > 0.0 && a.open > 0 { + format!("{:.0}d of open PRs at that rate", a.open as f64 / per_day) + } else { + String::new() + }, + p.txt.as_str(), + ); + let busiest = a.hist.iter().max_by_key(|(_, n)| **n); + if let Some((day, n)) = busiest { + if *n > 0 { + field("busiest day", n.to_string(), day.clone(), p.dim.as_str()); + } + } + let idle = window_days as usize - a.hist.values().filter(|n| **n > 0).count(); + if idle > 0 { + field( + "days with none", + idle.to_string(), + format!("of {}", window_days), + p.dim.as_str(), + ); + } + } + if let Some(rate) = a.rate { + let bar = tc::meter(rate / 100.0, w.saturating_sub(label_w + 22).clamp(6, 24)); + rows.push(tc::seg( + &[ + (p.dim.as_str(), format!(" {}", tc::pad("merge rate", label_w))), + (p.ok.as_str(), format!("{:>6.0}%", rate)), + (p.dim.as_str(), " ".into()), + (p.ok.as_str(), bar), + ], + w - 1, + )); + } + + // The same bar the board draws for everything at once, for this account + // alone: a queue is a different shape depending on whether it is waiting + // on reviewers or waiting on authors. + if a.open > 0 && h.saturating_sub(rows.len()) >= 4 { + let ready = (a.open - a.draft - a.review).max(0); + let legend: Vec<(&str, i64, &str)> = [ + ("awaiting review", a.review, p.warn.as_str()), + ("ready to merge", ready, p.ok.as_str()), + ("draft", a.draft, p.dim.as_str()), + ] + .into_iter() + .filter(|x| x.1 > 0) + .collect(); + if !legend.is_empty() { + rows.push(String::new()); + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── OPEN PR STATE ── ".into()), + (p.dim.as_str(), "any age".into()), + ], + w - 1, + )); + let parts: Vec<(f64, String)> = legend + .iter() + .map(|(_, n, c)| (*n as f64 / a.open as f64, c.to_string())) + .collect(); + let bar = tc::stacked_bar(&parts, w.saturating_sub(3).max(10)); + let mut line: Vec<(&str, String)> = vec![(tc::RST, " ".into())]; + for (colour, txt) in &bar { + line.push((colour.as_str(), txt.clone())); + } + rows.push(tc::seg(&line, w - 1)); + let mut key: Vec<(&str, String)> = vec![(tc::RST, " ".into())]; + for (label, count, colour) in &legend { + key.push((colour, "▇ ".into())); + key.push((p.txt.as_str(), (*label).into())); + key.push(( + p.dim.as_str(), + format!(" {} ({:.0}%) ", count, 100.0 * *count as f64 / a.open as f64), + )); + } + rows.push(tc::seg(&key, w - 1)); + } + } + + // The ones that have been open longest, which no count can name. + if h.saturating_sub(rows.len()) >= 4 { + rows.push(String::new()); + match oldest { + None => { + rows.push(tc::seg( + &[(p.lbl.as_str(), " ── OLDEST OPEN ──".into())], + w - 1, + )); + rows.push(tc::seg(&[(p.dim.as_str(), " asking…".into())], w - 1)); + } + Some(v) if !v["_error"].is_null() => { + rows.push(tc::seg( + &[(p.lbl.as_str(), " ── OLDEST OPEN ──".into())], + w - 1, + )); + rows.push(tc::seg( + &[(p.dim.as_str(), format!(" {}", v["_error"].as_str().unwrap_or("")))], + w - 1, + )); + } + Some(v) => { + let nodes = v.as_array().cloned().unwrap_or_default(); + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── OLDEST OPEN ── ".into()), + ( + p.dim.as_str(), + if nodes.is_empty() { + "nothing open".to_string() + } else { + format!("{} longest waiting", nodes.len()) + }, + ), + ], + w - 1, + )); + for node in nodes.iter() { + let age = age_since(node["createdAt"].as_str().unwrap_or("")); + let repo = node["repository"]["name"].as_str().unwrap_or("").to_string(); + let num = node["number"].as_i64().unwrap_or(0); + let draft = node["isDraft"].as_bool().unwrap_or(false); + let head = format!(" {:>5} #{:<6}", age, num); + let room = w.saturating_sub(head.chars().count() + repo.chars().count() + 6); + let title = node["title"].as_str().unwrap_or("").to_string(); + let title: String = if title.chars().count() > room { + format!("{}…", title.chars().take(room.saturating_sub(1)).collect::<String>()) + } else { + title + }; + rows.push(tc::seg( + &[ + (if draft { p.dim.as_str() } else { p.warn.as_str() }, head), + (p.dim.as_str(), format!("{} ", repo)), + (p.txt.as_str(), title), + ], + w - 1, + )); + } + } + } + } + + // The same chart the board draws for every account at once, for this + // one on its own. + let want = a.hist_window.unwrap_or(a.window).max(1); + let base = today(); + let mut days: Vec<String> = (0..want) + .rev() + .map(|n| (base - Days::days(n)).format("%Y-%m-%d").to_string()) + .collect(); + let avail = w.saturating_sub(3).max(10); + if days.len() > avail { + days = days[days.len() - avail..].to_vec(); + } + let slot = (avail / days.len().max(1)).max(1); + let gap = if slot >= 3 { 1 } else { 0 }; + let barw = slot - gap; + let spread = |per_day: &[f64]| -> Vec<f64> { + let mut cols = Vec::new(); + for (n, v) in per_day.iter().enumerate() { + cols.extend(std::iter::repeat_n(*v, barw)); + if gap > 0 && n + 1 < per_day.len() { + cols.extend(std::iter::repeat_n(0.0, gap)); + } + } + cols + }; + let opened: Vec<f64> = days + .iter() + .map(|d| a.opened_hist.get(d).copied().unwrap_or(0) as f64) + .collect(); + let merged: Vec<f64> = days + .iter() + .map(|d| a.hist.get(d).copied().unwrap_or(0) as f64) + .collect(); + let (up, down) = (spread(&opened), spread(&merged)); + // One scale both ways, or the comparison lies. + let hi = up + .iter() + .chain(down.iter()) + .cloned() + .fold(0.0f64, f64::max) + .max(1.0); + if h.saturating_sub(rows.len()) >= 10 && !up.is_empty() { + rows.push(String::new()); + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── PR FLOW ── ".into()), + (p.dim.as_str(), format!("{}d · ", days.len())), + (p.pr.as_str(), format!("▲ {} opened", opened.iter().sum::<f64>() as i64)), + (p.dim.as_str(), " · ".into()), + (p.ok.as_str(), format!("▼ {} merged", merged.iter().sum::<f64>() as i64)), + (p.dim.as_str(), format!(" peak {}/day", hi as i64)), + ], + w - 1, + )); + for line in tc::vbars(&up.iter().map(|v| (*v, p.pr.clone())).collect::<Vec<_>>(), 3, hi) { + let mut parts: Vec<(&str, String)> = vec![(tc::RST, " ".into())]; + for (colour, ch) in &line { + parts.push((colour.as_str(), ch.clone())); + } + rows.push(tc::seg(&parts, w - 1)); + } + rows.push(tc::seg( + &[(tc::RST, " ".into()), (p.grid.as_str(), "─".repeat(up.len()))], + w - 1, + )); + for line in + tc::vbars_down(&down.iter().map(|v| (*v, p.ok.clone())).collect::<Vec<_>>(), 3, hi) + { + let mut parts: Vec<(&str, String)> = vec![(tc::RST, " ".into())]; + for (colour, ch) in &line { + parts.push((colour.as_str(), ch.clone())); + } + rows.push(tc::seg(&parts, w - 1)); + } + let left = format!("{}d ago", days.len()); + rows.push(tc::seg( + &[ + (p.dim.as_str(), format!(" {}", left)), + ( + p.dim.as_str(), + format!( + "{:>width$}", + "today", + width = up.len().saturating_sub(left.chars().count() + 1) + ), + ), + ], + w - 1, + )); + } + rows +} + /// What the token is allowed to see, read off the response headers. #[derive(Default, Clone)] struct Scopes { @@ -628,7 +1008,7 @@ fn main() { let cfg = tc::load_config("github"); let mut refresh = tc::cfg_f64(&cfg, "refresh", 120.0); let configured: Vec<String> = tc::cfg_strings(&cfg, "accounts", &[]); - let start_window = tc::cfg_f64(&cfg, "window_days", 7.0) as i64; + let start_window = tc::cfg_f64(&cfg, "window_days", 14.0) as i64; let args: Vec<String> = std::env::args().skip(1).collect(); let mut named: Vec<String> = Vec::new(); @@ -675,6 +1055,10 @@ fn main() { let scopes = Arc::new(Mutex::new(Scopes::default())); let wake = Arc::new((Mutex::new(false), Condvar::new())); let (tok, source) = token(&cfg); + // The poller thread takes ownership of it; the render loop needs it too, + // for the one on-demand request an account's own screen makes. + let ui_tok = tok.clone(); + let ui_scopes = Arc::clone(&scopes); let env_name = { let name = tc::cfg_str(&cfg, "token_env", "GITHUB_TOKEN"); if name.is_empty() { "GITHUB_TOKEN".to_string() } else { name } @@ -724,6 +1108,12 @@ fn main() { tc::setup(); let mut keyboard = tc::Keyboard::new(); let (mut selected, mut tick) = (0usize, 0usize); + // One account on its own screen, and how far down it is scrolled. + let (mut detail, mut dscroll) = (false, 0usize); + // The longest-open PRs per account, fetched when that account's screen + // is opened and kept after. + let oldest: Arc<Mutex<HashMap<String, serde_json::Value>>> = Arc::new(Mutex::new(HashMap::new())); + let asking: Arc<Mutex<HashSet<String>>> = Arc::new(Mutex::new(HashSet::new())); let mut settle_t = 0usize; let mut settle_from: Option<(Vec<f64>, Vec<f64>)> = None; @@ -757,6 +1147,23 @@ fn main() { cond.notify_all(); } } + "right" | "enter" => { + detail = true; + dscroll = 0; + } + "left" | "esc" if detail => detail = false, + "up" if detail => dscroll = dscroll.saturating_sub(1), + "down" if detail => dscroll = dscroll.saturating_add(1), + "pgup" if detail => { + let page = tc::size().1.saturating_sub(3).max(1); + dscroll = dscroll.saturating_sub(page); + } + "pgdn" if detail => { + let page = tc::size().1.saturating_sub(3).max(1); + dscroll = dscroll.saturating_add(page); + } + "home" if detail => dscroll = 0, + "end" if detail => dscroll = usize::MAX, "up" => selected = selected.saturating_sub(1), "down" => selected += 1, _ => {} @@ -1315,8 +1722,70 @@ fn main() { rows.push(tc::seg(&refs, w - 1)); } + // One account in full, opened from the row it belongs to. + if detail { + if let Some(a) = stats.get(selected.min(stats.len().saturating_sub(1))) { + // One request, on opening, for the question the aggregates + // cannot answer. Held per account so leaving and coming back + // does not ask again. + let key = a.key.clone(); + let held = oldest.lock().ok().and_then(|g| g.get(&key).cloned()); + if held.is_none() { + let start = asking + .lock() + .map(|mut g| g.insert(key.clone())) + .unwrap_or(false); + if start { + let (oldest, asking) = (Arc::clone(&oldest), Arc::clone(&asking)); + // key is "@me" or the org; account is the bare + // login, which is what scope_of wants for "@me". + let (acc, viewer, tok, scopes) = + (a.key.clone(), a.account.clone(), ui_tok.clone(), Arc::clone(&ui_scopes)); + std::thread::spawn(move || { + let got = fetch_oldest(&acc, &viewer, &tok, &scopes); + if let Ok(mut g) = oldest.lock() { + g.insert(acc.clone(), got); + } + if let Ok(mut g) = asking.lock() { + g.remove(&acc); + } + }); + } + } + let body = account_detail(a, held.as_ref(), w, h, &p); + let hints: Vec<Vec<(&str, String)>> = vec![ + vec![(p.accent.as_str(), "↑↓".into()), (p.dim.as_str(), " scroll".into())], + vec![ + (p.accent.as_str(), "←".into()), + (p.dim.as_str(), "/esc back".into()), + ], + vec![(p.dim.as_str(), "[q]uit".into())], + ]; + let foot: Vec<String> = tc::pack_hints(&hints, w - 2, " ") + .into_iter() + .map(|l| format!(" {}", l)) + .collect(); + let room = h.saturating_sub(foot.len()).max(1); + dscroll = dscroll.min(body.len().saturating_sub(room)); + let last = (dscroll + room).min(body.len()); + let mut out: Vec<String> = body[dscroll..last].to_vec(); + while out.len() < room { + out.push(String::new()); + } + out.extend(foot); + tc::draw(&out, w, h); + std::thread::sleep(Duration::from_millis(300)); + continue; + } + detail = false; + } + let hints: Vec<Vec<(&str, String)>> = vec![ vec![(p.accent.as_str(), "↑↓".into()), (p.dim.as_str(), " account".into())], + vec![ + (p.accent.as_str(), "→/↵".into()), + (p.dim.as_str(), " account".into()), + ], vec![(p.dim.as_str(), "[w]indow".into())], vec![(p.dim.as_str(), "[r]efresh".into())], vec![(p.dim.as_str(), "[q]uit".into())], From 39a7d477605d3451752ad118f06e41e03c701a70 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Tue, 25 Aug 2026 15:04:23 +0800 Subject: [PATCH 098/147] github: walk the oldest PRs and copy one MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Ten rather than five, a cursor through them, and c copies the URL of the row it is on - the same key pr uses for the same job, so the pair agree. ↑↓ drive that cursor rather than the page, and the page scrolls to follow it, the way netwatch's detail follows a cursor into a section. Without that the row being selected is usually off the bottom: the list sits below nine fields and a stacked bar. PgUp/PgDn still move the page freely, which is how the sections above and below the list are reached. The copy reads the account from the shared state rather than the render's copy of it, because keys are handled before the frame is built and the render has not run yet on the frame that answers them. The check caught [c] before I did - it was in the footer and not in the doc, which is the pairing it exists to enforce. The doc now describes the whole screen rather than just naming the key. --- docs/github.md | 38 ++++++++++++- rust/widgets/src/bin/github.rs | 100 +++++++++++++++++++++++++++++---- 2 files changed, 125 insertions(+), 13 deletions(-) diff --git a/docs/github.md b/docs/github.md index e58a18e..0a278a8 100644 --- a/docs/github.md +++ b/docs/github.md @@ -196,10 +196,44 @@ into a single request returned HTTP 502 on the complexity limit. | Key | Action | |---|---| -| `↑` `↓` | select an account | +| `↑` `↓` | select an account — on an account's own screen, move through its oldest open PRs | +| `→` `↵` | open the selected account | +| `←` `esc` | back to the board | +| `c` | copy the selected PR's URL | +| `PgUp` `PgDn` `Home` `End` | scroll an account's screen by the page, or to either end | | `w` | cycle the window — 7 / 14 / 30 / 60 / 90 days | | `r` | refresh now, ignoring the day cache | -| `q` | quit | +| `q` | quit, from either screen | + +## One account on its own screen + +`→` or `↵` opens the highlighted account. Most of what is there the row +already carried and had no room to spell out — open split into what waits on +a reviewer and what is still a draft, merged split into what landed and what +was closed unmerged — plus a few figures worth deriving: + +- **net** — opened minus merged over the window. A queue of six hundred is a + different thing depending on whether it grew by forty this week or held + level. +- **merged/day**, with the open queue restated as time at that rate. *"110d + of open PRs"* is the number people estimate and get wrong. +- **busiest day** and **days with none** — the shape of the window. + +The **OPEN PR STATE** bar and the **PR FLOW** chart are the two the board +draws for every account added together, drawn here for one. That is the +reason to open the screen: a queue growing in a single account is invisible +in a total six others are also feeding. + +**OLDEST OPEN** lists the ten longest-waiting PRs, newest information the +board cannot hold. Everything else on this widget is built from `issueCount` +aggregates — exact at any volume, one rate-limit point per request rather +than per alias, and unable to name anything at all. So this one asks for +nodes, once per account when its screen is first opened, and keeps the +answer. + +`↑` `↓` move through that list and `c` copies the URL of the row under the +cursor, the same key `pr` uses for the same job. The page scrolls to follow +the cursor; `PgUp` `PgDn` move it freely for the sections above and below. ## Credentials diff --git a/rust/widgets/src/bin/github.rs b/rust/widgets/src/bin/github.rs index 1971ab8..4f0ce57 100644 --- a/rust/widgets/src/bin/github.rs +++ b/rust/widgets/src/bin/github.rs @@ -44,7 +44,7 @@ fn age_since(iso: &str) -> String { } } -const OLDEST_WANTED: usize = 5; +const OLDEST_WANTED: usize = 10; const API: &str = "https://api.github.com/graphql"; const WINDOWS: &[i64] = &[7, 14, 30, 60, 90]; @@ -107,6 +107,7 @@ fn fetch_oldest(acc: &str, viewer: &str, tok: &str, scopes: &Arc<Mutex<Scopes>>) ... on PullRequest {{ number title + url createdAt isDraft repository {{ name }} @@ -138,10 +139,15 @@ fn fetch_oldest(acc: &str, viewer: &str, tok: &str, scopes: &Arc<Mutex<Scopes>>) fn account_detail( a: &Account, oldest: Option<&serde_json::Value>, + pick: usize, w: usize, h: usize, p: &Palette, -) -> Vec<String> { +) -> (Vec<String>, Option<usize>) { + // Where the cursor over the oldest list ended up, so the caller can + // scroll to it. The caller cannot work it out: how far down the page + // that list starts depends on how many fields this account had. + let mut cursor: Option<usize> = None; let mut rows = vec![tc::title(&a.account, w, &p.accent)]; let label_w = 16usize; let mut field = |name: &str, value: String, aside: String, colour: &str| { @@ -331,7 +337,11 @@ fn account_detail( ], w - 1, )); - for node in nodes.iter() { + for (i, node) in nodes.iter().enumerate() { + let here = i == pick.min(nodes.len().saturating_sub(1)); + if here { + cursor = Some(rows.len()); + } let age = age_since(node["createdAt"].as_str().unwrap_or("")); let repo = node["repository"]["name"].as_str().unwrap_or("").to_string(); let num = node["number"].as_i64().unwrap_or(0); @@ -344,11 +354,21 @@ fn account_detail( } else { title }; + let tint = if here { tc::bg(38, 56, 76) } else { String::new() }; + let c = |colour: &str| format!("{}{}", tint, colour); rows.push(tc::seg( &[ - (if draft { p.dim.as_str() } else { p.warn.as_str() }, head), - (p.dim.as_str(), format!("{} ", repo)), - (p.txt.as_str(), title), + ( + &c(if here { p.accent.as_str() } else { p.dim.as_str() }), + if here { " ▸".into() } else { " ".to_string() }, + ), + ( + &c(if draft { p.dim.as_str() } else { p.warn.as_str() }), + head.trim_start().to_string(), + ), + (&c(p.dim.as_str()), format!(" {} ", repo)), + (&c(p.txt.as_str()), title), + (&tint, if here { " ".repeat(w) } else { String::new() }), ], w - 1, )); @@ -447,7 +467,7 @@ fn account_detail( w - 1, )); } - rows + (rows, cursor) } /// What the token is allowed to see, read off the response headers. @@ -1110,6 +1130,9 @@ fn main() { let (mut selected, mut tick) = (0usize, 0usize); // One account on its own screen, and how far down it is scrolled. let (mut detail, mut dscroll) = (false, 0usize); + // Which of the oldest PRs the cursor is on, and what [c] last said. + let mut osel = 0usize; + let (mut note, mut note_at) = (String::new(), 0.0f64); // The longest-open PRs per account, fetched when that account's screen // is opened and kept after. let oldest: Arc<Mutex<HashMap<String, serde_json::Value>>> = Arc::new(Mutex::new(HashMap::new())); @@ -1152,8 +1175,38 @@ fn main() { dscroll = 0; } "left" | "esc" if detail => detail = false, - "up" if detail => dscroll = dscroll.saturating_sub(1), - "down" if detail => dscroll = dscroll.saturating_add(1), + "up" if detail => osel = osel.saturating_sub(1), + "down" if detail => osel = osel.saturating_add(1), + "c" | "C" if detail => { + // The account under the cursor, read from the shared + // state rather than the render's copy - the keys are + // handled before the frame is built. + let key = state + .lock() + .ok() + .and_then(|g| { + g.stats + .get(selected.min(g.stats.len().saturating_sub(1))) + .map(|a| a.key.clone()) + }) + .unwrap_or_default(); + let url = oldest + .lock() + .ok() + .and_then(|g| g.get(&key).cloned()) + .and_then(|v| v.as_array().cloned()) + .and_then(|n| n.get(osel).cloned()) + .map(|n| n["url"].as_str().unwrap_or("").to_string()) + .unwrap_or_default(); + if !url.is_empty() { + note = if tc::clipboard(&url) { + format!("✓ copied {}", url) + } else { + format!("no clipboard: {}", url) + }; + note_at = now(); + } + } "pgup" if detail => { let page = tc::size().1.saturating_sub(3).max(1); dscroll = dscroll.saturating_sub(page); @@ -1752,9 +1805,19 @@ fn main() { }); } } - let body = account_detail(a, held.as_ref(), w, h, &p); + let nodes = held + .as_ref() + .and_then(|v| v.as_array().cloned()) + .unwrap_or_default(); + osel = osel.min(nodes.len().saturating_sub(1)); + let (body, cursor) = account_detail(a, held.as_ref(), osel, w, h, &p); let hints: Vec<Vec<(&str, String)>> = vec![ - vec![(p.accent.as_str(), "↑↓".into()), (p.dim.as_str(), " scroll".into())], + vec![ + (p.accent.as_str(), "↑↓".into()), + (p.dim.as_str(), if nodes.is_empty() { " scroll" } else { " oldest" }.into()), + ], + vec![(p.dim.as_str(), "[c]opy url".into())], + vec![(p.dim.as_str(), "pgup/pgdn page".into())], vec![ (p.accent.as_str(), "←".into()), (p.dim.as_str(), "/esc back".into()), @@ -1766,12 +1829,27 @@ fn main() { .map(|l| format!(" {}", l)) .collect(); let room = h.saturating_sub(foot.len()).max(1); + // The page follows the cursor into the oldest list, the way + // netwatch's detail follows one into a section. Without it + // the row being selected is often off the bottom. + if let Some(at) = cursor { + if at < dscroll { + dscroll = at; + } else if at >= dscroll + room { + dscroll = at + 1 - room; + } + } dscroll = dscroll.min(body.len().saturating_sub(room)); let last = (dscroll + room).min(body.len()); let mut out: Vec<String> = body[dscroll..last].to_vec(); while out.len() < room { out.push(String::new()); } + if !note.is_empty() && now() - note_at < 6.0 { + if let Some(row) = out.last_mut() { + *row = tc::seg(&[(p.ok.as_str(), format!(" {}", note))], w - 1); + } + } out.extend(foot); tc::draw(&out, w, h); std::thread::sleep(Duration::from_millis(300)); From 594c1bdbb471d320ea16d10ce1e9572cade8142f Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Tue, 25 Aug 2026 15:24:36 +0800 Subject: [PATCH 099/147] deployments: one filter you type, one you cycle, and the names say which [p]roject cycled one project at a time. With a dozen projects, reaching the last meant pressing it a dozen times, and it could never express "the failed ones in either of these two". Gone. [/] replaces it, the same key pr uses for the same job: type to narrow, enter to keep it, esc to clear. It matches the fields the row shows and one it does not - project, state, target, branch, commit subject, and the deployment id, that last because an id is what a link from somewhere else gives you to look something up by. While typing every key is text, so q types a q rather than quitting, which is the only way a filter can contain one. [f]ilter is [s]tate now, and carries its current value: "filter" said nothing about which of the two it was once there were two, and this is the one that cycles rather than types. The two stack, and the header says so - "filter: failed + /studio" - with a cursor while you are still typing, because otherwise an empty filter and one you are halfway through look identical. The check caught the help text still naming f, which the Rust no longer answers. deployments.py keeps f and p; the doc marks those rows py-only. Also removed a duplicated `let mut overlay = false;` that an earlier edit of mine left shadowing the first. Harmless - both were false - but it is the kind of thing that stops being harmless the moment one of them changes. --- docs/deployments.md | 31 ++++++- rust/widgets/src/bin/deployments.rs | 107 ++++++++++++++-------- rust/widgets/src/bin/deployments_help.txt | 4 +- 3 files changed, 95 insertions(+), 47 deletions(-) diff --git a/docs/deployments.md b/docs/deployments.md index 1e07b88..2778b35 100644 --- a/docs/deployments.md +++ b/docs/deployments.md @@ -5,7 +5,7 @@ Vercel deployments — how they are going over time, not just what shipped last. ``` ╺━ VERCEL DEPLOYMENTS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╸ 200 deploys · 20 proj 179 ready 21 error 0s ago - ↑↓ select · [c]opy · [r]efresh [f]ilter [p]roject [q]uit + ↑↓ select · →/↵ details · [s]tate all · [/]filter · [r]efresh · [q]uit ── ACTIVITY ── deploys/hour, last 48h ····▂▂·▃▃▄▄···················▂▄▆▄▃▃▃▄▂▃▃············▂▃·▃▂▂▄·▂▄█▃▂▃ @@ -116,10 +116,31 @@ on the way out rather than on the way in. | `→` / `Enter` | full detail view for the selected deployment | | `1`–`7` | inside the view, copy that item | | `←` / `esc` | close the detail view | -| `f` | filter — all / failed / production | -| `p` | cycle which project is shown | -| `r` | refresh now | -| `q` | quit | +| `s` | state filter — all / failed / production | +| `/` | filter by text — `enter` keeps it, `esc` clears it | +| `c` | copy the selected PR's… (in the detail view, the copy page) | +| `r` | refresh now, and in the detail view fetch it again | +| `q` | quit, from either screen | +| `f` `p` | the state filter and the project cycle — **`deployments.py` only**; the Rust build has `s` and `/` instead | + +## Filtering + +Two filters, and they stack. + +`s` cycles the **state** — all, failed, production. It is a fixed set, so it +cycles rather than types. + +`/` filters by **text**, against everything the row shows and one thing it +does not: project name, state, target, branch, commit subject, and the +deployment id — the last because an id is what a link from somewhere else +gives you to look something up by. Type to narrow, `enter` to keep it and go +back to the arrows, `esc` to clear it. While typing, every key is text: `q` +types a q rather than quitting, which is the only way a filter can contain +one. + +This replaced a `p` key that cycled one project at a time. With a dozen +projects, reaching the last meant pressing it a dozen times, and it could +never express "the failed ones in either of these two". ## Layout diff --git a/rust/widgets/src/bin/deployments.rs b/rust/widgets/src/bin/deployments.rs index 6fbee11..77dcfa5 100644 --- a/rust/widgets/src/bin/deployments.rs +++ b/rust/widgets/src/bin/deployments.rs @@ -381,6 +381,31 @@ fn titled(state: &str) -> String { /// One deployment in full: state, timings, why it failed, and what to copy. +/// Whether one deployment answers what was typed after `/`. +/// +/// Over the fields the row puts on screen and the one it does not: project, +/// state, target, branch and commit subject, plus the deployment id, because +/// that is what a URL from somewhere else gives you to look up. The project +/// filter this replaced could only ever say one name at a time and had to be +/// cycled through every project to reach the last one. +fn matches(dep: &serde_json::Value, needle: &str) -> bool { + if needle.is_empty() { + return true; + } + let meta = &dep["meta"]; + let hay = [ + text(dep, "name"), + text(dep, "state"), + text(dep, "target"), + text(dep, "uid"), + text(meta, "githubCommitRef"), + text(meta, "githubCommitMessage"), + ] + .join(" ") + .to_lowercase(); + hay.contains(&needle.to_lowercase()) +} + /// The build log, newest last, with what the build wrote to stderr picked /// out of what it wrote to stdout. /// @@ -845,9 +870,9 @@ fn main() { Arc::new(Mutex::new(HashMap::new())); let fetching: Arc<Mutex<HashSet<String>>> = Arc::new(Mutex::new(HashSet::new())); let mut filter = 0usize; - let mut only: Option<String> = None; - let (mut tick, mut selected, mut scroll) = (0usize, 0usize, 0usize); + let (mut needle, mut typing) = (String::new(), false); let mut overlay = false; + let (mut tick, mut selected, mut scroll) = (0usize, 0usize, 0usize); // The copy list is a page of its own, opened from the detail with c. let mut copying = false; // How far down the detail is scrolled. The build log makes it taller @@ -860,6 +885,24 @@ fn main() { loop { tick += 1; for key in keyboard.poll() { + // While filtering, keys are text - only escape and enter are + // navigation, or the filter could never contain "q". + if typing && !overlay { + match key.as_str() { + "esc" => { + needle.clear(); + typing = false; + } + "enter" => typing = false, + "backspace" => { + needle.pop(); + } + other if other.chars().count() == 1 => needle.push_str(other), + _ => {} + } + selected = 0; + continue; + } if overlay { match key.as_str() { // Left and esc come out. q quits outright, which is @@ -940,10 +983,14 @@ fn main() { cond.notify_all(); } } - "f" | "F" => { + // s, not f: "filter" said nothing about which of the two + // this was once there were two, and the state filter is the + // one that cycles rather than types. + "s" | "S" => { filter = (filter + 1) % FILTERS.len(); selected = 0; } + "/" => typing = true, "up" => selected = selected.saturating_sub(1), "down" => selected += 1, "pgup" => selected = selected.saturating_sub(visible), @@ -958,34 +1005,6 @@ fn main() { note = (String::new(), 0.0); } } - "p" | "P" => { - let names: Vec<String> = { - let guard = match state.lock() { - Ok(g) => g, - Err(_) => return, - }; - let mut seen: Vec<String> = guard - .deployments - .iter() - .map(|d| text(d, "name")) - .filter(|n| !n.is_empty()) - .collect(); - seen.sort(); - seen.dedup(); - seen - }; - // Cycles through every project and back to no filter, - // so the key always has somewhere to go. - only = match &only { - None => names.first().cloned(), - Some(current) => match names.iter().position(|n| n == current) { - Some(at) if at + 1 < names.len() => Some(names[at + 1].clone()), - Some(_) => None, - None => names.first().cloned(), - }, - }; - selected = 0; - } _ => {} } } @@ -999,9 +1018,7 @@ fn main() { note = (String::new(), 0.0); } shown = deps.clone(); - if let Some(name) = &only { - shown.retain(|d| text(d, "name") == *name); - } + shown.retain(|d| matches(d, &needle)); match FILTERS[filter] { "failed" => shown.retain(|d| { let s = text(d, "state"); @@ -1140,12 +1157,22 @@ fn main() { if FILTERS[filter] != "all" { bits.push(FILTERS[filter].to_string()); } - if let Some(name) = &only { - bits.push(name.clone()); + if !needle.is_empty() { + bits.push(format!("/{}", needle)); } - if !bits.is_empty() { + if !bits.is_empty() || typing { + // The cursor is the widget saying it is still listening: without + // it an empty filter and a filter you are halfway through typing + // look identical. rows.push(tc::seg( - &[(p.build.as_str(), format!(" filter: {}", bits.join(" + ")))], + &[ + (p.build.as_str(), format!(" filter: {}", bits.join(" + "))), + (p.build.as_str(), if typing { "▏".into() } else { String::new() }), + ( + p.dim.as_str(), + if typing { " enter to keep · esc to clear".into() } else { String::new() }, + ), + ], w - 1, )); } @@ -1314,8 +1341,8 @@ fn main() { (p.accent.as_str(), "→/↵".into()), (p.dim.as_str(), " details".into()), ], - vec![(p.dim.as_str(), "[f]ilter".into())], - vec![(p.dim.as_str(), "[p]roject".into())], + vec![(p.dim.as_str(), format!("[s]tate {}", FILTERS[filter]))], + vec![(p.dim.as_str(), "[/]filter".into())], vec![(p.dim.as_str(), "[r]efresh".into())], vec![(p.dim.as_str(), "[q]uit".into())], ]; diff --git a/rust/widgets/src/bin/deployments_help.txt b/rust/widgets/src/bin/deployments_help.txt index 656f6c9..cfa3df2 100644 --- a/rust/widgets/src/bin/deployments_help.txt +++ b/rust/widgets/src/bin/deployments_help.txt @@ -12,8 +12,8 @@ Keys while running: up/down (also PgUp/PgDn, Home/End) move the selection, → or Enter opens a full detail view for the selected deployment - state and failure reason, timings, regions, commit, and everything worth copying on number keys - r refreshes -now, f cycles the filter (all / failed / production), p cycles which project -is shown, q quits. +now, s cycles the state filter (all / failed / production), / filters by text +against the project, branch, commit subject and deployment id, q quits. Copying uses OSC 52, so the terminal you are sitting at performs it and the text reaches your local clipboard even over SSH. If your terminal or From b3e9089cf8c10c6f913752480e25de5814da512b Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Tue, 25 Aug 2026 15:48:37 +0800 Subject: [PATCH 100/147] linear: a screen of its own for a cycle, and for a team its projects MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The board answered every question about the workspace and none about a single row in it. `↵` or `→` now opens the highlighted cycle or team on a screen of its own, `←` or `esc` comes back, and the arrows scroll it. A cycle gives its progress, its scope, how long is left, and how much moved lately - the same day-over-day figure the ranking uses, so the order the board puts cycles in is legible rather than mysterious. A cycle with no name is called by its number: the title used to open with a bare "·" and read as a rendering fault. Churn near zero prints "0", never "-0". A team gives what it is holding broken out by state, and then every project it owns. Those needed a query - the board fetched no project field at all - and it is one request for the whole workspace rather than one per team, so a team's screen opens on data already in hand instead of showing nothing while a request goes out. A project shared by two teams appears on both. Three things that pay for themselves: The percentage is Linear's own `progress`, not one derived here. This widget fetches only what is open, so a finished project has nothing left to count; taking Linear's figure is the only way the two agree. It is also why a project can read 87% and still show open issues. Most issues are in no project, so the per-project counts do not sum to the team's open total three lines above. The heading says how many are loose - "672 open in no project" - because a column of numbers that does not reconcile with the one above it reads as a bug. A status this build has never heard of sorts with the running work, not under the finished work. Workspaces name their own statuses, and an unfamiliar one buried at the bottom would hide real work. Columns are sized to what is in them: the first cut capped names at 34 and cut a real project's name a character short of the end, which names something that does not exist. Nothing is capped now - the bar takes what is left, and a narrow pane sheds whole facts off the aside rather than cutting one in half, because a lead's name with its last letters missing is nobody. Each of the six new tests was watched failing against the defect it covers. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- docs/linear.md | 54 ++- rust/widgets/src/bin/linear.rs | 695 ++++++++++++++++++++++++++++++++- 2 files changed, 745 insertions(+), 4 deletions(-) diff --git a/docs/linear.md b/docs/linear.md index d4060bf..eb9e6f1 100644 --- a/docs/linear.md +++ b/docs/linear.md @@ -113,6 +113,53 @@ created against 88 completed. **By team** — ranked by open volume, windowing around the cursor when focused and there are more teams than rows. `DONE14D` follows the window. +## One cycle, or one team + +`↵` or `→` on the highlighted row opens it on a screen of its own; `←` or `esc` +comes back; `↑` `↓` and `PgUp` `PgDn` scroll it when it is longer than the pane. + +A **cycle** gives its progress, its scope and how much of it is closed, how long +is left to run, and how much moved lately — the same day-over-day figure the +board ranks cycles by, so the ordering is legible rather than mysterious. A +cycle with no name of its own is called by its number rather than left blank. + +A **team** gives what it is holding, broken out by state as a stacked bar, with +triage called out separately: it is work nobody has looked at, and a team can +hold hundreds of it while looking busy everywhere else. + +Under that, **every project the team owns**: + +``` + ── PROJECTS ── 6 · 672 open in no project + uptime-monitoring In Progress ███████████████ 100% 10 open + search-relevance In Progress █████████████░░ 88% 1 open · A Lead + storage-provider-swap Paused █░░░░░░░░░░░░░░ 3% due 2026-04-10 · A Lead + offline-mode Idea ░░░░░░░░░░░░░░░ 0% 25 open · A Lead + runtime-metrics Maintenance ███████████████ 100% A Lead + cluster-migration Completed █████████████░░ 87% 2 open · due 2024-07-26 · A Lead +``` + +Running work sorts first and finished work last, with a status this build has +never heard of sorting *with* the live work rather than under the dead work — +a workspace names its own statuses, and burying an unfamiliar one would hide +real work. The status is shown by the workspace's own name for it — `In +Progress`, not `started` — and its type picks the colour. + +The percentage is **Linear's own published `progress`**, not a figure derived +here. The board fetches only what is open, so a project that is finished has +nothing left for this widget to count; taking Linear's number is the only way +the two agree. That is also why a project can read 87% and still show open +issues, and why the per-project counts do not sum to the team's open total — +which is what `672 open in no project` is there to say. Without it a column of +numbers sits three lines under a larger one and reads as a bug. + +Projects are shared: one owned by two teams appears on both screens. + +Columns are sized to what is in them — no name is ever cut, because half a +project's name is a name for something else. The bar takes whatever is left, +and when the pane is too narrow the aside sheds whole facts off the end rather +than let one be cut in half. + ## Cost Linear allows **2,500 requests/hour** and 3,000,000 complexity points; a single @@ -121,7 +168,9 @@ multiplied by the page size, so the request count is the limit that binds and the field count barely matters. A full pass over a workspace of 14 teams and ~1,200 open issues costs about -**10 requests and 4 seconds**, so the default 120s refresh uses roughly 300 +**11 requests and 4 seconds** — one of them the whole workspace's projects, +fetched with everything else so a team's screen opens on data already in hand +rather than showing nothing while a request goes out, so the default 120s refresh uses roughly 300 requests an hour — an eighth of the budget. Remaining quota is read from `X-RateLimit-Requests-Remaining` and shown in the header. @@ -152,6 +201,9 @@ are stepped over in every direction. |---|---| | `tab` | focus the next pane, and from the last one back to no focus | | `↑` `↓` | move the cursor, crossing between panes at their ends — or step into one when none is focused | +| `↵` `→` | open the highlighted cycle or team on a screen of its own | +| `←` `esc` | back to the board | +| `↑` `↓` `PgUp` `PgDn` | scroll a detail screen | | `w` | cycle the window — 7 / 14 / 30 / 60 / 90 days | | `r` | refresh now | | `q` | quit | diff --git a/rust/widgets/src/bin/linear.rs b/rust/widgets/src/bin/linear.rs index 2d1acc7..a32293b 100644 --- a/rust/widgets/src/bin/linear.rs +++ b/rust/widgets/src/bin/linear.rs @@ -143,7 +143,7 @@ query($after: String) {{ filter: {{ state: {{ type: {{ nin: ["completed", "canceled", "duplicate"] }} }} }}) {{ nodes {{ identifier estimate startedAt createdAt - state {{ type }} team {{ key }} }} + state {{ type }} team {{ key }} project {{ id }} }} pageInfo {{ hasNextPage endCursor }} }} }}"#, @@ -190,6 +190,24 @@ const CYCLES_QUERY: &str = r#" } }"#; +/// Every project in the workspace, with the teams that own it. +/// +/// One request covers all of them - there are dozens, not thousands - so a +/// team's projects are already in hand when its screen opens, rather than +/// arriving a request later while the screen shows nothing. +const PROJECTS_QUERY: &str = r#" +query($after: String) { + projects(first: 100, after: $after) { + nodes { + id name progress targetDate + status { name type } + lead { name } + teams(first: 20) { nodes { key } } + } + pageInfo { hasNextPage endCursor } + } +}"#; + const TEAMS_QUERY: &str = r#" { teams(first: 100) { nodes { key name } pageInfo { hasNextPage } } }"#; @@ -269,6 +287,47 @@ fn median(xs: &[f64]) -> Option<f64> { }) } +/// One project, as much of it as a team's screen needs. +/// +/// `progress` is Linear's own published figure, not one derived here: it +/// counts issues this widget never fetches, because the board asks only for +/// what is open and a finished project has none. +#[derive(Clone, Default)] +struct Proj { + id: String, + name: String, + /// The workspace's own name for the status - "In Progress", not + /// "started" - with `kind` left to pick the colour. + label: String, + kind: String, + progress: f64, + target: String, + lead: String, +} + +/// A project's aside, as one string. Measured and drawn through the same +/// call so the separator cannot be counted one way and printed another. +fn joined(parts: &[String]) -> String { + parts.join(" · ") +} + +/// Where a project's status sorts, running work first and finished last. +/// +/// An unknown status sorts with the live ones rather than the dead ones: a +/// workspace can name its own statuses, and burying one this build has not +/// heard of would hide real work. +fn rank(kind: &str) -> usize { + match kind { + "started" => 0, + "planned" => 2, + "paused" => 3, + "backlog" => 4, + "completed" => 5, + "canceled" => 6, + _ => 1, + } +} + /// An issue worth going and looking at: how long, and which one. type Extreme = Option<(f64, String)>; @@ -277,6 +336,12 @@ struct State { teams: Vec<(String, String)>, states: HashMap<String, usize>, by_team: HashMap<String, HashMap<String, usize>>, + /// Team key to that team's projects, ordered as the screen shows them. + projects: HashMap<String, Vec<Proj>>, + /// Team key to project id to how many of that team's open issues sit in + /// it. The empty id is the bucket for issues in no project at all, which + /// is why the per-project figures do not sum to the team's open count. + proj_open: HashMap<String, HashMap<String, usize>>, cycles: Vec<serde_json::Value>, created: HashMap<String, usize>, completed: HashMap<String, usize>, @@ -340,6 +405,7 @@ fn one_pass( let (rows, capped) = pages(tok, &open_query(), &["issues"], &serde_json::json!({}), quota)?; let mut states: HashMap<String, usize> = HashMap::new(); let mut by_team: HashMap<String, HashMap<String, usize>> = HashMap::new(); + let mut proj_open: HashMap<String, HashMap<String, usize>> = HashMap::new(); let at = Utc::now().naive_utc(); let (mut oldest_open, mut oldest_wip): (Extreme, Extreme) = (None, None); for it in &rows { @@ -352,6 +418,13 @@ fn one_pass( continue; } *states.entry(st.clone()).or_insert(0) += 1; + // The empty string when the issue is in no project, which is a + // real and common answer here, not a missing one. + *proj_open + .entry(key.clone()) + .or_default() + .entry(text(&it["project"], "id")) + .or_insert(0) += 1; let slot = by_team.entry(key).or_default(); *slot.entry(st.clone()).or_insert(0) += 1; *slot.entry("open".into()).or_insert(0) += 1; @@ -380,6 +453,42 @@ fn one_pass( .cloned() .collect(); + // Every project, filed under each team that owns it. A project can be + // shared, so one node lands in more than one team's list. + let (proj_rows, cap4) = pages( + tok, + PROJECTS_QUERY, + &["projects"], + &serde_json::json!({}), + quota, + )?; + let mut projects: HashMap<String, Vec<Proj>> = HashMap::new(); + for pr in &proj_rows { + let made = Proj { + id: text(pr, "id"), + name: text(pr, "name"), + label: text(&pr["status"], "name"), + kind: text(&pr["status"], "type"), + progress: pr["progress"].as_f64().unwrap_or(0.0), + target: text(pr, "targetDate"), + lead: text(&pr["lead"], "name"), + }; + for t in pr["teams"]["nodes"].as_array().into_iter().flatten() { + let key = text(t, "key"); + if keys.contains(&key) { + projects.entry(key).or_default().push(made.clone()); + } + } + } + for list in projects.values_mut() { + list.sort_by(|a, b| { + rank(&a.kind) + .cmp(&rank(&b.kind)) + .then(b.progress.total_cmp(&a.progress)) + .then(a.name.cmp(&b.name)) + }); + } + // Arrivals and departures over the window. let vars = serde_json::json!({ "since": since }); let (made, cap2) = pages(tok, &created_query(), &["issues"], &vars, quota)?; @@ -424,6 +533,8 @@ fn one_pass( if let Ok(mut guard) = state.lock() { guard.states = states; guard.by_team = by_team; + guard.projects = projects; + guard.proj_open = proj_open; guard.cycles = cycles; guard.created = created; guard.completed = completed; @@ -434,7 +545,7 @@ fn one_pass( guard.oldest_open = oldest_open; guard.oldest_wip = oldest_wip; guard.window = days; - guard.truncated = capped || cap2 || cap3; + guard.truncated = capped || cap2 || cap3 || cap4; guard.fetched = now(); guard.err = if source == "config" { tc::config_token_warning().unwrap_or_default() @@ -493,6 +604,359 @@ fn state_label(state: &str) -> &'static str { } } +/// One cycle in full: how much work it holds, how much is done, and the +/// shape of both since it opened. +/// +/// The board ranks cycles by churn and shows a bar. The two histories behind +/// that bar are the interesting part and there is no room for them in a row: +/// scope rising while completed stays flat is a cycle taking on work, and +/// the two converging is one closing. Nothing here is a new request - the +/// arrays arrive with the cycle. +fn cycle_detail(c: &serde_json::Value, w: usize, h: usize, p: &Palette) -> Vec<String> { + let team = text(&c["team"], "name"); + // Linear cycles are often unnamed - the board falls back to their + // number and so does this, or the title reads " · TEAM" with a leading + // separator hanging off nothing. + let named = match text(c, "name") { + n if n.is_empty() => format!("Cycle {}", tidy(c["number"].as_f64().unwrap_or(0.0))), + n => n, + }; + let title = if team.is_empty() { named } else { format!("{} · {}", named, team) }; + let mut rows = vec![tc::title(&title, w, &p.accent)]; + let label_w = 18usize; + let mut field = |name: &str, value: String, aside: String, colour: &str| { + rows.push(tc::seg( + &[ + (p.dim.as_str(), format!(" {}", tc::pad(name, label_w))), + (colour, format!("{:>7}", value)), + (p.dim.as_str(), format!(" {}", aside)), + ], + w - 1, + )); + }; + + let series = |key: &str| -> Vec<f64> { + c[key] + .as_array() + .into_iter() + .flatten() + .filter_map(|v| v.as_f64()) + .collect() + }; + let scope = series("scopeHistory"); + let done = series("completedScopeHistory"); + let issues = series("issueCountHistory"); + let issues_done = series("completedIssueCountHistory"); + + let at = |v: &[f64]| v.last().copied().unwrap_or(0.0); + let pct = if at(&scope) > 0.0 { + 100.0 * at(&done) / at(&scope) + } else { + 0.0 + }; + field( + "progress", + format!("{:.0}%", pct), + tc::meter(pct / 100.0, w.saturating_sub(label_w + 22).clamp(6, 24)), + if pct >= 80.0 { p.ok.as_str() } else { p.txt.as_str() }, + ); + field( + "scope", + format!("{:.0}", at(&scope)), + format!("{:.0} done, {:.0} left", at(&done), (at(&scope) - at(&done)).max(0.0)), + p.txt.as_str(), + ); + if !issues.is_empty() { + field( + "issues", + format!("{:.0}", at(&issues)), + format!("{:.0} closed", at(&issues_done)), + p.dim.as_str(), + ); + } + // Scope that appeared after the cycle opened. The number people mean + // when they say a cycle "grew". + let added = at(&scope) - scope.first().copied().unwrap_or(0.0); + if added.abs() > 0.001 { + field( + "scope added", + format!("{:+.0}", added), + "since it opened".into(), + if added > 0.0 { p.warn.as_str() } else { p.ok.as_str() }, + ); + } + let (moved, left) = churn(c); + field( + "ends in", + if left >= 999 { "—".into() } else { format!("{}d", left) }, + text(c, "endsAt").chars().take(10).collect::<String>(), + p.dim.as_str(), + ); + // +0.0 formats as "-0" when the sum is a hair below zero, which reads + // as a negative churn and is not one. + field( + "churn", + format!("{:.0}", if moved.abs() < 0.05 { 0.0 } else { moved }), + "points moved lately".into(), + p.dim.as_str(), + ); + // What is left against what the cycle has been closing per day. The + // question a burn-up is usually read to answer, stated. + let days = done.len().max(1) as f64; + let rate = at(&done) / days; + if rate > 0.0 { + let remaining = (at(&scope) - at(&done)).max(0.0); + field( + "at this rate", + format!("{:.0}d", remaining / rate), + if left < 999 && remaining / rate > left as f64 { + "longer than the cycle has".into() + } else { + "to clear what is left".into() + }, + if left < 999 && remaining / rate > left as f64 { + p.warn.as_str() + } else { + p.ok.as_str() + }, + ); + } + + // Scope above the line, completed below it, on one scale. + if h.saturating_sub(rows.len()) >= 10 && scope.len() > 1 { + let hi = scope.iter().chain(done.iter()).cloned().fold(1.0f64, f64::max); + rows.push(String::new()); + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── BURN-UP ── ".into()), + (p.dim.as_str(), format!("{} days · ", scope.len())), + (p.txt.as_str(), "▲ scope".into()), + (p.dim.as_str(), " · ".into()), + (p.ok.as_str(), "▼ completed".into()), + ], + w - 1, + )); + let cols = w.saturating_sub(3).max(10); + let fit = |v: &[f64]| -> Vec<f64> { + if v.len() >= cols { + v[v.len() - cols..].to_vec() + } else { + v.to_vec() + } + }; + for line in tc::vbars( + &fit(&scope).iter().map(|v| (*v, p.txt.clone())).collect::<Vec<_>>(), + 3, + hi, + ) { + let mut parts: Vec<(&str, String)> = vec![(tc::RST, " ".into())]; + for (colour, ch) in &line { + parts.push((colour.as_str(), ch.clone())); + } + rows.push(tc::seg(&parts, w - 1)); + } + rows.push(tc::seg( + &[(tc::RST, " ".into()), (p.grid.as_str(), "─".repeat(fit(&scope).len()))], + w - 1, + )); + for line in tc::vbars_down( + &fit(&done).iter().map(|v| (*v, p.ok.clone())).collect::<Vec<_>>(), + 3, + hi, + ) { + let mut parts: Vec<(&str, String)> = vec![(tc::RST, " ".into())]; + for (colour, ch) in &line { + parts.push((colour.as_str(), ch.clone())); + } + rows.push(tc::seg(&parts, w - 1)); + } + } + rows +} + +/// One team in full: what it is holding, in the states it is holding it. +#[allow(clippy::too_many_arguments)] +fn team_detail( + key: &str, + name: &str, + counts: &HashMap<String, usize>, + projects: &[Proj], + opens: &HashMap<String, usize>, + window: i64, + w: usize, + h: usize, + p: &Palette, +) -> Vec<String> { + let mut rows = vec![tc::title(&format!("{} · {}", key, name), w, &p.accent)]; + let label_w = 18usize; + let get = |k: &str| counts.get(k).copied().unwrap_or(0); + let open = get("open"); + let mut field = |name: &str, value: String, aside: String, colour: &str| { + rows.push(tc::seg( + &[ + (p.dim.as_str(), format!(" {}", tc::pad(name, label_w))), + (colour, format!("{:>7}", value)), + (p.dim.as_str(), format!(" {}", aside)), + ], + w - 1, + )); + }; + field("open", open.to_string(), "issues not closed".into(), p.txt.as_str()); + field( + "done", + get("done").to_string(), + format!("in the last {}d", window), + p.ok.as_str(), + ); + // Triage is the one worth calling out: it is work nobody has looked at, + // and a team can hold hundreds of it while looking busy everywhere else. + let triage = get("triage"); + if triage > 0 { + field( + "in triage", + triage.to_string(), + if open > 0 { + format!("{:.0}% of open, unlooked at", 100.0 * triage as f64 / open as f64) + } else { + String::new() + }, + p.bad.as_str(), + ); + } + field("in progress", get("started").to_string(), String::new(), p.warn.as_str()); + + if open > 0 && h.saturating_sub(rows.len()) >= 4 { + let legend: Vec<(&str, usize, &str)> = [ + ("triage", triage, p.bad.as_str()), + ("backlog", get("backlog"), p.dim.as_str()), + ("unstarted", get("unstarted"), p.txt.as_str()), + ("in progress", get("started"), p.warn.as_str()), + ] + .into_iter() + .filter(|x| x.1 > 0) + .collect(); + if !legend.is_empty() { + rows.push(String::new()); + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── OPEN BY STATE ── ".into()), + (p.dim.as_str(), format!("{} issues", open)), + ], + w - 1, + )); + let parts: Vec<(f64, String)> = legend + .iter() + .map(|(_, n, c)| (*n as f64 / open as f64, c.to_string())) + .collect(); + let bar = tc::stacked_bar(&parts, w.saturating_sub(3).max(10)); + let mut line: Vec<(&str, String)> = vec![(tc::RST, " ".into())]; + for (colour, txt) in &bar { + line.push((colour.as_str(), txt.clone())); + } + rows.push(tc::seg(&line, w - 1)); + let mut legend_row: Vec<(&str, String)> = vec![(tc::RST, " ".into())]; + for (label, count, colour) in &legend { + legend_row.push((colour, "▇ ".into())); + legend_row.push((p.txt.as_str(), (*label).into())); + legend_row.push(( + p.dim.as_str(), + format!(" {} ({:.0}%) ", count, 100.0 * *count as f64 / open as f64), + )); + } + rows.push(tc::seg(&legend_row, w - 1)); + } + } + + rows.push(String::new()); + // The issues in no project. Said out loud because the per-project counts + // below will not add up to the team's open count without it, and a + // column of numbers that does not reconcile reads as a bug. + let loose = opens.get("").copied().unwrap_or(0); + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── PROJECTS ── ".into()), + ( + p.dim.as_str(), + if projects.is_empty() { + "none".to_string() + } else if loose > 0 { + format!("{} · {} open in no project", projects.len(), loose) + } else { + format!("{}", projects.len()) + }, + ), + ], + w - 1, + )); + if projects.is_empty() { + rows.push(tc::seg( + &[(p.dim.as_str(), " this team owns no projects".into())], + w - 1, + )); + return rows; + } + + // Every aside first, because the columns are sized to what is in them: + // names and statuses take the width they need and the meter takes what + // is left, so a wider pane draws a longer bar rather than a margin. No + // column is capped, because capping one truncates a project's name and + // a half-written name is a name for something else. + // + // Only what a project actually has goes in its aside: one with no open + // issues left says nothing rather than "0 open", and one with no target + // date says nothing rather than an em dash. + let asides: Vec<Vec<String>> = projects + .iter() + .map(|q| { + let mut parts = Vec::new(); + let open = opens.get(&q.id).copied().unwrap_or(0); + if open > 0 { + parts.push(format!("{} open", open)); + } + if !q.target.is_empty() { + parts.push(format!("due {}", q.target)); + } + if !q.lead.is_empty() { + parts.push(q.lead.clone()); + } + parts + }) + .collect(); + let widest = |xs: &mut dyn Iterator<Item = usize>| xs.max().unwrap_or(0); + let name_w = widest(&mut projects.iter().map(|q| q.name.chars().count())).max(8); + let label_w = widest(&mut projects.iter().map(|q| q.label.chars().count())).max(4); + let full = widest(&mut asides.iter().map(|a| joined(a).chars().count())); + // Everything on the row except the bar and the aside, the two that give. + let head = 2 + name_w + 2 + label_w + 2 + 5 + 2; + let bar_w = (w - 1).saturating_sub(head + full).clamp(6, 40); + let room = (w - 1).saturating_sub(head + bar_w); + for (q, parts) in projects.iter().zip(&asides) { + let colour = match q.kind.as_str() { + "started" => p.warn.as_str(), + "completed" => p.ok.as_str(), + "canceled" => p.dim.as_str(), + _ => p.txt.as_str(), + }; + // Drop whole facts off the end rather than let the pane cut one in + // half: "due 2024-07-26 · William L" names nobody. + let mut keep = parts.len(); + while keep > 0 && joined(&parts[..keep]).chars().count() > room { + keep -= 1; + } + rows.push(tc::seg( + &[ + (p.txt.as_str(), format!(" {}", tc::pad(&q.name, name_w))), + (colour, format!(" {}", tc::pad(&q.label, label_w))), + (colour, format!(" {}", tc::meter(q.progress, bar_w))), + (p.txt.as_str(), format!(" {:>3.0}%", 100.0 * q.progress)), + (p.dim.as_str(), format!(" {}", joined(&parts[..keep]))), + ], + w - 1, + )); + } + rows +} + /// How much a cycle has moved lately, for ranking. /// /// The burndown arrays already say where the action is: day-over-day @@ -662,6 +1126,9 @@ fn main() { // judged against the length it had a moment ago - which is the length // the reader is looking at. let mut pane_len = [0usize, 0usize]; + // Which pane's selection is open on a screen of its own, and how far + // down it is scrolled. + let (mut detail, mut dscroll): (Option<usize>, usize) = (None, 0); let mut tick = 0usize; let mut settle_t = 0usize; let mut settle_from: Option<(Vec<f64>, Vec<f64>)> = None; @@ -700,11 +1167,36 @@ fn main() { // the arrows moving an index nothing is drawn from, which // is a key that does nothing and says nothing. "tab" => focus = tc::next_section(focus, &pane_len), + // Enter opens whichever pane has the cursor. Without a + // focused pane there is nothing selected to open, which is + // the same rule the board's own cursor follows. + "right" | "enter" => { + if focus.is_some() { + detail = focus; + dscroll = 0; + } + } + "left" | "esc" if detail.is_some() => detail = None, // Walking off either end of a pane leaves it. There is no // screen scroll here to hand the arrows to - both panes // window themselves to fit - so from nothing focused they // step back in at the near end, the same ring latency and // link use. + "up" | "down" if detail.is_some() => { + if key == "down" { + dscroll = dscroll.saturating_add(1); + } else { + dscroll = dscroll.saturating_sub(1); + } + } + "pgup" if detail.is_some() => { + let page = tc::size().1.saturating_sub(3).max(1); + dscroll = dscroll.saturating_sub(page); + } + "pgdn" if detail.is_some() => { + let page = tc::size().1.saturating_sub(3).max(1); + dscroll = dscroll.saturating_add(page); + } "up" | "down" => { let down = key == "down"; focus = match focus { @@ -1247,7 +1739,57 @@ fn main() { line.iter().map(|(c, t)| (c.as_str(), t.clone())).collect(); rows.push(tc::seg(&refs, w - 1)); } - drop(s); + // One cycle, or one team, on a screen of its own. + if let Some(which) = detail { + let body = if which == cycles_pane { + ranked_cycles + .get(sel[cycles_pane].min(ranked_cycles.len().saturating_sub(1))) + .map(|c| cycle_detail(c, w, h, &p)) + .unwrap_or_default() + } else { + ranked + .get(sel[teams_pane].min(ranked.len().saturating_sub(1))) + .map(|(key, name)| { + let empty = HashMap::new(); + let counts = s.by_team.get(key).unwrap_or(&empty); + let opens = s.proj_open.get(key).unwrap_or(&empty); + let none: Vec<Proj> = Vec::new(); + let projects = s.projects.get(key).unwrap_or(&none); + team_detail(key, name, counts, projects, opens, s.window, w, h, &p) + }) + .unwrap_or_default() + }; + drop(s); + if body.is_empty() { + detail = None; + } else { + let hints: Vec<Vec<(&str, String)>> = vec![ + vec![(p.accent.as_str(), "↑↓".into()), (p.dim.as_str(), " scroll".into())], + vec![ + (p.accent.as_str(), "←".into()), + (p.dim.as_str(), "/esc back".into()), + ], + vec![(p.dim.as_str(), "[q]uit".into())], + ]; + let foot: Vec<String> = tc::pack_hints(&hints, w - 2, " ") + .into_iter() + .map(|l| format!(" {}", l)) + .collect(); + let room = h.saturating_sub(foot.len()).max(1); + dscroll = dscroll.min(body.len().saturating_sub(room)); + let last = (dscroll + room).min(body.len()); + let mut out: Vec<String> = body[dscroll..last].to_vec(); + while out.len() < room { + out.push(String::new()); + } + out.extend(foot); + tc::draw(&out, w, h); + std::thread::sleep(Duration::from_millis(300)); + continue; + } + } else { + drop(s); + } let hints: Vec<Vec<(&str, String)>> = vec![ // Not "scroll": nothing on this board scrolls. The arrows move @@ -1283,6 +1825,153 @@ fn main() { mod tests { use super::*; + fn a_project(id: &str, name: &str, label: &str, kind: &str, progress: f64) -> Proj { + Proj { + id: id.into(), + name: name.into(), + label: label.into(), + kind: kind.into(), + progress, + ..Default::default() + } + } + + /// The plain text of a rendered row, with the colour escapes taken out. + fn plain(rows: &[String]) -> String { + let joined = rows.join("\n"); + let mut out = String::new(); + let mut chars = joined.chars(); + while let Some(c) = chars.next() { + if c == '\u{1b}' { + for c in chars.by_ref() { + if c == 'm' { + break; + } + } + } else { + out.push(c); + } + } + out + } + + #[test] + fn a_team_screen_lists_its_projects_with_their_own_progress() { + let counts: HashMap<String, usize> = + [("open".to_string(), 9usize), ("started".to_string(), 4)].into_iter().collect(); + let projects = vec![ + a_project("p1", "hallway-lights", "In Progress", "started", 0.5), + a_project("p2", "old-thing", "Done", "completed", 1.0), + ]; + let opens: HashMap<String, usize> = [("p1".to_string(), 4usize)].into_iter().collect(); + let out = plain(&team_detail("ABC", "A Team", &counts, &projects, &opens, 14, 100, 40, &palette())); + assert!(out.contains("PROJECTS"), "{}", out); + assert!(out.contains("hallway-lights"), "{}", out); + assert!(out.contains("4 open"), "{}", out); + // Linear's own figure, not one derived from the open issues: this + // project has four of nine open and is still shown at 50%. + assert!(out.contains(" 50%"), "{}", out); + // A finished project keeps its place and says so, rather than + // showing a full bar with no explanation. + assert!(out.contains("Done"), "{}", out); + assert!(out.contains("100%"), "{}", out); + } + + #[test] + fn open_issues_in_no_project_are_counted_out_loud() { + // Nine open, four in a project: the other five are in none, and + // without saying so the column below does not reconcile with the + // team's own open count three lines above it. + let counts: HashMap<String, usize> = [("open".to_string(), 9usize)].into_iter().collect(); + let projects = vec![a_project("p1", "hallway-lights", "In Progress", "started", 0.5)]; + let opens: HashMap<String, usize> = + [("p1".to_string(), 4usize), (String::new(), 5)].into_iter().collect(); + let out = plain(&team_detail("ABC", "A Team", &counts, &projects, &opens, 14, 100, 40, &palette())); + assert!(out.contains("5 open in no project"), "{}", out); + + // With none loose, the aside is not there to be read past. + let opens: HashMap<String, usize> = [("p1".to_string(), 4usize)].into_iter().collect(); + let out = plain(&team_detail("ABC", "A Team", &counts, &projects, &opens, 14, 100, 40, &palette())); + assert!(!out.contains("in no project"), "{}", out); + } + + #[test] + fn a_long_project_name_is_shown_whole_and_the_bar_gives_way() { + // The first cut of this capped the name column at 34 characters, + // and a real project came out as "GCP Optimisations and GKE + // Migratio" - which reads as a project that does not exist. + let long = "GCP Optimisations and GKE Migration"; + let counts: HashMap<String, usize> = [("open".to_string(), 2usize)].into_iter().collect(); + let projects = vec![ + a_project("p1", long, "Completed", "completed", 0.87), + a_project("p2", "short", "In Progress", "started", 0.1), + ]; + let out = + plain(&team_detail("ABC", "A Team", &counts, &projects, &HashMap::new(), 14, 130, 40, &palette())); + assert!(out.contains(long), "{}", out); + // And the short one still lines up under it. + let row = out.lines().find(|l| l.contains("short")).unwrap(); + let wide = out.lines().find(|l| l.contains(long)).unwrap(); + assert_eq!( + row.find("In Progress").unwrap(), + wide.find("Completed").unwrap(), + "status column ragged:\n{}\n{}", + wide, + row + ); + } + + #[test] + fn a_narrow_pane_drops_whole_facts_off_the_aside_rather_than_half_of_one() { + let counts: HashMap<String, usize> = [("open".to_string(), 2usize)].into_iter().collect(); + let mut q = a_project("p1", "a-project", "In Progress", "started", 0.5); + q.target = "2024-07-26".into(); + q.lead = "Wilhelmina".into(); + let opens: HashMap<String, usize> = [("p1".to_string(), 2usize)].into_iter().collect(); + let wide = plain(&team_detail("ABC", "A", &counts, &[q.clone()], &opens, 14, 130, 40, &palette())); + let row = wide.lines().find(|l| l.contains("a-project")).unwrap(); + assert!(row.contains("2 open · due 2024-07-26 · Wilhelmina"), "{}", row); + + // Squeezed, the last fact leaves whole. What is left is still true, + // and no half-written name is on screen claiming to be someone. + for w in [58usize, 64, 70, 76, 82] { + let out = plain(&team_detail("ABC", "A", &counts, &[q.clone()], &opens, 14, w, 40, &palette())); + let row = out.lines().find(|l| l.contains("a-project")).unwrap(); + let aside = row.split("50%").nth(1).unwrap().trim(); + assert!( + ["", "2 open", "2 open · due 2024-07-26", "2 open · due 2024-07-26 · Wilhelmina"] + .contains(&aside), + "w={} left a part cut in half: {:?}", + w, + aside + ); + } + } + + #[test] + fn a_team_with_no_projects_says_so_rather_than_showing_an_empty_heading() { + let counts: HashMap<String, usize> = [("open".to_string(), 3usize)].into_iter().collect(); + let out = + plain(&team_detail("ABC", "A Team", &counts, &[], &HashMap::new(), 14, 100, 40, &palette())); + assert!(out.contains("owns no projects"), "{}", out); + } + + #[test] + fn running_projects_sort_above_finished_ones() { + let mut list = vec![ + a_project("p1", "done", "Done", "completed", 1.0), + a_project("p2", "dropped", "Cancelled", "canceled", 0.2), + a_project("p3", "running", "In Progress", "started", 0.3), + a_project("p4", "waiting", "Backlog", "backlog", 0.0), + // A status this build has never heard of belongs with the live + // work, not buried under the finished work. + a_project("p5", "odd", "Shipping", "some_new_type", 0.9), + ]; + list.sort_by(|a, b| rank(&a.kind).cmp(&rank(&b.kind)).then(a.name.cmp(&b.name))); + let order: Vec<&str> = list.iter().map(|q| q.name.as_str()).collect(); + assert_eq!(order, ["running", "odd", "waiting", "done", "dropped"]); + } + #[test] fn a_timestamp_that_is_not_ascii_is_declined_rather_than_fatal() { // A full-width digit puts a character boundary inside byte 19. From 9e9f7d40cc7b4d289040822eae917518beba5eda Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Tue, 25 Aug 2026 16:14:13 +0800 Subject: [PATCH 101/147] linear: open a project from the team that owns it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The team's screen listed its projects and stopped there. Its list now takes a cursor, and `→` or `↵` opens the project under it. `←` or `esc` comes back to the team, not the board: one level at a time. The open project is held by its id, never its index. The list re-sorts on every poll - by status, then progress - so an index would have handed the reader whichever project happened to fall into that slot while they were reading, without the cursor moving. Two sources meet on the screen and neither could answer alone. What is open in it, by state, and the oldest thing still open come from the board's own pass over every open issue. They cost nothing, stay current while the screen is up, and count the project across every team that shares it - the screen is about the project, not about whichever team's list it was opened from. Everything else - the burn-up, the milestones, the members, what it says it is for - is one request made when the screen opens, and again once what it fetched is older than the refresh interval. Fetching that for all forty-odd projects every two minutes would be paying, continuously, for screens nobody has opened. The frame it opens on already has the name, status and progress the list knew, so the screen is never blank; while the request is out it says so, and if it fails it says that instead of reading "loading" for ever. Four things the live data caught that no unit test would have: A finished project read "overdue by 760d". Its target date is in the past and nothing was asking whether the work had since landed. A completed one now shows when it completed and what its target was. Three measures sat next to each other unlabelled - Linear's own weighted progress, the points, the issue count - and 87% above "102 done" of 144 above "31 closed" of 38 reads as one measure got wrong three times. Scope says it is in points. Milestones report progress out of a hundred where a project reports it out of one, so every milestone bar read full. And Linear returns them in no order at all, which as a column of dates reads as noise; they fall due in order now, undated last. `↵` on a screen with nothing deeper fell through to the board's own arm and quietly reset the project cursor behind what was being read. The three screens also spoke two vocabularies for the same four states - the board said "todo" where the team screen said "unstarted". They all go through `state_label` now. Each of the six new tests was watched failing against the defect it covers. One existing test compared byte offsets to check two rows lined up, which the three-byte cursor marker broke; it measures columns now. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- docs/linear.md | 74 +++- rust/widgets/src/bin/linear.rs | 788 +++++++++++++++++++++++++++++++-- 2 files changed, 809 insertions(+), 53 deletions(-) diff --git a/docs/linear.md b/docs/linear.md index eb9e6f1..08ad7c4 100644 --- a/docs/linear.md +++ b/docs/linear.md @@ -139,6 +139,9 @@ Under that, **every project the team owns**: cluster-migration Completed █████████████░░ 87% 2 open · due 2024-07-26 · A Lead ``` +`↑` `↓` move a cursor through that list and the screen scrolls to follow it; +`→` or `↵` opens the project under the cursor. + Running work sorts first and finished work last, with a status this build has never heard of sorting *with* the live work rather than under the dead work — a workspace names its own statuses, and burying an unfamiliar one would hide @@ -160,6 +163,67 @@ project's name is a name for something else. The bar takes whatever is left, and when the pane is too narrow the aside sheds whole facts off the end rather than let one be cut in half. +## One project + +`→` or `↵` on a project opens it. `←` or `esc` comes back to the team it was +opened from, not to the board — one level at a time. + +``` +╺━ CLUSTER MIGRATION · OPS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╸ + progress 87% █████████████████████░░░ + status Completed + scope in points 144 102 done, 42 left + issues 38 31 closed + scope added +3 since it started + started 2024-06-25 + completed 2026-05-10 + target was 2024-07-26 + lead A Lead + members 1 A Lead + initiative Infrastructure + oldest open 2.2y OPS-37 + + ── OPEN BY STATE ── 2 issues + ████████████████████████████████████████████████████████████████████████████████ + ▇ backlog 1 (50%) ▇ todo 1 (50%) + + ── MILESTONES ── 3 + Workload Migrations ██████████████████████████████ 100% 2024-06-26 + SSL Optimisations ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 0% 2024-06-28 + Cost and Performance Optimisations ████████████████████░░░░░░░░░░ 67% 2024-07-26 + + ── WHAT IT IS FOR ── + Move every workload off the old cluster and onto the managed one, and + retire the old one once nothing is left on it. +``` + +Three measures sit next to each other and none of them is the others: Linear's +own weighted `progress`, the points, and the issue count. **Scope is labelled +in points** for that reason — unlabelled, 87% above `102 done` of 144 above +`31 closed` of 38 reads as one measure got wrong three times. + +`overdue by` appears only while the work is still running. A project that +finished after its target date is not late, and used to read `overdue by 760d` +because nothing was asking whether the work had since landed; a finished one +shows when it completed and what its target *was*. + +Milestones are ordered by target date, undated ones last — Linear returns them +in no order at all. Their `progress` is reported out of a hundred where a +project's is out of one, so it is divided before it reaches a bar; fed straight +in, every milestone read full. + +`── OPEN BY STATE ──` and `oldest open` come from the board's own pass over +every open issue, so they cost nothing and stay current while the screen is up. +They count the project across *every* team that shares it, because the screen is +about the project rather than about whichever team's list it was opened from. + +Everything else — the burn-up, the milestones, the members, the description — is +one request made when the screen opens, and again when what it fetched is older +than the refresh interval. Fetching that for every project in the workspace +every two minutes would be paying, continuously, for screens nobody has opened. +While the request is out the screen says so; if it fails it says that instead, +rather than reading "loading" for ever. + ## Cost Linear allows **2,500 requests/hour** and 3,000,000 complexity points; a single @@ -168,7 +232,8 @@ multiplied by the page size, so the request count is the limit that binds and the field count barely matters. A full pass over a workspace of 14 teams and ~1,200 open issues costs about -**11 requests and 4 seconds** — one of them the whole workspace's projects, +**11 requests and 4 seconds** — one of them the whole workspace's projects, plus +one more each time a project's own screen is opened, fetched with everything else so a team's screen opens on data already in hand rather than showing nothing while a request goes out, so the default 120s refresh uses roughly 300 requests an hour — an eighth of the budget. Remaining quota is read from @@ -201,9 +266,10 @@ are stepped over in every direction. |---|---| | `tab` | focus the next pane, and from the last one back to no focus | | `↑` `↓` | move the cursor, crossing between panes at their ends — or step into one when none is focused | -| `↵` `→` | open the highlighted cycle or team on a screen of its own | -| `←` `esc` | back to the board | -| `↑` `↓` `PgUp` `PgDn` | scroll a detail screen | +| `↵` `→` | open the highlighted cycle or team — and from a team, the project under its cursor | +| `←` `esc` | back one level: a project to its team, a team to the board | +| `↑` `↓` `PgUp` `PgDn` | move the cursor through a team's projects, or scroll any other detail screen | +| `r` | refresh, including the open project's own record | | `w` | cycle the window — 7 / 14 / 30 / 60 / 90 days | | `r` | refresh now | | `q` | quit | diff --git a/rust/widgets/src/bin/linear.rs b/rust/widgets/src/bin/linear.rs index a32293b..ca9f1f5 100644 --- a/rust/widgets/src/bin/linear.rs +++ b/rust/widgets/src/bin/linear.rs @@ -21,7 +21,7 @@ //! screen actually shows are asked for, because complexity is charged per //! property and the page count is what costs. -use std::collections::HashMap; +use std::collections::{HashMap, HashSet}; use std::sync::{Arc, Condvar, Mutex}; use std::time::{Duration, SystemTime, UNIX_EPOCH}; @@ -208,6 +208,25 @@ query($after: String) { } }"#; +/// One project in full, asked for only when its screen is opened. +/// +/// The board's own pass carries what a list needs - name, status, progress, +/// a target date. The rest is here: the burn-up, the milestones, who is on +/// it, what it says it is for. Fetching that for every project in the +/// workspace every two minutes would be paying, continuously, for screens +/// nobody has opened. +const PROJECT_QUERY: &str = r#" +query($id: String!) { + project(id: $id) { + id name url description startedAt completedAt + scopeHistory completedScopeHistory + issueCountHistory completedIssueCountHistory + members(first: 20) { nodes { name } } + projectMilestones(first: 25) { nodes { name targetDate progress } } + initiatives(first: 5) { nodes { name } } + } +}"#; + const TEAMS_QUERY: &str = r#" { teams(first: 100) { nodes { key name } pageInfo { hasNextPage } } }"#; @@ -305,6 +324,51 @@ struct Proj { lead: String, } +/// One project's own record, fetched when its screen opens. +/// +/// The error is kept in the same place the answer would be. A fetch that +/// fails silently leaves a screen saying "loading" for ever, which is this +/// widget's oldest lesson written a different way. +fn fetch_project(id: &str, tok: &str, quota: &Arc<Mutex<Quota>>) -> serde_json::Value { + let vars = serde_json::json!({ "id": id }); + match graphql(PROJECT_QUERY, tok, vars, quota) { + Ok(v) => v["project"].clone(), + Err(said) => serde_json::json!({ "_error": said }), + } +} + +/// Break text to a width without breaking a word, and without dropping one. +fn wrap(t: &str, width: usize) -> Vec<String> { + if width == 0 { + return Vec::new(); + } + let mut out: Vec<String> = Vec::new(); + let mut line = String::new(); + for word in t.split_whitespace() { + let n = word.chars().count(); + if line.is_empty() { + line = word.to_string(); + } else if line.chars().count() + 1 + n <= width { + line.push(' '); + line.push_str(word); + } else { + out.push(std::mem::take(&mut line)); + line = word.to_string(); + } + // A word longer than the line has to break somewhere; it breaks at + // the width rather than being thrown away. + while line.chars().count() > width { + let head: String = line.chars().take(width).collect(); + line = line.chars().skip(width).collect(); + out.push(head); + } + } + if !line.is_empty() { + out.push(line); + } + out +} + /// A project's aside, as one string. Measured and drawn through the same /// call so the separator cannot be counted one way and printed another. fn joined(parts: &[String]) -> String { @@ -342,6 +406,12 @@ struct State { /// it. The empty id is the bucket for issues in no project at all, which /// is why the per-project figures do not sum to the team's open count. proj_open: HashMap<String, HashMap<String, usize>>, + /// Project id to its open issues by state, across every team that shares + /// it - a project's own screen is about the project, not about whichever + /// team's screen it was opened from. + proj_state: HashMap<String, HashMap<String, usize>>, + /// Project id to the oldest thing still open in it. + proj_oldest: HashMap<String, (f64, String)>, cycles: Vec<serde_json::Value>, created: HashMap<String, usize>, completed: HashMap<String, usize>, @@ -406,6 +476,8 @@ fn one_pass( let mut states: HashMap<String, usize> = HashMap::new(); let mut by_team: HashMap<String, HashMap<String, usize>> = HashMap::new(); let mut proj_open: HashMap<String, HashMap<String, usize>> = HashMap::new(); + let mut proj_state: HashMap<String, HashMap<String, usize>> = HashMap::new(); + let mut proj_oldest: HashMap<String, (f64, String)> = HashMap::new(); let at = Utc::now().naive_utc(); let (mut oldest_open, mut oldest_wip): (Extreme, Extreme) = (None, None); for it in &rows { @@ -420,11 +492,27 @@ fn one_pass( *states.entry(st.clone()).or_insert(0) += 1; // The empty string when the issue is in no project, which is a // real and common answer here, not a missing one. + let in_project = text(&it["project"], "id"); *proj_open .entry(key.clone()) .or_default() - .entry(text(&it["project"], "id")) + .entry(in_project.clone()) .or_insert(0) += 1; + // A project's own screen wants these broken out, and every one of + // them is already in this row: no second request buys them. + if !in_project.is_empty() { + *proj_state + .entry(in_project.clone()) + .or_default() + .entry(st.clone()) + .or_insert(0) += 1; + if let Some(age) = hours_since(parse(&text(it, "createdAt")), Some(at)) { + let seat = proj_oldest.entry(in_project).or_insert((0.0, String::new())); + if age > seat.0 { + *seat = (age, text(it, "identifier")); + } + } + } let slot = by_team.entry(key).or_default(); *slot.entry(st.clone()).or_insert(0) += 1; *slot.entry("open".into()).or_insert(0) += 1; @@ -535,6 +623,8 @@ fn one_pass( guard.by_team = by_team; guard.projects = projects; guard.proj_open = proj_open; + guard.proj_state = proj_state; + guard.proj_oldest = proj_oldest; guard.cycles = cycles; guard.created = created; guard.completed = completed; @@ -782,11 +872,12 @@ fn team_detail( counts: &HashMap<String, usize>, projects: &[Proj], opens: &HashMap<String, usize>, + pick: usize, window: i64, w: usize, h: usize, p: &Palette, -) -> Vec<String> { +) -> (Vec<String>, Option<usize>) { let mut rows = vec![tc::title(&format!("{} · {}", key, name), w, &p.accent)]; let label_w = 18usize; let get = |k: &str| counts.get(k).copied().unwrap_or(0); @@ -827,10 +918,10 @@ fn team_detail( if open > 0 && h.saturating_sub(rows.len()) >= 4 { let legend: Vec<(&str, usize, &str)> = [ - ("triage", triage, p.bad.as_str()), - ("backlog", get("backlog"), p.dim.as_str()), - ("unstarted", get("unstarted"), p.txt.as_str()), - ("in progress", get("started"), p.warn.as_str()), + (state_label("triage"), triage, p.bad.as_str()), + (state_label("backlog"), get("backlog"), p.dim.as_str()), + (state_label("unstarted"), get("unstarted"), p.txt.as_str()), + (state_label("started"), get("started"), p.warn.as_str()), ] .into_iter() .filter(|x| x.1 > 0) @@ -893,7 +984,7 @@ fn team_detail( &[(p.dim.as_str(), " this team owns no projects".into())], w - 1, )); - return rows; + return (rows, None); } // Every aside first, because the columns are sized to what is in them: @@ -927,10 +1018,14 @@ fn team_detail( let label_w = widest(&mut projects.iter().map(|q| q.label.chars().count())).max(4); let full = widest(&mut asides.iter().map(|a| joined(a).chars().count())); // Everything on the row except the bar and the aside, the two that give. + // The marker sits in the left margin the same way the board's own two + // panes carry it, so the two-space indent is what it displaces. let head = 2 + name_w + 2 + label_w + 2 + 5 + 2; let bar_w = (w - 1).saturating_sub(head + full).clamp(6, 40); let room = (w - 1).saturating_sub(head + bar_w); - for (q, parts) in projects.iter().zip(&asides) { + let pick = pick.min(projects.len() - 1); + let mut cursor = None; + for (i, (q, parts)) in projects.iter().zip(&asides).enumerate() { let colour = match q.kind.as_str() { "started" => p.warn.as_str(), "completed" => p.ok.as_str(), @@ -943,9 +1038,16 @@ fn team_detail( while keep > 0 && joined(&parts[..keep]).chars().count() > room { keep -= 1; } + let here = i == pick; + if here { + cursor = Some(rows.len()); + } rows.push(tc::seg( &[ - (p.txt.as_str(), format!(" {}", tc::pad(&q.name, name_w))), + ( + if here { p.accent.as_str() } else { p.txt.as_str() }, + format!("{} {}", if here { "▸" } else { " " }, tc::pad(&q.name, name_w)), + ), (colour, format!(" {}", tc::pad(&q.label, label_w))), (colour, format!(" {}", tc::meter(q.progress, bar_w))), (p.txt.as_str(), format!(" {:>3.0}%", 100.0 * q.progress)), @@ -954,6 +1056,289 @@ fn team_detail( w - 1, )); } + (rows, cursor) +} + +/// One project in full. +/// +/// Two sources meet here and neither could answer alone. `held` is the +/// project's own record, fetched when this screen opened: its burn-up, its +/// milestones, who is on it. `states` and `oldest` come from the board's +/// own pass over every open issue, which is why they cost nothing and stay +/// current while the screen is up. +/// +/// `q` carries what the list already knew, so the screen has a name, a +/// status and a progress figure on the frame it opens - not one request +/// later. +#[allow(clippy::too_many_arguments)] +fn project_detail( + q: &Proj, + team: &str, + held: Option<&serde_json::Value>, + states: &HashMap<String, usize>, + oldest: Option<&(f64, String)>, + w: usize, + p: &Palette, +) -> Vec<String> { + let title = if team.is_empty() { + q.name.clone() + } else { + format!("{} · {}", q.name, team) + }; + let mut rows = vec![tc::title(&title, w, &p.accent)]; + let label_w = 18usize; + let mut field = |name: &str, value: String, aside: String, colour: &str| { + rows.push(tc::seg( + &[ + (p.dim.as_str(), format!(" {}", tc::pad(name, label_w))), + (colour, format!("{:>7}", value)), + (p.dim.as_str(), format!(" {}", aside)), + ], + w - 1, + )); + }; + + // Linear's own progress, the same figure the team's list shows. Derived + // here it would disagree with the line the reader just came from. + field( + "progress", + format!("{:.0}%", 100.0 * q.progress), + tc::meter(q.progress, w.saturating_sub(label_w + 22).clamp(6, 24)), + if q.progress >= 0.8 { p.ok.as_str() } else { p.txt.as_str() }, + ); + field( + "status", + String::new(), + q.label.clone(), + p.txt.as_str(), + ); + + let series = |v: &serde_json::Value, key: &str| -> Vec<f64> { + v[key].as_array().into_iter().flatten().filter_map(|x| x.as_f64()).collect() + }; + let at = |v: &[f64]| v.last().copied().unwrap_or(0.0); + if let Some(v) = held.filter(|v| v["_error"].is_null() && !v.is_null()) { + let scope = series(v, "scopeHistory"); + let done = series(v, "completedScopeHistory"); + let issues = series(v, "issueCountHistory"); + let issues_done = series(v, "completedIssueCountHistory"); + if at(&scope) > 0.0 { + // Named in points because the percentage above is Linear's + // own weighting and agrees with neither this nor the issue + // count. Three different measures unlabelled read as one + // measure got wrong three times. + field( + "scope in points", + format!("{:.0}", at(&scope)), + format!("{:.0} done, {:.0} left", at(&done), (at(&scope) - at(&done)).max(0.0)), + p.txt.as_str(), + ); + } + if at(&issues) > 0.0 { + field( + "issues", + format!("{:.0}", at(&issues)), + format!("{:.0} closed", at(&issues_done)), + p.dim.as_str(), + ); + } + // Scope that arrived after the project opened - the number people + // mean when they say a project "grew". + let added = at(&scope) - scope.first().copied().unwrap_or(0.0); + if added.abs() > 0.05 { + field( + "scope added", + format!("{:+.0}", added), + "since it started".into(), + if added > 0.0 { p.warn.as_str() } else { p.ok.as_str() }, + ); + } + } + + let record = held.unwrap_or(&serde_json::Value::Null); + let started = day(&text(record, "startedAt")); + if !started.is_empty() { + field("started", String::new(), started, p.dim.as_str()); + } + let finished = day(&text(record, "completedAt")); + if !finished.is_empty() { + field("completed", String::new(), finished.clone(), p.ok.as_str()); + } + // A finished project is not late. It was shown as "overdue by 760d" + // because the target date is still in the past and nothing was asking + // whether the work had since landed. + let done_with = !finished.is_empty() || q.kind == "completed" || q.kind == "canceled"; + if !q.target.is_empty() && done_with { + field("target was", String::new(), q.target.clone(), p.dim.as_str()); + } else if !q.target.is_empty() { + // Whether the date is still ahead, said in days rather than left to + // the reader to work out from today's. + let left = parse(&format!("{}T00:00:00", q.target)) + .and_then(|d| hours_since(Some(Utc::now().naive_utc()), Some(d))) + .map(|h| (h / 24.0).ceil() as i64); + // The label carries the direction so the value stays short enough + // for the column, the way the cycle screen's "ends in" does. + let (label, word, colour) = match left { + Some(d) if d < 0 => ("overdue by", format!("{}d", -d), p.bad.as_str()), + Some(d) => ("target in", format!("{}d", d), p.txt.as_str()), + None => ("target", String::new(), p.dim.as_str()), + }; + field(label, word, q.target.clone(), colour); + } + if !q.lead.is_empty() { + field("lead", String::new(), q.lead.clone(), p.txt.as_str()); + } + if let Some(v) = held.filter(|v| v["_error"].is_null() && !v.is_null()) { + let names: Vec<String> = v["members"]["nodes"] + .as_array() + .into_iter() + .flatten() + .map(|m| text(m, "name")) + .filter(|n| !n.is_empty()) + .collect(); + if !names.is_empty() { + field( + "members", + names.len().to_string(), + names.join(", "), + p.dim.as_str(), + ); + } + let inits: Vec<String> = v["initiatives"]["nodes"] + .as_array() + .into_iter() + .flatten() + .map(|i| text(i, "name")) + .filter(|n| !n.is_empty()) + .collect(); + if !inits.is_empty() { + field("initiative", String::new(), inits.join(" · "), p.dim.as_str()); + } + } + if let Some((age, ident)) = oldest { + field("oldest open", dur(Some(*age)), ident.clone(), p.warn.as_str()); + } + + // What is open in it, by state, across every team that shares it. + let open: usize = states.values().sum(); + if open > 0 { + let legend: Vec<(&str, usize, &str)> = STATE_ORDER + .iter() + .map(|st| (state_label(st), states.get(*st).copied().unwrap_or(0), state_colour(st, p))) + .filter(|x| x.1 > 0) + .collect(); + rows.push(String::new()); + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── OPEN BY STATE ── ".into()), + (p.dim.as_str(), format!("{} issues", open)), + ], + w - 1, + )); + let parts: Vec<(f64, String)> = legend + .iter() + .map(|(_, n, c)| (*n as f64 / open as f64, c.to_string())) + .collect(); + let bar = tc::stacked_bar(&parts, w.saturating_sub(3).max(10)); + let mut line: Vec<(&str, String)> = vec![(tc::RST, " ".into())]; + for (colour, txt) in &bar { + line.push((colour.as_str(), txt.clone())); + } + rows.push(tc::seg(&line, w - 1)); + let mut legend_row: Vec<(&str, String)> = vec![(tc::RST, " ".into())]; + for (label, count, colour) in &legend { + legend_row.push((colour, "▇ ".into())); + legend_row.push((p.txt.as_str(), (*label).into())); + legend_row.push(( + p.dim.as_str(), + format!(" {} ({:.0}%) ", count, 100.0 * *count as f64 / open as f64), + )); + } + rows.push(tc::seg(&legend_row, w - 1)); + } + + match held { + None => { + rows.push(String::new()); + rows.push(tc::seg(&[(p.dim.as_str(), " asking Linear for the rest...".into())], w - 1)); + return rows; + } + Some(v) if !v["_error"].is_null() => { + rows.push(String::new()); + rows.push(tc::seg( + &[ + (p.bad.as_str(), " could not read the project: ".into()), + (p.dim.as_str(), text(v, "_error")), + ], + w - 1, + )); + return rows; + } + Some(v) if v.is_null() => { + rows.push(String::new()); + rows.push(tc::seg(&[(p.bad.as_str(), " Linear returned no such project".into())], w - 1)); + return rows; + } + _ => {} + } + let v = held.unwrap_or(&serde_json::Value::Null); + + // Milestones, in the order they fall due. Linear returns them in no + // order at all, and a list of dates out of order reads as noise. + let mut stones: Vec<(String, String, f64)> = v["projectMilestones"]["nodes"] + .as_array() + .into_iter() + .flatten() + .map(|m| { + ( + text(m, "name"), + text(m, "targetDate"), + // Milestones report progress out of a hundred where the + // project reports it out of one. Fed straight to a meter + // every one of them would read full. + m["progress"].as_f64().unwrap_or(0.0) / 100.0, + ) + }) + .collect(); + // Undated last: they have no place in a sequence of dates. + stones.sort_by(|a, b| { + a.1.is_empty().cmp(&b.1.is_empty()).then(a.1.cmp(&b.1)).then(a.0.cmp(&b.0)) + }); + if !stones.is_empty() { + rows.push(String::new()); + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── MILESTONES ── ".into()), + (p.dim.as_str(), format!("{}", stones.len())), + ], + w - 1, + )); + let name_w = stones.iter().map(|(n, _, _)| n.chars().count()).max().unwrap_or(8).max(8); + let bar_w = (w - 1).saturating_sub(2 + name_w + 2 + 5 + 2 + 10).clamp(6, 30); + for (name, date, frac) in &stones { + let colour = if *frac >= 1.0 { p.ok.as_str() } else { p.txt.as_str() }; + rows.push(tc::seg( + &[ + (p.txt.as_str(), format!(" {}", tc::pad(name, name_w))), + (colour, format!(" {}", tc::meter(*frac, bar_w))), + (p.txt.as_str(), format!(" {:>3.0}%", 100.0 * frac)), + (p.dim.as_str(), format!(" {}", date)), + ], + w - 1, + )); + } + } + + let about = text(v, "description"); + if !about.trim().is_empty() { + rows.push(String::new()); + rows.push(tc::seg(&[(p.lbl.as_str(), " ── WHAT IT IS FOR ── ".into())], w - 1)); + // Wrapped whole, never cut: this screen scrolls, so there is no + // width to buy by dropping the end of a sentence. + for line in wrap(&about, w.saturating_sub(4)) { + rows.push(tc::seg(&[(p.txt.as_str(), format!(" {}", line))], w - 1)); + } + } rows } @@ -1061,6 +1446,9 @@ fn main() { let wake = Arc::new((Mutex::new(false), Condvar::new())); let (tok, source) = token(&cfg); + // The poller takes ownership of the key; the project screen fetches on + // its own thread and needs one too. + let ui_token = tok.clone(); let env_name = { let name = tc::cfg_str(&cfg, "token_env", "LINEAR_API_KEY"); if name.is_empty() { "LINEAR_API_KEY".to_string() } else { name } @@ -1129,6 +1517,26 @@ fn main() { // Which pane's selection is open on a screen of its own, and how far // down it is scrolled. let (mut detail, mut dscroll): (Option<usize>, usize) = (None, 0); + // Which project is under the cursor on a team's screen, and which one + // is open a level deeper. + // + // The deeper one is held by id, not by index: the list re-sorts on + // every poll - by status, then progress - so a refresh while the screen + // is up would otherwise swap out the project being read without + // touching the cursor. + let mut pick = 0usize; + let mut deep: Option<String> = None; + let mut pscroll = 0usize; + let held: Arc<Mutex<HashMap<String, (serde_json::Value, f64)>>> = + Arc::new(Mutex::new(HashMap::new())); + let asking: Arc<Mutex<HashSet<String>>> = Arc::new(Mutex::new(HashSet::new())); + let ui_tok = ui_token.clone(); + let ui_quota = Arc::clone("a); + // How many projects the team's screen held when it was last drawn, and + // which one the cursor was on - read by the keys, which run before the + // frame that answers them is built. + let mut projects_len = 0usize; + let mut open_project: Option<String> = None; let mut tick = 0usize; let mut settle_t = 0usize; let mut settle_from: Option<(Vec<f64>, Vec<f64>)> = None; @@ -1143,6 +1551,9 @@ fn main() { return; } "r" | "R" => { + if let Ok(mut g) = held.lock() { + g.clear(); + } let (lock, cond) = &*wake; if let Ok(mut asked) = lock.lock() { *asked = true; @@ -1170,35 +1581,71 @@ fn main() { // Enter opens whichever pane has the cursor. Without a // focused pane there is nothing selected to open, which is // the same rule the board's own cursor follows. + // A team's screen opens one of its projects; the board + // opens whichever pane has the cursor. Without a focused + // pane there is nothing selected to open, which is the + // same rule the board's own cursor follows. + "right" | "enter" if detail == Some(teams_pane) && deep.is_none() => { + if let Some(id) = open_project.clone() { + deep = Some(id); + pscroll = 0; + } + } + "right" | "enter" if detail.is_some() => {} "right" | "enter" => { if focus.is_some() { detail = focus; dscroll = 0; + pick = 0; } } + // Back one level at a time: out of a project to the team + // that owns it, and only then to the board. + "left" | "esc" if deep.is_some() => deep = None, "left" | "esc" if detail.is_some() => detail = None, + // A team's screen hands the arrows to its project list and + // scrolls itself to follow; every other screen has nothing + // to select, so they scroll outright. + "up" | "down" if detail == Some(teams_pane) && deep.is_none() => { + if key == "down" { + pick = pick.saturating_add(1).min(projects_len.saturating_sub(1)); + } else { + pick = pick.saturating_sub(1); + } + } + "pgup" | "pgdn" if detail == Some(teams_pane) && deep.is_none() => { + let page = tc::size().1.saturating_sub(3).max(1); + pick = if key == "pgdn" { + pick.saturating_add(page).min(projects_len.saturating_sub(1)) + } else { + pick.saturating_sub(page) + }; + } // Walking off either end of a pane leaves it. There is no // screen scroll here to hand the arrows to - both panes // window themselves to fit - so from nothing focused they // step back in at the near end, the same ring latency and // link use. "up" | "down" if detail.is_some() => { + let at = if deep.is_some() { &mut pscroll } else { &mut dscroll }; if key == "down" { - dscroll = dscroll.saturating_add(1); + *at = at.saturating_add(1); } else { - dscroll = dscroll.saturating_sub(1); + *at = at.saturating_sub(1); } } - "pgup" if detail.is_some() => { + "pgup" | "pgdn" if detail.is_some() => { let page = tc::size().1.saturating_sub(3).max(1); - dscroll = dscroll.saturating_sub(page); - } - "pgdn" if detail.is_some() => { - let page = tc::size().1.saturating_sub(3).max(1); - dscroll = dscroll.saturating_add(page); + let at = if deep.is_some() { &mut pscroll } else { &mut dscroll }; + *at = if key == "pgdn" { + at.saturating_add(page) + } else { + at.saturating_sub(page) + }; } "up" | "down" => { let down = key == "down"; + pick = 0; focus = match focus { Some(here) => tc::step_across_sections(here, sel[here], &pane_len, down) .map(|(pane, row)| { @@ -1739,46 +2186,146 @@ fn main() { line.iter().map(|(c, t)| (c.as_str(), t.clone())).collect(); rows.push(tc::seg(&refs, w - 1)); } - // One cycle, or one team, on a screen of its own. + // One cycle, one team, or one of that team's projects, each on a + // screen of its own. if let Some(which) = detail { - let body = if which == cycles_pane { - ranked_cycles - .get(sel[cycles_pane].min(ranked_cycles.len().saturating_sub(1))) - .map(|c| cycle_detail(c, w, h, &p)) - .unwrap_or_default() + let team = ranked + .get(sel[teams_pane].min(ranked.len().saturating_sub(1))) + .cloned(); + let none: Vec<Proj> = Vec::new(); + let projects: Vec<Proj> = team + .as_ref() + .and_then(|(key, _)| s.projects.get(key)) + .unwrap_or(&none) + .clone(); + if which == teams_pane { + projects_len = projects.len(); + pick = pick.min(projects_len.saturating_sub(1)); + open_project = projects.get(pick).map(|q| q.id.clone()); + } + // The project being read is found by its id, so a poll that + // re-sorts the list underneath cannot swap it for its + // neighbour. + let reading = deep + .as_ref() + .and_then(|id| projects.iter().find(|q| &q.id == id).cloned()); + let (body, cursor) = if let Some(q) = reading.as_ref() { + let empty = HashMap::new(); + let states = s.proj_state.get(&q.id).unwrap_or(&empty); + let oldest = s.proj_oldest.get(&q.id).cloned(); + let record = held.lock().ok().and_then(|g| g.get(&q.id).map(|(v, _)| v.clone())); + ( + project_detail( + q, + team.as_ref().map(|(k, _)| k.as_str()).unwrap_or(""), + record.as_ref(), + states, + oldest.as_ref(), + w, + &p, + ), + None, + ) + } else if which == cycles_pane { + ( + ranked_cycles + .get(sel[cycles_pane].min(ranked_cycles.len().saturating_sub(1))) + .map(|c| cycle_detail(c, w, h, &p)) + .unwrap_or_default(), + None, + ) } else { - ranked - .get(sel[teams_pane].min(ranked.len().saturating_sub(1))) + team.as_ref() .map(|(key, name)| { let empty = HashMap::new(); let counts = s.by_team.get(key).unwrap_or(&empty); let opens = s.proj_open.get(key).unwrap_or(&empty); - let none: Vec<Proj> = Vec::new(); - let projects = s.projects.get(key).unwrap_or(&none); - team_detail(key, name, counts, projects, opens, s.window, w, h, &p) + team_detail(key, name, counts, &projects, opens, pick, s.window, w, h, &p) }) .unwrap_or_default() }; drop(s); + + // Ask for the open project's own record, once, and again once + // it has gone stale - the screen is left up for minutes at a + // time and a burn-up from ten minutes ago is not this one. + if let Some(q) = reading.as_ref() { + let due = held + .lock() + .ok() + .and_then(|g| g.get(&q.id).map(|(_, at)| now() - at > refresh)) + .unwrap_or(true); + let mine = asking.lock().map(|g| !g.contains(&q.id)).unwrap_or(false); + if due && mine && !ui_tok.is_empty() { + if let Ok(mut g) = asking.lock() { + g.insert(q.id.clone()); + } + let (id, tok, quota) = (q.id.clone(), ui_tok.clone(), Arc::clone(&ui_quota)); + let (held, asking) = (Arc::clone(&held), Arc::clone(&asking)); + std::thread::spawn(move || { + let got = fetch_project(&id, &tok, "a); + if let Ok(mut g) = held.lock() { + g.insert(id.clone(), (got, now())); + } + if let Ok(mut g) = asking.lock() { + g.remove(&id); + } + }); + } + } + if body.is_empty() { detail = None; + deep = None; } else { - let hints: Vec<Vec<(&str, String)>> = vec![ - vec![(p.accent.as_str(), "↑↓".into()), (p.dim.as_str(), " scroll".into())], - vec![ - (p.accent.as_str(), "←".into()), - (p.dim.as_str(), "/esc back".into()), - ], - vec![(p.dim.as_str(), "[q]uit".into())], - ]; + let into = if reading.is_some() { + None + } else if which == teams_pane && projects_len > 0 { + Some(" open it") + } else { + None + }; + let mut hints: Vec<Vec<(&str, String)>> = vec![vec![ + (p.accent.as_str(), "↑↓".into()), + ( + p.dim.as_str(), + if into.is_some() { " project" } else { " scroll" }.into(), + ), + ]]; + if let Some(what) = into { + hints.push(vec![ + (p.accent.as_str(), "→/↵".into()), + (p.dim.as_str(), what.to_string()), + ]); + } + hints.push(vec![ + (p.accent.as_str(), "←".into()), + ( + p.dim.as_str(), + if reading.is_some() { "/esc the team".into() } else { "/esc back".to_string() }, + ), + ]); + hints.push(vec![(p.dim.as_str(), "[r]efresh".into())]); + hints.push(vec![(p.dim.as_str(), "[q]uit".into())]); let foot: Vec<String> = tc::pack_hints(&hints, w - 2, " ") .into_iter() .map(|l| format!(" {}", l)) .collect(); let room = h.saturating_sub(foot.len()).max(1); - dscroll = dscroll.min(body.len().saturating_sub(room)); - let last = (dscroll + room).min(body.len()); - let mut out: Vec<String> = body[dscroll..last].to_vec(); + let at = if reading.is_some() { &mut pscroll } else { &mut dscroll }; + // The page follows the cursor into the project list, the + // way netwatch's detail follows one into a section. + if let Some(row) = cursor { + if row < *at { + *at = row; + } else if row >= *at + room { + *at = row + 1 - room; + } + } + *at = (*at).min(body.len().saturating_sub(room)); + let from = *at; + let last = (from + room).min(body.len()); + let mut out: Vec<String> = body[from..last].to_vec(); while out.len() < room { out.push(String::new()); } @@ -1789,6 +2336,9 @@ fn main() { } } else { drop(s); + projects_len = 0; + open_project = None; + deep = None; } let hints: Vec<Vec<(&str, String)>> = vec![ @@ -1836,6 +2386,29 @@ mod tests { } } + /// Which screen column a string starts at. + /// + /// `str::find` answers in bytes, and the cursor marker is three of them + /// for one column - so two rows that line up on screen came back two + /// apart and failed a test about alignment. + fn col(line: &str, needle: &str) -> usize { + let at = line.find(needle).unwrap_or_else(|| panic!("{:?} not in {:?}", needle, line)); + line[..at].chars().count() + } + + /// A team's screen as plain text. `pick` is the project under the + /// cursor, which every test but the cursor's own leaves at the first. + fn team_rows( + counts: &HashMap<String, usize>, + projects: &[Proj], + opens: &HashMap<String, usize>, + w: usize, + ) -> String { + let (rows, _) = + team_detail("ABC", "A Team", counts, projects, opens, 0, 14, w, 40, &palette()); + plain(&rows) + } + /// The plain text of a rendered row, with the colour escapes taken out. fn plain(rows: &[String]) -> String { let joined = rows.join("\n"); @@ -1864,7 +2437,7 @@ mod tests { a_project("p2", "old-thing", "Done", "completed", 1.0), ]; let opens: HashMap<String, usize> = [("p1".to_string(), 4usize)].into_iter().collect(); - let out = plain(&team_detail("ABC", "A Team", &counts, &projects, &opens, 14, 100, 40, &palette())); + let out = team_rows(&counts, &projects, &opens, 100); assert!(out.contains("PROJECTS"), "{}", out); assert!(out.contains("hallway-lights"), "{}", out); assert!(out.contains("4 open"), "{}", out); @@ -1886,12 +2459,12 @@ mod tests { let projects = vec![a_project("p1", "hallway-lights", "In Progress", "started", 0.5)]; let opens: HashMap<String, usize> = [("p1".to_string(), 4usize), (String::new(), 5)].into_iter().collect(); - let out = plain(&team_detail("ABC", "A Team", &counts, &projects, &opens, 14, 100, 40, &palette())); + let out = team_rows(&counts, &projects, &opens, 100); assert!(out.contains("5 open in no project"), "{}", out); // With none loose, the aside is not there to be read past. let opens: HashMap<String, usize> = [("p1".to_string(), 4usize)].into_iter().collect(); - let out = plain(&team_detail("ABC", "A Team", &counts, &projects, &opens, 14, 100, 40, &palette())); + let out = team_rows(&counts, &projects, &opens, 100); assert!(!out.contains("in no project"), "{}", out); } @@ -1907,14 +2480,14 @@ mod tests { a_project("p2", "short", "In Progress", "started", 0.1), ]; let out = - plain(&team_detail("ABC", "A Team", &counts, &projects, &HashMap::new(), 14, 130, 40, &palette())); + team_rows(&counts, &projects, &HashMap::new(), 130); assert!(out.contains(long), "{}", out); // And the short one still lines up under it. let row = out.lines().find(|l| l.contains("short")).unwrap(); let wide = out.lines().find(|l| l.contains(long)).unwrap(); assert_eq!( - row.find("In Progress").unwrap(), - wide.find("Completed").unwrap(), + col(row, "In Progress"), + col(wide, "Completed"), "status column ragged:\n{}\n{}", wide, row @@ -1928,14 +2501,14 @@ mod tests { q.target = "2024-07-26".into(); q.lead = "Wilhelmina".into(); let opens: HashMap<String, usize> = [("p1".to_string(), 2usize)].into_iter().collect(); - let wide = plain(&team_detail("ABC", "A", &counts, &[q.clone()], &opens, 14, 130, 40, &palette())); + let wide = team_rows(&counts, &[q.clone()], &opens, 130); let row = wide.lines().find(|l| l.contains("a-project")).unwrap(); assert!(row.contains("2 open · due 2024-07-26 · Wilhelmina"), "{}", row); // Squeezed, the last fact leaves whole. What is left is still true, // and no half-written name is on screen claiming to be someone. for w in [58usize, 64, 70, 76, 82] { - let out = plain(&team_detail("ABC", "A", &counts, &[q.clone()], &opens, 14, w, 40, &palette())); + let out = team_rows(&counts, &[q.clone()], &opens, w); let row = out.lines().find(|l| l.contains("a-project")).unwrap(); let aside = row.split("50%").nth(1).unwrap().trim(); assert!( @@ -1948,11 +2521,128 @@ mod tests { } } + #[test] + fn the_cursor_marks_one_project_and_says_which_row_it_is_on() { + let counts: HashMap<String, usize> = [("open".to_string(), 3usize)].into_iter().collect(); + let projects = vec![ + a_project("p1", "first", "In Progress", "started", 0.1), + a_project("p2", "second", "In Progress", "started", 0.2), + a_project("p3", "third", "In Progress", "started", 0.3), + ]; + let (rows, at) = + team_detail("ABC", "A", &counts, &projects, &HashMap::new(), 1, 14, 100, 40, &palette()); + let at = at.expect("a project list has a cursor"); + assert!(plain(&[rows[at].clone()]).contains("second"), "{}", plain(&[rows[at].clone()])); + // Exactly one marker, so the reader is never asked which of two is + // the one enter would open. + assert_eq!(plain(&rows).matches('▸').count(), 1); + + // A cursor past the end lands on the last project rather than + // falling off it - the list shortens under the cursor whenever a + // poll lands. + let (rows, at) = + team_detail("ABC", "A", &counts, &projects, &HashMap::new(), 99, 14, 100, 40, &palette()); + assert!(plain(&[rows[at.unwrap()].clone()]).contains("third")); + } + + #[test] + fn a_project_screen_is_found_by_id_so_a_resort_cannot_swap_it() { + // This is the whole reason the open project is held by id. The + // list re-sorts on every poll; holding an index would have left + // the screen showing whichever project fell into that slot. + let mut projects = vec![ + a_project("p1", "first", "In Progress", "started", 0.1), + a_project("p2", "second", "In Progress", "started", 0.2), + ]; + let open = "p2".to_string(); + let before = projects.iter().find(|q| q.id == open).cloned().unwrap(); + projects.reverse(); + let after = projects.iter().find(|q| q.id == open).cloned().unwrap(); + assert_eq!(before.name, after.name); + assert_eq!(after.name, "second"); + // And the index that used to point at it now points elsewhere. + assert_eq!(projects[1].name, "first"); + } + + #[test] + fn a_project_screen_shows_what_it_has_before_the_rest_arrives() { + let q = a_project("p1", "hallway-lights", "In Progress", "started", 0.5); + let states: HashMap<String, usize> = + [("started".to_string(), 2usize), ("triage".to_string(), 1)].into_iter().collect(); + // Nothing fetched yet: the name, status and progress the list + // already knew are on the first frame, and the screen says a + // request is out rather than looking empty. + let out = plain(&project_detail(&q, "ABC", None, &states, None, 100, &palette())); + assert!(out.contains("HALLWAY-LIGHTS · ABC"), "{}", out); + assert!(out.contains(" 50%"), "{}", out); + assert!(out.contains("In Progress"), "{}", out); + assert!(out.contains("OPEN BY STATE"), "{}", out); + assert!(out.contains("asking Linear"), "{}", out); + } + + #[test] + fn a_finished_project_is_not_called_late() { + // It read "overdue by 760d" on a project completed two years ago, + // because nothing was asking whether the work had since landed. + let mut q = a_project("p1", "old-thing", "Completed", "completed", 1.0); + q.target = "2024-07-26".into(); + let record = serde_json::json!({ "completedAt": "2024-08-01T00:00:00.000Z" }); + let out = + plain(&project_detail(&q, "ABC", Some(&record), &HashMap::new(), None, 100, &palette())); + assert!(!out.contains("overdue"), "{}", out); + assert!(out.contains("2024-08-01"), "{}", out); + assert!(out.contains("target was"), "{}", out); + + // Still running and past its date, it is late and says so. + let mut q = a_project("p2", "live-thing", "In Progress", "started", 0.4); + q.target = "2024-07-26".into(); + let out = + plain(&project_detail(&q, "ABC", Some(&serde_json::json!({})), &HashMap::new(), None, 100, &palette())); + assert!(out.contains("overdue by"), "{}", out); + } + + #[test] + fn a_project_fetch_that_failed_says_so_instead_of_asking_for_ever() { + // A screen stuck on "loading" is this widget's oldest lesson: a + // failure nobody records is indistinguishable from a slow answer. + let q = a_project("p1", "hallway-lights", "In Progress", "started", 0.5); + let bad = serde_json::json!({ "_error": "HTTP 502 from Linear" }); + let out = + plain(&project_detail(&q, "ABC", Some(&bad), &HashMap::new(), None, 100, &palette())); + assert!(out.contains("could not read the project"), "{}", out); + assert!(out.contains("HTTP 502"), "{}", out); + assert!(!out.contains("asking Linear"), "{}", out); + } + + #[test] + fn milestones_fall_in_date_order_and_their_bars_are_out_of_a_hundred() { + let q = a_project("p1", "hallway-lights", "In Progress", "started", 0.5); + // Linear reports a milestone's progress out of 100 and a project's + // out of 1. Fed straight to the meter, every milestone read full. + let record = serde_json::json!({ + "projectMilestones": { "nodes": [ + { "name": "later", "targetDate": "2026-09-05", "progress": 0.0 }, + { "name": "undated", "targetDate": null, "progress": 50.0 }, + { "name": "sooner", "targetDate": "2026-09-03", "progress": 67.86 }, + ]}, + }); + let out = + plain(&project_detail(&q, "ABC", Some(&record), &HashMap::new(), None, 100, &palette())); + let rows: Vec<&str> = out.lines().collect(); + let seat = |name: &str| rows.iter().position(|l| l.contains(name)).unwrap(); + assert!(seat("sooner") < seat("later"), "{}", out); + assert!(seat("later") < seat("undated"), "dated milestones come first:\n{}", out); + // 67.86 out of a hundred, not 6786%. + let row = rows[seat("sooner")]; + assert!(row.contains(" 68%"), "{}", row); + assert!(row.contains('░'), "a 68% bar is not full: {}", row); + } + #[test] fn a_team_with_no_projects_says_so_rather_than_showing_an_empty_heading() { let counts: HashMap<String, usize> = [("open".to_string(), 3usize)].into_iter().collect(); let out = - plain(&team_detail("ABC", "A Team", &counts, &[], &HashMap::new(), 14, 100, 40, &palette())); + team_rows(&counts, &[], &HashMap::new(), 100); assert!(out.contains("owns no projects"), "{}", out); } From ee47a66eb6f7c18040e2f71c760f672d0b81be3e Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Tue, 25 Aug 2026 16:49:11 +0800 Subject: [PATCH 102/147] linear: the board scrolls, and carries a project list of its own Two things, and the first is why the second fits. The board never scrolled. Each section windowed itself around its own cursor - "1-6 of 11" - and in a short pane that left one row of teams visible and no way to read past it without focusing a section first. Every section is now drawn whole and the pane is a window onto the board: with nothing focused the arrows and PgUp/PgDn move that window; with a section focused they move its cursor and the window follows, by as little as it takes. The footer says which of the two it is doing. That arithmetic was inline in three places - the board, a team's screen, a project's - so it is one `follow` function now, which a test can break. On the room that buys, a third section: every project still going, whichever team owns it, running work first. One shared between teams shows both keys and appears once. Enter opens it directly, without going through its team, and escape comes back to the board rather than to a team screen that was never opened. The three sections walk as one continuous list under the arrows, the same rule as before with one more section in it. Finished and cancelled projects are not on the board. The heading says how many are not, because "34 running" on its own reads as a count of all of them; they are all still on their team's own screen. The widths were wrong three times and are now a function with a property test rather than arithmetic inline: The longest project name in a real workspace is 47 characters, and at eighty columns the name, the team key and the status do not fit together. The first cut let the row overflow, and what `seg` cut off the end was the percentage - the row's only number. So columns shed from the right instead. What never goes is the marker, the team, the name and the percentage. First to go is the bar, because the percentage beside it says the same thing in five columns; then the status, which the colour and the ordering carry anyway; last the open count, which is the one number on the row the percentage does not say. Shedding has to be ordered, not greedy. Reserving the bar's gap but not the open count's made a row lose its count as the pane got *wider*. Claiming the status before the count made seventy-seven columns show the status and drop the count that seventy-six had shown. Both are a pane that gets wider and says less, and both are now properties the test asserts across every width from 40 to 200. Each of the three new tests was watched failing against the defect it covers, including the two width bugs above - which the test found rather than the other way round. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- docs/linear.md | 66 +++-- rust/widgets/src/bin/linear.rs | 522 +++++++++++++++++++++++++++------ 2 files changed, 478 insertions(+), 110 deletions(-) diff --git a/docs/linear.md b/docs/linear.md index 08ad7c4..f2ff500 100644 --- a/docs/linear.md +++ b/docs/linear.md @@ -110,8 +110,24 @@ down, one bar per day, both directions on a shared scale. Read together they say whether the queue is filling faster than it drains. In the board above, 297 created against 88 completed. -**By team** — ranked by open volume, windowing around the cursor when focused -and there are more teams than rows. `DONE14D` follows the window. +**By team** — ranked by open volume. `DONE14D` follows the window the header +names. + +**Projects** — every project still going, whichever team owns it, running work +first. One shared between teams shows both keys (`OPS/WEB`) and appears once. + +``` + ── PROJECTS ── 34 running · 9 finished, not listed ↑↓ +▸ OPS uptime-monitoring Maintenance █████████████ 100% + WEB checkout-rewrite In Progress █████████░░░░ 72% 110 open + OPS/WEB storage-provider-swap Paused ░░░░░░░░░░░░░ 3% 9 open + CLI offline-mode Idea ░░░░░░░░░░░░░ 0% 25 open +``` + +Finished and cancelled projects are not on the board - the heading says how +many, because "34 running" alone reads as a count of all of them. They are all +still on their team's own screen. `↵` here opens a project directly, without +going through its team. ## One cycle, or one team @@ -139,8 +155,8 @@ Under that, **every project the team owns**: cluster-migration Completed █████████████░░ 87% 2 open · due 2024-07-26 · A Lead ``` -`↑` `↓` move a cursor through that list and the screen scrolls to follow it; -`→` or `↵` opens the project under the cursor. +`↑` `↓` move a cursor through that list and the screen scrolls to follow it, +the same way the board does; `→` or `↵` opens the project under the cursor. Running work sorts first and finished work last, with a status this build has never heard of sorting *with* the live work rather than under the dead work — @@ -246,29 +262,39 @@ reporting a smaller number. ## Keys -The board opens with no cursor anywhere — it is a thing to read before it is a -thing to work. `tab` focuses a pane, and the focused heading says so by -carrying the `↑↓` marker and its visible range; `↑` `↓` then move a cursor -through that pane, which windows itself around it. +The board is longer than most panes are tall, and **every section is drawn +whole** - the pane is a window onto it. So the arrows do one of two things, and +the footer says which. + +The board opens with no cursor anywhere - it is a thing to read before it is a +thing to work - and there the arrows and `PgUp` `PgDn` move the window: the way +to read the whole board without picking a section first. + +`tab` focuses a section, and the focused heading says so by carrying an arrow +marker. The arrows then move a cursor through that section, and the window +follows it - a cursor below the fold pulls the board down, one above it pulls +it up, each by as little as it takes. -Under the arrows the two panes read as **one continuous list**: `↓` off the -bottom of the cycles steps into the top of the teams, and `↑` off the top of -the teams steps into the *bottom* of the cycles. `tab` is the shortcut across -a whole pane rather than the only way between them. +Under the arrows the three sections read as **one continuous list**: down off +the bottom of the cycles steps into the top of the teams, off the bottom of the +teams into the top of the projects; up steps back the same way, into the +*last* row of the section above. `tab` is the shortcut across a whole section +rather than the only way between them. -You let go at exactly two places: `↑` from the first cycle, and `↓` from the -last team. `tab` from the last pane does the same. Panes with nothing in them -are stepped over in every direction. +You let go at exactly two places: up from the first cycle, and down from the +last project. `tab` from the last section does the same, and hands the arrows +back to the board. Sections with nothing in them are stepped over in every +direction. **This is the same rule in every widget here that has focusable sections.** | Key | Action | |---|---| -| `tab` | focus the next pane, and from the last one back to no focus | -| `↑` `↓` | move the cursor, crossing between panes at their ends — or step into one when none is focused | -| `↵` `→` | open the highlighted cycle or team — and from a team, the project under its cursor | -| `←` `esc` | back one level: a project to its team, a team to the board | -| `↑` `↓` `PgUp` `PgDn` | move the cursor through a team's projects, or scroll any other detail screen | +| `tab` | focus the next section, and from the last one back to no focus | +| `↑` `↓` | scroll the board — or, with a section focused, move its cursor, crossing between sections at their ends | +| `PgUp` `PgDn` | the same, a page at a time | +| `↵` `→` | open the highlighted cycle, team or project — and from a team, the project under its cursor | +| `←` `esc` | back one level: a project to wherever it was opened from, a team to the board | | `r` | refresh, including the open project's own record | | `w` | cycle the window — 7 / 14 / 30 / 60 / 90 days | | `r` | refresh now | diff --git a/rust/widgets/src/bin/linear.rs b/rust/widgets/src/bin/linear.rs index ca9f1f5..2297a95 100644 --- a/rust/widgets/src/bin/linear.rs +++ b/rust/widgets/src/bin/linear.rs @@ -322,6 +322,9 @@ struct Proj { progress: f64, target: String, lead: String, + /// Every team that owns it. A project can be shared, and the board's own + /// list is not filed under any one of them. + teams: Vec<String>, } /// One project's own record, fetched when its screen opens. @@ -337,6 +340,55 @@ fn fetch_project(id: &str, tok: &str, quota: &Arc<Mutex<Quota>>) -> serde_json:: } } +/// How much of a project row each optional column gets. +/// +/// `base` is what never goes - the marker, the team key, the name and the +/// percentage. Returns what the status column costs, how wide the bar may +/// be (zero for none), and how many columns are left for the open count. +/// +/// The order things go in as the pane narrows: the bar first, because the +/// percentage beside it says the same thing in five columns; then the +/// status, which the colour and the ordering carry anyway; and last the +/// open count, which is the one number on the row the percentage does not +/// say. Nothing is ever cut through the middle. +/// +/// This is a function because the arithmetic was wrong twice inline: once +/// overflowing the pane and letting `seg` cut the percentage off, and once +/// reserving the bar's gap but not the open count's - which made a row lose +/// its open count as the pane got *wider*. +fn project_columns(w: usize, base: usize, label_w: usize, aside: usize) -> (usize, usize, usize) { + let budget = w.saturating_sub(1); + // Each column is shown only when it and everything above it in the + // order fits, and the ones above it are reserved whether or not they + // are shown. Anything less than that and widening the pane by one + // column can trade one fact for another - at seventy-seven columns the + // status arrived and the open count left, which is a pane that gets + // wider and says less. + let need_aside = if aside > 0 { 2 + aside } else { 0 }; + let need_label = 2 + label_w; + let room = if base + need_aside <= budget { aside } else { 0 }; + let label_cost = if base + need_aside + need_label <= budget { need_label } else { 0 }; + let bar = budget.saturating_sub(base + need_aside + need_label + 2); + let bar = if bar >= 6 { bar.min(30) } else { 0 }; + (label_cost, bar, room) +} + +/// Where a window of `room` rows has to start to keep `row` in view. +/// +/// Every screen here is now drawn whole and shown through a window, and all +/// three of them - the board, a team, a project - move it the same way. It +/// is one function so that a test can break it, which a copy inlined three +/// times could not have. +fn follow(at: usize, row: usize, room: usize) -> usize { + if row < at { + row + } else if row + 1 > at + room { + row + 1 - room + } else { + at + } +} + /// Break text to a width without breaking a word, and without dropping one. fn wrap(t: &str, width: usize) -> Vec<String> { if width == 0 { @@ -402,6 +454,8 @@ struct State { by_team: HashMap<String, HashMap<String, usize>>, /// Team key to that team's projects, ordered as the screen shows them. projects: HashMap<String, Vec<Proj>>, + /// Every project once, in the same order, for the board's own section. + all_projects: Vec<Proj>, /// Team key to project id to how many of that team's open issues sit in /// it. The empty id is the bucket for issues in no project at all, which /// is why the per-project figures do not sum to the team's open count. @@ -551,7 +605,18 @@ fn one_pass( quota, )?; let mut projects: HashMap<String, Vec<Proj>> = HashMap::new(); + let mut all_projects: Vec<Proj> = Vec::new(); for pr in &proj_rows { + let owners: Vec<String> = pr["teams"]["nodes"] + .as_array() + .into_iter() + .flatten() + .map(|t| text(t, "key")) + .filter(|k| keys.contains(k)) + .collect(); + if owners.is_empty() { + continue; + } let made = Proj { id: text(pr, "id"), name: text(pr, "name"), @@ -560,22 +625,23 @@ fn one_pass( progress: pr["progress"].as_f64().unwrap_or(0.0), target: text(pr, "targetDate"), lead: text(&pr["lead"], "name"), + teams: owners.clone(), }; - for t in pr["teams"]["nodes"].as_array().into_iter().flatten() { - let key = text(t, "key"); - if keys.contains(&key) { - projects.entry(key).or_default().push(made.clone()); - } + for key in owners { + projects.entry(key).or_default().push(made.clone()); } + all_projects.push(made); } + let order = |a: &Proj, b: &Proj| { + rank(&a.kind) + .cmp(&rank(&b.kind)) + .then(b.progress.total_cmp(&a.progress)) + .then(a.name.cmp(&b.name)) + }; for list in projects.values_mut() { - list.sort_by(|a, b| { - rank(&a.kind) - .cmp(&rank(&b.kind)) - .then(b.progress.total_cmp(&a.progress)) - .then(a.name.cmp(&b.name)) - }); + list.sort_by(&order); } + all_projects.sort_by(&order); // Arrivals and departures over the window. let vars = serde_json::json!({ "since": since }); @@ -622,6 +688,7 @@ fn one_pass( guard.states = states; guard.by_team = by_team; guard.projects = projects; + guard.all_projects = all_projects; guard.proj_open = proj_open; guard.proj_state = proj_state; guard.proj_oldest = proj_oldest; @@ -1506,14 +1573,15 @@ fn main() { // question rather than an answer. It also used to open on the cycles // pane while the footer said the arrows scrolled, which was wrong // twice over. - let (cycles_pane, teams_pane) = (0usize, 1usize); + // In the order they are drawn, which is the order the arrows walk them. + let (cycles_pane, teams_pane, projects_pane) = (0usize, 1usize, 2usize); let mut focus: Option<usize> = None; - let mut sel = [0usize, 0usize]; + let mut sel = [0usize; 3]; // How long each pane was when it was last drawn. The keys are read // before the frame is built, so walking off the end of a pane has to be // judged against the length it had a moment ago - which is the length // the reader is looking at. - let mut pane_len = [0usize, 0usize]; + let mut pane_len = [0usize; 3]; // Which pane's selection is open on a screen of its own, and how far // down it is scrolled. let (mut detail, mut dscroll): (Option<usize>, usize) = (None, 0); @@ -1537,6 +1605,12 @@ fn main() { // frame that answers them is built. let mut projects_len = 0usize; let mut open_project: Option<String> = None; + // How far down the board itself is scrolled, and how tall it was when + // it was last drawn - the keys run before the frame that answers them. + let mut board = 0usize; + let mut board_len = 0usize; + // Which project the board's own list has under its cursor. + let mut board_project: Option<String> = None; let mut tick = 0usize; let mut settle_t = 0usize; let mut settle_from: Option<(Vec<f64>, Vec<f64>)> = None; @@ -1577,7 +1651,13 @@ fn main() { // away. Empty panes are stepped over: focusing one leaves // the arrows moving an index nothing is drawn from, which // is a key that does nothing and says nothing. - "tab" => focus = tc::next_section(focus, &pane_len), + "tab" => { + focus = tc::next_section(focus, &pane_len); + // Back to no focus means back to reading the board, + // and the window stays where the cursor left it rather + // than jumping to the top. + pick = 0; + } // Enter opens whichever pane has the cursor. Without a // focused pane there is nothing selected to open, which is // the same rule the board's own cursor follows. @@ -1597,11 +1677,27 @@ fn main() { detail = focus; dscroll = 0; pick = 0; + // The board's project list has no screen of its + // own between the board and a project. + if focus == Some(projects_pane) { + deep = board_project.clone(); + pscroll = 0; + if deep.is_none() { + detail = None; + } + } } } // Back one level at a time: out of a project to the team // that owns it, and only then to the board. - "left" | "esc" if deep.is_some() => deep = None, + "left" | "esc" if deep.is_some() => { + deep = None; + // A project opened from the board's own list has no + // team screen behind it to come back to. + if detail == Some(projects_pane) { + detail = None; + } + } "left" | "esc" if detail.is_some() => detail = None, // A team's screen hands the arrows to its project list and // scrolls itself to follow; every other screen has nothing @@ -1646,20 +1742,44 @@ fn main() { "up" | "down" => { let down = key == "down"; pick = 0; - focus = match focus { - Some(here) => tc::step_across_sections(here, sel[here], &pane_len, down) - .map(|(pane, row)| { - sel[pane] = row; - pane - }), - // Nothing focused, and no screen scroll to hand the - // arrows to - both panes window themselves. They - // step into the near end of the first pane that has - // rows, so the ring closes the way latency's does. - None => tc::next_section(None, &pane_len).map(|here| { - sel[here] = if down { 0 } else { pane_len[here] - 1 }; - here - }), + match focus { + Some(here) => { + focus = tc::step_across_sections(here, sel[here], &pane_len, down) + .map(|(pane, row)| { + sel[pane] = row; + pane + }); + } + // Nothing focused: the arrows move the board. The + // board is taller than the pane and every section + // is drawn whole, so this is the only way to reach + // the bottom of it without picking a section first. + None => { + board = if down { + board.saturating_add(1) + } else { + board.saturating_sub(1) + }; + } + } + } + "pgup" | "pgdn" => { + let page = tc::size().1.saturating_sub(3).max(1); + if focus.is_none() { + board = if key == "pgdn" { + board.saturating_add(page).min(board_len.saturating_sub(1)) + } else { + board.saturating_sub(page) + }; + } else if let Some(here) = focus { + // A page through a focused section, clamped to it - + // crossing out of a section is what the single + // arrows are for. + sel[here] = if key == "pgdn" { + sel[here].saturating_add(page).min(pane_len[here].saturating_sub(1)) + } else { + sel[here].saturating_sub(page) + }; } } _ => {} @@ -1678,6 +1798,9 @@ fn main() { let left = quota.lock().map(|g| g.requests).unwrap_or(None); let mut rows = vec![tc::title("linear ops", w, &p.new)]; + // Where the focused section's cursor landed, so the board can be + // scrolled to keep it on screen. + let mut cursor: Option<usize> = None; let mut head = vec![ ( p.dim.as_str(), @@ -1834,14 +1957,6 @@ fn main() { if !ranked_cycles.is_empty() { sel[cycles_pane] = sel[cycles_pane].min(ranked_cycles.len() - 1); } - let shown = ((h.saturating_sub(rows.len())) / 4).clamp(2, 6); - let cfirst = if ranked_cycles.len() > shown { - sel[cycles_pane] - .saturating_sub(shown / 2) - .min(ranked_cycles.len() - shown) - } else { - 0 - }; let here_now = focus == Some(cycles_pane); rows.push(tc::seg( &[ @@ -1852,17 +1967,7 @@ fn main() { (p.dim.as_str(), format!("{} running", s.cycles.len())), ( if here_now { p.accent.as_str() } else { p.dim.as_str() }, - if ranked_cycles.len() > shown { - format!( - " {}{}-{} of {}", - if here_now { "↑↓ " } else { "" }, - cfirst + 1, - (cfirst + shown).min(ranked_cycles.len()), - ranked_cycles.len() - ) - } else { - String::new() - }, + if here_now { " ↑↓".to_string() } else { String::new() }, ), ], w - 1, @@ -1873,7 +1978,10 @@ fn main() { w - 1, )); } - for (ci, c) in ranked_cycles.iter().enumerate().skip(cfirst).take(shown) { + for (ci, c) in ranked_cycles.iter().enumerate() { + if here_now && ci == sel[cycles_pane] { + cursor = Some(rows.len()); + } let scope = last_of(c, "scopeHistory"); let done = last_of(c, "completedScopeHistory"); let opened_at = first_of(c, "scopeHistory"); @@ -2102,12 +2210,6 @@ fn main() { if !ranked.is_empty() { sel[teams_pane] = sel[teams_pane].min(ranked.len() - 1); } - let room = h.saturating_sub(5 + rows.len()).max(1); - let first = if ranked.len() > room { - sel[teams_pane].saturating_sub(room / 2).min(ranked.len() - room) - } else { - 0 - }; let on_teams = focus == Some(teams_pane); rows.push(tc::seg( &[ @@ -2117,17 +2219,7 @@ fn main() { ), ( if on_teams { p.accent.as_str() } else { p.dim.as_str() }, - if ranked.len() > room { - format!( - " {}{}-{} of {}", - if on_teams { "↑↓ " } else { "" }, - first + 1, - (first + room).min(ranked.len()), - ranked.len() - ) - } else { - String::new() - }, + if on_teams { " ↑↓".to_string() } else { String::new() }, ), ], w - 1, @@ -2149,7 +2241,10 @@ fn main() { )], w - 1, )); - for (i, (key, name)) in ranked.iter().enumerate().skip(first).take(room) { + for (i, (key, name)) in ranked.iter().enumerate() { + if on_teams && i == sel[teams_pane] { + cursor = Some(rows.len()); + } let empty = HashMap::new(); let c = s.by_team.get(key).unwrap_or(&empty); let count = |k: &str| c.get(k).copied().unwrap_or(0); @@ -2186,6 +2281,130 @@ fn main() { line.iter().map(|(c, t)| (c.as_str(), t.clone())).collect(); rows.push(tc::seg(&refs, w - 1)); } + // Every project that is still going, whichever team owns it. The + // board reaches them without going through a team first, the way + // it reaches cycles without going through one. + rows.push(String::new()); + let live: Vec<Proj> = s + .all_projects + .iter() + .filter(|q| q.kind != "completed" && q.kind != "canceled") + .cloned() + .collect(); + let finished = s.all_projects.len() - live.len(); + pane_len[projects_pane] = live.len(); + if !live.is_empty() { + sel[projects_pane] = sel[projects_pane].min(live.len() - 1); + } + board_project = live.get(sel[projects_pane]).map(|q| q.id.clone()); + let on_projects = focus == Some(projects_pane); + rows.push(tc::seg( + &[ + ( + if on_projects { p.accent.as_str() } else { p.lbl.as_str() }, + " ── PROJECTS ── ".into(), + ), + // What is not in the list, because a count of the running + // ones alone reads as a count of all of them. + ( + p.dim.as_str(), + if finished > 0 { + format!("{} running · {} finished, not listed", live.len(), finished) + } else { + format!("{} running", live.len()) + }, + ), + ( + if on_projects { p.accent.as_str() } else { p.dim.as_str() }, + if on_projects { " ↑↓".to_string() } else { String::new() }, + ), + ], + w - 1, + )); + if live.is_empty() { + rows.push(tc::seg( + &[(p.dim.as_str(), " no project is running in any team".into())], + w - 1, + )); + } + { + // Sized the way the team screen sizes its own list: no column + // capped, the bar taking what is left, and the aside shedding + // whole facts rather than being cut through the middle. + let asides: Vec<String> = live + .iter() + .map(|q| { + let open: usize = + s.proj_state.get(&q.id).map(|m| m.values().sum()).unwrap_or(0); + if open > 0 { + format!("{} open", open) + } else { + String::new() + } + }) + .collect(); + let widest = |xs: &mut dyn Iterator<Item = usize>| xs.max().unwrap_or(0); + let team_w = widest(&mut live.iter().map(|q| q.teams.join("/").chars().count())).max(4); + let name_w = widest(&mut live.iter().map(|q| q.name.chars().count())).max(8); + let label_w = widest(&mut live.iter().map(|q| q.label.chars().count())).max(4); + let full = widest(&mut asides.iter().map(|a| a.chars().count())); + // Something has to go at narrow widths: the longest project + // name in this workspace is 47 characters, and at eighty + // columns the name, the team and the status alone do not fit. + let base = 2 + team_w + 2 + name_w + 5; + let (label_cost, bar_w, room) = project_columns(w, base, label_w, full); + for (i, (q, aside)) in live.iter().zip(&asides).enumerate() { + let here = on_projects && i == sel[projects_pane]; + if here { + cursor = Some(rows.len()); + } + let tint = if here { tc::bg(38, 56, 76) } else { String::new() }; + let c_of = |colour: &str| format!("{}{}", tint, colour); + let colour = match q.kind.as_str() { + "started" => p.warn.as_str(), + _ => p.txt.as_str(), + }; + let aside = if aside.chars().count() <= room { aside.as_str() } else { "" }; + let aside = + if aside.is_empty() { String::new() } else { format!(" {}", aside) }; + let line: Vec<(String, String)> = vec![ + ( + c_of(if here { &p.accent } else { &p.dim }), + format!( + "{} {}", + if here { "▸" } else { " " }, + tc::pad(&q.teams.join("/"), team_w) + ), + ), + ( + c_of(if here { &p.accent } else { &p.txt }), + format!(" {}", tc::pad(&q.name, name_w)), + ), + ( + c_of(colour), + if label_cost > 0 { + format!(" {}", tc::pad(&q.label, label_w)) + } else { + String::new() + }, + ), + ( + c_of(colour), + if bar_w > 0 { + format!(" {}", tc::meter(q.progress, bar_w)) + } else { + String::new() + }, + ), + (c_of(&p.txt), format!(" {:>3.0}%", 100.0 * q.progress)), + (c_of(&p.dim), aside), + ]; + let refs: Vec<(&str, String)> = + line.iter().map(|(c, t)| (c.as_str(), t.clone())).collect(); + rows.push(tc::seg(&refs, w - 1)); + } + } + // One cycle, one team, or one of that team's projects, each on a // screen of its own. if let Some(which) = detail { @@ -2206,9 +2425,12 @@ fn main() { // The project being read is found by its id, so a poll that // re-sorts the list underneath cannot swap it for its // neighbour. + // Looked up across the whole workspace, because the project + // may have been opened from the board's list rather than from + // the team whose screen is behind it. let reading = deep .as_ref() - .and_then(|id| projects.iter().find(|q| &q.id == id).cloned()); + .and_then(|id| s.all_projects.iter().find(|q| &q.id == id).cloned()); let (body, cursor) = if let Some(q) = reading.as_ref() { let empty = HashMap::new(); let states = s.proj_state.get(&q.id).unwrap_or(&empty); @@ -2217,7 +2439,7 @@ fn main() { ( project_detail( q, - team.as_ref().map(|(k, _)| k.as_str()).unwrap_or(""), + &q.teams.join(" · "), record.as_ref(), states, oldest.as_ref(), @@ -2302,7 +2524,15 @@ fn main() { (p.accent.as_str(), "←".into()), ( p.dim.as_str(), - if reading.is_some() { "/esc the team".into() } else { "/esc back".to_string() }, + // Back goes wherever this screen was opened from, + // and says which: a project reached through a team + // returns to that team, one reached from the + // board's own list returns to the board. + if reading.is_some() && which == teams_pane { + "/esc the team".to_string() + } else { + "/esc back".to_string() + }, ), ]); hints.push(vec![(p.dim.as_str(), "[r]efresh".into())]); @@ -2316,11 +2546,7 @@ fn main() { // The page follows the cursor into the project list, the // way netwatch's detail follows one into a section. if let Some(row) = cursor { - if row < *at { - *at = row; - } else if row >= *at + room { - *at = row + 1 - room; - } + *at = follow(*at, row, room); } *at = (*at).min(body.len().saturating_sub(room)); let from = *at; @@ -2341,32 +2567,57 @@ fn main() { deep = None; } - let hints: Vec<Vec<(&str, String)>> = vec![ - // Not "scroll": nothing on this board scrolls. The arrows move - // a cursor through whichever pane has the focus, and both panes - // window themselves around it. - vec![(p.accent.as_str(), "↑↓".into()), (p.dim.as_str(), " select".into())], + // The board is taller than the pane, so the arrows do one of two + // things and the footer has to say which. Unfocused they move the + // whole board; focused they move a cursor through one section, and + // the board follows. + let mut hints: Vec<Vec<(&str, String)>> = vec![ + vec![ + (p.accent.as_str(), "↑↓".into()), + ( + p.dim.as_str(), + if focus.is_some() { " select" } else { " scroll" }.to_string(), + ), + ], vec![ (p.accent.as_str(), "tab".into()), ( p.dim.as_str(), - if focus.is_some() { " next pane" } else { " into a pane" }.to_string(), + if focus.is_some() { " next section" } else { " into a section" }.to_string(), ), ], - vec![(p.dim.as_str(), "[w]indow".into())], - vec![(p.dim.as_str(), "[r]efresh".into())], - vec![(p.dim.as_str(), "[q]uit".into())], ]; + if focus.is_some() { + hints.push(vec![ + (p.accent.as_str(), "→/↵".into()), + (p.dim.as_str(), " open it".into()), + ]); + } + hints.push(vec![(p.dim.as_str(), "pgup/pgdn page".into())]); + hints.push(vec![(p.dim.as_str(), "[w]indow".into())]); + hints.push(vec![(p.dim.as_str(), "[r]efresh".into())]); + hints.push(vec![(p.dim.as_str(), "[q]uit".into())]); let footer: Vec<String> = tc::pack_hints(&hints, w - 2, " ") .into_iter() .map(|l| format!(" {}", l)) .collect(); - rows.truncate(h.saturating_sub(footer.len())); - while rows.len() < h.saturating_sub(footer.len()) { - rows.push(String::new()); + // The board is longer than most panes are tall, and every section + // is now drawn whole - so the frame is a window onto it. With a + // section focused the window chases its cursor; with none, the + // arrows move the window itself. + let room = h.saturating_sub(footer.len()).max(1); + if let Some(at) = cursor { + board = follow(board, at, room); + } + board = board.min(rows.len().saturating_sub(room)); + board_len = rows.len(); + let last = (board + room).min(rows.len()); + let mut out: Vec<String> = rows[board..last].to_vec(); + while out.len() < room { + out.push(String::new()); } - rows.extend(footer); - tc::draw(&rows, w, h); + out.extend(footer); + tc::draw(&out, w, h); std::thread::sleep(Duration::from_millis(300)); } } @@ -2638,6 +2889,97 @@ mod tests { assert!(row.contains('░'), "a 68% bar is not full: {}", row); } + #[test] + fn the_board_walks_three_sections_and_lets_go_only_at_the_ends() { + // Cycles, teams, then the board's own project list, in the order + // they are drawn. The rule is the same one every widget here with + // focusable sections follows; this is the third section arriving. + let lens = [5usize, 14, 34]; + assert_eq!(tc::next_section(None, &lens), Some(0)); + assert_eq!(tc::next_section(Some(0), &lens), Some(1)); + assert_eq!(tc::next_section(Some(1), &lens), Some(2)); + assert_eq!(tc::next_section(Some(2), &lens), None); + // Down off the last cycle lands on the first team, and off the + // last team on the first project. + assert_eq!(tc::step_across_sections(0, 4, &lens, true), Some((1, 0))); + assert_eq!(tc::step_across_sections(1, 13, &lens, true), Some((2, 0))); + assert_eq!(tc::step_across_sections(2, 33, &lens, true), None); + // And back up the same way, into the *last* row of the section + // above rather than its first. + assert_eq!(tc::step_across_sections(2, 0, &lens, false), Some((1, 13))); + assert_eq!(tc::step_across_sections(1, 0, &lens, false), Some((0, 4))); + assert_eq!(tc::step_across_sections(0, 0, &lens, false), None); + // A section with nothing in it is stepped over, not landed on. + let gap = [5usize, 0, 34]; + assert_eq!(tc::step_across_sections(0, 4, &gap, true), Some((2, 0))); + assert_eq!(tc::next_section(Some(0), &gap), Some(2)); + } + + #[test] + fn a_project_row_never_overflows_and_never_loses_ground_as_it_widens() { + // Both bugs this function exists for, stated as properties. + let (base, label_w, aside) = (2 + 7 + 2 + 47 + 5, 11usize, 8usize); + let mut had: Option<(bool, bool, bool)> = None; + for w in 40..200usize { + let (label_cost, bar, room) = project_columns(w, base, label_w, aside); + let bar_cost = if bar > 0 { 2 + bar } else { 0 }; + // It fits, once there is room for the name at all. Anything + // wider than the pane is cut by `seg`, and what `seg` cuts is + // the percentage - the row's only number. + if base <= w - 1 { + let aside_cost = if room > 0 { 2 + room } else { 0 }; + assert!( + base + label_cost + bar_cost + aside_cost <= w - 1, + "w={} overflows: base {} label {} bar {} aside {}", + w, base, label_cost, bar_cost, aside_cost + ); + } else { + // Too narrow even for the name: nothing optional is added + // on top of a row that is already over the edge. + assert_eq!((label_cost, bar, room), (0, 0, 0), "w={}", w); + } + // A wider pane never shows less than a narrower one did. + let now = (label_cost > 0, bar > 0, room >= aside); + if let Some(before) = had { + assert!( + now.0 >= before.0 && now.1 >= before.1 && now.2 >= before.2, + "w={} lost a column the narrower pane had: {:?} then {:?}", + w, before, now + ); + } + had = Some(now); + } + // And at the ends: nothing optional survives a very narrow pane, + // everything does in a wide one. + assert_eq!(project_columns(50, base, label_w, aside), (0, 0, 0)); + let (label_cost, bar, room) = project_columns(190, base, label_w, aside); + assert!(label_cost > 0 && bar == 30 && room >= aside); + } + + #[test] + fn the_window_chases_a_cursor_it_cannot_see() { + // Stated as what the reader sees rather than as the arithmetic: + // wherever the cursor is, the window has to contain it, and it has + // to move as little as it can to do that. + let holds = |at: usize, row: usize, room: usize| row >= at && row < at + room; + for room in [1usize, 3, 20] { + for start in [0usize, 5, 30] { + for row in [0usize, 4, 7, 12, 40] { + let moved = follow(start, row, room); + assert!(holds(moved, row, room), "row {} not in {}..+{}", row, moved, room); + // Not moved at all when it did not need to be. + if holds(start, row, room) { + assert_eq!(moved, start, "moved without needing to"); + } + } + } + } + // Reaching down puts the cursor on the last row, not past it. + assert_eq!(follow(0, 40, 20) + 20, 41); + // Reaching up puts it on the first. + assert_eq!(follow(30, 4, 20), 4); + } + #[test] fn a_team_with_no_projects_says_so_rather_than_showing_an_empty_heading() { let counts: HashMap<String, usize> = [("open".to_string(), 3usize)].into_iter().collect(); From b4415f3024b3df49c841a5dc7aaee0be1f5b1ff0 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Tue, 25 Aug 2026 17:31:48 +0800 Subject: [PATCH 103/147] linear, netwatch: a cycle lists what is in it, and headings say tab Two things, and the second is a request from William for every widget here that has focusable sections. A cycle's screen said how it was going and never what was in it. It now carries what is open by state, and then the issues themselves - what is moving first, then what is waiting, and inside each the oldest first, so the top row is the one that has been in progress longest. `[c]opy url` puts the one under the cursor on the clipboard, the way the pr widget does. An issue is a leaf here: there is no screen below it, so what it offers is somewhere to go and read it. None of that costs a request. The board already pages every open issue for its own counters, and three more fields on that query - the title, the url and the cycle - carry the list. The burn-up histories were already in the cycles query. Only the open issues are listed, because open issues are all this widget ever fetches, so the heading says how many are closed and not there. A cycle of eight showing one row otherwise reads as a cycle of one - the same partial-as-total trap the projects list has, answered the same way. A title too long for its column carries on underneath rather than being cut: an issue cut to forty characters is a different issue on screen. An issue nobody has pointed says nothing rather than "0p". The cursor is the same one the team screen uses. Only one of those screens is ever up, so `projects_len` became `list_len` and serves whichever list the open screen holds, rather than a second length to keep in step. Then the headings. Every focusable section now says how to focus it, on the one heading where that is true: the focused one carries the arrows, and exactly one *other* carries `[tab] to focus` - the one tab would actually reach next. Not all of them, because tab cycles, and a `[tab]` on three headings promises three sections that one press reaches when one press reaches one. Pressing it walks the marker down the board, which is the cycle teaching itself, and an empty section never carries it because tab steps over those. netwatch's `section_head` is where this was learned: it used to name a key per list, `[e]` and `[f]` pointing at keys that had gone, and the note left behind says tab was the only one that was ever true. So tab is what goes back, and only where it is true. linear and netwatch are the two widgets with tab-focused sections; usage's tab moves between provider tabs, which are already a visible bar, and herdr-panes has no focus to take. Each of the five new tests was watched failing against the defect it covers. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- docs/linear.md | 32 ++ docs/netwatch.md | 8 + rust/widgets/src/bin/linear.rs | 488 ++++++++++++++++++++++++++++--- rust/widgets/src/bin/netwatch.rs | 21 +- 4 files changed, 500 insertions(+), 49 deletions(-) diff --git a/docs/linear.md b/docs/linear.md index f2ff500..31b09e2 100644 --- a/docs/linear.md +++ b/docs/linear.md @@ -139,6 +139,30 @@ is left to run, and how much moved lately — the same day-over-day figure the board ranks cycles by, so the ordering is legible rather than mysterious. A cycle with no name of its own is called by its number rather than left blank. +Under the burn-up, what is open in it by state, and then the issues themselves: + +``` + ── OPEN IN THIS CYCLE ── 28 · 5 closed, not listed +▸ WEB-275 in progress Server-rendered context blocks on top of the share copy 19.3d 1p + WEB-300 in progress Check every published record against its upstream source 16.0d + WEB-229 todo Add an itinerary mode to the card renderer 22.1d 4p +``` + +What is moving comes first, then what is waiting, and inside each the oldest +first — so the row at the top is the one that has been in progress longest. An +issue nobody has pointed shows no points rather than `0p`. A title too long for +its column carries on underneath rather than being cut: an issue cut to forty +characters is a different issue on screen. + +**Only the open ones are listed**, because open issues are all this widget ever +fetches — so the heading says how many are closed. Without that, a cycle of +eight showing one row reads as a cycle of one. + +The arrows move a cursor through them and `[c]opy url` puts the selected +issue's address on the clipboard, over OSC 52, the same way the pr widget does. +An issue is a leaf here: there is no screen below it, so what it offers is +somewhere to go and read it. + A **team** gives what it is holding, broken out by state as a stacked bar, with triage called out separately: it is work nobody has looked at, and a team can hold hundreds of it while looking busy everywhere else. @@ -275,6 +299,13 @@ marker. The arrows then move a cursor through that section, and the window follows it - a cursor below the fold pulls the board down, one above it pulls it up, each by as little as it takes. +Exactly one *other* heading carries `[tab] to focus`, and it is the one tab +would actually focus next. Not all of them: tab cycles, so a `[tab]` on every +heading would promise three sections that one press reaches when one press +reaches one of them. As you press it the marker moves down the board, which is +the cycle teaching itself. A section with nothing in it never carries it, +because tab steps over those. + Under the arrows the three sections read as **one continuous list**: down off the bottom of the cycles steps into the top of the teams, off the bottom of the teams into the top of the projects; up steps back the same way, into the @@ -295,6 +326,7 @@ direction. | `PgUp` `PgDn` | the same, a page at a time | | `↵` `→` | open the highlighted cycle, team or project — and from a team, the project under its cursor | | `←` `esc` | back one level: a project to wherever it was opened from, a team to the board | +| `c` | copy the selected issue's url, on a cycle's screen | | `r` | refresh, including the open project's own record | | `w` | cycle the window — 7 / 14 / 30 / 60 / 90 days | | `r` | refresh now | diff --git a/docs/netwatch.md b/docs/netwatch.md index 34b50a5..f266080 100644 --- a/docs/netwatch.md +++ b/docs/netwatch.md @@ -319,6 +319,14 @@ Every list is drawn in full, always, and `↑` `↓` scroll the screen. `tab` focuses a list instead: the focused one is marked `▏`, `↑` `↓` then move a cursor `▸` inside it, and `c` copies whatever that cursor is on. +Exactly one *other* heading carries `[tab] to focus`, and it is the one tab +would actually focus next — not all of them, because tab cycles and a `[tab]` +on all three would promise three lists that one press reaches. This heading +used to name a key per list, `[e]` and `[f]`, pointing at keys that no longer +existed; tab was the only one that was ever true, so tab is what is left, and +only where it is true. A list with nothing in it never carries it, because tab +steps over those. + Under the arrows the three lists read as **one continuous list**: `↓` off the bottom of a list steps into the top of the next, and `↑` off the top steps into the *bottom* of the one above — the row you were about to reach if they diff --git a/rust/widgets/src/bin/linear.rs b/rust/widgets/src/bin/linear.rs index 2297a95..ae7ae4e 100644 --- a/rust/widgets/src/bin/linear.rs +++ b/rust/widgets/src/bin/linear.rs @@ -142,8 +142,8 @@ query($after: String) {{ issues(first: {}, after: $after, filter: {{ state: {{ type: {{ nin: ["completed", "canceled", "duplicate"] }} }} }}) {{ - nodes {{ identifier estimate startedAt createdAt - state {{ type }} team {{ key }} project {{ id }} }} + nodes {{ identifier title url estimate startedAt createdAt + state {{ type }} team {{ key }} project {{ id }} cycle {{ id }} }} pageInfo {{ hasNextPage endCursor }} }} }}"#, @@ -181,7 +181,7 @@ const CYCLES_QUERY: &str = r#" { cycles(first: 50, filter: { isActive: { eq: true } }) { nodes { - name number startsAt endsAt progress + id name number startsAt endsAt progress issueCountHistory completedIssueCountHistory scopeHistory completedScopeHistory team { key name } @@ -306,6 +306,22 @@ fn median(xs: &[f64]) -> Option<f64> { }) } +/// One open issue, as much of it as a list needs. +/// +/// Every field here rides the pass the board already makes over every open +/// issue, so a cycle's list of them costs no request of its own. +#[derive(Clone, Default)] +struct Issue { + ident: String, + title: String, + url: String, + state: String, + /// Hours since it was created. + age: f64, + /// None when nobody has pointed it, which is not the same as zero. + points: Option<f64>, +} + /// One project, as much of it as a team's screen needs. /// /// `progress` is Linear's own published figure, not one derived here: it @@ -427,6 +443,45 @@ fn joined(parts: &[String]) -> String { parts.join(" · ") } +/// What a section heading says about the keys, given where the focus is. +/// +/// The focused one carries the arrows. Exactly one other carries `[tab]` - +/// the one tab would actually focus next - because tab cycles, and a +/// `[tab]` on every heading would promise three sections that one press +/// reaches, when one press reaches one of them. netwatch learned this the +/// expensive way with per-heading letters bound to keys that had gone; the +/// note in its `section_head` says tab was the only one that was ever true. +fn heading_keys(me: usize, focus: Option<usize>, lens: &[usize]) -> &'static str { + if focus == Some(me) { + " ↑↓" + } else if tc::next_section(focus, lens) == Some(me) { + " [tab] to focus" + } else { + "" + } +} + +/// A count with its noun, singular when it is one. +fn plural(n: usize, noun: &str) -> String { + if n == 1 { + format!("{} {}", n, noun) + } else { + format!("{} {}s", n, noun) + } +} + +/// Where an issue's state sorts: what is moving first, what nobody has +/// looked at last. +fn state_rank(state: &str) -> usize { + match state { + "started" => 0, + "unstarted" => 1, + "backlog" => 2, + "triage" => 3, + _ => 4, + } +} + /// Where a project's status sorts, running work first and finished last. /// /// An unknown status sorts with the live ones rather than the dead ones: a @@ -466,6 +521,10 @@ struct State { proj_state: HashMap<String, HashMap<String, usize>>, /// Project id to the oldest thing still open in it. proj_oldest: HashMap<String, (f64, String)>, + /// Cycle id to its open issues by state, and to the issues themselves in + /// the order a screen shows them. + cycle_state: HashMap<String, HashMap<String, usize>>, + cycle_issues: HashMap<String, Vec<Issue>>, cycles: Vec<serde_json::Value>, created: HashMap<String, usize>, completed: HashMap<String, usize>, @@ -532,6 +591,8 @@ fn one_pass( let mut proj_open: HashMap<String, HashMap<String, usize>> = HashMap::new(); let mut proj_state: HashMap<String, HashMap<String, usize>> = HashMap::new(); let mut proj_oldest: HashMap<String, (f64, String)> = HashMap::new(); + let mut cycle_state: HashMap<String, HashMap<String, usize>> = HashMap::new(); + let mut cycle_issues: HashMap<String, Vec<Issue>> = HashMap::new(); let at = Utc::now().naive_utc(); let (mut oldest_open, mut oldest_wip): (Extreme, Extreme) = (None, None); for it in &rows { @@ -567,6 +628,24 @@ fn one_pass( } } } + // Which cycle it is in, if any, and the issue itself - both ride + // this pass, so a cycle's screen costs no request of its own. + let in_cycle = text(&it["cycle"], "id"); + if !in_cycle.is_empty() { + *cycle_state + .entry(in_cycle.clone()) + .or_default() + .entry(st.clone()) + .or_insert(0) += 1; + cycle_issues.entry(in_cycle).or_default().push(Issue { + ident: text(it, "identifier"), + title: text(it, "title"), + url: text(it, "url"), + state: st.clone(), + age: hours_since(parse(&text(it, "createdAt")), Some(at)).unwrap_or(0.0), + points: it["estimate"].as_f64(), + }); + } let slot = by_team.entry(key).or_default(); *slot.entry(st.clone()).or_insert(0) += 1; *slot.entry("open".into()).or_insert(0) += 1; @@ -676,6 +755,18 @@ fn one_pass( ctime.push(hrs); } } + // What is being worked first, then what is waiting, and inside each the + // oldest first. Ties break on the identifier so a poll cannot shuffle + // two equal rows under the cursor. + for list in cycle_issues.values_mut() { + list.sort_by(|a, b| { + state_rank(&a.state) + .cmp(&state_rank(&b.state)) + .then(b.age.total_cmp(&a.age)) + .then(a.ident.cmp(&b.ident)) + }); + } + for (key, slot) in by_team.iter_mut() { let n = done .iter() @@ -692,6 +783,8 @@ fn one_pass( guard.proj_open = proj_open; guard.proj_state = proj_state; guard.proj_oldest = proj_oldest; + guard.cycle_state = cycle_state; + guard.cycle_issues = cycle_issues; guard.cycles = cycles; guard.created = created; guard.completed = completed; @@ -769,7 +862,16 @@ fn state_label(state: &str) -> &'static str { /// scope rising while completed stays flat is a cycle taking on work, and /// the two converging is one closing. Nothing here is a new request - the /// arrays arrive with the cycle. -fn cycle_detail(c: &serde_json::Value, w: usize, h: usize, p: &Palette) -> Vec<String> { +#[allow(clippy::too_many_arguments)] +fn cycle_detail( + c: &serde_json::Value, + states: &HashMap<String, usize>, + issues: &[Issue], + pick: usize, + w: usize, + h: usize, + p: &Palette, +) -> (Vec<String>, Option<usize>) { let team = text(&c["team"], "name"); // Linear cycles are often unnamed - the board falls back to their // number and so does this, or the title reads " · TEAM" with a leading @@ -802,8 +904,8 @@ fn cycle_detail(c: &serde_json::Value, w: usize, h: usize, p: &Palette) -> Vec<S }; let scope = series("scopeHistory"); let done = series("completedScopeHistory"); - let issues = series("issueCountHistory"); - let issues_done = series("completedIssueCountHistory"); + let issue_count = series("issueCountHistory"); + let issues_closed = series("completedIssueCountHistory"); let at = |v: &[f64]| v.last().copied().unwrap_or(0.0); let pct = if at(&scope) > 0.0 { @@ -823,11 +925,11 @@ fn cycle_detail(c: &serde_json::Value, w: usize, h: usize, p: &Palette) -> Vec<S format!("{:.0} done, {:.0} left", at(&done), (at(&scope) - at(&done)).max(0.0)), p.txt.as_str(), ); - if !issues.is_empty() { + if !issue_count.is_empty() { field( "issues", - format!("{:.0}", at(&issues)), - format!("{:.0} closed", at(&issues_done)), + format!("{:.0}", at(&issue_count)), + format!("{:.0} closed", at(&issues_closed)), p.dim.as_str(), ); } @@ -928,7 +1030,136 @@ fn cycle_detail(c: &serde_json::Value, w: usize, h: usize, p: &Palette) -> Vec<S rows.push(tc::seg(&parts, w - 1)); } } - rows + // What is open in it right now, by state. The burn-up above is where + // the cycle has been; this is where it is. + let open: usize = states.values().sum(); + if open > 0 { + let legend: Vec<(&str, usize, &str)> = STATE_ORDER + .iter() + .map(|st| (state_label(st), states.get(*st).copied().unwrap_or(0), state_colour(st, p))) + .filter(|x| x.1 > 0) + .collect(); + rows.push(String::new()); + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── OPEN BY STATE ── ".into()), + (p.dim.as_str(), plural(open, "issue")), + ], + w - 1, + )); + let parts: Vec<(f64, String)> = legend + .iter() + .map(|(_, n, c)| (*n as f64 / open as f64, c.to_string())) + .collect(); + let bar = tc::stacked_bar(&parts, w.saturating_sub(3).max(10)); + let mut line: Vec<(&str, String)> = vec![(tc::RST, " ".into())]; + for (colour, txt) in &bar { + line.push((colour.as_str(), txt.clone())); + } + rows.push(tc::seg(&line, w - 1)); + let mut legend_row: Vec<(&str, String)> = vec![(tc::RST, " ".into())]; + for (label, count, colour) in &legend { + legend_row.push((colour, "▇ ".into())); + legend_row.push((p.txt.as_str(), (*label).into())); + legend_row.push(( + p.dim.as_str(), + format!(" {} ({:.0}%) ", count, 100.0 * *count as f64 / open as f64), + )); + } + rows.push(tc::seg(&legend_row, w - 1)); + } + + // The issues themselves. Only the open ones are here, because the open + // ones are all this widget ever fetches - so the heading says how many + // are closed rather than letting a count of one read as a cycle of one. + let closed = (at(&issues_closed) as usize).min(at(&issue_count) as usize); + rows.push(String::new()); + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " ── OPEN IN THIS CYCLE ── ".into()), + ( + p.dim.as_str(), + if closed > 0 { + format!("{} · {} closed, not listed", issues.len(), closed) + } else { + format!("{}", issues.len()) + }, + ), + ], + w - 1, + )); + if issues.is_empty() { + rows.push(tc::seg( + &[( + p.dim.as_str(), + if closed > 0 { + " nothing open in it - every issue is closed".into() + } else { + " nothing open in it".to_string() + }, + )], + w - 1, + )); + return (rows, None); + } + + let pick = pick.min(issues.len() - 1); + let mut cursor = None; + let widest = |xs: &mut dyn Iterator<Item = usize>| xs.max().unwrap_or(0); + let ident_w = widest(&mut issues.iter().map(|i| i.ident.chars().count())).max(6); + let state_w = widest(&mut issues.iter().map(|i| state_label(&i.state).chars().count())).max(4); + // Identifier, state, age and points are fixed; the title takes the rest, + // and is the one thing here long enough to need it. + let head = 2 + ident_w + 2 + state_w + 2 + 6 + 2 + 5 + 2; + let title_w = (w - 1).saturating_sub(head).max(10); + for (i, it) in issues.iter().enumerate() { + let here = i == pick; + if here { + cursor = Some(rows.len()); + } + // A title long enough to overrun the column carries on underneath + // it rather than being cut. An issue titled "Verify fares · Sun + // Ferry Services · Peng Chau" and one cut to the same forty + // characters are two different issues on screen. + let lines = wrap(&it.title, title_w); + let (first, rest) = lines.split_first().map(|(a, b)| (a.clone(), b)).unwrap_or_default(); + rows.push(tc::seg( + &[ + ( + if here { p.accent.as_str() } else { p.dim.as_str() }, + format!("{} {}", if here { "▸" } else { " " }, tc::pad(&it.ident, ident_w)), + ), + ( + state_colour(&it.state, p), + format!(" {}", tc::pad(state_label(&it.state), state_w)), + ), + ( + if here { p.accent.as_str() } else { p.txt.as_str() }, + format!(" {}", tc::pad(&first, title_w)), + ), + (p.dim.as_str(), format!(" {:>6}", dur(Some(it.age)))), + // Nothing rather than "0 pts" when nobody has pointed it. + ( + p.dim.as_str(), + match it.points { + Some(n) if n > 0.0 => format!(" {:>4}", format!("{}p", tidy(n))), + _ => " ".to_string(), + }, + ), + ], + w - 1, + )); + for line in rest { + rows.push(tc::seg( + &[( + if here { p.accent.as_str() } else { p.txt.as_str() }, + format!("{}{}", " ".repeat(2 + ident_w + 2 + state_w + 2), line), + )], + w - 1, + )); + } + } + (rows, cursor) } /// One team in full: what it is holding, in the states it is holding it. @@ -998,7 +1229,7 @@ fn team_detail( rows.push(tc::seg( &[ (p.lbl.as_str(), " ── OPEN BY STATE ── ".into()), - (p.dim.as_str(), format!("{} issues", open)), + (p.dim.as_str(), plural(open, "issue")), ], w - 1, )); @@ -1298,7 +1529,7 @@ fn project_detail( rows.push(tc::seg( &[ (p.lbl.as_str(), " ── OPEN BY STATE ── ".into()), - (p.dim.as_str(), format!("{} issues", open)), + (p.dim.as_str(), plural(open, "issue")), ], w - 1, )); @@ -1600,11 +1831,17 @@ fn main() { let asking: Arc<Mutex<HashSet<String>>> = Arc::new(Mutex::new(HashSet::new())); let ui_tok = ui_token.clone(); let ui_quota = Arc::clone("a); - // How many projects the team's screen held when it was last drawn, and - // which one the cursor was on - read by the keys, which run before the - // frame that answers them is built. - let mut projects_len = 0usize; + // How long the open screen's own list was when it was last drawn, and + // what the cursor was on - read by the keys, which run before the frame + // that answers them is built. A team's screen lists its projects and a + // cycle's lists its open issues; only one is ever up, so one length and + // one cursor serve both. + let mut list_len = 0usize; let mut open_project: Option<String> = None; + let mut copy_url: Option<(String, String)> = None; + // What the last copy did, and when - shown for a few seconds on the + // bottom row of whichever screen asked for it. + let (mut note, mut note_at) = (String::new(), 0.0f64); // How far down the board itself is scrolled, and how tall it was when // it was last drawn - the keys run before the frame that answers them. let mut board = 0usize; @@ -1702,17 +1939,33 @@ fn main() { // A team's screen hands the arrows to its project list and // scrolls itself to follow; every other screen has nothing // to select, so they scroll outright. - "up" | "down" if detail == Some(teams_pane) && deep.is_none() => { + // The issue under the cursor, by its address. An issue is + // a leaf here - there is no screen below it - so what it + // offers is somewhere to go and read it. + "c" | "C" if copy_url.is_some() => { + let (url, ident) = copy_url.clone().unwrap_or_default(); + (note, note_at) = if url.is_empty() { + ("that issue has no url".to_string(), now()) + } else if tc::clipboard(&url) { + (format!("copied {}", ident), now()) + } else { + // Said out loud: a copy that silently did nothing + // is indistinguishable from one that worked until + // the paste comes up empty. + ("could not reach the clipboard".to_string(), now()) + }; + } + "up" | "down" if detail.is_some() && deep.is_none() && list_len > 0 => { if key == "down" { - pick = pick.saturating_add(1).min(projects_len.saturating_sub(1)); + pick = pick.saturating_add(1).min(list_len.saturating_sub(1)); } else { pick = pick.saturating_sub(1); } } - "pgup" | "pgdn" if detail == Some(teams_pane) && deep.is_none() => { + "pgup" | "pgdn" if detail.is_some() && deep.is_none() && list_len > 0 => { let page = tc::size().1.saturating_sub(3).max(1); pick = if key == "pgdn" { - pick.saturating_add(page).min(projects_len.saturating_sub(1)) + pick.saturating_add(page).min(list_len.saturating_sub(1)) } else { pick.saturating_sub(page) }; @@ -1967,7 +2220,7 @@ fn main() { (p.dim.as_str(), format!("{} running", s.cycles.len())), ( if here_now { p.accent.as_str() } else { p.dim.as_str() }, - if here_now { " ↑↓".to_string() } else { String::new() }, + heading_keys(cycles_pane, focus, &pane_len).to_string(), ), ], w - 1, @@ -2219,7 +2472,7 @@ fn main() { ), ( if on_teams { p.accent.as_str() } else { p.dim.as_str() }, - if on_teams { " ↑↓".to_string() } else { String::new() }, + heading_keys(teams_pane, focus, &pane_len).to_string(), ), ], w - 1, @@ -2316,7 +2569,7 @@ fn main() { ), ( if on_projects { p.accent.as_str() } else { p.dim.as_str() }, - if on_projects { " ↑↓".to_string() } else { String::new() }, + heading_keys(projects_pane, focus, &pane_len).to_string(), ), ], w - 1, @@ -2418,8 +2671,8 @@ fn main() { .unwrap_or(&none) .clone(); if which == teams_pane { - projects_len = projects.len(); - pick = pick.min(projects_len.saturating_sub(1)); + list_len = projects.len(); + pick = pick.min(list_len.saturating_sub(1)); open_project = projects.get(pick).map(|q| q.id.clone()); } // The project being read is found by its id, so a poll that @@ -2449,13 +2702,20 @@ fn main() { None, ) } else if which == cycles_pane { - ( - ranked_cycles - .get(sel[cycles_pane].min(ranked_cycles.len().saturating_sub(1))) - .map(|c| cycle_detail(c, w, h, &p)) - .unwrap_or_default(), - None, - ) + ranked_cycles + .get(sel[cycles_pane].min(ranked_cycles.len().saturating_sub(1))) + .map(|c| { + let id = text(c, "id"); + let empty = HashMap::new(); + let none: Vec<Issue> = Vec::new(); + let states = s.cycle_state.get(&id).unwrap_or(&empty); + let issues = s.cycle_issues.get(&id).unwrap_or(&none); + list_len = issues.len(); + copy_url = issues.get(pick.min(issues.len().saturating_sub(1))) + .map(|i| (i.url.clone(), i.ident.clone())); + cycle_detail(c, states, issues, pick, w, h, &p) + }) + .unwrap_or_default() } else { team.as_ref() .map(|(key, name)| { @@ -2500,26 +2760,34 @@ fn main() { detail = None; deep = None; } else { - let into = if reading.is_some() { + // What this screen's own list is called, when it has one: + // a team's holds its projects and a cycle's its open + // issues. A screen with an empty list hands the arrows + // back to plain scroll and says so. + let listing = if reading.is_some() || list_len == 0 { None - } else if which == teams_pane && projects_len > 0 { - Some(" open it") + } else if which == teams_pane { + Some(" project") + } else if which == cycles_pane { + Some(" issue") } else { None }; let mut hints: Vec<Vec<(&str, String)>> = vec![vec![ (p.accent.as_str(), "↑↓".into()), - ( - p.dim.as_str(), - if into.is_some() { " project" } else { " scroll" }.into(), - ), + (p.dim.as_str(), listing.unwrap_or(" scroll").to_string()), ]]; - if let Some(what) = into { + // Only a project can be opened; an issue is a leaf, and + // what a leaf offers here is its address. + if listing.is_some() && which == teams_pane { hints.push(vec![ (p.accent.as_str(), "→/↵".into()), - (p.dim.as_str(), what.to_string()), + (p.dim.as_str(), " open it".into()), ]); } + if copy_url.is_some() { + hints.push(vec![(p.dim.as_str(), "[c]opy url".into())]); + } hints.push(vec![ (p.accent.as_str(), "←".into()), ( @@ -2555,6 +2823,11 @@ fn main() { while out.len() < room { out.push(String::new()); } + if !note.is_empty() && now() - note_at < 6.0 { + if let Some(row) = out.last_mut() { + *row = tc::seg(&[(p.ok.as_str(), format!(" {}", note))], w - 1); + } + } out.extend(foot); tc::draw(&out, w, h); std::thread::sleep(Duration::from_millis(300)); @@ -2562,8 +2835,9 @@ fn main() { } } else { drop(s); - projects_len = 0; + list_len = 0; open_project = None; + copy_url = None; deep = None; } @@ -2679,6 +2953,105 @@ mod tests { out } + fn an_issue(ident: &str, title: &str, state: &str, age: f64, points: Option<f64>) -> Issue { + Issue { + ident: ident.into(), + title: title.into(), + url: format!("https://linear.app/x/issue/{}", ident), + state: state.into(), + age, + points, + } + } + + /// A cycle carrying the two histories its screen reads. + fn a_cycle(total: f64, closed: f64) -> serde_json::Value { + serde_json::json!({ + "number": 7, "name": "", "endsAt": "2026-09-06T00:00:00.000Z", + "team": { "name": "A Team" }, + "scopeHistory": [10.0, 10.0], "completedScopeHistory": [0.0, 2.0], + "issueCountHistory": [total, total], "completedIssueCountHistory": [closed, closed], + }) + } + + #[test] + fn a_cycle_lists_what_is_open_in_it_and_counts_what_is_not() { + // The scan behind this fetches open issues only, so a cycle of + // eight with seven closed has one row - and without saying so, a + // heading reading "1" under "issues 8" reads as a bug. + let issues = vec![an_issue("ABC-1", "a thing", "started", 30.0, Some(3.0))]; + let states: HashMap<String, usize> = [("started".to_string(), 1usize)].into_iter().collect(); + let (rows, at) = cycle_detail(&a_cycle(8.0, 7.0), &states, &issues, 0, 110, 40, &palette()); + let out = plain(&rows); + assert!(out.contains("OPEN IN THIS CYCLE"), "{}", out); + assert!(out.contains("7 closed, not listed"), "{}", out); + assert!(out.contains("ABC-1"), "{}", out); + assert!(out.contains("a thing"), "{}", out); + // The state's own vocabulary, the same word the board uses. + assert!(out.contains("in progress"), "{}", out); + assert!(out.contains("3p"), "{}", out); + // And a cursor, on the row it named. + assert!(plain(&[rows[at.unwrap()].clone()]).contains("ABC-1")); + assert_eq!(out.matches('▸').count(), 1); + } + + #[test] + fn a_cycle_with_nothing_open_says_so_and_offers_no_cursor() { + let (rows, at) = + cycle_detail(&a_cycle(4.0, 4.0), &HashMap::new(), &[], 0, 110, 40, &palette()); + let out = plain(&rows); + assert!(out.contains("nothing open in it"), "{}", out); + // No cursor means the arrows go back to scrolling the screen, and + // the footer says "scroll" rather than naming a list to walk. + assert!(at.is_none()); + } + + #[test] + fn a_long_issue_title_carries_on_underneath_rather_than_being_cut() { + // The shape that broke it: a title built from a long chain of + // separated parts, far past any column a list can give it. + let long = "Check every published rate · northern route · via the interchange \ + stop · against the operator's own timetable"; + let issues = vec![an_issue("ABC-1", long, "started", 30.0, None)]; + let states: HashMap<String, usize> = [("started".to_string(), 1usize)].into_iter().collect(); + let (rows, _) = cycle_detail(&a_cycle(1.0, 0.0), &states, &issues, 0, 100, 40, &palette()); + let out = plain(&rows); + // Every word of it is on screen, even though no single row is wide + // enough to hold the title. + for word in long.split_whitespace() { + assert!(out.contains(word), "{:?} missing from:\n{}", word, out); + } + // The issue rows fit in the pane. Measured against `w`, not + // `w - 1`: the heading bar pads to the full width and the rows do + // not, so a single bound for both would pass on the wrong one. + assert!( + out.lines().all(|l| l.chars().count() <= 100), + "a row ran past the pane: {:?}", + out.lines().max_by_key(|l| l.chars().count()) + ); + // An issue nobody has pointed says nothing, not "0p". + assert!(!out.contains("0p"), "{}", out); + } + + #[test] + fn a_cycles_issues_put_what_is_moving_first_and_the_oldest_of_those_first() { + let mut issues = vec![ + an_issue("ABC-3", "newer wip", "started", 10.0, None), + an_issue("ABC-1", "waiting", "unstarted", 900.0, None), + an_issue("ABC-2", "older wip", "started", 500.0, None), + an_issue("ABC-4", "unlooked at", "triage", 999.0, None), + an_issue("ABC-5", "shelved", "backlog", 999.0, None), + ]; + issues.sort_by(|a, b| { + state_rank(&a.state) + .cmp(&state_rank(&b.state)) + .then(b.age.total_cmp(&a.age)) + .then(a.ident.cmp(&b.ident)) + }); + let order: Vec<&str> = issues.iter().map(|i| i.ident.as_str()).collect(); + assert_eq!(order, ["ABC-2", "ABC-3", "ABC-1", "ABC-5", "ABC-4"]); + } + #[test] fn a_team_screen_lists_its_projects_with_their_own_progress() { let counts: HashMap<String, usize> = @@ -2889,6 +3262,37 @@ mod tests { assert!(row.contains('░'), "a 68% bar is not full: {}", row); } + #[test] + fn one_heading_at_a_time_says_tab_and_it_is_the_one_tab_reaches() { + let lens = [5usize, 14, 34]; + let says = |focus: Option<usize>| -> Vec<&'static str> { + (0..3).map(|me| heading_keys(me, focus, &lens)).collect() + }; + // Nothing focused: the first section is where tab goes. + assert_eq!(says(None), [" [tab] to focus", "", ""]); + // Focused: that heading takes the arrows, and the hint moves on to + // the one the next press actually reaches. + assert_eq!(says(Some(0)), [" ↑↓", " [tab] to focus", ""]); + assert_eq!(says(Some(1)), ["", " ↑↓", " [tab] to focus"]); + // From the last, tab lets go - so no heading claims it. + assert_eq!(says(Some(2)), ["", "", " ↑↓"]); + // Never two at once, whatever the focus. + for focus in [None, Some(0), Some(1), Some(2)] { + assert_eq!( + says(focus).iter().filter(|h| h.contains("[tab]")).count() <= 1, + true, + "two headings claimed tab with focus {:?}", + focus + ); + } + // A section with nothing in it never claims it, because tab steps + // over it - a hint on a heading no press reaches is the thing this + // is careful about. + let gap = [5usize, 0, 34]; + assert_eq!(heading_keys(1, Some(0), &gap), ""); + assert_eq!(heading_keys(2, Some(0), &gap), " [tab] to focus"); + } + #[test] fn the_board_walks_three_sections_and_lets_go_only_at_the_ends() { // Cycles, teams, then the board's own project list, in the order diff --git a/rust/widgets/src/bin/netwatch.rs b/rust/widgets/src/bin/netwatch.rs index 25a8d34..7f298f5 100644 --- a/rust/widgets/src/bin/netwatch.rs +++ b/rust/widgets/src/bin/netwatch.rs @@ -1058,6 +1058,7 @@ fn section_head( count: usize, note: &str, focused: bool, + next: bool, w: usize, p: &Palette, ) -> String { @@ -1071,12 +1072,17 @@ fn section_head( p.dim.as_str(), format!("{} {}{}", count, note, if count == 1 { "" } else { "s" }), ), - // No key named here. There is one way between sections and the - // footer says what it is; a letter per heading meant [e] and [f] - // pointing at keys that no longer exist and the middle section - // pointing at tab, which is the only one that was ever true. - // The ▏ at the head of the line is the focus mark; a second one - // out here was just the hole the key left. + // One key, on the one heading it is true of. This used to name + // a letter per section - [e] and [f] pointing at keys that no + // longer existed, and the middle one pointing at tab, which was + // the only one that was ever true. So tab is what is left, and + // it is shown only on the section tab would actually focus + // next: it cycles, and a [tab] on all three would promise three + // sections that one press reaches. + ( + p.accent.as_str(), + if next { " [tab] to focus".to_string() } else { String::new() }, + ), ], w - 1, ) @@ -1460,7 +1466,8 @@ fn detail_rows( .enumerate() { let focused = focus == Some(which); - out.push(section_head(name, counts[which], note, focused, w, p)); + let next = tc::next_section(focus, &counts) == Some(which); + out.push(section_head(name, counts[which], note, focused, next, w, p)); let room = shares[which]; if counts[which] == 0 { out.push(tc::seg(&[(p.dim.as_str(), " none".into())], w - 1)); From 63e9959445a316cb8d765f35ae383a28264e8d41 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Tue, 25 Aug 2026 17:54:34 +0800 Subject: [PATCH 104/147] ports: name the program that is running, not the directory it sits in Found by running the two implementations side by side, which is what they are both kept for. The Python asks whether a command line *runs* node or python - `[/ ]node(\s|$)` and `[/ ]python[0-9.]*(\s|$)`. The port turned every entry in that table into a plain substring test, and the two anchored ones lost their anchors. Any program installed under a directory with `node` or `python` in its path then answered to the wrong name. On this machine a standalone browser binary that npm had put in `node_modules` was listed as "Node" - the runtime it is not written in - while the Python named it correctly. Anything under `node_modules`, under a version manager's `versions/node/...`, or in a `python-tools` directory had the same problem. So the two runtimes move to their own table and are matched by whether they are the command being run: the last path segment of some word on the line, allowing a trailing version, which is what the `[0-9.]*` was for. The rest of the table keeps the substring test, because the rest of it is looking for substrings - `manage.py`, `node_modules/.bin/vite` - and matches the Python as it stands. Both implementations then had a second fault, which the first was hiding. The WHAT column was a flat eighteen cells with no gap after it, so a name of exactly that length ran into the project name and the two read as one word, and anything longer was cut - and a program name cut short is a different program. It was only ever visible in the Python because only the Python produced a name that long. Both now size that column to the widest name in the list, with a gap, and the project column takes what is left. Sized over the whole list rather than the visible slice, so the columns do not shift as it scrolls. The first test of this passed against the bug: it exercised the new predicate while the table still called `contains`. The one that counts goes through `kind_of`, and was watched failing with the old line restored. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- ports.py | 16 ++++-- rust/widgets/src/bin/ports.rs | 97 ++++++++++++++++++++++++++++++++--- 2 files changed, 103 insertions(+), 10 deletions(-) diff --git a/ports.py b/ports.py index 303efc7..bb78f93 100755 --- a/ports.py +++ b/ports.py @@ -1292,9 +1292,19 @@ def main(): # The project column takes whatever the fixed ones leave, because it # is the one that identifies the server and the one whose contents # are a directory name of any length. - fixed = 1 + 6 + 8 + 18 + (6 + 8 if wide else 0) + # The WHAT column takes the widest name it has to show, plus a gap. + # It used to be a flat eighteen with nothing after it, so a name of + # exactly that length ran straight into the project and the two read + # as one word - and anything longer was cut, which names a different + # program. Sized to the whole list rather than the visible slice, so + # the columns do not shift as it scrolls. + rest = 1 + 6 + 8 + 2 + 8 + (6 + 8 if wide else 0) + widest = max([len(r["kind"] or "") for r in shown] or [0]) + kind_w = max(4, min(widest, max(4, (w - 1) - rest))) + fixed = 1 + 6 + 8 + kind_w + 2 + (6 + 8 if wide else 0) name_w = max(8, (w - 1) - fixed) - rows.append(seg([(DIM, " PORT BIND WHAT "), + rows.append(seg([(DIM, " PORT BIND "), + (DIM, pad("WHAT", kind_w) + " "), (DIM, pad("PROJECT", name_w)), (DIM, "UP EXPOSED" if wide else "")], w - 1)) visible = max(1, h - len(rows) - 3) @@ -1319,7 +1329,7 @@ def main(): ("▸" if here else " ") + "%-6d" % row["port"]), (tint + note_colour, "%-8s" % note), (tint + (DIM if row["guessed"] or not row["kind"] else TXT), - pad(row["kind"], 18)), + pad(row["kind"], kind_w) + " "), (tint + (WARN if row["gone"] else DIM if row.get("user") else TXT), pad(who, name_w))] diff --git a/rust/widgets/src/bin/ports.rs b/rust/widgets/src/bin/ports.rs index ddf6b30..8eba381 100644 --- a/rust/widgets/src/bin/ports.rs +++ b/rust/widgets/src/bin/ports.rs @@ -77,10 +77,34 @@ const KINDS: &[(&str, &str)] = &[ ("tailscaled", "Tailscale"), ("sshd", "SSH"), ("systemd-resolve", "DNS"), - ("python", "Python"), - ("node", "Node"), ]; +/// The two that are runtimes rather than programs, and so have to be the +/// command being run rather than a word anywhere in its path. +/// +/// The Python anchors these - `[/ ]node(\s|$)` and `[/ ]python[0-9.]*(\s|$)` +/// - and the port flattened both to a plain substring. Every binary that +/// lives under a directory with `node` or `python` in it then answered to +/// the wrong name: a standalone tool installed into `node_modules` was +/// listed as "Node", which is the runtime it is not written in. +const RUNTIMES: &[(&str, &str)] = &[("python", "Python"), ("node", "Node")]; + +/// Whether a command line actually runs `name`, rather than merely passing +/// through a directory called that. +/// +/// A trailing version is part of the name - `python3`, `python3.11` - which +/// is what the `[0-9.]*` in the Python's pattern is for. +fn runs_command(cmdline: &str, name: &str) -> bool { + cmdline.split_whitespace().any(|word| { + let base = word.rsplit('/').next().unwrap_or(word); + match base.strip_prefix(name) { + Some("") => true, + Some(tail) => tail.chars().all(|c| c.is_ascii_digit() || c == '.'), + None => false, + } + }) +} + /// Ports whose owner is usually root, so /proc will not say what it is. /// Naming them by convention is a guess, and is marked as one. const BY_PORT: &[(u16, &str)] = &[ @@ -370,8 +394,12 @@ fn json_string(text: &str, key: &str) -> Option<String> { /// What sort of server this is, from the process itself. fn kind_of(cmdline: &str, port: u16) -> (String, bool) { if !cmdline.is_empty() { - for (needle, name) in KINDS { - if cmdline.contains(needle) { + for (needle, name) in KINDS.iter().chain(RUNTIMES) { + if if RUNTIMES.iter().any(|(n, _)| n == needle) { + runs_command(cmdline, needle) + } else { + cmdline.contains(needle) + } { // Next.js rewrites its own title to next-server (v16.3.0), // which hands over the framework and the version at once. if let Some(version) = version_in(cmdline) { @@ -2030,11 +2058,25 @@ fn main() { // The project column takes whatever the fixed ones leave: it is the // one that identifies the server, and the one whose contents are a // directory name of any length. - let fixed = 1 + 6 + 8 + 18 + if wide { 6 + 8 } else { 0 }; + // The WHAT column takes the widest name it has to show, plus a gap. + // It used to be a flat eighteen with nothing after it, so a name of + // exactly that length ran straight into the project and the two read + // as one word - and anything longer was cut, which names a different + // program. Sized to the whole list rather than the visible slice, so + // the columns do not shift as it scrolls. + let rest = 1 + 6 + 8 + 2 + 8 + if wide { 6 + 8 } else { 0 }; + let kind_w = shown + .iter() + .map(|r| r.kind.chars().count()) + .max() + .unwrap_or(0) + .clamp(4, (w - 1).saturating_sub(rest).max(4)); + let fixed = 1 + 6 + 8 + kind_w + 2 + if wide { 6 + 8 } else { 0 }; let name_w = std::cmp::max(8, (w - 1).saturating_sub(fixed)); rows.push(tc::seg( &[ - (ok.dim.as_str(), " PORT BIND WHAT ".into()), + (ok.dim.as_str(), " PORT BIND ".into()), + (ok.dim.as_str(), format!("{} ", tc::pad("WHAT", kind_w))), (ok.dim.as_str(), tc::pad("PROJECT", name_w)), ( ok.dim.as_str(), @@ -2096,7 +2138,7 @@ fn main() { format!("{}{:<6}", if here { "▸" } else { " " }, row.port), ), (note_c.as_str(), format!("{:<8}", note)), - (kind_c.as_str(), tc::pad(&row.kind, 18)), + (kind_c.as_str(), format!("{} ", tc::pad(&row.kind, kind_w))), (who_c.as_str(), tc::pad(&who, name_w)), ]; let up_c = format!("{}{}", tint, ok.dim); @@ -2208,6 +2250,47 @@ fn bind_note(row: &Row, p: &Palette) -> (String, String) { mod tests { use super::*; + #[test] + fn a_binary_living_under_a_runtimes_path_is_not_that_runtime() { + // Through `kind_of`, not the helper alone: an earlier version of + // this test passed with the table still calling `contains`, which + // is the bug it was written for. + // + // A real one from this machine: a standalone browser binary that + // npm installed into node_modules. It is not written in Node and + // the widget said "Node". + let under = "/home/u/.nvm/versions/node/v24.18.0/lib/node_modules/agent-browser/bin/agent-browser-linux-x64"; + assert_eq!(kind_of(under, 37397).0, "agent-browser-linux-x64"); + assert_eq!(kind_of("/srv/python-tools/bin/collector", 9000).0, "collector"); + + // The runtimes themselves still answer to their names. + assert_eq!(kind_of("/usr/bin/node server.js", 3000).0, "Node"); + assert_eq!(kind_of("/usr/bin/python3 app.py", 8000).0, "Python"); + + // And the specific frameworks still win over the runtime, which is + // the order the table is written in. + assert_eq!(kind_of("node /app/node_modules/.bin/vite", 5173).0, "Vite"); + } + + #[test] + fn a_runtime_is_named_only_when_it_is_the_thing_being_run() { + // The command really is the runtime. + assert!(runs_command("/usr/bin/node server.js", "node")); + assert!(runs_command("node server.js", "node")); + assert!(runs_command("/usr/bin/python3 app.py", "python")); + assert!(runs_command("/usr/bin/python3.11 -m http.server", "python")); + + // A directory on the way to something else is not. This is the + // whole bug: a standalone binary installed under node_modules was + // listed as "Node", the runtime it is not written in. + assert!(!runs_command("/usr/lib/node_modules/x/bin/mytool", "node")); + assert!(!runs_command("/home/u/.nvm/versions/node/v24/bin/agent-browser-linux-x64", "node")); + assert!(!runs_command("/srv/python-tools/bin/collector", "python")); + // And a name that merely starts the same way is a different name. + assert!(!runs_command("/usr/bin/nodemon app.js", "node")); + assert!(!runs_command("/usr/bin/python-config", "python")); + } + #[test] fn ipv6_comes_out_of_little_endian_words() { // ::1 as /proc/net/tcp6 writes it: four words, each reversed. From ee4e90c7ab36774f63f2f2f97c2af50743140b00 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Tue, 25 Aug 2026 17:56:23 +0800 Subject: [PATCH 105/147] ports: the footer names the arrow that has always opened a port MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Python answers `enter`, `right` and `i` for the detail screen and its footer named only the return. The Rust answers `enter` and `right` and says `→/↵`, which is where this came from - the two were compared side by side and the footers did not match. `check.py` catches a hint naming a key nothing answers. It cannot catch the other direction, and this is that direction: a key that works and is not on screen is a feature nobody finds. `i` is left alone and still undocumented in either. The Rust has no such key and dropping one from the Python is a decision rather than a fix. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- docs/ports.md | 4 ++-- ports.py | 5 ++++- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/ports.md b/docs/ports.md index 2074597..5570f03 100644 --- a/docs/ports.md +++ b/docs/ports.md @@ -148,7 +148,7 @@ never a dev server. Neither case is offered a prompt. ## The second screen -`↵` opens the selected port, and only when there is something behind it — a +`↵` or `→` opens the selected port, and only when there is something behind it — a process of yours, or a port Tailscale is already serving. Another user's socket does not get a screen, because the four columns already carry everything `/proc` will say about it, and a press that opens a repeat of the @@ -288,7 +288,7 @@ are on this screen rather than an IP. | Key | Action | |---|---| | `↑` `↓` | select a row — or an address, on the second screen | -| `↵` | open the selected port, where there is more to show | +| `↵` `→` | open the selected port, where there is more to show | | `esc` | back to the list | | `c` | copy the highlighted address | | `s` | `tailscale serve` this port, or stop serving it | diff --git a/ports.py b/ports.py index bb78f93..cdfb267 100755 --- a/ports.py +++ b/ports.py @@ -1345,7 +1345,10 @@ def main(): foot = footer(confirm, watch, working, notice, w, [[(ACCENT, "↑↓"), (DIM, " select")], - [(ACCENT, "↵"), (DIM, " details")], [(DIM, "[k]ill")], + # The right arrow has always opened it too, and the + # footer only ever named the return. A key that works + # and is not on screen is a feature nobody finds. + [(ACCENT, "→/↵"), (DIM, " details")], [(DIM, "[k]ill")], [(DIM, "[o]%s system" % ("show" if hide_system else "hide"))], [(DIM, "[r]efresh")], [(DIM, "[q]uit")]]) From 37f77011e537ae4d9e5d365cd085c3f6de102dc1 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Tue, 25 Aug 2026 18:40:41 +0800 Subject: [PATCH 106/147] ports: what has actually gone through each port MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A TRAFFIC column on the table and a chart on a port's own screen, from the kernel's own per-socket byte counters - `bytes_sent` and `bytes_received` out of `ss -tine`, the same two fields netwatch reads. Nothing here is derived from a guess. A listening socket carries no bytes. The traffic is on the connections accepted from it, so a port's figure is summed over every established socket whose *local* port is that one. Only ports something is listening on are tallied: most established sockets are outbound and their local port is an ephemeral number that belongs to nothing. The parsing is netwatch's, the filtering deliberately is not. netwatch drops loopback peers because it is about what leaves the machine; here loopback is the whole point, since a browser hitting a dev server on the loopback address is the traffic being asked about. Taking that filter with the parser would have flatlined every dev server and made "no traffic" and "filtered out" look identical - which is this widget's founding gotcha, drawn as a chart. Four things the accumulator has to get right, and each has a test that was watched failing: A socket has to be seen twice to say anything. Counted from one sample it would report its whole lifetime as one interval - a new connection to a busy port arriving as a spike of everything it has ever carried. Inodes come back after a socket closes. The new socket's counters start again, so the same inode on a different port is a different socket and the subtraction is meaningless. A counter that goes backwards clamps rather than wrapping to sixteen exabytes. Rates divide by the gap that actually happened. `[r]` polls early, and a rate measured against the nominal interval reads high every time somebody presses it, so each sample carries its own elapsed time. History is bounded and ports that stop listening are forgotten, or the map grows for as long as the widget is up. Sampling rides the existing poll rather than a thread of its own. A second thread would buy a finer chart and would also have to be watched, and `-n 1` already exists for anyone who wants the resolution. On screen: each direction scaled to its own peak and saying what that peak was, because a shared scale flattens the quieter one into nothing and nothing is what a dead source looks like. The rule under the bars is as wide as the bars, not as wide as the pane. A direction that has not moved gets no "peak -", a quiet port gets no "0 B/s", and a port serving a download reads "↑820K" rather than "↑820K ↓0B". The column appears at 96 columns and above. Verified end to end against a server on a known port with a rate-limited load through it, and against a socket that only reads, which is the only way to see the downward half drawn at all. Rust only. The Python stays the fidelity baseline it has been since netwatch. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- docs/ports.md | 61 ++++- rust/widgets/src/bin/ports.rs | 492 +++++++++++++++++++++++++++++++++- 2 files changed, 547 insertions(+), 6 deletions(-) diff --git a/docs/ports.md b/docs/ports.md index 5570f03..ba9d544 100644 --- a/docs/ports.md +++ b/docs/ports.md @@ -79,6 +79,56 @@ pointing at it and nothing behind it — the URL exists, answers 502, and nothing in `lsof` explains why. It gets its own row rather than being left out for lacking a socket. +## Traffic + +The **TRAFFIC** column, and the chart on a port's own screen, come from the +kernel's own per-socket byte counters — `bytes_sent` and `bytes_received` out +of `ss -tine`, the same two fields netwatch reads. Nothing here is derived +from a guess. + +A *listening* socket carries no bytes. The traffic is on the connections +accepted from it, so a port's figure is the sum over every established socket +whose **local** port is that one. Only ports something is actually listening +on are tallied: most established sockets are outbound, and their local port is +an ephemeral number that belongs to nothing. + +``` + ── TRAFFIC ── ↑ out above · ↓ in below · 52s of history, sampled every 1s + ▃▁ █▁▄▃▂ ▃▃▅ ▂▄▂▇▄ peak 15.1 MB/s + ▁▆██▇█████▅███▇█████▆▁ + ▁██████████████████████▆ + ──────────────────────────────────────────── +``` + +Each direction is scaled to its own peak and says what that peak was. A shared +scale would flatten the quieter of the two into nothing, and nothing is what a +source with no traffic looks like — the one reading this widget must never +produce by accident. + +Three things it is honest about: + +**It counts what moved between two samples,** so a socket has to be seen twice +to say anything. A connection that opens and closes inside one interval is +never counted, and a long-lived one loses its last few bytes when it closes. +At the default four-second poll that is a real gap; `-n 1` narrows it. + +**Rates divide by the gap that actually happened,** not by the interval that +was asked for. `[r]` polls early, and a rate measured against the nominal +interval would read high every time somebody pressed it. + +**It is TCP.** A port serving anything else reads as quiet, because these +counters exist only for TCP sockets. Ports whose process belongs to another +user are counted the same as any other — the byte counters need no privilege, +even where naming the process does. + +Unlike netwatch, nothing is filtered by peer. netwatch drops loopback because +it is about what leaves the machine; here loopback is the whole point, since a +browser hitting a dev server on `127.0.0.1` is the traffic being asked about. + +The column appears at 96 columns and above, and a port nothing is calling +shows nothing rather than `0 B/s` — a column of zeroes down the table reads as +a measurement that has failed. + ## What it cannot see Sockets owned by another user, which on a normal machine means everything root @@ -303,9 +353,14 @@ are on this screen rather than an IP. ## Cost Nothing measurable. `/proc/net/tcp` and a walk of `/proc/*/fd` every four -seconds, plus one `tailscale serve status` — no network, no root, no -dependency beyond Tailscale for the exposure column, which is simply blank -without it. +seconds, one `ss -tine` for the byte counters, plus one `tailscale serve +status` — no network, no root, no dependency beyond Tailscale for the exposure +column, which is simply blank without it. + +The traffic sampling rides that same poll rather than a thread of its own. A +second thread would buy a finer chart and would also have to be watched: a +poller that dies is invisible, and its pane is indistinguishable from a source +with nothing to say. ## Configuration diff --git a/rust/widgets/src/bin/ports.rs b/rust/widgets/src/bin/ports.rs index 8eba381..fba2a49 100644 --- a/rust/widgets/src/bin/ports.rs +++ b/rust/widgets/src/bin/ports.rs @@ -26,7 +26,7 @@ //! Keys: up/down select, o hides the machine's own ports, r refreshes, //! q quits. -use std::collections::HashMap; +use std::collections::{HashMap, VecDeque}; use std::sync::{Arc, Condvar, Mutex}; use std::time::{Duration, SystemTime, UNIX_EPOCH}; @@ -51,6 +51,311 @@ fn is_system_port(port: u16) -> bool { } } +/// Per-port traffic, sample by sample. +/// +/// Each entry is one poll's worth: bytes out, bytes in, and how long the +/// gap to the previous sample actually was. The elapsed time is recorded +/// rather than assumed, because `[r]` polls early and a rate computed +/// against the nominal interval would read high every time someone pressed +/// it. +#[derive(Default)] +struct Traffic { + last: HashMap<String, Counters>, + at: f64, + seen: HashMap<u16, VecDeque<(u64, u64, f64)>>, +} + +impl Traffic { + /// Fold one sample in, and forget ports nothing is listening on. + fn sample(&mut self, text: &str, listening: &[u16], at: f64) { + let now = socket_counters(text); + let gap = at - self.at; + // The first sample has nothing to subtract from, and a gap of zero + // would divide a rate by nothing. + if self.at > 0.0 && gap > 0.0 { + let moved_now = moved(&self.last, &now, listening); + for &port in listening { + let (up, down) = moved_now.get(&port).copied().unwrap_or((0, 0)); + let ring = self.seen.entry(port).or_default(); + ring.push_back((up, down, gap)); + while ring.len() > TRAFFIC_KEPT { + ring.pop_front(); + } + } + } + self.seen.retain(|port, _| listening.contains(port)); + self.last = now; + self.at = at; + } + + /// The most recent sample as a rate, in bytes per second. + fn rate(&self, port: u16) -> Option<(f64, f64)> { + let (up, down, gap) = *self.seen.get(&port)?.back()?; + (gap > 0.0).then(|| (up as f64 / gap, down as f64 / gap)) + } + + /// Every kept sample as a rate, oldest first, for the chart. + fn series(&self, port: u16) -> Vec<(f64, f64)> { + self.seen + .get(&port) + .map(|ring| { + ring.iter() + .filter(|(_, _, gap)| *gap > 0.0) + .map(|(up, down, gap)| (*up as f64 / gap, *down as f64 / gap)) + .collect() + }) + .unwrap_or_default() + } + + /// How long the kept samples reach back. + fn span(&self, port: u16) -> f64 { + self.seen + .get(&port) + .map(|ring| ring.iter().map(|(_, _, gap)| gap).sum()) + .unwrap_or(0.0) + } +} + +/// How many samples of per-port traffic to keep, which is what the chart +/// on a port's own screen is drawn from. At the default four-second poll +/// that is a little over six minutes. +const TRAFFIC_KEPT: usize = 100; + +/// One TCP socket's byte counters, as the kernel has them. +/// +/// Keyed by inode because that is what identifies a socket across samples. +/// The port is the *local* one: traffic to a listening port arrives on the +/// connections accepted from it, and the listening socket itself carries +/// none. +#[derive(Clone, Copy, Default, PartialEq, Debug)] +struct Counters { + port: u16, + sent: u64, + recv: u64, +} + +/// Every TCP socket's byte counters, keyed by inode. +/// +/// `-i` for the counters, `-e` for the inode - the same two flags netwatch +/// asks for, and the same two-line shape: addresses and inode, then the +/// counters on an indented continuation. +/// +/// Unlike netwatch this filters nothing. netwatch drops loopback peers +/// because it is about what leaves the machine; here the loopback peers are +/// the whole point, since a browser hitting a dev server on 127.0.0.1 is +/// the traffic being asked about. +fn socket_counters(text: &str) -> HashMap<String, Counters> { + let mut found = HashMap::new(); + let (mut inode, mut port) = (None, 0u16); + for (i, line) in text.lines().enumerate() { + if i == 0 && line.starts_with("State") { + continue; + } + if !line.starts_with(' ') && !line.starts_with('\t') { + let cols: Vec<&str> = line.split_whitespace().collect(); + // Column 3 is our address, and its port is the one a listener + // would be on. + port = cols + .get(3) + .and_then(|a| a.rsplit_once(':')) + .and_then(|(_, p)| p.parse().ok()) + .unwrap_or(0); + inode = counter_field(line, "ino:").filter(|v| v != "0"); + continue; + } + let Some(id) = inode.take() else { continue }; + found.insert( + id, + Counters { + port, + sent: counter_field(line, "bytes_sent:") + .and_then(|v| v.parse().ok()) + .unwrap_or(0), + recv: counter_field(line, "bytes_received:") + .and_then(|v| v.parse().ok()) + .unwrap_or(0), + }, + ); + } + found +} + +/// The value after `key:` on a line, up to the next space. +fn counter_field(line: &str, key: &str) -> Option<String> { + let at = line.find(key)? + key.len(); + let rest = &line[at..]; + let end = rest.find(char::is_whitespace).unwrap_or(rest.len()); + Some(rest[..end].to_string()).filter(|v| !v.is_empty()) +} + +/// What moved on each listening port between two samples. +/// +/// Only sockets present in *both* count. A socket that appeared since the +/// last sample has no previous total to subtract, and one that closed took +/// its last few bytes with it - said out loud in the doc rather than +/// guessed at here. +/// +/// Inodes are reused after a socket closes, so a raw subtraction can go +/// negative; it is clamped rather than wrapped. And only ports something is +/// actually listening on are tallied, because most established sockets are +/// outbound and their local port is an ephemeral one that means nothing. +fn moved( + before: &HashMap<String, Counters>, + now: &HashMap<String, Counters>, + listening: &[u16], +) -> HashMap<u16, (u64, u64)> { + let mut out: HashMap<u16, (u64, u64)> = HashMap::new(); + for (id, c) in now { + if !listening.contains(&c.port) { + continue; + } + let Some(was) = before.get(id) else { continue }; + // A reused inode is a different socket wearing the same name; its + // counters start again and the subtraction is meaningless. + if was.port != c.port { + continue; + } + let slot = out.entry(c.port).or_default(); + slot.0 += c.sent.saturating_sub(was.sent); + slot.1 += c.recv.saturating_sub(was.recv); + } + out +} + +/// A rate in as few cells as it can be read in, for a table column. +/// +/// One significant figure and a single-letter unit: five cells at most, so +/// two of them and their arrows fit in thirteen. +fn brief(n: f64) -> String { + for (suffix, scale) in [("G", 1e9), ("M", 1e6), ("K", 1e3)] { + if n >= scale { + let v = n / scale; + return if v < 10.0 { + format!("{:.1}{}", v, suffix) + } else { + format!("{:.0}{}", v, suffix) + }; + } + } + format!("{:.0}B", n) +} + +/// A byte count at whatever unit keeps it readable. +fn units(n: f64) -> String { + for (suffix, scale) in [("GB", 1e9), ("MB", 1e6), ("KB", 1e3)] { + if n >= scale { + return format!("{:.1} {}", n / scale, suffix); + } + } + format!("{} B", n as i64) +} + +fn rate_of(n: f64) -> String { + if n > 0.0 { + format!("{}/s", units(n)) + } else { + "-".into() + } +} + +/// A span at whatever unit keeps it readable. +fn over(seconds: f64) -> String { + let s = seconds as i64; + if s < 60 { + format!("{}s", s) + } else if s < 3600 { + format!("{}m", s / 60) + } else { + format!("{}h{}m", s / 3600, (s % 3600) / 60) + } +} + +/// Traffic on one port over time: out above the line, in below it. +/// +/// Each direction is scaled to its own peak and each says what that peak +/// was, so a quiet direction is still readable beside a busy one. A shared +/// scale would flatten the smaller of the two into nothing and it would +/// look like no traffic at all. +fn traffic_chart(series: &[(f64, f64)], span: f64, gap: f64, w: usize, p: &Palette) -> Vec<String> { + let plot = (w - 1).saturating_sub(4).max(12); + // The most recent `plot` samples, oldest on the left. + let window: Vec<(f64, f64)> = series.iter().rev().take(plot).rev().copied().collect(); + let up: Vec<f64> = window.iter().map(|s| s.0).collect(); + let down: Vec<f64> = window.iter().map(|s| s.1).collect(); + let up_peak = up.iter().copied().fold(0.0f64, f64::max); + let down_peak = down.iter().copied().fold(0.0f64, f64::max); + + let mut out = vec![tc::seg( + &[ + (p.lbl.as_str(), " ── TRAFFIC ── ".into()), + (p.open.as_str(), "↑ out above".into()), + (p.dim.as_str(), " · ".into()), + (p.local.as_str(), "↓ in below".into()), + // The window is named, because a chart of an unnamed window is + // a shape rather than a measurement. + ( + p.dim.as_str(), + format!(" · {} of history, sampled every {}", over(span), over(gap)), + ), + ], + w - 1, + )]; + if window.iter().all(|(a, b)| *a == 0.0 && *b == 0.0) { + out.push(tc::seg( + &[( + p.dim.as_str(), + if series.is_empty() { + " waiting for a second sample".into() + } else { + " nothing has moved on it".to_string() + }, + )], + w - 1, + )); + return out; + } + + let bars = |values: &[f64], colour: &str, peak: f64, down: bool| -> Vec<Vec<(String, String)>> { + let cols: Vec<(f64, String)> = + values.iter().map(|v| (*v, colour.to_string())).collect(); + if down { + tc::vbars_down(&cols, 3, peak) + } else { + tc::vbars(&cols, 3, peak) + } + }; + // The peak is written beside the top row of each half, which is the + // row it belongs to: the tallest bar there is that number. + // The peak is written beside the top row of each half, which is the row + // it belongs to - and only when that direction has moved, because "peak + // -" is four cells spent saying nothing happened. + let drawn = |rows: Vec<Vec<(String, String)>>, peak: f64, colour: &str| -> Vec<String> { + rows.into_iter() + .enumerate() + .map(|(i, row)| { + let mut line: Vec<(&str, String)> = vec![(tc::RST, " ".into())]; + for (c, t) in &row { + line.push((c.as_str(), t.clone())); + } + if i == 0 && peak > 0.0 { + line.push((colour, format!(" peak {}", rate_of(peak)))); + } + tc::seg(&line, w - 1) + }) + .collect() + }; + out.extend(drawn(bars(&up, &p.open, up_peak, false), up_peak, p.open.as_str())); + // As wide as the bars actually are, not as wide as they could have been: + // there is one column per sample, and until the history fills the pane a + // full-width rule would sit under nothing. + out.push(tc::seg( + &[(p.grid.as_str(), format!(" {}", "─".repeat(window.len().max(1))))], + w - 1, + )); + out.extend(drawn(bars(&down, &p.local, down_peak, true), down_peak, p.local.as_str())); + out +} + /// Process titles worth recognising, first match winning, so the specific /// ones come before `node` and `python`. const KINDS: &[(&str, &str)] = &[ @@ -1339,12 +1644,16 @@ fn expose_options( /// The second screen: everything known about one port, and what to do. #[allow(clippy::too_many_arguments)] +#[allow(clippy::too_many_arguments)] fn detail_rows( row: &Row, net: &Net, tunnel: &Option<Tunnel>, links: &[(String, String)], sel: usize, + seen: &[(f64, f64)], + reach: f64, + gap: f64, w: usize, p: &Palette, ) -> Vec<String> { @@ -1415,6 +1724,11 @@ fn detail_rows( w - 1, )); rows.push(String::new()); + // What has actually gone through it. The kernel's own per-socket byte + // counters, summed over the connections accepted from this port - so + // this is TCP, and a port serving anything else reads as quiet. + rows.extend(traffic_chart(seen, reach, gap, w, p)); + rows.push(String::new()); rows.push(tc::seg( &[ (p.lbl.as_str(), " ── REACHABLE AT ── ".into()), @@ -1640,6 +1954,11 @@ fn footer( struct Store { rows: Mutex<Vec<Row>>, + /// What has moved on each listening port, sampled by the same poll that + /// finds the ports. One `ss` call per scan rather than a second thread: + /// a thread that dies is invisible, and this needs no finer resolution + /// than the table it sits under. + traffic: Mutex<Traffic>, // [r] asks for a scan now rather than at the end of the interval, and // so does anything that has just changed what a scan would find. wake: (Mutex<bool>, Condvar), @@ -1682,6 +2001,7 @@ fn main() { let ok = rgb_ok(); let store = Arc::new(Store { rows: Mutex::new(Vec::new()), + traffic: Mutex::new(Traffic::default()), wake: (Mutex::new(false), Condvar::new()), }); let poller = Arc::clone(&store); @@ -1690,9 +2010,17 @@ fn main() { // caught rather than left to unwind: an empty table would look // exactly like a machine with nothing listening. let found = std::panic::catch_unwind(scan).unwrap_or_default(); + // The ports to tally against, taken from the scan that just ran, so + // a port that has just appeared is measured from its next sample + // rather than never. + let listening: Vec<u16> = found.iter().filter(|r| !r.gone).map(|r| r.port).collect(); + let counters = std::panic::catch_unwind(|| run(&["ss", "-tine"])).unwrap_or_default(); if let Ok(mut guard) = poller.rows.lock() { *guard = found; } + if let Ok(mut guard) = poller.traffic.lock() { + guard.sample(&counters, &listening, now()); + } let (lock, cond) = &poller.wake; let mut asked = match lock.lock() { Ok(g) => g, @@ -1995,12 +2323,20 @@ fn main() { .push((t.url.clone(), "public · cloudflare".to_string())); } view.at = view.at.min(view.links.len().saturating_sub(1)); + let (seen, span) = store + .traffic + .lock() + .map(|t| (t.series(view.port), t.span(view.port))) + .unwrap_or_default(); let mut rows = detail_rows( &view.row, self_node, &view.tunnel, &view.links, view.at, + &seen, + span, + refresh, w, &ok, ); @@ -2055,6 +2391,11 @@ fn main() { rows.push(String::new()); let wide = w >= 78; + // The traffic column is the first thing to go and the last to + // arrive: it is the only one that is not about what the port *is*. + // Its two rates are eleven cells plus a gap. + let rates = store.traffic.lock().ok(); + let busy = w >= 96 && rates.is_some(); // The project column takes whatever the fixed ones leave: it is the // one that identifies the server, and the one whose contents are a // directory name of any length. @@ -2064,20 +2405,25 @@ fn main() { // as one word - and anything longer was cut, which names a different // program. Sized to the whole list rather than the visible slice, so // the columns do not shift as it scrolls. - let rest = 1 + 6 + 8 + 2 + 8 + if wide { 6 + 8 } else { 0 }; + let traffic_w = if busy { 13 } else { 0 }; + let rest = 1 + 6 + 8 + 2 + 8 + traffic_w + if wide { 6 + 8 } else { 0 }; let kind_w = shown .iter() .map(|r| r.kind.chars().count()) .max() .unwrap_or(0) .clamp(4, (w - 1).saturating_sub(rest).max(4)); - let fixed = 1 + 6 + 8 + kind_w + 2 + if wide { 6 + 8 } else { 0 }; + let fixed = 1 + 6 + 8 + kind_w + 2 + traffic_w + if wide { 6 + 8 } else { 0 }; let name_w = std::cmp::max(8, (w - 1).saturating_sub(fixed)); rows.push(tc::seg( &[ (ok.dim.as_str(), " PORT BIND ".into()), (ok.dim.as_str(), format!("{} ", tc::pad("WHAT", kind_w))), (ok.dim.as_str(), tc::pad("PROJECT", name_w)), + ( + ok.dim.as_str(), + if busy { tc::pad("TRAFFIC", traffic_w) } else { String::new() }, + ), ( ok.dim.as_str(), if wide { "UP EXPOSED".into() } else { String::new() }, @@ -2132,6 +2478,28 @@ fn main() { &ok.txt } ); + // Nothing rather than "0 B/s" on a quiet port: a column of + // zeroes down the table reads as a measurement that has failed, + // and this one is just a port nobody is calling. + let (up, down) = rates + .as_ref() + .and_then(|t| t.rate(row.port)) + .unwrap_or((0.0, 0.0)); + let moving = up > 0.0 || down > 0.0; + // Each direction only when it has moved. A port serving a + // download reads "↑820K", not "↑820K ↓0B" - the second half + // would be four cells saying nothing happened. + let traffic_text = if busy && moving { + [(up, "↑"), (down, "↓")] + .into_iter() + .filter(|(v, _)| *v > 0.0) + .map(|(v, arrow)| format!("{}{}", arrow, brief(v))) + .collect::<Vec<_>>() + .join(" ") + } else { + String::new() + }; + let traffic_c = format!("{}{}", tint, if moving { &ok.open } else { &ok.dim }); let mut line = vec![ ( port_colour.as_str(), @@ -2141,6 +2509,9 @@ fn main() { (kind_c.as_str(), format!("{} ", tc::pad(&row.kind, kind_w))), (who_c.as_str(), tc::pad(&who, name_w)), ]; + if busy { + line.push((traffic_c.as_str(), tc::pad(&traffic_text, traffic_w))); + } let up_c = format!("{}{}", tint, ok.dim); let exp_c = format!( "{}{}", @@ -2250,6 +2621,121 @@ fn bind_note(row: &Row, p: &Palette) -> (String, String) { mod tests { use super::*; + /// Two sockets in the shape `ss -tine` prints them: the addresses and + /// the inode on one line, the counters on an indented continuation. + fn ss_dump(sent_a: u64, sent_b: u64, ino_b: &str) -> String { + format!( + "State Recv-Q Send-Q Local Address:Port Peer Address:Port\n\ + ESTAB 0 0 192.0.2.7:3000 192.0.2.9:51234 ino:111 sk:1\n\ + \t ts sack cubic bytes_sent:{} bytes_received:40 segs_out:9\n\ + ESTAB 0 0 192.0.2.7:9999 192.0.2.9:51235 ino:{} sk:2\n\ + \t ts sack cubic bytes_sent:{} bytes_received:70 segs_out:9\n", + sent_a, ino_b, sent_b + ) + } + + #[test] + fn a_sockets_counters_are_read_off_its_continuation_line() { + let got = socket_counters(&ss_dump(1000, 2000, "222")); + assert_eq!(got.len(), 2); + // The *local* port, because that is the one a listener is on. + assert_eq!(got["111"], Counters { port: 3000, sent: 1000, recv: 40 }); + assert_eq!(got["222"], Counters { port: 9999, sent: 2000, recv: 70 }); + } + + #[test] + fn only_a_socket_seen_twice_can_say_what_moved() { + let before = socket_counters(&ss_dump(1000, 2000, "222")); + let after = socket_counters(&ss_dump(1500, 2000, "222")); + let moved_now = moved(&before, &after, &[3000, 9999]); + assert_eq!(moved_now.get(&3000), Some(&(500, 0))); + assert_eq!(moved_now.get(&9999), Some(&(0, 0))); + + // A socket with no previous reading contributes nothing rather than + // its whole lifetime total in one sample. Stated on a port that + // *also* has a socket carrying over, because a new connection to a + // busy port is when this actually happens - and because asserting + // it on an empty result would pass whether or not it were true. + let mut fresh = after.clone(); + fresh.insert( + "333".into(), + Counters { port: 3000, sent: 8_000_000, recv: 8_000_000 }, + ); + let moved_now = moved(&before, &fresh, &[3000, 9999]); + assert_eq!( + moved_now.get(&3000), + Some(&(500, 0)), + "a connection seen for the first time reported its whole life as one sample" + ); + + // Ports nothing is listening on are not tallied at all. Most + // established sockets are outbound and their local port is an + // ephemeral number that belongs to nothing. + let moved_now = moved(&before, &after, &[3000]); + assert!(!moved_now.contains_key(&9999)); + } + + #[test] + fn a_reused_inode_does_not_report_a_lifetime_as_one_sample() { + // Inodes come back after a socket closes. The new socket's counters + // start again, so subtracting the old ones is meaningless - and + // subtracting a larger number from a smaller one would wrap. + let before = socket_counters(&ss_dump(1000, 9_000_000, "222")); + // Same inode, now on a different port: a different socket. + let after = socket_counters(&ss_dump(1000, 5, "222")) + .into_iter() + .map(|(k, mut c)| { + if k == "222" { + c.port = 4444; + } + (k, c) + }) + .collect(); + let moved_now = moved(&before, &after, &[3000, 4444, 9999]); + assert_eq!(moved_now.get(&4444), None, "a reused inode was counted"); + + // And on the same port, a counter that went backwards clamps rather + // than wrapping to sixteen exabytes. + let after = socket_counters(&ss_dump(1000, 5, "222")); + let moved_now = moved(&before, &after, &[3000, 9999]); + assert_eq!(moved_now.get(&9999), Some(&(0, 0))); + } + + #[test] + fn a_rate_is_measured_against_the_gap_that_actually_happened() { + // [r] polls early. A rate divided by the nominal interval would + // read high every time somebody pressed it. + let mut t = Traffic::default(); + t.sample(&ss_dump(1000, 0, "222"), &[3000], 100.0); + // The first sample has nothing to subtract from and so is not a + // reading at all. + assert_eq!(t.rate(3000), None); + assert!(t.series(3000).is_empty()); + + // Two seconds later, a thousand bytes: five hundred a second. + t.sample(&ss_dump(3000, 0, "222"), &[3000], 102.0); + assert_eq!(t.rate(3000), Some((1000.0, 0.0))); + // Half a second later, the same thousand: two thousand a second. + t.sample(&ss_dump(4000, 0, "222"), &[3000], 102.5); + assert_eq!(t.rate(3000), Some((2000.0, 0.0))); + assert_eq!(t.span(3000), 2.5); + assert_eq!(t.series(3000).len(), 2); + } + + #[test] + fn a_port_that_stops_listening_is_forgotten_and_the_ring_is_bounded() { + let mut t = Traffic::default(); + for i in 0..(TRAFFIC_KEPT + 40) { + t.sample(&ss_dump(i as u64 * 10, 0, "222"), &[3000], 100.0 + i as f64); + } + assert_eq!(t.series(3000).len(), TRAFFIC_KEPT); + // Nothing listens on it any more: its history goes with it rather + // than growing for as long as the widget is up. + t.sample(&ss_dump(9999, 0, "222"), &[], 500.0); + assert!(t.series(3000).is_empty()); + assert_eq!(t.rate(3000), None); + } + #[test] fn a_binary_living_under_a_runtimes_path_is_not_that_runtime() { // Through `kind_of`, not the helper alone: an earlier version of From eafe5b7f537bbd7e868982b2cc74f1aaba28af23 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Tue, 25 Aug 2026 18:44:04 +0800 Subject: [PATCH 107/147] ports: the traffic column arrives when the names still fit It was gated on ninety-six columns, which is a number picked in advance and not the thing that matters. What matters is whether the project column still has room for the longest name in it, because that is the column that gives and a project's name cut in half is a different project. So the gate now asks that question: the widest name actually on screen, plus the WHAT column, plus the thirteen cells two rates need. On this machine it turns up at eighty-eight columns rather than ninety-six, and on a table of short names it would turn up sooner still. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- docs/ports.md | 8 +++++--- rust/widgets/src/bin/ports.rs | 34 ++++++++++++++++++++++++---------- 2 files changed, 29 insertions(+), 13 deletions(-) diff --git a/docs/ports.md b/docs/ports.md index ba9d544..049666f 100644 --- a/docs/ports.md +++ b/docs/ports.md @@ -125,9 +125,11 @@ Unlike netwatch, nothing is filtered by peer. netwatch drops loopback because it is about what leaves the machine; here loopback is the whole point, since a browser hitting a dev server on `127.0.0.1` is the traffic being asked about. -The column appears at 96 columns and above, and a port nothing is calling -shows nothing rather than `0 B/s` — a column of zeroes down the table reads as -a measurement that has failed. +The column arrives when there is room for it *after* the names, rather than +past some width picked in advance: the project column is the one that gives, +and a project's name cut in half is a different project. A port nothing is +calling shows nothing rather than `0 B/s` — a column of zeroes down the table +reads as a measurement that has failed. ## What it cannot see diff --git a/rust/widgets/src/bin/ports.rs b/rust/widgets/src/bin/ports.rs index fba2a49..b9289e3 100644 --- a/rust/widgets/src/bin/ports.rs +++ b/rust/widgets/src/bin/ports.rs @@ -222,6 +222,11 @@ fn moved( out } +/// The widest name in the table, which is what the WHAT column has to be. +fn longest_kind(rows: &[&Row]) -> usize { + rows.iter().map(|r| r.kind.chars().count()).max().unwrap_or(0).max(4) +} + /// A rate in as few cells as it can be read in, for a table column. /// /// One significant figure and a single-letter unit: five cells at most, so @@ -2391,11 +2396,7 @@ fn main() { rows.push(String::new()); let wide = w >= 78; - // The traffic column is the first thing to go and the last to - // arrive: it is the only one that is not about what the port *is*. - // Its two rates are eleven cells plus a gap. let rates = store.traffic.lock().ok(); - let busy = w >= 96 && rates.is_some(); // The project column takes whatever the fixed ones leave: it is the // one that identifies the server, and the one whose contents are a // directory name of any length. @@ -2405,14 +2406,27 @@ fn main() { // as one word - and anything longer was cut, which names a different // program. Sized to the whole list rather than the visible slice, so // the columns do not shift as it scrolls. - let traffic_w = if busy { 13 } else { 0 }; - let rest = 1 + 6 + 8 + 2 + 8 + traffic_w + if wide { 6 + 8 } else { 0 }; - let kind_w = shown + // The traffic column is the first to go and the last to arrive: it + // is the only one here not about what the port *is*. It arrives when + // there is room for it *after* the names, rather than past some + // number of columns picked in advance - the project column is the + // one that gives, and a project's name cut in half is a different + // project. + let traffic_w = 13usize; + let widest_project = shown .iter() - .map(|r| r.kind.chars().count()) + .map(|r| { + if r.project.is_empty() { &r.user } else { &r.project }.chars().count() + }) .max() - .unwrap_or(0) - .clamp(4, (w - 1).saturating_sub(rest).max(4)); + .unwrap_or(8) + .clamp(8, 24); + let without = 1 + 6 + 8 + 2 + if wide { 6 + 8 } else { 0 }; + let busy = rates.is_some() + && (w - 1) >= without + widest_project + traffic_w + longest_kind(&shown); + let traffic_w = if busy { traffic_w } else { 0 }; + let rest = 1 + 6 + 8 + 2 + 8 + traffic_w + if wide { 6 + 8 } else { 0 }; + let kind_w = longest_kind(&shown).min((w - 1).saturating_sub(rest).max(4)); let fixed = 1 + 6 + 8 + kind_w + 2 + traffic_w + if wide { 6 + 8 } else { 0 }; let name_w = std::cmp::max(8, (w - 1).saturating_sub(fixed)); rows.push(tc::seg( From e80498844ee2d13cfa09ec0cc209dd98a2bddc36 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Tue, 25 Aug 2026 19:02:08 +0800 Subject: [PATCH 108/147] ports: the traffic chart is as wide as the pane It drew one column per sample and stopped, so a chart with forty seconds of history was forty columns wide in a pane of a hundred and twenty, with the rule under it running on past the end of it. The plot now takes the width. The peaks move to a gutter down the left, which is where netwatch puts them and which leaves the rest to the chart; samples fill from the right, newest last; and the rule spans exactly the plot. Where there is no history yet the baseline is dotted rather than blank. Left blank it is indistinguishable from a stretch of real zeroes - and once the bars fill from the right, the blank on the left and the blank after a load stops would have read the same way. A quiet port and an unmeasured one are not the same thing, and that is the one confusion this widget exists not to cause. Two things follow from the width. Each sample now carries the gap it was measured over, so the heading counts the history actually on screen rather than everything kept - they stop being the same number as soon as the ring is longer than the pane is wide. And the ring is 512 samples rather than 100, because one column per sample means it has to outlast the widest pane anyone opens it in. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- docs/ports.md | 27 ++++-- rust/widgets/src/bin/ports.rs | 156 +++++++++++++++++++++------------- 2 files changed, 114 insertions(+), 69 deletions(-) diff --git a/docs/ports.md b/docs/ports.md index 049666f..361d13e 100644 --- a/docs/ports.md +++ b/docs/ports.md @@ -93,17 +93,26 @@ on are tallied: most established sockets are outbound, and their local port is an ephemeral number that belongs to nothing. ``` - ── TRAFFIC ── ↑ out above · ↓ in below · 52s of history, sampled every 1s - ▃▁ █▁▄▃▂ ▃▃▅ ▂▄▂▇▄ peak 15.1 MB/s - ▁▆██▇█████▅███▇█████▆▁ - ▁██████████████████████▆ - ──────────────────────────────────────────── + ── TRAFFIC ── ↑ out above · ↓ in below · 44s of history, sampled every 1s + █ ▁ + █▆ ▃ ▆▄▁▂ ▁█▁▁ ▁▂▇▄▁ +↑ 4.7 MB/s ··································██▅█▂ ▄▂▇████▅ ▃▂████▄▂▂▄█████▇ + ───────────────────────────────────────────────────────────────── + ·································· ``` -Each direction is scaled to its own peak and says what that peak was. A shared -scale would flatten the quieter of the two into nothing, and nothing is what a -source with no traffic looks like — the one reading this widget must never -produce by accident. +The chart is as wide as the pane. One column is one sample, newest at the +right, and each direction is scaled to its own peak and says what that peak +was in a gutter down the left. A shared scale would flatten the quieter of the +two into nothing, and nothing is what a source with no traffic looks like — +the one reading this widget must never produce by accident. + +The dots are where there is no history yet. Left blank they would be +indistinguishable from a stretch of real zeroes, and a quiet port and an +unmeasured one are not the same thing. They fill in from the right as the +samples arrive, and once the history is longer than the pane is wide the +chart shows the most recent of it — which is what the heading's `44s of +history` counts, not everything kept. Three things it is honest about: diff --git a/rust/widgets/src/bin/ports.rs b/rust/widgets/src/bin/ports.rs index b9289e3..618e2cb 100644 --- a/rust/widgets/src/bin/ports.rs +++ b/rust/widgets/src/bin/ports.rs @@ -94,32 +94,29 @@ impl Traffic { (gap > 0.0).then(|| (up as f64 / gap, down as f64 / gap)) } - /// Every kept sample as a rate, oldest first, for the chart. - fn series(&self, port: u16) -> Vec<(f64, f64)> { + /// Every kept sample as a rate, oldest first, each with the gap it was + /// measured over - so a chart showing only the last so many of them can + /// say how much history *that* is, rather than how much is kept. + fn series(&self, port: u16) -> Vec<(f64, f64, f64)> { self.seen .get(&port) .map(|ring| { ring.iter() .filter(|(_, _, gap)| *gap > 0.0) - .map(|(up, down, gap)| (*up as f64 / gap, *down as f64 / gap)) + .map(|(up, down, gap)| (*up as f64 / gap, *down as f64 / gap, *gap)) .collect() }) .unwrap_or_default() } - - /// How long the kept samples reach back. - fn span(&self, port: u16) -> f64 { - self.seen - .get(&port) - .map(|ring| ring.iter().map(|(_, _, gap)| gap).sum()) - .unwrap_or(0.0) - } } -/// How many samples of per-port traffic to keep, which is what the chart -/// on a port's own screen is drawn from. At the default four-second poll -/// that is a little over six minutes. -const TRAFFIC_KEPT: usize = 100; +/// How many samples of per-port traffic to keep, which is what the chart on +/// a port's own screen is drawn from. +/// +/// The chart draws one column per sample, so this has to outlast the widest +/// pane anyone opens it in. At the default four-second poll it is a little +/// over half an hour. +const TRAFFIC_KEPT: usize = 512; /// One TCP socket's byte counters, as the kernel has them. /// @@ -277,18 +274,39 @@ fn over(seconds: f64) -> String { /// Traffic on one port over time: out above the line, in below it. /// +/// The chart is as wide as the pane. One column is one sample, newest at the +/// right, and until there is enough history to fill it the left of the plot +/// carries a dotted baseline rather than bars of no height: a flat line +/// there would say the port was quiet then, and it says nothing of the sort. +/// /// Each direction is scaled to its own peak and each says what that peak -/// was, so a quiet direction is still readable beside a busy one. A shared -/// scale would flatten the smaller of the two into nothing and it would -/// look like no traffic at all. -fn traffic_chart(series: &[(f64, f64)], span: f64, gap: f64, w: usize, p: &Palette) -> Vec<String> { - let plot = (w - 1).saturating_sub(4).max(12); - // The most recent `plot` samples, oldest on the left. - let window: Vec<(f64, f64)> = series.iter().rev().take(plot).rev().copied().collect(); - let up: Vec<f64> = window.iter().map(|s| s.0).collect(); - let down: Vec<f64> = window.iter().map(|s| s.1).collect(); - let up_peak = up.iter().copied().fold(0.0f64, f64::max); - let down_peak = down.iter().copied().fold(0.0f64, f64::max); +/// was, in a gutter down the left so the plot keeps the rest of the width. A +/// shared scale would flatten the smaller of the two into nothing, and +/// nothing is what a source with no traffic looks like. +fn traffic_chart(series: &[(f64, f64, f64)], gap: f64, w: usize, p: &Palette) -> Vec<String> { + let up_peak = series.iter().map(|s| s.0).fold(0.0f64, f64::max); + let down_peak = series.iter().map(|s| s.1).fold(0.0f64, f64::max); + // The gutter is as wide as the wider of the two labels, so the plots + // line up under each other and the divider spans exactly the plot. + let label = |arrow: &str, peak: f64| { + if peak > 0.0 { + format!("{} {}", arrow, rate_of(peak)) + } else { + String::new() + } + }; + let (up_label, down_label) = (label("↑", up_peak), label("↓", down_peak)); + let lab = up_label + .chars() + .count() + .max(down_label.chars().count()) + .clamp(4, 16); + let plot = (w - 1).saturating_sub(lab + 2).max(12); + // The most recent `plot` samples, and how far back that reaches - which + // is not how far back the kept history reaches once it has overflowed. + let window: Vec<(f64, f64, f64)> = series.iter().rev().take(plot).rev().copied().collect(); + let reach: f64 = window.iter().map(|s| s.2).sum(); + let blank = plot - window.len(); let mut out = vec![tc::seg( &[ @@ -296,16 +314,20 @@ fn traffic_chart(series: &[(f64, f64)], span: f64, gap: f64, w: usize, p: &Palet (p.open.as_str(), "↑ out above".into()), (p.dim.as_str(), " · ".into()), (p.local.as_str(), "↓ in below".into()), - // The window is named, because a chart of an unnamed window is - // a shape rather than a measurement. + // The window is named, because a chart of an unnamed window is a + // shape rather than a measurement. ( p.dim.as_str(), - format!(" · {} of history, sampled every {}", over(span), over(gap)), + if window.is_empty() { + String::new() + } else { + format!(" · {} of history, sampled every {}", over(reach), over(gap)) + }, ), ], w - 1, )]; - if window.iter().all(|(a, b)| *a == 0.0 && *b == 0.0) { + if window.iter().all(|(a, b, _)| *a == 0.0 && *b == 0.0) { out.push(tc::seg( &[( p.dim.as_str(), @@ -320,44 +342,57 @@ fn traffic_chart(series: &[(f64, f64)], span: f64, gap: f64, w: usize, p: &Palet return out; } - let bars = |values: &[f64], colour: &str, peak: f64, down: bool| -> Vec<Vec<(String, String)>> { - let cols: Vec<(f64, String)> = - values.iter().map(|v| (*v, colour.to_string())).collect(); - if down { + let half = |pick: fn(&(f64, f64, f64)) -> f64, + colour: &str, + peak: f64, + text: &str, + down: bool| + -> Vec<String> { + let cols: Vec<(f64, String)> = window.iter().map(|s| (pick(s), colour.to_string())).collect(); + let rows = if down { tc::vbars_down(&cols, 3, peak) } else { tc::vbars(&cols, 3, peak) - } - }; - // The peak is written beside the top row of each half, which is the - // row it belongs to: the tallest bar there is that number. - // The peak is written beside the top row of each half, which is the row - // it belongs to - and only when that direction has moved, because "peak - // -" is four cells spent saying nothing happened. - let drawn = |rows: Vec<Vec<(String, String)>>, peak: f64, colour: &str| -> Vec<String> { + }; + // The label sits on the row nearest the divider, which is the row a + // full-height bar reaches: the top for the upward half, the first + // drawn row for the downward one. + let on = if down { 0 } else { rows.len().saturating_sub(1) }; rows.into_iter() .enumerate() .map(|(i, row)| { - let mut line: Vec<(&str, String)> = vec![(tc::RST, " ".into())]; + let mut line: Vec<(&str, String)> = vec![( + colour, + format!("{:>1$} ", if i == on { text } else { "" }, lab), + )]; + // Where there is no history yet, a dotted baseline on the + // row against the divider. Left blank it would be + // indistinguishable from a stretch of real zeroes, and a + // quiet port and an unmeasured one are not the same thing - + // which is the one confusion this widget must never cause. + if blank > 0 { + if i == on { + line.push((p.grid.as_str(), "·".repeat(blank))); + } else { + line.push((tc::RST, " ".repeat(blank))); + } + } for (c, t) in &row { line.push((c.as_str(), t.clone())); } - if i == 0 && peak > 0.0 { - line.push((colour, format!(" peak {}", rate_of(peak)))); - } tc::seg(&line, w - 1) }) .collect() }; - out.extend(drawn(bars(&up, &p.open, up_peak, false), up_peak, p.open.as_str())); - // As wide as the bars actually are, not as wide as they could have been: - // there is one column per sample, and until the history fills the pane a - // full-width rule would sit under nothing. + out.extend(half(|s| s.0, p.open.as_str(), up_peak, &up_label, false)); out.push(tc::seg( - &[(p.grid.as_str(), format!(" {}", "─".repeat(window.len().max(1))))], + &[ + (p.dim.as_str(), " ".repeat(lab + 1)), + (p.grid.as_str(), "─".repeat(plot)), + ], w - 1, )); - out.extend(drawn(bars(&down, &p.local, down_peak, true), down_peak, p.local.as_str())); + out.extend(half(|s| s.1, p.local.as_str(), down_peak, &down_label, true)); out } @@ -1656,8 +1691,7 @@ fn detail_rows( tunnel: &Option<Tunnel>, links: &[(String, String)], sel: usize, - seen: &[(f64, f64)], - reach: f64, + seen: &[(f64, f64, f64)], gap: f64, w: usize, p: &Palette, @@ -1732,7 +1766,7 @@ fn detail_rows( // What has actually gone through it. The kernel's own per-socket byte // counters, summed over the connections accepted from this port - so // this is TCP, and a port serving anything else reads as quiet. - rows.extend(traffic_chart(seen, reach, gap, w, p)); + rows.extend(traffic_chart(seen, gap, w, p)); rows.push(String::new()); rows.push(tc::seg( &[ @@ -2328,10 +2362,10 @@ fn main() { .push((t.url.clone(), "public · cloudflare".to_string())); } view.at = view.at.min(view.links.len().saturating_sub(1)); - let (seen, span) = store + let seen = store .traffic .lock() - .map(|t| (t.series(view.port), t.span(view.port))) + .map(|t| t.series(view.port)) .unwrap_or_default(); let mut rows = detail_rows( &view.row, @@ -2340,7 +2374,6 @@ fn main() { &view.links, view.at, &seen, - span, refresh, w, &ok, @@ -2732,8 +2765,11 @@ mod tests { // Half a second later, the same thousand: two thousand a second. t.sample(&ss_dump(4000, 0, "222"), &[3000], 102.5); assert_eq!(t.rate(3000), Some((2000.0, 0.0))); - assert_eq!(t.span(3000), 2.5); - assert_eq!(t.series(3000).len(), 2); + // Each sample carries the gap it was measured over, so a chart of + // the last few can say how much history they are. + let seen = t.series(3000); + assert_eq!(seen.len(), 2); + assert_eq!(seen.iter().map(|s| s.2).sum::<f64>(), 2.5); } #[test] From ac02b90bf9543b28a3cb48736b1f7e71399f59c7 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Tue, 25 Aug 2026 20:02:01 +0800 Subject: [PATCH 109/147] ports: the main screen shows what is moving, and each row its own shape MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two charts, and every cell in both is a byte the kernel counted. Across the top, everything moving through every listening port over time - the same chart a port's own screen draws, given a heading and a height and pointed at a totals ring. One function, two call sites, and it was already mutation-tested and verified against real load. The totals are kept as their own ring rather than summed at render time. Ports come and go mid-history, so the per-port rings are different lengths and adding them up by index would quietly credit one port's sample to another port's moment. One entry per sample whether or not anything moved, because the chart's columns are moments and a gap in it would compress a quiet minute into no width at all. The table is what this widget is for, so the chart yields to it: it is drawn only when there are rows to spare after the table, the header and the footer. At twenty rows there is no chart and there is a full table. Beside the rates, each row now carries the shape of its own traffic, scaled to its own peak rather than to the busiest port on screen. A shared scale flattens every quiet port to nothing, and nothing is what a port with no traffic looks like. So the shape column says shape and the rates beside it say size, and a full bar next to "↑2K" is a port at its own busiest, which is not busy. The window is named in the heading - LAST 17s - because a sparkline without one is a shape rather than a measurement. Three states, kept visibly apart the way the chart keeps them: dots where no sample exists yet, a flat line for measured and quiet, bars for traffic. "·····─────────" is a port that appeared ten seconds ago and has done nothing since, and it would have been indistinguishable from an idle one. The width gate was wrong again and is now a function with a property test. TRAFFIC arrived at seventy-six columns and left again at seventy-eight, where UP and EXPOSED turn up and take the room - one fact traded for another as the pane grew, which is the third time that shape of bug has appeared this week. Both columns are now measured against a row that already carries UP and EXPOSED whether or not the pane is wide enough to show them, and the test walks every width from forty to two hundred and twenty asserting that a wider pane never shows less. What was deliberately not added: anything that draws without measuring. There is a helper here that generates pleasant shapes and it stays unused - one widget in this repo is allowed to compute nothing, and it is not this one. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- docs/ports.md | 35 +++- rust/widgets/src/bin/ports.rs | 290 +++++++++++++++++++++++++++++++--- 2 files changed, 299 insertions(+), 26 deletions(-) diff --git a/docs/ports.md b/docs/ports.md index 361d13e..c1c6f2e 100644 --- a/docs/ports.md +++ b/docs/ports.md @@ -134,11 +134,38 @@ Unlike netwatch, nothing is filtered by peer. netwatch drops loopback because it is about what leaves the machine; here loopback is the whole point, since a browser hitting a dev server on `127.0.0.1` is the traffic being asked about. -The column arrives when there is room for it *after* the names, rather than +The same chart is drawn once across the top of the main screen — everything +moving through every listening port — when there are rows to spare after the +table. The table is what this widget is for, so the chart yields to it. + +Beside the rates, each row carries **the shape** of its own traffic: + +``` + PORT BIND WHAT PROJECT TRAFFIC LAST 17s UP EXPOSED + 38611 local node a-project ·····───────── 10s - + 39311 all Python serve ↑503K ▆▃▁ ▂▂▄▇▅█▃▃▁▁ 4m - +``` + +Each row is scaled to **its own peak**, not to the busiest port on screen. A +shared scale would flatten every quiet port to nothing, and nothing is what a +port with no traffic looks like. So the shape column says *shape* and the +rates beside it say *size*, and the two are read together — a row with a full +bar and `↑2K` is a port at its own busiest, which is not busy. + +The three states are kept visibly apart, the same way the chart keeps them: +dots for cells with no sample behind them yet, a flat line for measured and +quiet, bars for traffic. `·····─────────` is a port that appeared ten seconds +ago and has done nothing since. + +Both columns arrive when there is room for them *after* the names, rather than past some width picked in advance: the project column is the one that gives, -and a project's name cut in half is a different project. A port nothing is -calling shows nothing rather than `0 B/s` — a column of zeroes down the table -reads as a measurement that has failed. +and a project's name cut in half is a different project. Both are measured +against a row that already carries UP and EXPOSED whether or not the pane is +yet wide enough to show them, so that crossing that width cannot trade one +fact for another. The shapes are the more decorative of the two and so arrive +last and leave first. A port nothing is calling shows nothing in the rates +column rather than `0 B/s` — a column of zeroes down the table reads as a +measurement that has failed. ## What it cannot see diff --git a/rust/widgets/src/bin/ports.rs b/rust/widgets/src/bin/ports.rs index 618e2cb..06561c2 100644 --- a/rust/widgets/src/bin/ports.rs +++ b/rust/widgets/src/bin/ports.rs @@ -63,6 +63,12 @@ struct Traffic { last: HashMap<String, Counters>, at: f64, seen: HashMap<u16, VecDeque<(u64, u64, f64)>>, + /// The same samples summed over every listening port, kept separately + /// rather than added up at render time. Ports appear and disappear + /// mid-history, so their rings are different lengths and summing them + /// by index would quietly attribute one port's sample to another's + /// moment. + total: VecDeque<(u64, u64, f64)>, } impl Traffic { @@ -82,6 +88,16 @@ impl Traffic { ring.pop_front(); } } + // One entry per sample whether or not anything moved, so the + // chart's columns are moments rather than events - a gap in it + // would compress quiet minutes into no width at all. + let (up, down) = moved_now + .values() + .fold((0u64, 0u64), |(a, b), (u, d)| (a + u, b + d)); + self.total.push_back((up, down, gap)); + while self.total.len() > TRAFFIC_KEPT { + self.total.pop_front(); + } } self.seen.retain(|port, _| listening.contains(port)); self.last = now; @@ -98,18 +114,24 @@ impl Traffic { /// measured over - so a chart showing only the last so many of them can /// say how much history *that* is, rather than how much is kept. fn series(&self, port: u16) -> Vec<(f64, f64, f64)> { - self.seen - .get(&port) - .map(|ring| { - ring.iter() - .filter(|(_, _, gap)| *gap > 0.0) - .map(|(up, down, gap)| (*up as f64 / gap, *down as f64 / gap, *gap)) - .collect() - }) - .unwrap_or_default() + self.seen.get(&port).map(|r| rates(r)).unwrap_or_default() + } + + /// Every sample summed over all the listening ports. + fn totals(&self) -> Vec<(f64, f64, f64)> { + rates(&self.total) } } +/// A ring of byte counts as rates, oldest first, each keeping the gap it +/// was measured over so a chart can say how much history it is showing. +fn rates(ring: &VecDeque<(u64, u64, f64)>) -> Vec<(f64, f64, f64)> { + ring.iter() + .filter(|(_, _, gap)| *gap > 0.0) + .map(|(up, down, gap)| (*up as f64 / gap, *down as f64 / gap, *gap)) + .collect() +} + /// How many samples of per-port traffic to keep, which is what the chart on /// a port's own screen is drawn from. /// @@ -219,6 +241,31 @@ fn moved( out } +/// Whether the two traffic columns fit, given what the row must show first. +/// +/// Both are measured against a row that already has UP and EXPOSED on it, +/// whether or not this pane is wide enough to be showing them yet. Without +/// that, crossing the width where those two arrive pushed TRAFFIC back off +/// again - a pane that got wider and said less, which is the same fault the +/// linear board had and the reason this is a function with a test rather +/// than arithmetic inline. +/// +/// Returns whether the rates fit, and whether the shapes fit after them. +fn extra_columns( + w: usize, + kind_w: usize, + project_w: usize, + traffic_w: usize, + spark_w: usize, +) -> (bool, bool) { + // Marker and port, bind, the gap after the name, and the two columns at + // the end - counted always, so nothing here trades places with them. + let fixed = 1 + 6 + 8 + 2 + 6 + 8; + let room = |extra: usize| w.saturating_sub(1) >= fixed + project_w + kind_w + extra; + let busy = room(traffic_w); + (busy, busy && room(traffic_w + spark_w)) +} + /// The widest name in the table, which is what the WHAT column has to be. fn longest_kind(rows: &[&Row]) -> usize { rows.iter().map(|r| r.kind.chars().count()).max().unwrap_or(0).max(4) @@ -272,6 +319,43 @@ fn over(seconds: f64) -> String { } } +/// One row's worth of shape: the last `cells` samples of a port's traffic, +/// both directions together, in a single line of bars. +/// +/// Scaled to its *own* peak, not to the busiest port on screen. A shared +/// scale would flatten every quiet port to nothing, and nothing is what a +/// port with no traffic looks like. So this column says shape and the +/// TRAFFIC column beside it says size - and the two are read together. +/// +/// Cells with no sample behind them are dotted, the same as the chart on the +/// port's own screen, because a port nobody has measured yet and a port +/// nobody is calling are not the same thing. +fn spark(series: &[(f64, f64, f64)], cells: usize, p: &Palette) -> Vec<(String, String)> { + if cells == 0 { + return Vec::new(); + } + let window: Vec<f64> = series.iter().rev().take(cells).rev().map(|s| s.0 + s.1).collect(); + let peak = window.iter().copied().fold(0.0f64, f64::max); + let mut out = Vec::new(); + if window.len() < cells { + out.push((p.grid.clone(), "·".repeat(cells - window.len()))); + } + if peak <= 0.0 { + // Measured, and nothing moved: a flat baseline. Blank would put it + // in the same shape as a port nothing has sampled yet, and the + // dotted cells beside it exist precisely to keep those apart. + out.push((p.grid.clone(), "─".repeat(window.len()))); + return out; + } + let cols: Vec<(f64, String)> = window.iter().map(|v| (*v, p.open.clone())).collect(); + for row in tc::vbars(&cols, 1, peak) { + for (colour, text) in row { + out.push((colour, text)); + } + } + out +} + /// Traffic on one port over time: out above the line, in below it. /// /// The chart is as wide as the pane. One column is one sample, newest at the @@ -283,7 +367,14 @@ fn over(seconds: f64) -> String { /// was, in a gutter down the left so the plot keeps the rest of the width. A /// shared scale would flatten the smaller of the two into nothing, and /// nothing is what a source with no traffic looks like. -fn traffic_chart(series: &[(f64, f64, f64)], gap: f64, w: usize, p: &Palette) -> Vec<String> { +fn traffic_chart( + series: &[(f64, f64, f64)], + heading: &str, + rows: usize, + gap: f64, + w: usize, + p: &Palette, +) -> Vec<String> { let up_peak = series.iter().map(|s| s.0).fold(0.0f64, f64::max); let down_peak = series.iter().map(|s| s.1).fold(0.0f64, f64::max); // The gutter is as wide as the wider of the two labels, so the plots @@ -310,7 +401,7 @@ fn traffic_chart(series: &[(f64, f64, f64)], gap: f64, w: usize, p: &Palette) -> let mut out = vec![tc::seg( &[ - (p.lbl.as_str(), " ── TRAFFIC ── ".into()), + (p.lbl.as_str(), format!(" ── {} ── ", heading)), (p.open.as_str(), "↑ out above".into()), (p.dim.as_str(), " · ".into()), (p.local.as_str(), "↓ in below".into()), @@ -349,16 +440,16 @@ fn traffic_chart(series: &[(f64, f64, f64)], gap: f64, w: usize, p: &Palette) -> down: bool| -> Vec<String> { let cols: Vec<(f64, String)> = window.iter().map(|s| (pick(s), colour.to_string())).collect(); - let rows = if down { - tc::vbars_down(&cols, 3, peak) + let bars = if down { + tc::vbars_down(&cols, rows, peak) } else { - tc::vbars(&cols, 3, peak) + tc::vbars(&cols, rows, peak) }; // The label sits on the row nearest the divider, which is the row a // full-height bar reaches: the top for the upward half, the first // drawn row for the downward one. - let on = if down { 0 } else { rows.len().saturating_sub(1) }; - rows.into_iter() + let on = if down { 0 } else { bars.len().saturating_sub(1) }; + bars.into_iter() .enumerate() .map(|(i, row)| { let mut line: Vec<(&str, String)> = vec![( @@ -1766,7 +1857,7 @@ fn detail_rows( // What has actually gone through it. The kernel's own per-socket byte // counters, summed over the connections accepted from this port - so // this is TCP, and a port serving anything else reads as quiet. - rows.extend(traffic_chart(seen, gap, w, p)); + rows.extend(traffic_chart(seen, "TRAFFIC", 3, gap, w, p)); rows.push(String::new()); rows.push(tc::seg( &[ @@ -2430,6 +2521,25 @@ fn main() { let wide = w >= 78; let rates = store.traffic.lock().ok(); + // Everything moving through every listening port, over time. The + // table is what this widget is for, so the chart yields to it: it is + // drawn only when there are rows to spare after the table, the + // header and the footer have taken theirs. + let totals = rates.as_ref().map(|t| t.totals()).unwrap_or_default(); + let spare = h + .saturating_sub(rows.len() + 3 + shown.len().min(12) + 1) + .min(3); + if spare >= 3 && totals.iter().any(|(u, d, _)| *u > 0.0 || *d > 0.0) { + rows.extend(traffic_chart( + &totals, + "EVERYTHING MOVING", + spare / 2 + spare % 2, + refresh, + w, + &ok, + )); + rows.push(String::new()); + } // The project column takes whatever the fixed ones leave: it is the // one that identifies the server, and the one whose contents are a // directory name of any length. @@ -2446,6 +2556,9 @@ fn main() { // one that gives, and a project's name cut in half is a different // project. let traffic_w = 13usize; + // The shape column is the more decorative of the two, so it arrives + // after the rates and leaves before them. + let spark_cells = 14usize; let widest_project = shown .iter() .map(|r| { @@ -2454,13 +2567,40 @@ fn main() { .max() .unwrap_or(8) .clamp(8, 24); - let without = 1 + 6 + 8 + 2 + if wide { 6 + 8 } else { 0 }; - let busy = rates.is_some() - && (w - 1) >= without + widest_project + traffic_w + longest_kind(&shown); + let (fits, shapes) = extra_columns( + w, + longest_kind(&shown), + widest_project, + traffic_w, + spark_cells + 4, + ); + let busy = rates.is_some() && fits; + let sparks = rates.is_some() && shapes; let traffic_w = if busy { traffic_w } else { 0 }; - let rest = 1 + 6 + 8 + 2 + 8 + traffic_w + if wide { 6 + 8 } else { 0 }; + // Two cells of gap either side, the same as every other column here. + let spark_w = if sparks { spark_cells + 4 } else { 0 }; + // Named from the samples actually shown, so it stays true while the + // history is still filling. + let spark_head = rates + .as_ref() + .map(|t| { + let deepest = shown + .iter() + .map(|r| t.series(r.port)) + .map(|s| { + s.iter().rev().take(spark_cells).map(|x| x.2).sum::<f64>() + }) + .fold(0.0f64, f64::max); + if deepest > 0.0 { + format!("LAST {}", over(deepest)) + } else { + "SHAPE".to_string() + } + }) + .unwrap_or_else(|| "SHAPE".to_string()); + let rest = 1 + 6 + 8 + 2 + 8 + traffic_w + spark_w + if wide { 6 + 8 } else { 0 }; let kind_w = longest_kind(&shown).min((w - 1).saturating_sub(rest).max(4)); - let fixed = 1 + 6 + 8 + kind_w + 2 + traffic_w + if wide { 6 + 8 } else { 0 }; + let fixed = 1 + 6 + 8 + kind_w + 2 + traffic_w + spark_w + if wide { 6 + 8 } else { 0 }; let name_w = std::cmp::max(8, (w - 1).saturating_sub(fixed)); rows.push(tc::seg( &[ @@ -2471,6 +2611,18 @@ fn main() { ok.dim.as_str(), if busy { tc::pad("TRAFFIC", traffic_w) } else { String::new() }, ), + // The window the shapes cover, named rather than left to be + // guessed at - a sparkline without one is a shape. + ( + ok.dim.as_str(), + // The same two-cell gap the cells carry, so the heading + // sits over the shapes rather than two left of them. + if sparks { + format!(" {} ", tc::pad(&spark_head, spark_cells)) + } else { + String::new() + }, + ), ( ok.dim.as_str(), if wide { "UP EXPOSED".into() } else { String::new() }, @@ -2547,6 +2699,19 @@ fn main() { String::new() }; let traffic_c = format!("{}{}", tint, if moving { &ok.open } else { &ok.dim }); + // Built before the row, because every segment's colour has to + // outlive the borrows the row is assembled from. + let shape: Vec<(String, String)> = if sparks { + let mut out = vec![(format!("{}{}", tint, ok.dim), " ".to_string())]; + let seen = rates.as_ref().map(|t| t.series(row.port)).unwrap_or_default(); + for (colour, text) in spark(&seen, spark_cells, &ok) { + out.push((format!("{}{}", tint, colour), text)); + } + out.push((format!("{}{}", tint, ok.dim), " ".to_string())); + out + } else { + Vec::new() + }; let mut line = vec![ ( port_colour.as_str(), @@ -2559,6 +2724,9 @@ fn main() { if busy { line.push((traffic_c.as_str(), tc::pad(&traffic_text, traffic_w))); } + for (colour, text) in &shape { + line.push((colour.as_str(), text.clone())); + } let up_c = format!("{}{}", tint, ok.dim); let exp_c = format!( "{}{}", @@ -2772,6 +2940,84 @@ mod tests { assert_eq!(seen.iter().map(|s| s.2).sum::<f64>(), 2.5); } + #[test] + fn a_wider_pane_never_shows_fewer_columns_than_a_narrower_one() { + // TRAFFIC used to arrive at seventy-six and leave again at + // seventy-eight, where UP and EXPOSED turn up and take the room - + // one fact traded for another as the pane grew. + let (kind_w, project_w, traffic_w, spark_w) = (23usize, 22usize, 13usize, 18usize); + let mut had = (false, false); + for w in 40..220usize { + let now = extra_columns(w, kind_w, project_w, traffic_w, spark_w); + assert!( + now.0 >= had.0 && now.1 >= had.1, + "w={} lost a column the narrower pane had: {:?} then {:?}", + w, had, now + ); + // The shapes are the more decorative of the two and never + // arrive on their own. + assert!(!now.1 || now.0, "shapes without rates at w={}", w); + had = now; + } + // Both ends: nothing in a narrow pane, both in a wide one. + assert_eq!(extra_columns(60, kind_w, project_w, traffic_w, spark_w), (false, false)); + assert_eq!(extra_columns(210, kind_w, project_w, traffic_w, spark_w), (true, true)); + } + + #[test] + fn the_totals_ring_has_one_entry_per_sample_whether_or_not_anything_moved() { + let mut t = Traffic::default(); + t.sample(&ss_dump(1000, 0, "222"), &[3000, 9999], 100.0); + // The first sample is not a reading, here as anywhere. + assert!(t.totals().is_empty()); + + // Quiet second. + t.sample(&ss_dump(1000, 0, "222"), &[3000, 9999], 101.0); + // Busy second, on both ports at once. + t.sample(&ss_dump(1500, 400, "222"), &[3000, 9999], 102.0); + let totals = t.totals(); + assert_eq!(totals.len(), 2, "a quiet sample still takes a column"); + assert_eq!(totals[0].0, 0.0); + // Summed across ports: five hundred on one, four hundred on the + // other, in one second. + assert_eq!(totals[1].0, 900.0); + + // Bounded like the per-port rings, or a chart that keeps one column + // per sample grows for as long as the widget is up. + for i in 0..(TRAFFIC_KEPT + 20) { + t.sample(&ss_dump(2000 + i as u64, 0, "222"), &[3000], 200.0 + i as f64); + } + assert_eq!(t.totals().len(), TRAFFIC_KEPT); + } + + #[test] + fn a_sparkline_keeps_unmeasured_and_quiet_apart() { + let p = rgb_ok(); + let plain = |cells: Vec<(String, String)>| -> String { + cells.into_iter().map(|(_, t)| t).collect() + }; + + // Nothing sampled at all: every cell dotted. + assert_eq!(plain(spark(&[], 6, &p)), "······"); + + // Sampled and quiet: a baseline, which is a different thing and has + // to look like one - the port's own screen makes the same + // distinction one keypress away. + let quiet: Vec<(f64, f64, f64)> = (0..6).map(|_| (0.0, 0.0, 1.0)).collect(); + assert_eq!(plain(spark(&quiet, 6, &p)), "──────"); + + // Partly sampled: dots for what is missing, then the rest. + let some: Vec<(f64, f64, f64)> = (0..2).map(|_| (0.0, 0.0, 1.0)).collect(); + assert_eq!(plain(spark(&some, 6, &p)), "········".chars().take(4).collect::<String>() + "──"); + + // Scaled to its own peak, not to some other row's: the biggest + // sample here is full height whatever its absolute size. + let small: Vec<(f64, f64, f64)> = vec![(1.0, 0.0, 1.0), (8.0, 0.0, 1.0)]; + let big: Vec<(f64, f64, f64)> = vec![(1e6, 0.0, 1.0), (8e6, 0.0, 1.0)]; + assert_eq!(plain(spark(&small, 2, &p)), plain(spark(&big, 2, &p))); + assert!(plain(spark(&small, 2, &p)).ends_with('█'), "the peak is full height"); + } + #[test] fn a_port_that_stops_listening_is_forgotten_and_the_ring_is_bounded() { let mut t = Traffic::default(); From c1df434addd1b4d8f6d7a27bda3dd0edb4af86d3 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Tue, 25 Aug 2026 20:15:36 +0800 Subject: [PATCH 110/147] docs: where the Rust and the Python differ on purpose TOY-8's second acceptance criterion, which was the only part of it still open: the deliberate divergences written down somewhere durable rather than living only in commit messages. All fourteen review sub-issues are already through; this is what the reviews produced. Structured by decision rather than by widget, because nearly everything in the list is one of five policies applied across many widgets - one way in and one way out, sections focused with tab instead of a letter each, three renames with their reasons, the charts, and the features that only exist on one side. A key-by-key list would be wrong the next time a widget is added; the policies survive it. Verified by reading both sources rather than diffing them. Three attempts at a mechanical key-differ each reported something different and each was wrong in its own way: one read only match arms and so missed `if key == "f"`, one counted `for key in ("send", ...)` as a keyboard key, and one looked only at the first element of a tuple and so missed `key in ("enter", "right", "i")` in five widgets at once. That last one matters - it is the `i` that opens a detail screen in five Pythons, has never been in any of their footers, and is deliberately absent from the Rust. Every row in the page was confirmed by grepping for the specific key in both files. Two things the page records that were not previously written down anywhere: `netwatch.py` still gives each of its three lists its own focus key, `e` and `f`, where the Rust has only tab; and `matrix.py` has no keyboard at all and exits on Ctrl-C, where the Rust answers q. It also says what is still open rather than pretending the two are level: `ports.py`'s undocumented `i`, and two Rust fixes worth backporting if the Python is staying - the braille cell that shows one trace in another's colour, and netwatch's flickering rate column. Linked from the README and from AGENTS.md, the latter saying what to do with it: anything not listed is a finding rather than a decision, and a new deliberate divergence belongs in it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- AGENTS.md | 8 +++ README.md | 6 ++ docs/rust-vs-python.md | 130 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 144 insertions(+) create mode 100644 docs/rust-vs-python.md diff --git a/AGENTS.md b/AGENTS.md index 5052d9c..18f3740 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -139,5 +139,13 @@ impossible. widgets holding a secret, non-blocking `Keyboard`, and OSC 52 `clipboard()`. +`docs/rust-vs-python.md` records where the two implementations answer +differently on purpose. Anything not listed there is a finding rather than a +decision, and a new deliberate divergence belongs in it. + +`docs/rust-vs-python.md` records where the two implementations answer +differently on purpose. Anything not listed there is a finding rather than a +decision, and a new deliberate divergence belongs in it. + `docs/building-herdr-panels.md` records what was learned driving these from Herdr: resize semantics, focus, and the layout mistakes worth skipping. diff --git a/README.md b/README.md index 85e08ce..aa09f56 100644 --- a/README.md +++ b/README.md @@ -161,6 +161,12 @@ was learned building these against Herdr: resize semantics, focus, detecting what a pane is running, notification gating, and the layout mistakes worth skipping. +[`docs/rust-vs-python.md`](docs/rust-vs-python.md) records where the two +implementations answer differently **on purpose** — the keys the Rust +consolidated, the two it renamed, the charts it draws differently, and the +features that exist only on one side. Anything not listed there is a finding +rather than a decision. + Both implementations are checked the same way. `cargo test` from `rust/` runs each widget's tests plus `widgets/tests/check.rs`, which reads the sources and fails on a poller that dies without saying why, a footer hint naming a key diff --git a/docs/rust-vs-python.md b/docs/rust-vs-python.md new file mode 100644 index 0000000..4ee457a --- /dev/null +++ b/docs/rust-vs-python.md @@ -0,0 +1,130 @@ +# Where the Rust and the Python differ + +Every widget here exists twice. The Rust is not a transliteration: some of it +answers differently on purpose, and the difference between *on purpose* and +*a defect the port introduced* is the whole point of the side-by-side review +([TOY-8](https://linear.app/stealth-company/issue/TOY-8)). This page is the +durable half of that review — the divergences that were meant. + +Anything not listed here and not obviously a Rust-only feature should be +treated as a finding, not a decision. + +**Reviewed against `ac02b90`.** Verified by reading both sources, not by +diffing them: three attempts at a mechanical key-differ each reported +something different and each was wrong in its own way — one missed +`if key == "f"` because it only read match arms, one counted `for key in +("send", ...)` as a keyboard key, and one missed `key in ("enter", "right", +"i")` because it only looked at the first element. That is the usual lesson +here: a grep that finds nothing is as often a wrong pattern as an absent +thing. + +## One way in, and one way out + +Seven widgets have a drill-in view and no two of them agreed on how to reach +it. `i` opened one in three of them, `c` opened another, `↵` alone opened +two, and coming back was `esc`, or `backspace`, or `q`, or `↵` again. + +**The Rust: `→` or `↵` in, `←` or `esc` out, everywhere.** No letter is +spent on it. + +Which means the Rust deliberately does *not* answer: + +| Key | Still opens a detail view in | Replaced by | +|---|---|---| +| `i` | `ports.py`, `link.py`, `netwatch.py`, `start.py`, `tailnet.py` | `→` / `↵` | +| `backspace` | `ports.py`, `netwatch.py` | `←` / `esc` | + +`i` was never in any footer in the Python either, in any of the five. It +worked and nothing said so. + +`q` quits from inside a detail view rather than closing it. In the Python it +closes the overlay in four widgets while the footer beside it reads +`[q]uit` — the key disagreeing with its own hint, and quietly, because the +widget stays up. + +**`usage` is untouched.** Its `←` and `→` move between vendor tabs, which is +lateral rather than into anything. + +**`pr` is a special case.** Inside its detail `↵` walks the stack, so `→` +drills further rather than closing, and `esc` keeps its second job of +clearing the search, which `←` has no business doing. + +## Sections are focused with tab, not with a letter each + +`netwatch.py` gives each of its three lists a key: `e` focuses endpoints, +`f` focuses files, `tab` cycles. The Rust has **only `tab`**, plus the rule +every widget here with focusable sections now follows: the sections read as +one continuous list under the arrows, crossing at their ends, letting go at +exactly two places. + +The heading of the section `tab` would focus *next* carries `[tab] to +focus`. The Python's headings carry the per-section letters instead. + +## Keys renamed, and why + +| Widget | Python | Rust | Why | +|---|---|---|---| +| `tailnet` | `n` cycles the interval | `i` cycles the interval | `i` is what `latency` calls the same thing, and `i` was free once the info screen moved to the arrows. `n` was this widget's own letter and meant nothing to a reader coming from the widget beside it. | +| `deployments` | `f` filters by project | `s` filters by state, `/` filters by text | Two different filters wanted the same letter. The one you type is `/`, as everywhere else that has one. | +| `herdr-panes` | `o` | `i` | Named after what it toggles. | + +`clocks`, `latency` and `deployments` also answer `j` and `k` as aliases for +`↓` and `↑` in the Rust only. + +## Charts + +**`latency` and `link` draw on a braille canvas** in the Rust, the way +`netwatch` always has — two dots to a character across and four down, with +consecutive samples joined. The Pythons plot one glyph per sample and fill +`│` between the steps, so a value that moves quickly reads as a column of +marks rather than a line. The side effect worth having is resolution: a cell +that used to hold one sample holds two. + +**A braille cell belongs to one trace.** Both Pythons merge every series' dot +masks into each cell and give the cell to whichever series comes later in the +table. A cell can hold two traces' dots but only one colour, so where two +hosts sit close together on the axis one is drawn end to end in the other's +colour and a third can vanish as a distinct line. No number is false; the +colour saying whose it is, is. **The Pythons still do this.** + +**`netwatch` averages rates over about four seconds** in the Rust. Over one +sample interval the delta really is zero whenever a bursty process is between +bursts, so the column flickered between a figure and a dash — every reading +correct and the column unreadable. The header names the window. Totals are +untouched: smoothing a rate is honest, smoothing a total would not be. +`netwatch.py` still flickers. + +## Columns + +| Widget | Difference | +|---|---| +| `netwatch` | The connection list has a **LOCAL** column in the Rust — our end of the socket. Without it, several connections to one host and port are identical rows, and the only field telling them apart is not on screen. | +| `ports` | **WHAT** is sized to the widest name it has to show, in both, since the review; it was a flat eighteen cells with nothing after it and a name of exactly that length ran into the project name. | + +## Rust-only features + +Built after the port, on the Rust side only, because that is where the work +went once the ports were accepted: + +| Widget | What | +|---|---| +| `linear` | A screen of its own for a cycle, a team, and a project; the board scrolls as a whole; a PROJECTS section; `[c]opy url` on a cycle's issues | +| `ports` | Per-port traffic — a column, a per-row sparkline, a chart on the port's screen and one across the top | +| `deployments` | Build logs, a scrolling detail screen, `[/]` filter, copy on its own page | +| `github` | A per-account screen with the oldest open PRs and `[c]opy` | +| `matrix` | Answers `q`. `matrix.py` has no keyboard at all and exits on Ctrl-C | + +## Where the Rust deliberately agrees + +Worth writing down because it was checked rather than assumed: subprocess +timeouts are the Pythons' own numbers, config defaults were compared key by +key against the Pythons', and `ports`' program-name table matches the +Python's patterns — including the two that have to be anchored, which the +port had flattened to substring tests until the review caught it. + +## Still open + +- `ports.py` answers `i` and the Rust does not. Dropping it from the Python + is a decision rather than a fix. +- The braille colour bug and `netwatch`'s rate window are both worth + backporting if the Python is staying. From cd2bd3ef80909fb00e89326b5e64dc2631e26b0a Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Tue, 25 Aug 2026 20:36:16 +0800 Subject: [PATCH 111/147] docs: the port's decisions, now that the Python is leaving The page was written while both implementations were peers, and framed as the differences between them. The Python goes when #31 merges, so the framing had a shelf life of about an hour. Reframed to what survives it. Most of the page was never a comparison: it is the reason a key is the key it is, the reason a rate is averaged, the reason a braille cell belongs to one trace. The Python is how those reasons are explained rather than why they matter. The two open questions it ended on are answered by the same news. Dropping `i` from ports.py is not a decision anybody has to make, and neither Rust fix is worth backporting. Both bugs move to a section that says what they were: found by this review, fixed in the Rust, never fixed in the Python because there was no reason to. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- docs/rust-vs-python.md | 48 +++++++++++++++++++++++++++++------------- 1 file changed, 33 insertions(+), 15 deletions(-) diff --git a/docs/rust-vs-python.md b/docs/rust-vs-python.md index 4ee457a..62ab473 100644 --- a/docs/rust-vs-python.md +++ b/docs/rust-vs-python.md @@ -1,13 +1,20 @@ -# Where the Rust and the Python differ +# What the port changed, and why -Every widget here exists twice. The Rust is not a transliteration: some of it -answers differently on purpose, and the difference between *on purpose* and -*a defect the port introduced* is the whole point of the side-by-side review -([TOY-8](https://linear.app/stealth-company/issue/TOY-8)). This page is the -durable half of that review — the divergences that were meant. +For the length of the port every widget here existed twice, and the Rust was +never a transliteration: some of it answers differently on purpose. Telling +*on purpose* from *a defect the port introduced* was the whole point of the +side-by-side review ([TOY-8](https://linear.app/stealth-company/issue/TOY-8)), +and this page is what that review produced. -Anything not listed here and not obviously a Rust-only feature should be -treated as a finding, not a decision. +**The Python goes when [#31](https://github.com/stealth-factory/terminal-toys/pull/31) +merges.** This page outlives it, because most of what is here is not a +comparison — it is the reason a key is the key it is, the reason a rate is +averaged, the reason a braille cell belongs to one trace. The Python is how +those reasons are explained, not why they matter. + +Until it merges, both implementations are still in the tree, and anything not +listed here and not obviously a Rust-only feature should be treated as a +finding rather than a decision. **Reviewed against `ac02b90`.** Verified by reading both sources, not by diffing them: three attempts at a mechanical key-differ each reported @@ -85,14 +92,14 @@ masks into each cell and give the cell to whichever series comes later in the table. A cell can hold two traces' dots but only one colour, so where two hosts sit close together on the axis one is drawn end to end in the other's colour and a third can vanish as a distinct line. No number is false; the -colour saying whose it is, is. **The Pythons still do this.** +colour saying whose it is, is. The Pythons were never fixed — see below. **`netwatch` averages rates over about four seconds** in the Rust. Over one sample interval the delta really is zero whenever a bursty process is between bursts, so the column flickered between a figure and a dash — every reading correct and the column unreadable. The header names the window. Totals are untouched: smoothing a rate is honest, smoothing a total would not be. -`netwatch.py` still flickers. +`netwatch.py` was never fixed — see below. ## Columns @@ -122,9 +129,20 @@ key against the Pythons', and `ports`' program-name table matches the Python's patterns — including the two that have to be anchored, which the port had flattened to substring tests until the review caught it. -## Still open +## Two bugs that leave with the Python + +Both were found by this review, both are fixed in the Rust, and neither was +ever fixed in the Python — there was no reason to, once it was going. + +**A braille cell showed one trace in another trace's colour.** `latency.py` +and `link.py` merge every series' dot masks into a cell and give the cell to +whichever series comes later in the table. Where two hosts sit close together +on the axis, one is drawn end to end in the other's colour and a third can +vanish as a distinct line. No number was false; the colour saying whose it +was, was. This is the founding-rule break that started the review, and it was +found by eye — *why does that host have two lines* — after every test had +passed on it all day. -- `ports.py` answers `i` and the Rust does not. Dropping it from the Python - is a decision rather than a fix. -- The braille colour bug and `netwatch`'s rate window are both worth - backporting if the Python is staying. +**`netwatch.py`'s rate column flickers** between a figure and a dash, because +over one sample interval the delta really is zero whenever a bursty process is +between bursts. Every reading correct, the column unreadable. From b6c3b8bb23436a0604a9bf5a90a7e8ca61306972 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Tue, 25 Aug 2026 21:11:30 +0800 Subject: [PATCH 112/147] herdr-panes: the cursor stays on a row you can see TOY-36. `selected` was clamped against the whole list while each of the three drawing loops stopped at a row budget of its own, so on any pane too short for every pane on the machine the cursor kept moving past the last drawn row and vanished - and enter still switched to whatever it was invisibly sitting on. Invisible on a tall pane, which is why it survived. Reproduced first, at 24 rows and 110 columns, on a machine with 15 agents, 13 running panes and 15 idle: a row carried the cursor at 0 downs and none did at 12, 25 or 40. All four carry it now. The three lists read as one under a window, the way netwatch's process list reads, and the header above them is pinned - the counts and the "N agents waiting for you" line are the reason to have the widget open and must not scroll away. The footer is built before the body rather than after it: it wraps, so its height depends on the width, and the body cannot know its own budget until that is settled. The window is measured in rows, not entries. That is the part I got wrong first: an agent takes two rows and a pane takes one, so a window counted in entries admits more rows than the pane has, they are cut off the bottom, and the cursor goes with them - the same bug, one layer down. Then the chrome was one row short, because the processes section has a column head and the agents section's was the only one I had counted; the row that overflowed was the last one, which is exactly where the cursor is when you have pressed end. `idle_fit` goes. It rationed rows so the idle heading could not be pushed off the bottom, which was TOY-34; a window makes that impossible by construction, so the heading is simply always drawn. The rule it protected is kept and its test now states it in the new terms rather than in the old arithmetic. Headings say what they are showing when they are not showing all of it, and say "none on screen" when the window has scrolled past them - a heading standing over nothing reads as a section that failed to load rather than one you scrolled away from. `follow` moves to toys-core with its test. This is its third widget, and `window_over` here is the variable-height version of the same idea. One invariant is now load-bearing twice and has a comment saying so: the screen draws running-then-resting while the cursor indexes agents ++ panels, and those agree only because `panels` is sorted idle-last. Reorder that sort and the cursor marks one pane while enter switches to another. Each of the four new tests was watched failing against the defect it covers. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- docs/herdr-panes.md | 29 ++- rust/core/src/lib.rs | 40 ++++ rust/widgets/src/bin/herdr-panes.rs | 340 +++++++++++++++++++--------- rust/widgets/src/bin/linear.rs | 42 +--- 4 files changed, 300 insertions(+), 151 deletions(-) diff --git a/docs/herdr-panes.md b/docs/herdr-panes.md index ecebd72..31f4cc6 100644 --- a/docs/herdr-panes.md +++ b/docs/herdr-panes.md @@ -74,11 +74,38 @@ differs from its own shell pid. Command names come from `argv`, so a pane shows widget started — we did not see it begin, so it is only a lower bound. Herdr does not timestamp state changes, so transitions are tracked here. +## When it does not all fit + +The three lists read as one under the arrows, and the pane is a window onto +that one list. The header above them is pinned — the counts and the +`▸ N agents waiting for you` line are the reason to have the widget open, and +they never scroll away. + +The window follows the cursor: it holds still while the cursor moves inside +it, and moves by as little as it takes when the cursor would leave. It is +measured in **rows**, not entries, because an agent takes two rows — its +second carries the directory and the pane title — while a process takes one. +Counted in entries it admits more rows than the pane has, they are cut off the +bottom, and the cursor goes with them: it kept moving past the last drawn row +and disappeared, while `Enter` still switched to whatever it was invisibly +sitting on. + +A heading whose section is not all on screen says so — `── IDLE ── 15 panes at +a prompt · showing 4-15` — and one the window has scrolled clean past says +`none on screen` rather than standing over nothing, which reads as a section +that has failed to load. A section entirely on screen says nothing: a range on +a list you can see all of is noise. + +The idle heading is drawn whenever there are idle panes, at every height. It +used to be rationed — granted a heading only if the lists above had left room +— and dropping it silently left the footer offering `[i]dle` with nothing +behind it. + ## Keys | Key | Action | |---|---| -| `↑` `↓` `Home` `End` | select, across all three sections | +| `↑` `↓` `Home` `End` | select, across all three sections; the window follows | | `Enter` / `f` | **go there** — the agent's pane, or the tab holding that process | | `i` | show/hide the idle section — `o` in the Python, which is being retired | | `l` | workspace labels vs pane ids | diff --git a/rust/core/src/lib.rs b/rust/core/src/lib.rs index 4fc5500..e8ad669 100644 --- a/rust/core/src/lib.rs +++ b/rust/core/src/lib.rs @@ -614,6 +614,22 @@ pub fn meter(frac: f64, n: usize) -> String { } const EIGHTHS: &[char] = &[' ', '▁', '▂', '▃', '▄', '▅', '▆', '▇', '█']; +/// Where a window of `room` rows has to start to keep `row` in view. +/// +/// Every list here that is longer than its pane is drawn whole and shown +/// through a window, and they all move it the same way: linear's board and +/// its detail screens, herdr-panes' three sections. It is one function so +/// that a test can break it, which a copy inlined in each could not have. +pub fn follow(at: usize, row: usize, room: usize) -> usize { + if row < at { + row + } else if row + 1 > at + room { + row + 1 - room + } else { + at + } +} + /// Vertical bar chart, one column per value. /// @@ -1161,6 +1177,30 @@ pub fn maybe_help(doc: &str) { #[cfg(test)] mod tests { + #[test] + fn the_window_chases_a_cursor_it_cannot_see() { + // Stated as what the reader sees rather than as the arithmetic: + // wherever the cursor is, the window has to contain it, and it has + // to move as little as it can to do that. + let holds = |at: usize, row: usize, room: usize| row >= at && row < at + room; + for room in [1usize, 3, 20] { + for start in [0usize, 5, 30] { + for row in [0usize, 4, 7, 12, 40] { + let moved = follow(start, row, room); + assert!(holds(moved, row, room), "row {} not in {}..+{}", row, moved, room); + // Not moved at all when it did not need to be. + if holds(start, row, room) { + assert_eq!(moved, start, "moved without needing to"); + } + } + } + } + // Reaching down puts the cursor on the last row, not past it. + assert_eq!(follow(0, 40, 20) + 20, 41); + // Reaching up puts it on the first. + assert_eq!(follow(30, 4, 20), 4); + } + // The rule every widget with focusable sections follows. It is tested // here rather than in each widget because "the same rule everywhere" is diff --git a/rust/widgets/src/bin/herdr-panes.rs b/rust/widgets/src/bin/herdr-panes.rs index f49a36d..de3c658 100644 --- a/rust/widgets/src/bin/herdr-panes.rs +++ b/rust/widgets/src/bin/herdr-panes.rs @@ -151,37 +151,70 @@ struct Agent { rss: Option<u64>, } -/// What the idle section gets, once the lists above it have been drawn. +/// The slice of a variable-height list that fits `room` rows and holds the +/// cursor. /// -/// The three sections used to budget against the same bound, so the -/// running list could spend the whole pane and the idle heading was pushed -/// past the bottom and truncated - leaving the footer offering a key with -/// nothing behind it. -#[derive(PartialEq, Eq, Debug, Clone, Copy)] -enum IdleFit { - /// Heading, blank line and at least one pane. - Full, - /// No room to list them, but room to say how many there are. Dropping - /// the section silently is what made the key look broken. - CountOnly, - /// Not even one line: the pane is shorter than the lists above it. - Nothing, +/// The three lists here do not have one height between them: an agent takes +/// two rows, its second carrying the directory and the pane title, while a +/// process takes one. A window counted in *entries* therefore admits more +/// rows than the pane has, they are cut off the bottom, and the cursor goes +/// with them - which is the bug this is here to fix, arrived at the second +/// time rather than the first. +/// +/// `from` is where the window sat last frame. It is honoured when it can be, +/// so the view holds still while the cursor moves inside it, and moves by as +/// little as it takes when the cursor would leave. +fn window_over( + heights: &[usize], + at: usize, + room: usize, + from: usize, +) -> std::ops::Range<usize> { + let n = heights.len(); + if n == 0 || room == 0 { + return 0..0; + } + let at = at.min(n - 1); + // Never start below the cursor: reaching up moves the window to it. + let mut first = from.min(at); + loop { + let (mut used, mut end) = (0usize, first); + while end < n && used + heights[end] <= room { + used += heights[end]; + end += 1; + } + // A row taller than the whole pane still gets drawn, or the list + // would be empty and the cursor nowhere. + if end == first { + end = first + 1; + } + if at < end || first + 1 >= n { + return first..end; + } + first += 1; + } } -/// How many rows the full section needs: a blank, a heading, and a pane. -const IDLE_ROWS: usize = 3; - -fn idle_fit(h: usize, used: usize, show: bool, resting: usize) -> IdleFit { - if !show || resting == 0 { - return IdleFit::Nothing; +/// What a section heading adds when the window does not hold all of it. +/// +/// `first` is where the section starts in the flat list the three of them +/// make together, and `len` is how many rows it has. Nothing when the whole +/// section is on screen - a range on a section you can see all of is noise. +fn showing(window: &std::ops::Range<usize>, first: usize, len: usize) -> String { + if len == 0 { + return String::new(); } - let body = h.saturating_sub(2); - if used + IDLE_ROWS <= body { - IdleFit::Full - } else if used < body { - IdleFit::CountOnly + let from = window.start.max(first); + let to = window.end.min(first + len); + if from <= first && to >= first + len { + String::new() + } else if to <= from { + // Scrolled clean past it. Said out loud, because a heading with a + // count and no rows under it otherwise reads as a section that has + // failed to load rather than one you have scrolled away from. + " · none on screen".to_string() } else { - IdleFit::Nothing + format!(" · showing {}-{}", from - first + 1, to - first) } } @@ -348,6 +381,11 @@ fn poll(state: &Arc<Mutex<State>>, seen: &mut Seen, hz: f64) { } // Busy first, and the busiest of those first: the point of the section // is what is costing something. + // Idle last, and that ordering is load-bearing twice over. The screen + // draws `running` then `resting`, and both the cursor and the window are + // indices into `agents ++ panels` - so the two agree only because + // `panels` is already running-then-resting. Reorder this and the cursor + // silently marks one pane while enter switches to another. panels.sort_by(|a, b| { a.idle .cmp(&b.idle) @@ -552,6 +590,10 @@ fn main() { let mut keyboard = tc::Keyboard::new(); let (mut show_labels, mut show_idle) = (true, true); let (mut selected, mut tick) = (0usize, 0usize); + // How far down the three lists, read as one, the window has scrolled. + // Kept across frames so the view holds still while the cursor moves + // inside it, and only moves when the cursor would leave it. + let mut scroll = 0usize; let mut note: Option<(String, bool, f64)> = None; let mut rows_now: Vec<Row> = Vec::new(); @@ -691,10 +733,68 @@ fn main() { rows.push(String::new()); let wide = w >= 66; + + // The footer must always be the last visible line, so it is built + // before the body rather than after it: it wraps, so how many rows + // it takes depends on the width, and the body cannot know its own + // budget until that is settled. Each section budgeting for itself is + // what drifted before, and left the footer written past the bottom. + let hints: Vec<Vec<(&str, String)>> = vec![ + vec![(p.accent.as_str(), "↑↓".into()), (p.dim.as_str(), " select".into())], + vec![ + (p.accent.as_str(), "↵".into()), + (p.dim.as_str(), " switch to this pane".into()), + ], + vec![(p.dim.as_str(), "[i]dle".into())], + vec![(p.dim.as_str(), "[l]abels".into())], + vec![(p.dim.as_str(), "[r]efresh".into())], + vec![(p.dim.as_str(), "[q]uit".into())], + ]; + let footer: Vec<String> = tc::pack_hints(&hints, w - 2, " ") + .into_iter() + .map(|l| format!(" {}", l)) + .collect(); + + // One window over the three lists read as one, which is the order + // `rows_now` is in and the order the keys walk. The cursor used to + // be clamped against the whole list while each section stopped at a + // row budget of its own, so on any pane too short for everything the + // cursor walked past the last drawn row and vanished - and enter + // still acted on whatever it was invisibly sitting on. + let idle_listed = show_idle && !resting.is_empty(); + // Every heading is drawn, always: AGENTS and its column head, a + // blank and PROCESSES, and the same again for IDLE when there is an + // idle section at all. TOY-34's rule survives that way rather than + // by rationing - the heading and its count are never what gets cut. + // Everything that is not an entry row: the pinned header already + // pushed, each section's heading and column head, the note line and + // the footer. Counted rather than estimated, because one row short + // is one entry admitted that the truncate below then cuts - and the + // row it cuts is the last one, which is where the cursor is when you + // have just pressed end. + let chrome = rows.len() + + 2 // AGENTS, and its column head + + 2 + usize::from(wide) // blank, PROCESSES, its column head + + usize::from(agents.is_empty()) // the line that stands in for a list + + usize::from(running.is_empty()) + + if idle_listed { 2 } else { 0 } // blank, IDLE + + footer.len() + + 1; // the note line + let room = h.saturating_sub(chrome).max(1); + // An agent takes two rows and a pane takes one, in the order the + // keys walk them. + let heights: Vec<usize> = std::iter::repeat(2) + .take(agents.len()) + .chain(std::iter::repeat(1).take(rows_now.len() - agents.len())) + .collect(); + let window = window_over(&heights, selected, room, scroll); + scroll = window.start; + rows.push(tc::seg( &[ (p.lbl.as_str(), " ── AGENTS ── ".into()), (p.dim.as_str(), format!("{}", agents.len())), + (p.dim.as_str(), showing(&window, 0, agents.len())), ], w - 1, )); @@ -705,8 +805,8 @@ fn main() { rows.push(tc::seg(&[(p.dim.as_str(), tc::pad(&head, w - 1))], w - 1)); for (i, a) in agents.iter().enumerate() { - if rows.len() >= h.saturating_sub(6) { - break; + if !window.contains(&i) { + continue; } let here = i == selected; let colour = colour_of(&a.state, &p); @@ -797,6 +897,7 @@ fn main() { plural(running.len()) ), ), + (p.dim.as_str(), showing(&window, agents.len(), running.len())), ], w - 1, )); @@ -812,16 +913,9 @@ fn main() { w - 1, )); } - // The idle section is claimed before the running list spends the - // pane, not after. It used to be filled up to the same h-2 the - // idle loop then checked, so on a busy machine the heading was - // pushed past the bottom and truncated - while the header counted - // the panes and the footer offered the key to reveal them. - let idle_room = if show_idle && !resting.is_empty() { IDLE_ROWS } else { 0 }; - let running_budget = h.saturating_sub(2 + idle_room); for (j, n) in running.iter().enumerate() { - if rows.len() >= running_budget { - break; + if !window.contains(&(agents.len() + j)) { + continue; } let here = agents.len() + j == selected; let tint = if here { tc::bg(38, 56, 76) } else { String::new() }; @@ -862,42 +956,31 @@ fn main() { )); } - // Two lines for the blank and the heading, one for a pane. Below - // that the section cannot be drawn, but the count still can: one - // line saying how many are there and that the pane is too short to - // list them, rather than nothing at all under a footer still - // offering the key. - if idle_fit(h, rows.len(), show_idle, resting.len()) == IdleFit::CountOnly { + // The idle section's heading is drawn whenever there is an idle + // section at all, and it is never what gets cut - that was TOY-34: + // dropping it silently left the footer offering [i]dle with nothing + // behind it. Rationing rows for it is no longer how that is kept. + // The window bounds the entries above, so the heading always fits, + // and it says how many are on screen when not all of them are. + if idle_listed { + rows.push(String::new()); rows.push(tc::seg( &[ (p.lbl.as_str(), " ── IDLE ── ".into()), ( p.dim.as_str(), - format!( - "{} pane{} at a prompt, too short to list", - resting.len(), - plural(resting.len()) - ), + format!("{} pane{} at a prompt", resting.len(), plural(resting.len())), ), - ], - w - 1, - )); - } - if idle_fit(h, rows.len(), show_idle, resting.len()) == IdleFit::Full { - rows.push(String::new()); - rows.push(tc::seg( - &[ - (p.lbl.as_str(), " ── IDLE ── ".into()), ( p.dim.as_str(), - format!("{} pane{} at a prompt", resting.len(), plural(resting.len())), + showing(&window, agents.len() + running.len(), resting.len()), ), ], w - 1, )); for (j, n) in resting.iter().enumerate() { - if rows.len() >= h.saturating_sub(2) { - break; + if !window.contains(&(agents.len() + running.len() + j)) { + continue; } let here = agents.len() + running.len() + j == selected; let tint = if here { tc::bg(38, 56, 76) } else { String::new() }; @@ -922,25 +1005,6 @@ fn main() { } } - // The footer must always be the last visible line, so the body is - // clamped to the space left for it rather than each section - // budgeting for itself - that drifted, and the footer ended up - // written past the bottom row. - let hints: Vec<Vec<(&str, String)>> = vec![ - vec![(p.accent.as_str(), "↑↓".into()), (p.dim.as_str(), " select".into())], - vec![ - (p.accent.as_str(), "↵".into()), - (p.dim.as_str(), " switch to this pane".into()), - ], - vec![(p.dim.as_str(), "[i]dle".into())], - vec![(p.dim.as_str(), "[l]abels".into())], - vec![(p.dim.as_str(), "[r]efresh".into())], - vec![(p.dim.as_str(), "[q]uit".into())], - ]; - let footer: Vec<String> = tc::pack_hints(&hints, w - 2, " ") - .into_iter() - .map(|l| format!(" {}", l)) - .collect(); let reserve = footer.len() + 1; // +1 for the note line rows.truncate(h.saturating_sub(reserve)); while rows.len() < h.saturating_sub(reserve) { @@ -975,45 +1039,101 @@ mod tests { use super::*; #[test] - fn the_idle_section_is_never_silently_absent() { - // The bug this replaces: the running list budgeted the whole pane - // and the idle heading was then pushed past the bottom, so the - // section vanished while the footer still offered its key. At - // every height, with idle panes to show, the answer must be - // something the reader can see - the full section, or the count - // saying why the rest is missing. - for h in 6usize..80 { - let body = h.saturating_sub(2); - for used in 0..body { - let got = idle_fit(h, used, true, 9); - assert_ne!( - got, - IdleFit::Nothing, - "h={} with {} rows used and 9 panes idle says nothing at all", - h, - used - ); + fn the_window_holds_the_cursor_whatever_the_rows_cost() { + // Fifteen agents at two rows each, then twenty-eight panes at one: + // the shape that broke it. A window counted in entries admits more + // rows than the pane has, they are cut off the bottom, and the + // cursor goes with them. + let heights: Vec<usize> = std::iter::repeat(2) + .take(15) + .chain(std::iter::repeat(1).take(28)) + .collect(); + for room in [1usize, 4, 12, 30, 200] { + for at in 0..heights.len() { + for from in [0usize, 5, 14, 30, 42] { + let w = window_over(&heights, at, room, from); + assert!(w.contains(&at), "room={} at={} from={} gave {:?}", room, at, from, w); + // And it fits, unless one entry alone is taller than the + // pane - in which case it is drawn anyway, because the + // alternative is drawing nothing. + let used: usize = heights[w.clone()].iter().sum(); + assert!( + used <= room || w.len() == 1, + "room={} at={} from={} drew {} rows in {:?}", + room, at, from, used, w + ); + } } } } #[test] - fn the_full_section_needs_a_heading_a_blank_and_a_pane() { - // Exactly at the boundary, and one row either side of it. - let h = 40; - let body = h - 2; - assert_eq!(idle_fit(h, body - IDLE_ROWS, true, 9), IdleFit::Full); - assert_eq!(idle_fit(h, body - IDLE_ROWS + 1, true, 9), IdleFit::CountOnly); - assert_eq!(idle_fit(h, body - 1, true, 9), IdleFit::CountOnly); - assert_eq!(idle_fit(h, body, true, 9), IdleFit::Nothing); + fn the_window_holds_still_while_the_cursor_moves_inside_it() { + let heights = vec![1usize; 40]; + // Already on screen: the view does not jump under the reader. + assert_eq!(window_over(&heights, 12, 10, 8), 8..18); + assert_eq!(window_over(&heights, 8, 10, 8), 8..18); + assert_eq!(window_over(&heights, 17, 10, 8), 8..18); + // Off the bottom: it moves by exactly enough. + assert_eq!(window_over(&heights, 18, 10, 8), 9..19); + // Off the top: it moves to the cursor rather than past it. + assert_eq!(window_over(&heights, 3, 10, 8), 3..13); + // An empty list has no window at all. + assert_eq!(window_over(&[], 0, 10, 0), 0..0); + } + + #[test] + fn a_heading_says_its_range_only_when_the_section_is_cut() { + // Thirteen agents, then fifteen running panes, then fifteen idle. + let (agents, running, resting) = (13usize, 15usize, 15usize); + let (a, r, i) = (0, agents, agents + running); + + // A window holding everything says nothing about ranges. + let all = 0..43; + assert_eq!(showing(&all, a, agents), ""); + assert_eq!(showing(&all, r, running), ""); + assert_eq!(showing(&all, i, resting), ""); + + // A window over the middle: agents cut short, running cut at both + // ends, idle not reached. + let mid = 6..20; + assert_eq!(showing(&mid, a, agents), " · showing 7-13"); + assert_eq!(showing(&mid, r, running), " · showing 1-7"); + assert_eq!(showing(&mid, i, resting), " · none on screen"); + + // And past the end: the sections above say so rather than showing a + // count with no rows under it. + let low = 30..43; + assert_eq!(showing(&low, a, agents), " · none on screen"); + assert_eq!(showing(&low, i, resting), " · showing 3-15"); + + // An empty section has no range to give. + assert_eq!(showing(&mid, r, 0), ""); } #[test] - fn nothing_is_drawn_when_there_is_nothing_to_say() { - // Hidden by the key, or no idle panes at all: silence is correct - // here, and is the only case where it is. - assert_eq!(idle_fit(60, 0, false, 9), IdleFit::Nothing); - assert_eq!(idle_fit(60, 0, true, 0), IdleFit::Nothing); + fn the_idle_section_is_never_silently_absent() { + // TOY-34's rule, which this rewrite had to keep: dropping the idle + // section silently left the footer offering [i]dle with nothing + // behind it. + // + // It used to be kept by rationing rows - the section was granted a + // heading only if the lists above had left room. It is now kept by + // construction: the window bounds how many entry rows the lists + // above can take, so the heading always fits, and when the window + // has scrolled past the idle panes the heading says that rather + // than nothing. + for start in 0..40usize { + for room in 1..12usize { + let window = start..start + room; + let said = showing(&window, 28, 15); + assert!( + !said.is_empty() || (window.start <= 28 && window.end >= 43), + "window {:?} says nothing about a section it does not hold", + window + ); + } + } } diff --git a/rust/widgets/src/bin/linear.rs b/rust/widgets/src/bin/linear.rs index ae7ae4e..812492b 100644 --- a/rust/widgets/src/bin/linear.rs +++ b/rust/widgets/src/bin/linear.rs @@ -389,21 +389,6 @@ fn project_columns(w: usize, base: usize, label_w: usize, aside: usize) -> (usiz (label_cost, bar, room) } -/// Where a window of `room` rows has to start to keep `row` in view. -/// -/// Every screen here is now drawn whole and shown through a window, and all -/// three of them - the board, a team, a project - move it the same way. It -/// is one function so that a test can break it, which a copy inlined three -/// times could not have. -fn follow(at: usize, row: usize, room: usize) -> usize { - if row < at { - row - } else if row + 1 > at + room { - row + 1 - room - } else { - at - } -} /// Break text to a width without breaking a word, and without dropping one. fn wrap(t: &str, width: usize) -> Vec<String> { @@ -2814,7 +2799,7 @@ fn main() { // The page follows the cursor into the project list, the // way netwatch's detail follows one into a section. if let Some(row) = cursor { - *at = follow(*at, row, room); + *at = tc::follow(*at, row, room); } *at = (*at).min(body.len().saturating_sub(room)); let from = *at; @@ -2881,7 +2866,7 @@ fn main() { // arrows move the window itself. let room = h.saturating_sub(footer.len()).max(1); if let Some(at) = cursor { - board = follow(board, at, room); + board = tc::follow(board, at, room); } board = board.min(rows.len().saturating_sub(room)); board_len = rows.len(); @@ -3360,29 +3345,6 @@ mod tests { assert!(label_cost > 0 && bar == 30 && room >= aside); } - #[test] - fn the_window_chases_a_cursor_it_cannot_see() { - // Stated as what the reader sees rather than as the arithmetic: - // wherever the cursor is, the window has to contain it, and it has - // to move as little as it can to do that. - let holds = |at: usize, row: usize, room: usize| row >= at && row < at + room; - for room in [1usize, 3, 20] { - for start in [0usize, 5, 30] { - for row in [0usize, 4, 7, 12, 40] { - let moved = follow(start, row, room); - assert!(holds(moved, row, room), "row {} not in {}..+{}", row, moved, room); - // Not moved at all when it did not need to be. - if holds(start, row, room) { - assert_eq!(moved, start, "moved without needing to"); - } - } - } - } - // Reaching down puts the cursor on the last row, not past it. - assert_eq!(follow(0, 40, 20) + 20, 41); - // Reaching up puts it on the first. - assert_eq!(follow(30, 4, 20), 4); - } #[test] fn a_team_with_no_projects_says_so_rather_than_showing_an_empty_heading() { From 22a9bc77516b9b30ee58a9dd1134efdf616c455f Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Tue, 25 Aug 2026 21:22:20 +0800 Subject: [PATCH 113/147] rust moves to the root, and the Python goes The port is over. Fourteen widgets, a shared core and a check that reads them all live at the top of the tree now, and the seventeen Python files they were ported from are gone. `git mv` throughout, so `--follow` still reaches every widget's history - fourteen docs and the whole of TOY-8's review record cite paths under `rust/`, and a delete-and-recreate would have cut them off from what they describe. Three things had to move with it: `start` embeds every widget's doc with `include_str!`, and the path to `docs/` is one directory shorter from here. `check.rs` resolves the repo root from its own crate, which is also one shorter, and looked for widgets under `rust/widgets/src/bin`. Verified it is reading the new layout rather than quietly finding nothing: a hint for a key nothing answers, planted in tailnet, was caught by name along with the doc it was missing from. `.gitignore` keeps the half that matters - config.json and the secret variants - and trades the Python's `__pycache__` and virtualenvs for `target/`. `start` still answers to `netwatch.py`. Every widget here had that name for years and the muscle memory outlives the files; the suffix is stripped and the binary of the same stem runs. It is the one place the Python is still spoken. What leaves with the Python, said out loud rather than quietly absorbed: `check.py`, which covered the same ground as `check.rs` for `*.py` plus unbound names - a class of bug the compiler makes impossible. Nothing else it guarded is uncovered: `config.example.json` is read by `check.rs` too, and it still passes, so the example held no key only the Python read. Docs, README and AGENTS.md follow in the next commit; they still describe two implementations. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- .gitignore | 5 +- rust/Cargo.lock => Cargo.lock | 0 rust/Cargo.toml => Cargo.toml | 0 __main__.py | 29 - check.py | 185 - clocks.py | 701 ---- common.py | 583 --- {rust/core => core}/Cargo.toml | 0 {rust/core => core}/src/lib.rs | 0 {rust/core => core}/tests/bounded.rs | 0 deployments.py | 627 --- github.py | 811 ---- herdr-panes.py | 518 --- latency.py | 512 --- linear.py | 710 ---- link.py | 778 ---- matrix.py | 101 - netwatch.py | 1427 ------- ports.py | 1363 ------- pr.py | 1073 ----- rust/.gitignore | 1 - start.py | 272 -- tailnet.py | 893 ---- usage.py | 3607 ----------------- {rust/widgets => widgets}/Cargo.toml | 0 {rust/widgets => widgets}/src/bin/clocks.rs | 0 .../src/bin/clocks_help.txt | 0 .../src/bin/deployments.rs | 0 .../src/bin/deployments_help.txt | 0 {rust/widgets => widgets}/src/bin/github.rs | 0 .../src/bin/github_help.txt | 0 .../src/bin/herdr-panes.rs | 0 .../src/bin/herdr-panes_help.txt | 0 {rust/widgets => widgets}/src/bin/latency.rs | 0 .../src/bin/latency_help.txt | 0 {rust/widgets => widgets}/src/bin/linear.rs | 0 .../src/bin/linear_help.txt | 0 {rust/widgets => widgets}/src/bin/link.rs | 0 .../widgets => widgets}/src/bin/link_help.txt | 0 {rust/widgets => widgets}/src/bin/matrix.rs | 0 .../src/bin/matrix_help.txt | 0 {rust/widgets => widgets}/src/bin/netwatch.rs | 0 .../src/bin/netwatch_help.txt | 0 {rust/widgets => widgets}/src/bin/ports.rs | 0 .../src/bin/ports_help.txt | 0 {rust/widgets => widgets}/src/bin/pr.rs | 0 {rust/widgets => widgets}/src/bin/pr_help.txt | 0 {rust/widgets => widgets}/src/bin/start.rs | 27 +- .../src/bin/start_help.txt | 0 {rust/widgets => widgets}/src/bin/tailnet.rs | 0 .../src/bin/tailnet_help.txt | 0 {rust/widgets => widgets}/src/bin/usage.rs | 0 .../src/bin/usage/antigravity.rs | 0 .../src/bin/usage/claude.rs | 0 .../src/bin/usage/codex.rs | 0 .../src/bin/usage/copilot.rs | 0 .../src/bin/usage/cursor.rs | 0 .../widgets => widgets}/src/bin/usage/grok.rs | 0 .../src/bin/usage/shared.rs | 0 .../src/bin/usage/vendors.rs | 0 .../src/bin/usage_help.txt | 0 {rust/widgets => widgets}/tests/check.rs | 6 +- 62 files changed, 19 insertions(+), 14210 deletions(-) rename rust/Cargo.lock => Cargo.lock (100%) rename rust/Cargo.toml => Cargo.toml (100%) delete mode 100644 __main__.py delete mode 100755 check.py delete mode 100755 clocks.py delete mode 100644 common.py rename {rust/core => core}/Cargo.toml (100%) rename {rust/core => core}/src/lib.rs (100%) rename {rust/core => core}/tests/bounded.rs (100%) delete mode 100755 deployments.py delete mode 100755 github.py delete mode 100755 herdr-panes.py delete mode 100755 latency.py delete mode 100755 linear.py delete mode 100755 link.py delete mode 100755 matrix.py delete mode 100755 netwatch.py delete mode 100755 ports.py delete mode 100755 pr.py delete mode 100644 rust/.gitignore delete mode 100755 start.py delete mode 100755 tailnet.py delete mode 100755 usage.py rename {rust/widgets => widgets}/Cargo.toml (100%) rename {rust/widgets => widgets}/src/bin/clocks.rs (100%) rename {rust/widgets => widgets}/src/bin/clocks_help.txt (100%) rename {rust/widgets => widgets}/src/bin/deployments.rs (100%) rename {rust/widgets => widgets}/src/bin/deployments_help.txt (100%) rename {rust/widgets => widgets}/src/bin/github.rs (100%) rename {rust/widgets => widgets}/src/bin/github_help.txt (100%) rename {rust/widgets => widgets}/src/bin/herdr-panes.rs (100%) rename {rust/widgets => widgets}/src/bin/herdr-panes_help.txt (100%) rename {rust/widgets => widgets}/src/bin/latency.rs (100%) rename {rust/widgets => widgets}/src/bin/latency_help.txt (100%) rename {rust/widgets => widgets}/src/bin/linear.rs (100%) rename {rust/widgets => widgets}/src/bin/linear_help.txt (100%) rename {rust/widgets => widgets}/src/bin/link.rs (100%) rename {rust/widgets => widgets}/src/bin/link_help.txt (100%) rename {rust/widgets => widgets}/src/bin/matrix.rs (100%) rename {rust/widgets => widgets}/src/bin/matrix_help.txt (100%) rename {rust/widgets => widgets}/src/bin/netwatch.rs (100%) rename {rust/widgets => widgets}/src/bin/netwatch_help.txt (100%) rename {rust/widgets => widgets}/src/bin/ports.rs (100%) rename {rust/widgets => widgets}/src/bin/ports_help.txt (100%) rename {rust/widgets => widgets}/src/bin/pr.rs (100%) rename {rust/widgets => widgets}/src/bin/pr_help.txt (100%) rename {rust/widgets => widgets}/src/bin/start.rs (96%) rename {rust/widgets => widgets}/src/bin/start_help.txt (100%) rename {rust/widgets => widgets}/src/bin/tailnet.rs (100%) rename {rust/widgets => widgets}/src/bin/tailnet_help.txt (100%) rename {rust/widgets => widgets}/src/bin/usage.rs (100%) rename {rust/widgets => widgets}/src/bin/usage/antigravity.rs (100%) rename {rust/widgets => widgets}/src/bin/usage/claude.rs (100%) rename {rust/widgets => widgets}/src/bin/usage/codex.rs (100%) rename {rust/widgets => widgets}/src/bin/usage/copilot.rs (100%) rename {rust/widgets => widgets}/src/bin/usage/cursor.rs (100%) rename {rust/widgets => widgets}/src/bin/usage/grok.rs (100%) rename {rust/widgets => widgets}/src/bin/usage/shared.rs (100%) rename {rust/widgets => widgets}/src/bin/usage/vendors.rs (100%) rename {rust/widgets => widgets}/src/bin/usage_help.txt (100%) rename {rust/widgets => widgets}/tests/check.rs (99%) diff --git a/.gitignore b/.gitignore index a88863d..a11bf6f 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,4 @@ -__pycache__/ -*.py[cod] -.venv/ -venv/ +target/ .DS_Store # Personal settings, and now secrets: config.json holds the Vercel token. diff --git a/rust/Cargo.lock b/Cargo.lock similarity index 100% rename from rust/Cargo.lock rename to Cargo.lock diff --git a/rust/Cargo.toml b/Cargo.toml similarity index 100% rename from rust/Cargo.toml rename to Cargo.toml diff --git a/__main__.py b/__main__.py deleted file mode 100644 index 05b8a7a..0000000 --- a/__main__.py +++ /dev/null @@ -1,29 +0,0 @@ -#!/usr/bin/env python3 -# terminal-toys - small dependency-free terminal widgets -# Copyright (C) 2026 William Li -# -# This program is free software: you can redistribute it and/or modify -# it under the terms of the GNU Affero General Public License as published -# by the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU Affero General Public License for more details. -# -# You should have received a copy of the GNU Affero General Public License -# along with this program. If not, see <https://www.gnu.org/licenses/>. -"""Makes the directory itself runnable: `python3 terminal-toys`. - -Python's own convention for an entry point, so the collection can be started -without knowing which file inside it to name. Everything it does is in -start.py; this is the doorbell, not the door. -""" -import os -import runpy -import sys - -HERE = os.path.dirname(os.path.abspath(__file__)) -sys.argv[0] = os.path.join(HERE, "start.py") -runpy.run_path(sys.argv[0], run_name="__main__") diff --git a/check.py b/check.py deleted file mode 100755 index 4582e15..0000000 --- a/check.py +++ /dev/null @@ -1,185 +0,0 @@ -#!/usr/bin/env python3 -# terminal-toys - small dependency-free terminal widgets -# Copyright (C) 2026 William Li -# -# This program is free software: you can redistribute it and/or modify -# it under the terms of the GNU Affero General Public License as published -# by the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU Affero General Public License for more details. -# -# You should have received a copy of the GNU Affero General Public License -# along with this program. If not, see <https://www.gnu.org/licenses/>. -"""Checks for the failure modes these widgets actually had. - - python3 check.py - -Every check here exists because something shipped broken. `compile()` catches -none of them: each is a runtime or presentation fault that looks, on screen, -exactly like "there is no data". -""" -import ast -import builtins -import glob -import json -import os -import re -import sys - -os.chdir(os.path.dirname(os.path.abspath(__file__))) -# The library, the checker, the launcher and the directory's entry point are -# not widgets: none of them draws a panel, and none has a doc page of the -# shape these checks look for. -WIDGETS = [f for f in sorted(glob.glob("*.py")) - if f not in ("common.py", "check.py", "start.py", "__main__.py")] -PROBLEMS = [] - - -def fail(check, where, detail): - PROBLEMS.append((check, where, detail)) - - -def bound_names(tree): - out = {"__file__", "__name__", "__doc__"} - for n in ast.walk(tree): - if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)): - out.add(n.name) - args = getattr(n, "args", None) - if args: - for grp in (args.posonlyargs, args.args, args.kwonlyargs): - out |= {a.arg for a in grp} - for a in (args.vararg, args.kwarg): - if a: - out.add(a.arg) - elif isinstance(n, ast.Lambda): - for grp in (n.args.posonlyargs, n.args.args, n.args.kwonlyargs): - out |= {a.arg for a in grp} - elif isinstance(n, (ast.Import, ast.ImportFrom)): - out |= {(a.asname or a.name).split(".")[0] for a in n.names} - elif isinstance(n, ast.Name) and isinstance(n.ctx, (ast.Store, ast.Del)): - out.add(n.id) - elif isinstance(n, ast.ExceptHandler) and n.name: - out.add(n.name) - elif isinstance(n, ast.Global): - out |= set(n.names) - return out - - -def check_unbound(): - """A name used but never bound raises NameError only when reached. - - deployments.py lost `config_token_warning` from its imports and its poll - thread died on the first iteration for a day, showing an empty board. - """ - for f in WIDGETS + ["common.py"]: - tree = ast.parse(open(f).read()) - used = {n.id for n in ast.walk(tree) - if isinstance(n, ast.Name) and isinstance(n.ctx, ast.Load)} - for name in sorted(used - bound_names(tree) - set(dir(builtins))): - fail("unbound name", f, name) - - -def check_poller_guarded(): - """A daemon thread that raises simply stops. - - The widget then shows no data and no error, which is indistinguishable - from a source that genuinely has none. - """ - for f in WIDGETS: - src = open(f).read() - if "threading.Thread" not in src: - continue - tree = ast.parse(src) - ok = False - for n in ast.walk(tree): - if (isinstance(n, ast.FunctionDef) and n.name in ("run", "reader") - and any(isinstance(b, ast.Try) for b in n.body)): - ok = True - if not ok: - fail("unguarded poller", f, "run()/reader() may die silently") - - -def check_config_keys(): - """A key in the example the widget never reads is a lie in a sample file.""" - try: - example = json.load(open("config.example.json")) - except (OSError, ValueError) as e: - return fail("config.example.json", "-", str(e)[:60]) - # a section can be read by more than one widget - pr.py borrows github's - # token - so a key is only dead if *nothing* reads it - known = {} - for f in WIDGETS: - for m in re.finditer(r'load_config\(\s*"(\w+)"\s*,\s*\{(.*?)\n\}\)', - open(f).read(), re.S): - known.setdefault(m.group(1), set()) - known[m.group(1)] |= set(re.findall(r'"(\w+)":', m.group(2))) - # The port reads the same file, and has keys of its own. A setting the - # Rust reads is not dead because the Python has not caught up - it would - # only be dead if nothing at all read it, and this script can only see - # half the tree. Read as text: a key counts as read if the widget - # mentions it, which is the same rule the Rust check settled on after - # two attempts that guessed at the variable name and got it wrong. - ported = {} - for section in known: - found = set() - for path in glob.glob("rust/widgets/src/bin/%s.rs" % section) + glob.glob( - "rust/widgets/src/bin/%s/*.rs" % section - ): - try: - found.add(open(path).read()) - except OSError: - pass - ported[section] = "\n".join(found) - for section, keys in known.items(): - shipped = {k for k in example.get(section, {}) if not k.startswith("_")} - for dead in sorted(shipped - keys): - if '"%s"' % dead in ported.get(section, ""): - continue - fail("dead config key", section, dead) - - -def check_docs(): - """Every widget carries a doc page and a README row, or says why not.""" - readme = open("README.md").read() - for f in WIDGETS: - if f == "matrix.py": # decorative, deliberately undocumented - continue - if not os.path.exists("docs/%s.md" % f[:-3]): - fail("missing doc", f, "docs/%s.md" % f[:-3]) - if "`%s`" % f not in readme: - fail("missing README row", f, "not in the widget table") - - -def check_keys_documented(): - """A documented key that does not exist teaches a lie; so does the reverse.""" - for f in WIDGETS: - doc = "docs/%s.md" % f[:-3] - if not os.path.exists(doc): - continue - src, text = open(f).read(), open(doc).read() - handled = set(re.findall(r'key\s*(?:==|in\s*\()\s*[("]([a-z0-9])["\)]', - src)) - # a footer hint is "[w]indow" or "[r]efresh": the bracket is followed - # straight away by the rest of the word. Indexing like rows[0] is not. - hinted = set(re.findall(r'\[([a-z0-9])\](?=[a-z])', - " ".join(re.findall(r'"([^"\n]*)"', src)))) - for k in sorted(hinted - set(re.findall(r'`([a-z0-9])`', text))): - fail("undocumented key", f, "[%s] in the footer, not in %s" % (k, doc)) - - -for fn in (check_unbound, check_poller_guarded, check_config_keys, - check_docs, check_keys_documented): - fn() - -if not PROBLEMS: - print("all checks pass across %d widgets" % len(WIDGETS)) - raise SystemExit(0) -width = max(len(p[0]) for p in PROBLEMS) -for check, where, detail in PROBLEMS: - print("%-*s %-18s %s" % (width, check, where, detail)) -print("\n%d problem(s)" % len(PROBLEMS)) -raise SystemExit(1) diff --git a/clocks.py b/clocks.py deleted file mode 100755 index 5c61a46..0000000 --- a/clocks.py +++ /dev/null @@ -1,701 +0,0 @@ -#!/usr/bin/env python3 -# terminal-toys - small dependency-free terminal widgets -# Copyright (C) 2026 William Li -# -# This program is free software: you can redistribute it and/or modify -# it under the terms of the GNU Affero General Public License as published -# by the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU Affero General Public License for more details. -# -# You should have received a copy of the GNU Affero General Public License -# along with this program. If not, see <https://www.gnu.org/licenses/>. -"""Clocks: this server's, everyone else's, and the ones counting down. - -A big clock in the machine's own timezone, countdown bars for the next hour, -office hours and the end of day, an optional pomodoro, and a world clock -covering the hubs you care about. - -The pomodoro is off until you press p. It runs the standard 25/5 with a longer -break every fourth session, all configurable, and persists across restarts so -relaunching the panel does not cost you a session. - -A phase does not end itself. When the time is up the counter keeps going, -showing how far over you are, and the bar rescales so a growing red section -represents the overrun — the longer you ignore it, the more of the bar is red. -The whole panel also flashes twice, a second apart, on every alert - visible -with the sound muted. The terminal is alerted when the phase elapses and again -every minute it keeps running: BEL plus OSC 9 and OSC 777 desktop notifications, which are the only -channels that survive SSH. Under Herdr it additionally raises a native toast -with a sound — additive, never required, and skipped entirely elsewhere. - -Keys: up/down (and PgUp/PgDn, Home/End) scroll the city list while the clock, -countdowns and footer stay pinned. p shows or hides the pomodoro and suspends -it with them, space pauses or -resumes, r restarts the phase, s starts a break during focus and ends one during -a break - b and e do the same, and the footer names whichever applies - +/- -change the focus length, ? hides or shows the pomodoro controls, -0 zeroes today's completed count, q quits. - -The completed tally is per day: it resets when the date changes, including -while the panel is running. Preferences - focus length, whether the timer is -shown - are not tied to the day and persist. - -Big digits show this server's system-timezone clock. Below it, each hub -is shown in its own timezone, sorted west to east, coloured by whether people -there are plausibly at work. -""" -import datetime -import json -import os -import re -import subprocess -import sys -import time -from zoneinfo import ZoneInfo - -sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) -from common import (RST, Keyboard, bar, bg, big, draw, flush, load_config, - maybe_help, out, pack_hints, pad, rgb, seg, setup, size, - title) - -# None = follow the system timezone for the big digits. -TZ = None - -_CFG = load_config("clocks", { - "cities": [ - ["San Francisco", "America/Los_Angeles"], - ["New York", "America/New_York"], - ["London", "Europe/London"], - ["Berlin", "Europe/Berlin"], - ["Bengaluru", "Asia/Kolkata"], - ["Singapore", "Asia/Singapore"], - ["Tokyo", "Asia/Tokyo"], - ["Sydney", "Australia/Sydney"], - ], - "work_start_hour": 9, - "work_end_hour": 18, - "pomodoro_enabled": False, - "pomodoro_focus_minutes": 25, - "pomodoro_short_break_minutes": 5, - "pomodoro_long_break_minutes": 15, - "pomodoro_sessions_before_long_break": 4, - "pomodoro_bell": True, # terminal bell on elapse and each minute over - "pomodoro_notify": True, # OSC 9 desktop notification, where supported - "pomodoro_flash": True, # flash the panel when an alert fires - "pomodoro_flash_count": 2, # how many flashes - "pomodoro_flash_gap": 1.0, # seconds between them - "pomodoro_flash_rgb": [246, 248, 252], # flash colour; near-white by default - "show_hints": True, # key hints along the bottom; ? toggles -}) - -CITIES = [tuple(c) for c in _CFG["cities"]] - - -WORK_START_H = int(_CFG["work_start_hour"]) -WORK_END_H = int(_CFG["work_end_hour"]) - -# Pomodoro: 25 minutes of focus, 5 off, a longer break every fourth session. -PHASES = ("focus", "short", "long") -PHASE_LABEL = {"focus": "FOCUS", "short": "SHORT BREAK", "long": "LONG BREAK"} -STATE_FILE = os.path.join( - os.environ.get("XDG_STATE_HOME") or os.path.expanduser("~/.local/state"), - "terminal-toys", "pomodoro.json") - -C1 = rgb(120, 255, 200) -PURPLE = rgb(175, 130, 255) -HOUR = rgb(90, 220, 255) -FOCUS = rgb(255, 130, 120) -BREAK = rgb(120, 235, 170) -PAUSED = rgb(160, 172, 190) -OVER = rgb(255, 80, 90) -C2 = rgb(40, 150, 120) -DIM = rgb(70, 130, 110) -TXT = rgb(220, 255, 240) -WORK = rgb(130, 255, 180) # inside working hours -EVE = rgb(255, 200, 90) # evening -NIGHT = rgb(95, 130, 175) # asleep -WEEKEND = rgb(150, 150, 170) -HERE = rgb(255, 170, 220) - - -ANSI_RE = re.compile(r"\x1b\[[0-9;]*m") -FLASH_ON = 0.35 # seconds each flash stays lit -_FLASH_RGB = tuple(int(c) for c in _CFG["pomodoro_flash_rgb"])[:3] -FLASH_BG = bg(*_FLASH_RGB) -# Text colour follows the flash colour rather than being fixed, so a custom -# dark flash stays readable instead of turning the panel into a black square. -_FLASH_LUM = (0.2126 * _FLASH_RGB[0] + 0.7152 * _FLASH_RGB[1] - + 0.0722 * _FLASH_RGB[2]) / 255.0 -FLASH_FG = rgb(18, 20, 26) if _FLASH_LUM > 0.5 else rgb(255, 240, 240) - - -def flash_window(started, count, gap): - """Is the panel lit right now? - - Flashes are derived from one timestamp rather than driven by sleeps, so - the render loop keeps running - the clock stays live and keys stay - responsive while it blinks. - """ - if not started: - return False - since = time.time() - started - for n in range(max(1, count)): - edge = n * gap - if edge <= since < edge + FLASH_ON: - return True - return False - - -def flash_frame(rows, w, h): - """The same frame, repainted solid: colours stripped, one loud background.""" - out_rows = [] - for i in range(h): - text = ANSI_RE.sub("", rows[i]) if i < len(rows) else "" - out_rows.append(FLASH_BG + FLASH_FG + pad(text, w)) - return out_rows - - -# Herdr, when we happen to be inside it, can raise a real toast with a sound. -# Purely additive: nothing here requires Herdr, and outside it this is skipped. -UNDER_HERDR = os.environ.get("HERDR_ENV") == "1" - - -def herdr_toast(title, body, sound="done"): - """Best-effort native Herdr notification; a no-op anywhere else. - - Fire and forget: waiting on a subprocess would stall the render loop, and - a failed toast is not worth interrupting a timer for. Herdr itself decides - whether to display it, per `[ui.toast] delivery` in its config. - """ - if not UNDER_HERDR: - return - try: - subprocess.Popen(["herdr", "notification", "show", title, - "--body", body, "--sound", sound], - stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL) - except OSError: - pass - - -def alert(text, bell=True, notify=True, sound="done"): - """Nudge the user through the terminal, requiring nothing but a terminal. - - Escape sequences are the only alerting channel that survives SSH: the - program runs on a server, so anything local to it - notify-send, a sound - file - would fire where nobody is sitting. These reach the terminal the - user is actually in front of. - - BEL is universal. OSC 9 covers iTerm2, WezTerm, Windows Terminal and - Ghostty; OSC 777 covers urxvt and several others. Terminals ignore the - notification sequences they do not implement, so sending both costs - nothing. A multiplexer in between decides whether to forward them. - """ - if bell: - out("\a") - if notify: - out("\x1b]9;%s\x07" % text) # iTerm2 & friends - out("\x1b]777;notify;Pomodoro;%s\x07" % text) # urxvt & friends - flush() - if notify: - herdr_toast("Pomodoro", text, sound) - - -class Pomodoro(object): - """A pomodoro that survives the panel being restarted. - - Panels get relaunched often, and losing a 20-minute session to that would - make the timer useless, so phase and elapsed time are persisted and - reloaded. Time is tracked as an absolute deadline rather than by counting - down, so a stalled or slow redraw cannot make the timer drift. - """ - - def __init__(self): - self.focus = int(_CFG["pomodoro_focus_minutes"]) - self.short = int(_CFG["pomodoro_short_break_minutes"]) - self.long = int(_CFG["pomodoro_long_break_minutes"]) - self.cycle = int(_CFG["pomodoro_sessions_before_long_break"]) - self.enabled = bool(_CFG["pomodoro_enabled"]) - self.phase = "focus" - self.completed = 0 - self.running = False - self.left = self.focus * 60.0 # seconds remaining when paused - self.deadline = None # wall-clock end when running - self.rang = False - self.day = time.strftime("%Y-%m-%d") - self.was_running = False # run state to restore when unhidden - # A display preference rather than timer state, but it rides along in - # the same file so the panel comes back looking how you left it. - self.hints = bool(_CFG["show_hints"]) - self.nagged = 0 # whole minutes of overtime already alerted - self.bell = bool(_CFG["pomodoro_bell"]) - self.notify = bool(_CFG["pomodoro_notify"]) - self._load() - - # ---- persistence ------------------------------------------------- - def _load(self): - try: - with open(STATE_FILE) as f: - d = json.load(f) - except (OSError, ValueError): - return - # Preferences outlive the day; only the tally and the block in - # progress belong to it. - self.focus = int(d.get("focus", self.focus)) - self.enabled = bool(d.get("enabled", self.enabled)) - self.hints = bool(d.get("hints", self.hints)) - if d.get("day") != self.day: - return # a new day starts a fresh count - self.phase = d.get("phase", self.phase) - self.completed = int(d.get("completed", 0)) - self.was_running = bool(d.get("was_running", False)) - self.left = float(d.get("left", self.left)) - if d.get("running") and d.get("deadline"): - # resume mid-phase; if it elapsed while we were away the timer - # simply shows how far over it has run - self.deadline = float(d["deadline"]) - self.running = True - self.rang = self.signed() <= 0 - - def save(self): - try: - os.makedirs(os.path.dirname(STATE_FILE), exist_ok=True) - with open(STATE_FILE, "w") as f: - json.dump({"day": self.day, "phase": self.phase, - "completed": self.completed, "focus": self.focus, - "enabled": self.enabled, "running": self.running, - "was_running": self.was_running, - "hints": self.hints, - "left": self.left, "deadline": self.deadline}, f) - except OSError: - pass - - # ---- state ------------------------------------------------------- - def duration(self): - return {"focus": self.focus, "short": self.short, - "long": self.long}[self.phase] * 60.0 - - def signed(self): - """Seconds left; negative once the phase has been overrun.""" - if self.running and self.deadline: - return self.deadline - time.time() - return self.left - - def remaining(self): - return max(0.0, self.signed()) - - def overtime(self): - return max(0.0, -self.signed()) - - def toggle(self): - """Show/hide, and suspend with it. - - A timer that keeps counting while hidden is worse than no timer: you - come back to a focus block that expired half an hour ago. Hiding - freezes it where it stands, and showing resumes it only if it was - running when it went away. - """ - if self.enabled: - self.was_running = self.running - if self.running: - self.pause() # freezes, preserving any overtime - self.enabled = False - else: - self.enabled = True - if self.was_running and not self.running: - self.pause() # resume exactly where it stopped - self.save() - - def pause(self): - if self.running: - self.left = self.signed() # keeps any overtime accrued - self.running, self.deadline = False, None - else: - self.deadline = time.time() + self.signed() - self.running = True - self.save() - - def restart(self): - self.left = self.duration() - self.deadline = time.time() + self.left if self.running else None - self.rang = False - self.nagged = 0 - self.save() - - def advance(self): - """Move to the next phase; a long break every `cycle` focus sessions. - - Keeps whatever run state it had: skipping out of a running focus block - starts the break immediately, which is what "I am done, move on" means. - """ - if self.phase == "focus": - self.completed += 1 - self.phase = ("long" if self.cycle and self.completed % self.cycle == 0 - else "short") - else: - self.phase = "focus" - self.left = self.duration() - self.deadline = time.time() + self.left if self.running else None - self.rang = False - self.nagged = 0 - self.save() - - def next_label(self): - """What pressing the advance key will actually do, right now. - - The same key starts a break during focus and ends one during a break, - so a fixed label like "skip" describes neither. - """ - if self.phase != "focus": - return "[e]nd break" - upcoming_long = self.cycle and (self.completed + 1) % self.cycle == 0 - return "[s]tart long break" if upcoming_long else "[s]tart break" - - def roll_day(self): - """Zero the tally when the date changes, even if nothing restarted. - - The count previously reset only on load, so a panel left running over - midnight kept adding to yesterday's total. - """ - today = time.strftime("%Y-%m-%d") - if today != self.day: - self.day = today - self.completed = 0 - self.save() - return True - return False - - def reset_count(self): - """Zero today's completed count, leaving the running phase alone.""" - self.completed = 0 - self.save() - - def adjust(self, delta): - """Change the focus length, shifting the block in progress by the same. - - The bar divides by duration() while the counter reads the deadline, so - changing one without the other made them disagree - the bar moved and - the countdown sat still. Both now shift together: +5 means five more - minutes on the clock, whether the block is running, paused, or has not - started. - """ - before = self.focus - # Snap to the next multiple of five rather than adding to whatever is - # there: stepping by five from an odd length can never reach a round - # number, so 1 minute becomes 6, 11, 16 and never 25. - step = 5 - target = ((before // step + 1) * step if delta > 0 - else (before - 1) // step * step) - self.focus = max(1, min(120, target)) - change = (self.focus - before) * 60.0 - if change and self.phase == "focus": - if self.running and self.deadline: - self.deadline += change - else: - self.left += change - if self.signed() > 0: - # extended back out of overtime, so let it alert again - self.rang = False - self.nagged = 0 - self.save() - - def tick(self): - """True exactly once, when a phase elapses. - - The phase is not advanced automatically: overrunning a focus block is - worth seeing rather than silently resetting, so the timer keeps - counting upward until `s` moves it on. - """ - if not self.running: - return False - over = self.overtime() - if over <= 0: - return False - if not self.rang: - self.rang = True - self.nagged = 0 - return True - # keep nagging once per minute for as long as it is ignored - minutes = int(over // 60) - if minutes > self.nagged: - self.nagged = minutes - return True - return False - - -def hint_tokens(pomo): - """Key hints for the current state, as atomic tokens for pack_hints. - - Only the pomodoro's own controls are hidden by `?`. The toggle itself and - the panel-level keys always stay: hiding the way back leaves no way back. - """ - tokens = [] - if pomo.enabled and pomo.hints: - tokens += [[(DIM, "[space] "), (TXT, "pause" if pomo.running else "start")], - [(DIM, pomo.next_label())], - [(DIM, "[r]estart")], - [(DIM, "[±]%dmin" % pomo.focus)]] - if pomo.completed: - # nothing to reset at zero, so the hint only appears once it counts - tokens.append([(DIM, "[0]reset %d done" % pomo.completed)]) - tokens.append([(DIM, "[p]off" if pomo.enabled else "[p] pomodoro")]) - tokens.append([(DIM, "↑↓ cities")]) - if pomo.enabled: - # only meaningful while there are pomodoro controls to hide, but shown - # even when they are hidden, so there is always a way back. Names the - # action rather than the state, like [s]tart break / [e]nd break. - tokens.append([(DIM, "[?]%s pomodoro tips" - % ("hide" if pomo.hints else "show"))]) - return tokens - - -def render_big(s, w): - return big(s, w) - - -def offset_str(dt): - off = dt.utcoffset() - total = int(off.total_seconds()) // 60 - sign = "+" if total >= 0 else "-" - total = abs(total) - if total % 60: - return "UTC%s%d:%02d" % (sign, total // 60, total % 60) - return "UTC%s%d" % (sign, total // 60) - - -def hms(seconds): - seconds = max(0, int(seconds)) - return "%02d:%02d:%02d" % (seconds // 3600, seconds % 3600 // 60, seconds % 60) - - -def at(now, day, hour): - """Wall-clock `hour` on `day`, in the same timezone as `now`.""" - return datetime.datetime.combine(day, datetime.time(hour, 0), tzinfo=now.tzinfo) - - -def is_office(dt): - return dt.weekday() < 5 and WORK_START_H <= dt.hour < WORK_END_H - - -def next_open(now): - day = now.date() - cand = at(now, day, WORK_START_H) - while cand <= now or cand.weekday() >= 5: - day += datetime.timedelta(days=1) - cand = at(now, day, WORK_START_H) - return cand - - -def prev_close(now): - day = now.date() - cand = at(now, day, WORK_END_H) - while cand > now or cand.weekday() >= 5: - day -= datetime.timedelta(days=1) - cand = at(now, day, WORK_END_H) - return cand - - -def office_countdown(now): - """Office hours are Mon-Fri 09:00-18:00 local.""" - if is_office(now): - start = at(now, now.date(), WORK_START_H) - end = at(now, now.date(), WORK_END_H) - span = (end - start).total_seconds() - return ("End of Office Hour", hms((end - now).total_seconds()), - (now - start).total_seconds() / span) - opens = next_open(now) - closed = prev_close(now) - span = (opens - closed).total_seconds() - return ("Start of Office Hour", hms((opens - now).total_seconds()), - (now - closed).total_seconds() / span if span > 0 else 0.0) - - -def countdowns(now): - """Real countdowns for the current local day. Returns rows of - (label, text, elapsed_fraction, colour), stacked top to bottom.""" - midnight = now.replace(hour=0, minute=0, second=0, microsecond=0) - day_end = midnight + datetime.timedelta(days=1) - hour_start = now.replace(minute=0, second=0, microsecond=0) - hour_end = hour_start + datetime.timedelta(hours=1) - label, text, frac = office_countdown(now) - - return [ - ("Next Hour", hms((hour_end - now).total_seconds()), - (now - hour_start).total_seconds() / 3600.0, HOUR), - (label, text, frac, EVE), - ("End of Day", hms((day_end - now).total_seconds()), - (now - midnight).total_seconds() / 86400.0, PURPLE), - ] - - -def phase(dt): - """Colour + glyph for what people there are plausibly doing.""" - hour = dt.hour + dt.minute / 60.0 - weekend = dt.weekday() >= 5 - if hour < 6.5 or hour >= 22: - return NIGHT, "☾" - if weekend: - return WEEKEND, "☀" - if 9 <= hour < 18: - return WORK, "☀" - if hour >= 18: - return EVE, "☾" - return EVE, "☀" - - -def main(): - maybe_help(__doc__) - setup() - keyboard = Keyboard() - pomo = Pomodoro() - scroll = 0 - flash_at = 0.0 - zones = [] - for name, key in CITIES: - try: - zones.append((name, ZoneInfo(key))) - except Exception: - continue - local_key = time.tzname[0] - while True: - for key in keyboard.poll(): - if key in ("q", "Q"): - keyboard.restore() - raise SystemExit(0) - if key == "up": - scroll -= 1 - elif key == "down": - scroll += 1 - elif key == "pgup": - scroll -= 8 - elif key == "pgdn": - scroll += 8 - elif key == "home": - scroll = 0 - elif key == "end": - scroll = 10 ** 6 # clamped to the end below - elif key in ("?", "h"): - pomo.hints = not pomo.hints - pomo.save() - elif key == "p": - pomo.toggle() - elif not pomo.enabled: - continue - elif key == " ": - pomo.pause() - elif key == "r": - pomo.restart() - elif key in ("s", "b", "e"): - # one action, three mnemonics: skip / break / end - pomo.advance() - elif key in ("0", "c"): - pomo.reset_count() - elif key in ("+", "="): - pomo.adjust(5) - elif key == "-": - pomo.adjust(-5) - pomo.roll_day() - if pomo.tick(): - over = pomo.overtime() - alert("%s %s" % (PHASE_LABEL[pomo.phase], - "finished" if over < 60 - else "running %dm over" % (over // 60)), - pomo.bell, pomo.notify, - "done" if over < 60 else "request") - if bool(_CFG["pomodoro_flash"]): - flash_at = time.time() - - w, h = size() - stamp = datetime.datetime.now(TZ) if TZ else datetime.datetime.now().astimezone() - - rows = [title("clocks", w)] - rows.append(DIM + " ── SERVER TIME ──") - for i, ln in enumerate(render_big(stamp.strftime("%H:%M:%S"), w - 2)): - rows.append(" " + (C1 if i < 3 else C2) + ln) - rows.append("") - rows.append(seg([(DIM, " "), (TXT, stamp.strftime("%Y-%m-%d %A").upper()), - (DIM, " " + offset_str(stamp))], w - 1)) - rows.append("") - rows.append(DIM + " ── COUNTDOWN ──") - if pomo.enabled: - over = pomo.overtime() - col = FOCUS if pomo.phase == "focus" else BREAK - if not pomo.running: - col = PAUSED - rows.append(seg([(col, " " + pad("Pomodoro · " + PHASE_LABEL[pomo.phase], - 23)), - (OVER if over else TXT, - ("+" + hms(over)) if over else hms(pomo.remaining())), - (PAUSED, " paused" if not pomo.running else ""), - (OVER if over else DIM, - " OVER" if over else ""), - (DIM, " %d done" % pomo.completed)], w - 1)) - n = max(4, w - 3) - if over: - # the bar rescales to duration+overtime, so the red share grows - # the longer the phase is ignored - total = pomo.duration() + over - base = max(1, int(round(n * pomo.duration() / total))) - rows.append(" " + col + "█" * base + OVER + "█" * (n - base)) - else: - done = 1.0 - (pomo.remaining() / pomo.duration() - if pomo.duration() else 0) - rows.append(" " + col + bar(done, n)) - for label, text, frac, col in countdowns(stamp): - rows.append(seg([(DIM, " " + pad(label, 21)), (TXT, text)], w - 1)) - rows.append(" " + col + bar(frac, max(4, w - 3))) - - rows.append("") - - # sort west -> east by current UTC offset - now_utc = datetime.datetime.now(datetime.timezone.utc) - entries = [] - for name, tz in zones: - entries.append((now_utc.astimezone(tz), name)) - entries.sort(key=lambda e: (e[0].utcoffset(), e[1])) - - # The clock, countdowns and footer stay pinned; only this list scrolls. - room = max(1, h - len(rows) - 1 - - len(pack_hints(hint_tokens(pomo), w - 2))) - scroll = max(0, min(scroll, max(0, len(entries) - room))) - window = entries[scroll:scroll + room] - more = len(entries) > room - rows.append(DIM + " ── WORLD CLOCK ──" + - (" %d-%d of %d ↑↓" % (scroll + 1, scroll + len(window), - len(entries)) if more else "")) - namew = max(9, min(15, w - 26)) - for dt, name in window: - if len(rows) >= h - 1: - break - col, glyph = phase(dt) - same_zone = dt.strftime("%Z") == stamp.strftime("%Z") - daydiff = (dt.date() - stamp.date()).days - tag = "" - if daydiff > 0: - tag = " +1d" - elif daydiff < 0: - tag = " -1d" - rows.append(seg([(col, " " + glyph + " "), - (HERE if same_zone else TXT, pad(name, namew)), - (col, dt.strftime(" %H:%M")), - (DIM, dt.strftime(" %a")), - (DIM, " " + pad(offset_str(dt), 8)), - (EVE, tag)], w - 1)) - footer = [" " + line for line in pack_hints(hint_tokens(pomo), w - 2)] - rows = rows[:h - len(footer)] - while len(rows) < h - len(footer): - rows.append("") - rows.extend(footer) - if flash_window(flash_at, int(_CFG["pomodoro_flash_count"]), - float(_CFG["pomodoro_flash_gap"])): - draw(flash_frame(rows, w, h), w, h) - else: - draw(rows, w, h) - time.sleep(0.15) - - -main() diff --git a/common.py b/common.py deleted file mode 100644 index 111a9c9..0000000 --- a/common.py +++ /dev/null @@ -1,583 +0,0 @@ -# terminal-toys - small dependency-free terminal widgets -# Copyright (C) 2026 William Li -# -# This program is free software: you can redistribute it and/or modify -# it under the terms of the GNU Affero General Public License as published -# by the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU Affero General Public License for more details. -# -# You should have received a copy of the GNU Affero General Public License -# along with this program. If not, see <https://www.gnu.org/licenses/>. -"""Shared drawing and input helpers for the terminal widgets.""" -import atexit -import base64 -import json -import math -import os -import re -import select -import shutil -import signal -import sys -import termios -import time -import tty - -HIDE = "\x1b[?25l" -SHOW = "\x1b[?25h" -HOME = "\x1b[H" -CLEAR = "\x1b[2J" -EL = "\x1b[K" -RST = "\x1b[0m" - - -CONFIG_NAME = "config.json" - - -def config_paths(): - """Where settings are looked for, in order of preference.""" - env = os.environ.get("TERMINAL_TOYS_CONFIG") - xdg = os.environ.get("XDG_CONFIG_HOME") or os.path.expanduser("~/.config") - here = os.path.dirname(os.path.abspath(__file__)) - return [p for p in (env, - os.path.join(xdg, "terminal-toys", CONFIG_NAME), - os.path.join(here, CONFIG_NAME)) if p] - - -def missing(*programs): - """Which of these required commands are not on PATH.""" - return [p for p in programs if not shutil.which(p)] - - -def cannot_start(name, needed, why, install=""): - """Draw a widget that cannot run, and wait, rather than exiting. - - A widget that exits on a missing dependency is a pane that vanishes the - moment you look at it, taking its explanation with it - and in a tiled - wall, or launched from the menu, there is nowhere for a line on stderr - to go. So it draws the reason at the size it was given and holds there, - answering q like everything else. Nothing is polled and nothing is - retried: the answer will not change while it sits there. - """ - BAD = rgb(255, 100, 110) - DIM = rgb(127, 147, 172) - TXT = rgb(225, 235, 245) - setup() - keyboard = Keyboard() - while True: - for key in keyboard.poll(): - if key in ("q", "Q"): - raise SystemExit(0) - w, h = size() - rows = [title(name, w, BAD), ""] - rows.append(seg([(BAD, " cannot start · "), - (TXT, "needs %s" % ", ".join(needed))], w - 1)) - rows.append("") - for line in why: - rows.append(seg([(DIM, " " + line)], w - 1)) - if install: - rows.append("") - rows.append(seg([(DIM, " try: "), (TXT, install)], w - 1)) - while len(rows) < h - 2: - rows.append("") - rows.append(" " + pack_hints([[(DIM, "[q]uit")]], w - 2)[0]) - draw(rows, w, h) - time.sleep(0.2) - - -def config_token_warning(): - """Warn when a config file holding a token is readable by others. - - Any widget that takes a token writes it into this file, so the check - belongs beside the loader rather than in whichever widget happened to - need it first. - """ - for path in config_paths(): - if not path or not os.path.exists(path): - continue - try: - mode = os.stat(path).st_mode & 0o077 - except OSError: - return None - return "config.json is readable by others; chmod 600 it" if mode else None - return None - - -def load_config(section, defaults): - """Settings for `section`, overlaid on `defaults`. - - Keeps personal data — hostnames, targets, city lists — out of the source - tree and therefore out of a public repository. The first readable file in - `config_paths()` wins; unknown keys are ignored, and a malformed file falls - back to the defaults rather than crashing a running panel. - """ - merged = dict(defaults) - for path in config_paths(): - try: - with open(path) as f: - data = json.load(f) - except (OSError, ValueError): - continue - chunk = data.get(section) - if isinstance(chunk, dict): - for key, value in chunk.items(): - if key in merged: - merged[key] = value - return merged - return merged - - -def maybe_help(doc): - """Print the tool's docstring and exit if -h/--help was passed.""" - if any(a in ("-h", "--help") for a in sys.argv[1:]): - print((doc or "").strip()) - raise SystemExit(0) - - -def size(): - try: - c = os.get_terminal_size() - return max(8, c.columns), max(4, c.lines) - except OSError: - return 80, 24 - - -def rgb(r, g, b): - return "\x1b[38;2;%d;%d;%dm" % (r, g, b) - - -def bg(r, g, b): - return "\x1b[48;2;%d;%d;%dm" % (r, g, b) - - -def out(s): - sys.stdout.write(s) - - -def flush(): - try: - sys.stdout.flush() - except BrokenPipeError: - raise SystemExit(0) - - -def _bye(*_a): - out(SHOW + RST + CLEAR + HOME) - flush() - raise SystemExit(0) - - -def setup(): - signal.signal(signal.SIGINT, _bye) - signal.signal(signal.SIGTERM, _bye) - out(HIDE + CLEAR + HOME) - flush() - - -def draw(rows, w, h): - """Paint `rows` (list of pre-colored strings) from the top-left.""" - buf = [HOME] - for i in range(h): - line = rows[i] if i < len(rows) else "" - buf.append(line + RST + EL) - if i != h - 1: - buf.append("\r\n") - out("".join(buf)) - flush() - - -def pad(s, n): - """Truncate/pad a *plain* (uncolored) string to n cells.""" - if len(s) > n: - return s[:n] - return s + " " * (n - len(s)) - - -def bar(frac, n, on="█", off="░"): - frac = 0.0 if frac < 0 else (1.0 if frac > 1 else frac) - k = int(round(frac * n)) - return on * k + off * (n - k) - - -def seg(parts, width): - """Join (color, text) segments, hard-clipped to `width` printable cells.""" - out = [] - n = 0 - for color, text in parts: - if n >= width: - break - room = width - n - if len(text) > room: - text = text[:room] - out.append(color + text) - n += len(text) - return "".join(out) - - -BIG_DIGITS = { - "0": ["███", "█ █", "█ █", "█ █", "███"], - "1": [" █", " █", " █", " █", " █"], - "2": ["███", " █", "███", "█ ", "███"], - "3": ["███", " █", "███", " █", "███"], - "4": ["█ █", "█ █", "███", " █", " █"], - "5": ["███", "█ ", "███", " █", "███"], - "6": ["███", "█ ", "███", "█ █", "███"], - "7": ["███", " █", " █", " █", " █"], - "8": ["███", "█ █", "███", "█ █", "███"], - "9": ["███", "█ █", "███", " █", "███"], - ":": [" ", " █ ", " ", " █ ", " "], - "%": ["█ █", " █", " █ ", "█ ", "█ █"], - ".": [" ", " ", " ", " ", " █ "], - " ": [" ", " ", " ", " ", " "], - "-": [" ", " ", "███", " ", " "], -} - - -def big(text, width=None): - """Render text as five rows of block digits.""" - rows = ["", "", "", "", ""] - for ch in text: - glyph = BIG_DIGITS.get(ch, BIG_DIGITS[" "]) - for i in range(5): - rows[i] += glyph[i] + " " - return [r[:width] if width else r for r in rows] - - -# Braille packs 2x4 sub-pixels into one cell, so a chart drawn with it has -# eight times the resolution of block characters. Dot bit per (column, row): -BRAILLE_DOTS = ((0x01, 0x02, 0x04, 0x40), (0x08, 0x10, 0x20, 0x80)) - - -def braille_plot(values, width, height, lo=None, hi=None): - """A continuous line chart in braille. - - Consecutive samples are joined rather than plotted as isolated dots - - without that the line reads as scattered specks wherever it moves quickly. - Returns `height` strings of `width` cells. - """ - if not values: - return [""] * height - lo = min(values) if lo is None else lo - hi = max(values) if hi is None else hi - span = (hi - lo) or 1.0 - px_w, px_h = width * 2, height * 4 - cells = [[0] * width for _ in range(height)] - - def row_of(v): - return max(0, min(px_h - 1, int(round((1 - (v - lo) / span) * (px_h - 1))))) - - prev = None - for px in range(px_w): - v = values[min(len(values) - 1, int(px * len(values) / float(px_w)))] - y = row_of(v) - span_y = (y, y) if prev is None else (min(prev, y), max(prev, y)) - for py in range(span_y[0], span_y[1] + 1): - cells[py // 4][px // 2] |= BRAILLE_DOTS[px % 2][py % 4] - prev = y - return ["".join(chr(0x2800 + c) for c in row) for row in cells] - - -def stacked_bar(parts, width): - """Proportions as one bar: [(fraction, colour), ...] -> coloured segments. - - A bar beats a pie in a character grid - no aliasing, and the eye compares - lengths far better than angles. - """ - out, used = [], 0 - for i, (frac, colour) in enumerate(parts): - n = width - used if i == len(parts) - 1 else int(round(frac * width)) - n = max(0, min(n, width - used)) - if n: - out.append((colour, "█" * n)) - used += n - return out - - -def meter(frac, n, on="█", off="░"): - """A gauge bar. Rectangular blocks, not parallelograms: ▰▱ are literally - tilted and read as slanted next to everything else on a character grid.""" - frac = 0.0 if frac < 0 else (1.0 if frac > 1 else frac) - k = int(round(frac * n)) - return on * k + off * (n - k) - - -def spread(count, room): - """Cell widths for `count` bars that fill `room` columns exactly. - - The remainder goes to the leftmost bars rather than being dropped on the - floor by integer division: stopping short of the right edge leaves no way - to tell a finished chart from a truncated one. Twenty-eight days across - fifty-nine columns is two cells each and three columns wasted, which - reads as a chart that gave up. - """ - if count <= 0: - return [] - if count >= room: - # One cell each and the caller decides what to drop: silently - # returning fewer widths than bars would lose data without saying so. - return [1] * count - slot, extra = divmod(room, count) - return [slot + (1 if i < extra else 0) for i in range(count)] - - -def vbars(columns, height, hi=None): - """Vertical bar chart. `columns` is [(value, colour), ...]. - - Each cell resolves an eighth of a row via the partial-block glyphs, so a - five-row chart has forty levels rather than five. Pass `hi` to fix the - full-scale value, so two charts can share a scale and stay comparable. - """ - steps = " ▁▂▃▄▅▆▇█" - hi = hi or max((v for v, _ in columns), default=0) or 1 - rows = [] - for r in range(height): - top = hi * (height - r) / float(height) - bottom = hi * (height - r - 1) / float(height) - line = [] - for value, colour in columns: - if value >= top: - ch = "█" - elif value <= bottom: - ch = " " - else: - ch = steps[max(1, int((value - bottom) / (top - bottom) * 8))] - line.append((colour, ch)) - rows.append(line) - return rows - - -def vbars_down(columns, height, hi=None): - """Bar chart hanging downward from a baseline above it. - - Paired with `vbars` and a shared `hi`, this makes a diverging chart: one - series growing up, another down, one column per day. - - The partial-block glyphs are all bottom-anchored, so a downward bar cannot - resolve an eighth of a cell the way `vbars` does - only `▀` exists as a - top-anchored partial. Half a cell is ample once peaks are scaled, and the - alternative (inverting foreground and background) needs the terminal's - background painted, which these widgets deliberately never do. - """ - hi = hi or max((v for v, _ in columns), default=0) or 1 - rows = [] - for r in range(height): - full = hi * (r + 1) / float(height) # value that fills this row - empty = hi * r / float(height) # value at which it starts - line = [] - for value, colour in columns: - if value >= full: - ch = "█" - elif value <= empty: - ch = " " - else: - ch = "▀" if (value - empty) / (full - empty) >= 0.5 else " " - line.append((colour, ch)) - rows.append(line) - return rows - - -def dance(width, tick, phase=0.0): - """Column heights in 0..1 bouncing like a level meter, for pending data. - - Two sine waves of different periods per column, so neighbours move - together enough to read as one instrument but never march in lockstep. - Deterministic in `tick`, so every frame is reproducible and no random - source is needed. - """ - out = [] - for i in range(width): - a = math.sin(tick * 0.55 + i * 0.85 + phase) - b = math.sin(tick * 0.31 + i * 0.41 + phase * 1.7) - out.append(min(1.0, max(0.08, 0.5 + 0.33 * a + 0.17 * b))) - return out - - -def mix(c1, c2, t): - """Blend two (r, g, b) tuples, for fading a placeholder into real data.""" - t = 0.0 if t < 0 else (1.0 if t > 1 else t) - return rgb(*[int(round(c1[i] + (c2[i] - c1[i]) * t)) for i in range(3)]) - - -def skeleton(width, tick, span=7): - """A placeholder bar with a highlight sweeping across it. - - For values that are being refetched: showing the previous number while a - new one is in flight states something false, and blanking the row makes - the layout jump. A shimmering grey bar says "pending" without either. - """ - period = width + span * 2 - centre = (tick % period) - span - out, last, run = [], None, [] - for i in range(width): - near = max(0.0, 1.0 - abs(i - centre) / float(span)) - level = int(58 + near * 118) - colour = rgb(level, level, level + 8) - if colour != last: - if run: - out.append((last, "".join(run))) - last, run = colour, [] - run.append("█") - if run: - out.append((last, "".join(run))) - return out - - -def pack_hints(hints, width, sep=" "): - """Lay key hints across as many lines as they need. - - Each hint is a list of (colour, text) segments and is kept whole: footers - are the one place a truncated line is actively harmful, since a hint cut to - "[±]25" teaches the wrong key. Returns the rendered rows, so a caller can - reserve exactly that many at the bottom. - """ - rows, parts, used = [], [], 0 - for hint in hints: - length = sum(len(text) for _, text in hint) - gap = len(sep) if parts else 0 - if parts and used + gap + length > width: - rows.append("".join(parts)) - parts, used, gap = [], 0, 0 - if gap: - parts.append(sep) - for color, text in hint: - parts.append(color + text) - used += gap + length - if parts: - rows.append("".join(parts)) - return rows or [""] - - -def heat(frac): - """Green -> amber -> red gradient.""" - frac = 0.0 if frac < 0 else (1.0 if frac > 1 else frac) - if frac < 0.5: - t = frac / 0.5 - return rgb(int(40 + 200 * t), 255, int(120 - 100 * t)) - t = (frac - 0.5) / 0.5 - return rgb(255, int(240 - 200 * t), int(20 + 10 * t)) - - -def title(text, w, color=None, accent="│"): - color = color or rgb(0, 255, 170) - t = " " + text.upper() + " " - left = "╺━" - fill = "━" * max(0, w - len(t) - len(left) - 1) - return color + left + RST + rgb(220, 255, 240) + t + RST + color + fill + "╸" + RST - - -def now(): - return time.strftime("%H:%M:%S") - - -KEY_SEQUENCES = { - "\x1b[A": "up", "\x1b[B": "down", "\x1b[C": "right", "\x1b[D": "left", - "\x1bOA": "up", "\x1bOB": "down", "\x1bOC": "right", "\x1bOD": "left", - "\x1b[5~": "pgup", "\x1b[6~": "pgdn", - "\x1b[H": "home", "\x1b[F": "end", "\x1b[1~": "home", "\x1b[4~": "end", - "\r": "enter", "\n": "enter", "\x7f": "backspace", "\t": "tab", -} -CSI_RE = re.compile(r"\x1b(\[[0-9;]*[A-Za-z~]|O[A-Za-z])") - - -class Keyboard(object): - """Non-blocking key input, decoding arrows and navigation sequences. - - Returns names ("up", "pgdn", "enter", "esc") for special keys and the bare - character otherwise. No-ops when stdin is not a tty, so piped and cron runs - are unaffected. Restores termios on exit. - """ - - def __init__(self): - self.fd = None - self.saved = None - self.buf = "" - self._lone_esc = False - if sys.stdin.isatty(): - try: - self.fd = sys.stdin.fileno() - self.saved = termios.tcgetattr(self.fd) - tty.setcbreak(self.fd) - atexit.register(self.restore) - except (termios.error, ValueError): - self.fd = None - - def restore(self): - if self.fd is not None and self.saved is not None: - try: - termios.tcsetattr(self.fd, termios.TCSADRAIN, self.saved) - except (termios.error, ValueError): - pass - - def poll(self): - keys = [] - if self.fd is None: - return keys - while select.select([self.fd], [], [], 0)[0]: - try: - chunk = os.read(self.fd, 64) - except OSError: - break - if not chunk: - break - self.buf += chunk.decode("utf-8", "replace") - - while self.buf: - if self.buf[0] == "\x1b": - match = None - for seq, name in KEY_SEQUENCES.items(): - if len(seq) > 1 and self.buf.startswith(seq): - if match is None or len(seq) > len(match[0]): - match = (seq, name) - if match: - self.buf = self.buf[len(match[0]):] - keys.append(match[1]) - continue - m = CSI_RE.match(self.buf) - if m: # a sequence we don't map; drop it - self.buf = self.buf[m.end():] - continue - if self.buf == "\x1b": - # bare ESC, or the start of a sequence still arriving. Only - # treat it as Escape once a second poll finds nothing more. - if self._lone_esc: - self.buf = "" - self._lone_esc = False - keys.append("esc") - else: - self._lone_esc = True - break - self.buf = self.buf[1:] # malformed; discard the ESC - continue - ch, self.buf = self.buf[0], self.buf[1:] - keys.append(KEY_SEQUENCES.get(ch, ch)) - if self.buf != "\x1b": - self._lone_esc = False - return keys - - -def cycle(seq, current): - try: - return seq[(seq.index(current) + 1) % len(seq)] - except ValueError: - return seq[0] - - -def clipboard(text): - """Ask the terminal to put `text` on the system clipboard, via OSC 52. - - The terminal emulator performs the copy, so this reaches the machine you - are sitting at even when the program runs on a remote host over SSH. - Multiplexers must be willing to forward it. Returns False when stdout is - not a terminal, so callers can fall back to showing the text instead. - """ - if not sys.stdout.isatty(): - return False - payload = base64.b64encode(text.encode("utf-8")).decode("ascii") - out("\x1b]52;c;%s\x07" % payload) - flush() - return True diff --git a/rust/core/Cargo.toml b/core/Cargo.toml similarity index 100% rename from rust/core/Cargo.toml rename to core/Cargo.toml diff --git a/rust/core/src/lib.rs b/core/src/lib.rs similarity index 100% rename from rust/core/src/lib.rs rename to core/src/lib.rs diff --git a/rust/core/tests/bounded.rs b/core/tests/bounded.rs similarity index 100% rename from rust/core/tests/bounded.rs rename to core/tests/bounded.rs diff --git a/deployments.py b/deployments.py deleted file mode 100755 index d737b15..0000000 --- a/deployments.py +++ /dev/null @@ -1,627 +0,0 @@ -#!/usr/bin/env python3 -# terminal-toys - small dependency-free terminal widgets -# Copyright (C) 2026 William Li -# -# This program is free software: you can redistribute it and/or modify -# it under the terms of the GNU Affero General Public License as published -# by the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU Affero General Public License for more details. -# -# You should have received a copy of the GNU Affero General Public License -# along with this program. If not, see <https://www.gnu.org/licenses/>. -"""Vercel deployments, live. - -Shows deployment activity over time, build-duration trend, and the most recent -deployments with their state, project, branch, commit and build time. - - python3 deployments.py [-n SECONDS] [-t TEAM_ID] [project ...] - -Polls every 15s by default (-n changes it, minimum 5s). One request per team -per poll, so the default is 4 polls/min — modest against the API's limits. - -Keys while running: up/down (also PgUp/PgDn, Home/End) move the selection, -Enter, i or c opens a full detail view for the selected deployment - state and -failure reason, timings, regions, commit, and everything worth copying on -number keys - r refreshes -now, f cycles the filter (all / failed / production), p cycles which project -is shown, q quits. - -Copying uses OSC 52, so the terminal you are sitting at performs it and the -text reaches your local clipboard even over SSH. If your terminal or -multiplexer blocks OSC 52, the sheet still shows each URL in full for mouse -selection. - -Credentials: `deployments.token` in config.json, or $VERCEL_TOKEN. Create one -at Account Settings -> Tokens. The Vercel CLI's own session is deliberately not -used - it expires within hours and only the CLI can refresh it, so anything -reading it goes dark overnight. The token is read locally and never printed. `vercel ls --all --format json` is an equivalent data source -but spawns a Node process per refresh, so this queries the REST API directly. -""" -import collections -import json -import os -import ssl -import sys -import threading -import time -import urllib.error -import urllib.request - -sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) -from common import (RST, Keyboard, bar, bg, clipboard, config_paths, - config_token_warning, cycle, draw, load_config, maybe_help, - pack_hints, pad, rgb, seg, setup, size, title) - -_CFG = load_config("deployments", { - "token": "", # a Vercel token; keep it in config.json, not here - "token_env": "VERCEL_TOKEN", - "refresh": 15, # seconds between API polls (-n) - "limit": 100, # deployments per request (API maximum) - "teams": [], # empty = discover every team you can see - "projects": [], # empty = all projects -}) - -REFRESH = float(_CFG["refresh"]) -LIMIT = int(_CFG["limit"]) -API = "https://api.vercel.com" - -FILTERS = ("all", "failed", "production") - -READY = rgb(80, 235, 150) -BUILD = rgb(255, 200, 90) -ERROR = rgb(255, 95, 105) -QUEUE = rgb(120, 160, 220) -CANCEL = rgb(140, 145, 160) -# Contrast is measured against both the terminal background and the selected -# row's tint, which is the harder case. Body text clears WCAG AA (4.5:1) on -# both; GRID is decorative gridline dots only and is never used for text. -DIM = rgb(127, 147, 172) # secondary text: ages, labels (6.7:1 / 4.5:1) -GRID = rgb(71, 91, 116) # chart gridlines only, never text (3.0:1) -MSG = rgb(158, 174, 196) # commit subjects (9.3:1 / 6.3:1) -URL = rgb(130, 200, 255) # links (11.7:1 / 7.9:1) -HINT = rgb(126, 148, 173) # key hints (6.7:1 / 4.5:1) -TXT = rgb(225, 235, 245) -LBL = rgb(130, 165, 200) -PROD = rgb(120, 180, 255) -SHA = rgb(190, 170, 255) -BRANCH = rgb(150, 210, 255) -SPARK = "▁▂▃▄▅▆▇█" -ACCENT = rgb(150, 210, 255) - -STATE_COLOR = {"READY": READY, "BUILDING": BUILD, "ERROR": ERROR, - "QUEUED": QUEUE, "INITIALIZING": QUEUE, "CANCELED": CANCEL} -SPINNER = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏" - - -def token(): - """A Vercel token, from config.json or the environment. - - Deliberately not the Vercel CLI's session: that expires within hours and - only the CLI can refresh it, so a panel reading it goes dark overnight. - Create one at Account Settings -> Tokens instead. Returns (token, source). - """ - if _CFG["token"]: - return _CFG["token"], "config" - tok = os.environ.get(_CFG["token_env"] or "VERCEL_TOKEN") - if tok: - return tok, "env" - return None, "missing" - - -def api(path, tok): - req = urllib.request.Request(API + path, - headers={"Authorization": "Bearer " + tok}) - ctx = ssl.create_default_context() - with urllib.request.urlopen(req, timeout=25, context=ctx) as r: - return json.load(r) - - -def discover_teams(tok): - """Every team the token can see, so deployments are not just personal. - - Returning [] on failure is deliberate - the personal scope still works - - but it also hid a caller passing token()'s whole tuple instead of its - first element, so the bare except now names what went wrong. - """ - try: - return [t["id"] for t in api("/v2/teams", tok).get("teams", [])] - except TypeError: - raise # a programming error, not a network one - except Exception: - return [] - - -def fetch_detail(dep, tok): - """Per-deployment detail: why it failed, timings, regions, aliases. - - The list endpoint carries none of this, so it is fetched on demand when the - info view opens rather than for 200 deployments nobody has asked about. - """ - q = "/v13/deployments/%s" % dep.get("uid") - if dep.get("_team"): - q += "?teamId=" + dep["_team"] - try: - return api(q, tok) - except Exception as e: - return {"_error": "%s: %s" % (type(e).__name__, e)} - - -class Store(object): - """Deployments fetched in the background, so the UI never blocks on HTTP.""" - - def __init__(self, teams, projects): - self.teams = teams - self.projects = projects - self.lock = threading.Lock() - self.deployments = [] - self.error = None - self.fetched_at = 0 - self.wake = threading.Event() - - def snapshot(self): - with self.lock: - return list(self.deployments), self.error, self.fetched_at - - def run(self): - try: - self.poll() - except Exception as e: # a daemon thread that dies - with self.lock: # silently looks like "no data" - self.error = "poller stopped: %s: %s" % (type(e).__name__, - str(e)[:60]) - - def poll(self): - while True: - tok, source = token() - if not tok: - with self.lock: - self.error = ("no token: set deployments.token in " - "config.json, or $%s" - % (_CFG["token_env"] or "VERCEL_TOKEN")) - else: - out, err = [], None - if source == "config": - err = config_token_warning() - scopes = self.teams or [None] - for team in scopes: - q = "/v6/deployments?limit=%d" % LIMIT - if team: - q += "&teamId=" + team - try: - got = api(q, tok).get("deployments", []) - for d in got: - d["_team"] = team # needed to fetch detail - out.extend(got) - except urllib.error.HTTPError as e: - err = "HTTP %s from Vercel%s" % ( - e.code, " (token expired? run `vercel login`)" - if e.code in (401, 403) else "") - except Exception as e: - err = "%s: %s" % (type(e).__name__, e) - if self.projects: - out = [d for d in out if d.get("name") in self.projects] - out.sort(key=lambda d: d.get("created", 0), reverse=True) - with self.lock: - if out or not err: - self.deployments = out - self.fetched_at = time.time() - self.error = err - self.wake.wait(REFRESH) - self.wake.clear() - - -def age(ms): - s = max(0, time.time() - ms / 1000.0) - if s < 90: - return "%ds" % s - if s < 5400: - return "%dm" % (s / 60) - if s < 172800: - return "%dh" % (s / 3600) - return "%dd" % (s / 86400) - - -def dur(seconds): - if seconds is None: - return " -- " - if seconds < 60: - return "%5.0fs" % seconds - return "%dm%02ds" % (seconds // 60, seconds % 60) - - -def build_seconds(d): - if d.get("ready") and d.get("buildingAt"): - return (d["ready"] - d["buildingAt"]) / 1000.0 - if d.get("state") in ("BUILDING", "QUEUED", "INITIALIZING") and d.get("buildingAt"): - return time.time() - d["buildingAt"] / 1000.0 - return None - - - -def wrap(text, width): - return [text[i:i + width] for i in range(0, len(text), width)] or [""] - - -def when(ms): - return time.strftime("%Y-%m-%d %H:%M", time.localtime(ms / 1000.0)) if ms else None - - -def copy_items(dep, detail): - """Everything worth copying out of a deployment.""" - meta = dep.get("meta") or {} - items = [] - if dep.get("inspectorUrl"): - items.append(("Deployment dashboard", dep["inspectorUrl"])) - if meta.get("branchAlias"): - items.append(("Branch preview", "https://" + meta["branchAlias"])) - if dep.get("url"): - items.append(("Commit preview", "https://" + dep["url"])) - if meta.get("githubPrId") and meta.get("githubOrg") and meta.get("githubRepo"): - items.append(("Pull request", "https://github.com/%s/%s/pull/%s" % ( - meta["githubOrg"], meta["githubRepo"], meta["githubPrId"]))) - if meta.get("githubCommitSha"): - items.append(("Commit SHA", meta["githubCommitSha"])) - if meta.get("githubCommitRef"): - items.append(("Branch name", meta["githubCommitRef"])) - err = (detail or {}).get("errorMessage") - if err: - items.append(("Error message", err)) - return items - - -def info_overlay(dep, detail, w, h, note): - """One deployment in full: state, timings, why it failed, and what to copy.""" - meta = dep.get("meta") or {} - d = detail or {} - rows = [title("deployment", w, PROD)] - - def field(label, value, color=TXT): - if value in (None, "", []): - return - rows.append(seg([(DIM, " %-11s" % label), (color, str(value))], w - 1)) - - state = dep.get("state", "?") - scol = STATE_COLOR.get(state, DIM) - field("project", dep.get("name"), ACCENT) - field("state", state.title() + (" (%s)" % d.get("errorStep") - if d.get("errorStep") else ""), scol) - field("target", "production" if dep.get("target") == "production" else "preview", - PROD if dep.get("target") == "production" else DIM) - field("created", when(dep.get("created") or dep.get("createdAt"))) - secs = build_seconds(dep) - if secs: - queued = ((dep.get("buildingAt", 0) - (dep.get("createdAt") or 0)) / 1000.0 - if dep.get("createdAt") and dep.get("buildingAt") else None) - field("build", dur(secs).strip() + (" queued %.0fs" % queued - if queued and queued > 0.5 else "")) - if d.get("regions"): - field("regions", ", ".join(d["regions"]) + - (" plan %s" % d["plan"] if d.get("plan") else "")) - aliases = d.get("alias") or [] - if aliases: - field("aliases", "%d assigned" % len(aliases), DIM) - - if d.get("errorMessage") or d.get("errorCode"): - rows.append("") - rows.append(LBL + " ── WHY IT FAILED ──") - if d.get("errorCode"): - rows.append(seg([(ERROR, " " + d["errorCode"])], w - 1)) - for line in wrap(d.get("errorMessage") or "", max(10, w - 4)): - rows.append(seg([(MSG, " " + line)], w - 1)) - if d.get("errorLink"): - rows.append(seg([(URL, " " + d["errorLink"])], w - 1)) - elif d.get("_error"): - rows.append("") - rows.append(seg([(ERROR, " detail unavailable: " + d["_error"])], w - 1)) - elif not d: - rows.append("") - rows.append(seg([(DIM, " loading detail…")], w - 1)) - - if meta.get("githubCommitSha"): - rows.append("") - rows.append(LBL + " ── COMMIT ──") - rows.append(seg([(SHA, " " + meta["githubCommitSha"][:7]), - (BRANCH, " " + (meta.get("githubCommitRef") or ""))], w - 1)) - for line in wrap((meta.get("githubCommitMessage") or "").split("\n")[0], - max(10, w - 4)): - rows.append(seg([(MSG, " " + line)], w - 1)) - who = meta.get("githubCommitAuthorName") or meta.get("githubCommitAuthorLogin") - if who: - rows.append(seg([(DIM, " by " + who)], w - 1)) - - pairs = copy_items(dep, detail) - if pairs: - rows.append("") - rows.append(LBL + " ── COPY ──") - for i, (label, value) in enumerate(pairs, 1): - short = value if len(value) <= w - 28 else value[:w - 31] + "…" - rows.append(seg([(READY, " [%d] " % i), (TXT, "%-21s " % label), - (URL, short)], w - 1)) - - while len(rows) < h - 2: - rows.append("") - rows.append(seg([(HINT, " press 1-%d to copy · esc or i to close" % len(pairs))], - w - 1)) - rows.append(seg([(READY, " " + note) if note else (DIM, "")], w - 1)) - return rows - - -def columns(w): - """Progressive disclosure: spend extra width on more content, not padding. - - Under 66 columns only the essentials fit. Above that the commit SHA and - branch appear. From 110 the metadata and commit subject share one line, so - twice as many deployments are visible in the same height. - """ - return { - "detail": w >= 66, - "single": w >= 110, - "project": 12 if w < 80 else (16 if w < 110 else 20), - "branch": max(12, min(34, w // 5)), - } - - -def activity(deps, w, hours=48): - """Deployments per time bucket, coloured by the worst outcome in it.""" - cols = max(10, w - 2) - now = time.time() * 1000 - span = hours * 3600000.0 - buckets = [[] for _ in range(cols)] - for d in deps: - off = now - d.get("created", now) - if 0 <= off < span: - buckets[cols - 1 - int(off / span * cols)].append(d) - peak = max((len(b) for b in buckets), default=0) - if not peak: - return [DIM + " no deployments in the last %dh" % hours], 0 - out, last = [" "], None - for b in buckets: - if not b: - if last != GRID: - out.append(GRID) - last = GRID - out.append("·") - continue - states = {x.get("state") for x in b} - col = (ERROR if "ERROR" in states else - BUILD if states & {"BUILDING", "QUEUED", "INITIALIZING"} else READY) - if col != last: - out.append(col) - last = col - out.append(SPARK[min(7, int((len(b) / float(peak)) * 7.99))]) - return ["".join(out)], peak - - -def main(): - maybe_help(__doc__) - global REFRESH - args = sys.argv[1:] - teams = list(_CFG["teams"]) - while args and args[0] in ("-n", "--refresh", "-t", "--team"): - if args[0] in ("-n", "--refresh"): - REFRESH = max(5.0, float(args[1])) - else: - teams.append(args[1]) - args = args[2:] - projects = set(args) or set(_CFG["projects"]) - - setup() - keyboard = Keyboard() - tok, _source = token() # token() returns (value, where it came from) - if tok and not teams: - teams = discover_teams(tok) - store = Store(teams, projects) - th = threading.Thread(target=store.run) - th.daemon = True - th.start() - - flt = "all" - details = {} # uid -> detail dict, fetched on demand - fetching = set() - only = None # project cycled with `p` - tick = 0 - selected = 0 # index into the filtered list - scroll = 0 # first visible row - overlay = False # copy sheet open - note = "" # transient confirmation - note_until = 0 - visible = 1 - shown = [] - while True: - tick += 1 - for key in keyboard.poll(): - if overlay: - if key in ("esc", "c", "i", "q", "Q", "enter"): - overlay = False - elif key.isdigit() and shown: - chosen = shown[min(selected, len(shown) - 1)] - pairs = copy_items(chosen, details.get(chosen.get("uid"))) - idx = int(key) - 1 - if 0 <= idx < len(pairs): - label, url = pairs[idx] - note = ("✓ copied %s" % label.lower()) if clipboard(url) \ - else "! no clipboard; select the text with the mouse" - note_until = time.time() + 3 - continue - if key in ("q", "Q"): - keyboard.restore() - raise SystemExit(0) - if key == "r": - store.wake.set() - elif key == "f": - flt = cycle(FILTERS, flt) - selected = 0 - elif key == "up": - selected = max(0, selected - 1) - elif key == "down": - selected += 1 - elif key == "pgup": - selected = max(0, selected - visible) - elif key == "pgdn": - selected += visible - elif key == "home": - selected = 0 - elif key == "end": - selected = max(0, len(shown) - 1) - elif key in ("c", "i", "enter"): - if shown: - overlay = True - note = "" - elif key == "p": - deps, _, _ = store.snapshot() - names = sorted({d.get("name") for d in deps if d.get("name")}) - options = [None] + names - only = options[(options.index(only) + 1) % len(options)] \ - if only in options else (names[0] if names else None) - selected = 0 - - w, h = size() - deps, err, fetched = store.snapshot() - if note and time.time() > note_until: - note = "" - shown = deps - if only: - shown = [d for d in shown if d.get("name") == only] - if flt == "failed": - shown = [d for d in shown if d.get("state") in ("ERROR", "CANCELED")] - elif flt == "production": - shown = [d for d in shown if d.get("target") == "production"] - - selected = max(0, min(selected, len(shown) - 1)) if shown else 0 - if overlay and shown: - chosen = shown[selected] - uid = chosen.get("uid") - if uid and uid not in details and uid not in fetching: - fetching.add(uid) - - def grab(dep=chosen, key=uid): - tok, _ = token() - details[key] = fetch_detail(dep, tok) if tok else {} - fetching.discard(key) - - t = threading.Thread(target=grab) - t.daemon = True - t.start() - draw(info_overlay(chosen, details.get(uid), w, h, note), w, h) - time.sleep(0.1) - continue - - states = collections.Counter(d.get("state") for d in deps) - projects_seen = len({d.get("name") for d in deps}) - rows = [title("vercel deployments", w, PROD)] - - live = sum(states[s] for s in ("BUILDING", "QUEUED", "INITIALIZING")) - head = [(DIM, " %d deploys" % len(deps)), - (DIM, " · %d proj" % projects_seen), - (READY, " %d ready" % states.get("READY", 0))] - if states.get("ERROR"): - head.append((ERROR, " %d error" % states["ERROR"])) - if live: - head.append((BUILD, " %s %d building" % (SPINNER[tick % len(SPINNER)], live))) - head.append((DIM, " %s ago" % (age(fetched * 1000) if fetched else "--"))) - rows.append(seg(head, w - 1)) - if err: - rows.append(seg([(ERROR, " ! " + err)], w - 1)) - filt_bits = [] - if flt != "all": - filt_bits.append(flt) - if only: - filt_bits.append(only) - if filt_bits: - rows.append(seg([(BUILD, " filter: " + " + ".join(filt_bits))], w - 1)) - rows.append("") - - # --- deployments over time --- - rows.append(LBL + " ── ACTIVITY ── " + DIM + "deploys/hour, last 48h") - act, peak = activity(deps, w) - rows.extend(act) - if peak: - rows.append(seg([(DIM, " 48h ago"), - (DIM, " " * max(1, w - 22)), - (DIM, "peak %d/h" % peak)], w - 1)) - - durs = sorted(x for x in (build_seconds(d) for d in deps) if x) - if durs: - med = durs[len(durs) // 2] - p95 = durs[min(len(durs) - 1, int(len(durs) * 0.95))] - rows.append("") - rows.append(seg([(LBL, " ── BUILD TIME ── "), - (DIM, "median "), (TXT, dur(med)), - (DIM, " p95 "), (TXT, dur(p95)), - (DIM, " max "), (TXT, dur(durs[-1]))], w - 1)) - recent = [build_seconds(d) for d in deps[:max(10, w - 2)]][::-1] - recent = [x for x in recent if x] - if recent: - hi = max(recent) - spark = "".join(SPARK[min(7, int(x / hi * 7.99))] for x in recent) - rows.append(" " + READY + spark) - rows.append("") - - # --- recent deployments --- - rows.append(seg([(LBL, " ── RECENT ── "), - (DIM, "%d of %d" % (selected + 1, len(shown)) if shown else "")], - w - 1)) - cols = columns(w) - wide, single = cols["detail"], cols["single"] - per_item = 1 if single else 2 - visible = max(1, (h - len(rows) - 1) // per_item) - scroll = min(scroll, max(0, len(shown) - visible)) - if selected < scroll: - scroll = selected - elif selected >= scroll + visible: - scroll = selected - visible + 1 - for i in range(scroll, min(len(shown), scroll + visible)): - d = shown[i] - if len(rows) >= h - 1: - break - here = (i == selected) - tint = bg(28, 44, 62) if here else "" - meta = d.get("meta") or {} - state = d.get("state", "?") - col = STATE_COLOR.get(state, DIM) - mark = SPINNER[tick % len(SPINNER)] if state in ( - "BUILDING", "QUEUED", "INITIALIZING") else ( - "●" if state == "READY" else "✖" if state == "ERROR" else "○") - msg = (meta.get("githubCommitMessage") or "").split("\n")[0] - line = [(tint + col, ("▸" if here else " ") + "%s %-9s" % (mark, state.title())), - (tint + TXT, pad(d.get("name", "?"), cols["project"])), - (tint + DIM, dur(build_seconds(d))), - (tint + DIM, " %4s" % age(d.get("created", 0)))] - if d.get("target") == "production": - line.append((tint + PROD, " PROD")) - elif wide: - line.append((tint + DIM, " prev")) - if wide: - line.append((tint + SHA, " " + (meta.get("githubCommitSha") or "")[:7])) - line.append((tint + BRANCH, " " + pad((meta.get("githubCommitRef") or ""), - cols["branch"]))) - if single: - line.append((tint + (TXT if here else MSG), " " + msg)) - if here: - line.append((tint, " " * w)) - rows.append(seg(line, w - 1)) - if not single and len(rows) < h - 1: - rows.append(seg([(tint + (TXT if here else MSG), " " + msg), - (tint, " " * w if here else "")], w - 1)) - if not shown: - rows.append(DIM + " (nothing matches the current filter)") - - hints = [[(ACCENT, "↑↓"), (DIM, " select")], - [(ACCENT, "↵/[i]"), (DIM, " details")], - [(DIM, "[f]ilter")], [(DIM, "[p]roject")], - [(DIM, "[r]efresh")], [(DIM, "[q]uit")]] - footer = [" " + line for line in pack_hints(hints, w - 2)] - rows = rows[:h - len(footer)] - while len(rows) < h - len(footer): - rows.append("") - rows.extend(footer) - draw(rows, w, h) - time.sleep(0.25) - - -main() diff --git a/github.py b/github.py deleted file mode 100755 index 44a0167..0000000 --- a/github.py +++ /dev/null @@ -1,811 +0,0 @@ -#!/usr/bin/env python3 -# terminal-toys - small dependency-free terminal widgets -# Copyright (C) 2026 William Li -# -# This program is free software: you can redistribute it and/or modify -# it under the terms of the GNU Affero General Public License as published -# by the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU Affero General Public License for more details. -# -# You should have received a copy of the GNU Affero General Public License -# along with this program. If not, see <https://www.gnu.org/licenses/>. -"""GitHub delivery metrics across every org and account you can see. - -Open pull requests, how many are actually merging, review backlog and issue -counts - for one org, several, or your personal account alongside them. - - python3 github.py [-n SECONDS] [account ...] - -Accounts are org logins, or @me for your own. With none given it uses -`github.accounts` from config, and failing that every org you belong to plus -your personal account. - -Open counts - PRs, issues, drafts, review backlog - are point-in-time totals of -whatever is open right now, at any age. Everything else - the merge rate, the -per-day charts and the per-account merged/rate columns - covers the merge -window, which is the N days ending today. - -Credentials: `github.token` in config.json, or $GITHUB_TOKEN. It must be a -*classic* token: a fine-grained one is limited to a single resource owner, so -it cannot span the orgs this board exists to compare. Two scopes - `repo` so search sees private -repositories, and `read:org` to enumerate your orgs. Missing either one does -not fail, it silently undercounts, so the granted scopes are checked and named. -The API is called directly, so the `gh` CLI is not required. - -Keys: up/down select an account, r refreshes now, w cycles the window -(7/14/30/60/90 days), q quits. -""" -import collections -import datetime -import math -import json -import os -import sys -import threading -import time -import urllib.error -import urllib.request - -sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) -from common import (RST, Keyboard, bar, bg, big, braille_plot, - config_token_warning, cycle, dance, draw, mix, - heat, load_config, maybe_help, meter, pack_hints, pad, rgb, - seg, setup, size, skeleton, stacked_bar, title, vbars, - vbars_down) - -_CFG = load_config("github", { - "token": "", - "token_env": "GITHUB_TOKEN", - "accounts": [], # org logins and/or "@me"; empty = discover - "window_days": 7, # window the board opens on - "refresh": 120, # seconds between polls; GraphQL is 5000 points/hour -}) - -REFRESH = float(_CFG["refresh"]) -WINDOWS = (7, 14, 30, 60, 90) -CONTRIB_WEEKS = 52 # a full year, like the calendar on github.com -API = "https://api.github.com/graphql" - -OK = rgb(90, 240, 160) -WARN = rgb(255, 200, 90) -BAD = rgb(255, 100, 110) -DIM = rgb(127, 147, 172) -GRID = rgb(60, 78, 98) -TXT = rgb(225, 235, 245) -LBL = rgb(130, 165, 200) -ACCENT = rgb(150, 210, 255) -PR = rgb(180, 160, 255) -# the chart fades from these into the real colours as figures land: pale -# enough to read as "not yet", tinted enough to still say which half is which -PR_RGB, OK_RGB = (180, 160, 255), (90, 240, 160) -GHOST = (96, 106, 124) -LOAD_PR, LOAD_OK = mix(GHOST, PR_RGB, 0.45), mix(GHOST, OK_RGB, 0.45) -SETTLE_FRAMES = 8 -SPARK = "▁▂▃▄▅▆▇█" - - -def token(): - """A GitHub token from config.json or the environment. - - Deliberately not shelled out to the `gh` CLI: this widget talks to the API - directly and should not require another program to be installed, logged in - and current just to read a number. - """ - if _CFG["token"]: - return _CFG["token"], "config" - tok = os.environ.get(_CFG["token_env"] or "GITHUB_TOKEN") - if tok: - return tok, "env" - return None, "missing" - - -_SCOPES = {"seen": False, "have": set()} - - -def graphql(query, tok): - body = json.dumps({"query": query}).encode() - req = urllib.request.Request(API, data=body, headers={ - "Authorization": "Bearer " + tok, - "Content-Type": "application/json", - "User-Agent": "terminal-toys", - }) - with urllib.request.urlopen(req, timeout=30) as r: - granted = r.headers.get("X-OAuth-Scopes") - if granted is not None: # absent on fine-grained tokens - _SCOPES["seen"] = True - _SCOPES["have"] = set(x.strip() for x in granted.split(",") if x.strip()) - return json.load(r) - - -def scope_warning(): - """Flag a token that will undercount rather than fail. - - A classic token without `repo` still searches happily - it just returns - public results only, so every figure on the board comes back smaller with - nothing to say it did. Without `read:org` the account list comes back - short the same way. Both are worse than an error, so name them. - """ - if not _SCOPES["seen"]: - return None - missing = [x for x in ("repo", "read:org") if x not in _SCOPES["have"]] - if not missing: - return None - why = ("private repos are not counted" if "repo" in missing - else "orgs cannot be discovered") - return "token lacks %s - %s" % (" and ".join(missing), why) - - -def discover_accounts(tok): - """Every org you belong to, plus your own account.""" - q = "{ viewer { login organizations(first:20) { nodes { login } } } }" - try: - d = graphql(q, tok)["data"]["viewer"] - except Exception: - return [] - return [o["login"] for o in d["organizations"]["nodes"]] + ["@me"] - - -def scope(acc, viewer): - """The search qualifier that limits results to a single account.""" - return ("user:%s" % viewer) if acc == "@me" else ("org:%s" % acc) - - -DAY_CHUNK = 20 # 2 searches a day; the alias ceiling sits between 60 and 90 -FRESH_DAYS = 2 # trailing days to always refetch: today is still running, - # and the search index lags a little behind a merge - - -def build_day_query(q, dates): - """Exact per-day PR counts for one account. - - The charts used to read PR nodes and bucket their timestamps, but a search - connection returns at most 100 nodes per page, so a busy fortnight lost - everything past the hundredth record - and the merged series sorted by - update time, so those hundred were not even the hundred most recently - merged. A count per day is exact at any volume, and aliased searches cost - one rate-limit point per request however many are packed into it. - """ - parts = ["{"] - for n, day in enumerate(dates): - parts.append( - '\n m%(n)d: search(query:"%(q)s is:pr is:merged merged:%(d)s",' - ' type:ISSUE) { issueCount }' - '\n c%(n)d: search(query:"%(q)s is:pr created:%(d)s",' - ' type:ISSUE) { issueCount }' % {"n": n, "q": q, "d": day}) - parts.append("\n}") - return "".join(parts) - - -def build_query(accounts, days, viewer): - """Metrics for a batch of accounts in one request. - - Seven aliased searches per account keeps each request within GitHub's - complexity limit - asking for seven accounts at once returned HTTP 502 - - while still being far fewer round trips than one query per metric. - """ - # N days *ending today*, so this spans exactly the dates the per-day - # charts plot - `days` rather than `days - 1` would cover one day more - # and quietly disagree with the chart drawn directly beneath it. - since = (datetime.date.today() - - datetime.timedelta(days=days - 1)).isoformat() - parts = ["{"] - for i, acc in enumerate(accounts): - q = scope(acc, viewer) - parts.append(''' - o%(i)d_open: search(query:"%(q)s is:pr is:open", type:ISSUE) { issueCount } - o%(i)d_draft: search(query:"%(q)s is:pr is:open draft:true", type:ISSUE) { issueCount } - o%(i)d_review: search(query:"%(q)s is:pr is:open review:required", type:ISSUE) { issueCount } - o%(i)d_merged: search(query:"%(q)s is:pr is:merged merged:>=%(s)s", type:ISSUE) { issueCount } - o%(i)d_dropped: search(query:"%(q)s is:pr is:unmerged is:closed closed:>=%(s)s", type:ISSUE) { issueCount } - o%(i)d_issues: search(query:"%(q)s is:issue is:open", type:ISSUE) { issueCount }''' - % {"i": i, "q": q, "s": since}) - parts.append("\n rateLimit { remaining limit }\n}") - return "".join(parts) - - -class Store(object): - def __init__(self, accounts, days): - self.lock = threading.Lock() - self.accounts = accounts - self.days = days - self.stats = [] - self.day_cache = {} # account -> {date: (merged, opened)} - self.bust_days = False # set by [r]: drop the day cache and refetch - self.calendar = None - self.rate = None - self.error = None - self.fetched = 0 - self.wake = threading.Event() - - def snapshot(self): - with self.lock: - return (list(self.stats), self.rate, self.error, self.fetched, - self.calendar) - - def run(self): - # A daemon thread that raises just stops, and a dead poller looks - # exactly like a source with no data - which is how deployments.py - # showed "0 deploys" for a day after an import went missing. - try: - self.poll() - except Exception as e: - with self.lock: - self.error = "poller stopped: %s: %s" % (type(e).__name__, - str(e)[:70]) - - def poll(self): - viewer = None - while True: - tok, source = token() - if not tok: - with self.lock: - self.error = ("no token: set github.token in config.json " - "or $%s (needs repo + read:org)" - % (_CFG["token_env"] or "GITHUB_TOKEN")) - self.wake.wait(REFRESH) - self.wake.clear() - continue - try: - if viewer is None: - viewer = graphql("{ viewer { login } }", - tok)["data"]["viewer"]["login"] - if not self.accounts: - self.accounts = discover_accounts(tok) or ["@me"] - try: - cal = graphql(contribution_query(CONTRIB_WEEKS), tok)["data"]["viewer"] - with self.lock: - self.calendar = cal["contributionsCollection"]["contributionCalendar"] - except Exception: - pass - with self.lock: - days_now, bust = self.days, self.bust_days - self.bust_days = False - # Start the pass from what is already on screen, keyed by - # account, so rows are replaced in place as each lands - # instead of the table emptying and refilling every pass. - by_acc = dict((x["key"], x) for x in self.stats) - today = datetime.date.today() - dates = [(today - datetime.timedelta(days=k)).isoformat() - for k in range(days_now - 1, -1, -1)] - keep_from = (today - datetime.timedelta( - days=max(WINDOWS) - 1)).isoformat() - failed, rate = [], None - - def publish(): - with self.lock: - self.stats = [by_acc[a] for a in self.accounts - if a in by_acc] - self.rate = rate - self.fetched = time.time() - - # Aggregates first, for every account, before any per-day work. - # One request each, so the headline is live in seconds; the day - # charts below can cost fifty requests on a cold 90d window and - # would otherwise hold the whole board grey for minutes. - for acc in self.accounts: - try: - data = graphql(build_query([acc], days_now, viewer), tok) - if data.get("errors"): - raise ValueError(data["errors"][0].get("message", "")[:50]) - except Exception as e: - failed.append("%s (%s)" % (acc, type(e).__name__)) - continue - d = data["data"] - rate = d.get("rateLimit") or rate - i = 0 - g = lambda k: (d.get("o%d_%s" % (i, k)) or {}).get("issueCount", 0) - merged, dropped = g("merged"), g("dropped") - prev = by_acc.get(acc) or {} - by_acc[acc] = { - "key": acc, - "window": days_now, # which window these figures cover - "account": viewer if acc == "@me" else acc, - "is_me": acc == "@me", - "open": g("open"), "draft": g("draft"), - "review": g("review"), "issues": g("issues"), - "merged": merged, "dropped": dropped, - "rate": (100.0 * merged / (merged + dropped) - if merged + dropped else None), - # carried over until this account's day counts land, and - # tagged with the window they actually cover so a - # half-updated board cannot sum two windows together - "hist": prev.get("hist") or collections.Counter(), - "opened_hist": prev.get("opened_hist") or collections.Counter(), - "hist_window": prev.get("hist_window"), - } - publish() - - # Then the per-day counts. A past day cannot change - a PR - # merged on the 3rd stays merged on the 3rd - so only days never - # seen before, plus the trailing few (still running, and the - # search index lags), cost a request. Widening the window - # therefore buys only the days it adds; narrowing is free. - for acc in self.accounts: - if acc not in by_acc: - continue - cache = self.day_cache.setdefault(acc, {}) - if bust: - cache.clear() - want = [x for x in dates - if x not in cache or x in dates[-FRESH_DAYS:]] - for c in range(0, len(want), DAY_CHUNK): - chunk = want[c:c + DAY_CHUNK] - try: - dd = graphql(build_day_query(scope(acc, viewer), - chunk), tok)["data"] - except Exception: - continue - for n, day in enumerate(chunk): - cache[day] = ((dd.get("m%d" % n) or {}).get("issueCount", 0), - (dd.get("c%d" % n) or {}).get("issueCount", 0)) - for old_day in [x for x in cache if x < keep_from]: - del cache[old_day] # older than any window - if not all(x in cache for x in dates): - continue # a chunk failed; leave it - by_acc[acc]["hist"] = collections.Counter( - dict((x, cache[x][0]) for x in dates)) - by_acc[acc]["opened_hist"] = collections.Counter( - dict((x, cache[x][1]) for x in dates)) - by_acc[acc]["hist_window"] = days_now - publish() - with self.lock: - # with nothing else to report, surface a token sitting in a - # file other users on the box can read - self.error = (("could not read: " + ", ".join(failed)) - if failed else - (scope_warning() or - (config_token_warning() - if source == "config" else None))) - except urllib.error.HTTPError as e: - with self.lock: - self.error = "HTTP %s from GitHub%s" % ( - e.code, " (token lacks scope?)" if e.code == 403 else "") - except Exception as e: - with self.lock: - self.error = "%s: %s" % (type(e).__name__, str(e)[:60]) - self.wake.wait(REFRESH) - self.wake.clear() - - -def contribution_query(weeks): - """GitHub's own contribution calendar - the green squares. - - contributionsCollection is per-viewer rather than per-org, so this is your - activity across everything, which is what the calendar means on github.com. - """ - since = (datetime.datetime.now(datetime.timezone.utc) - - datetime.timedelta(weeks=weeks)).strftime("%Y-%m-%dT%H:%M:%SZ") - return """{ viewer { contributionsCollection(from:"%s") { - contributionCalendar { totalContributions - weeks { contributionDays { date contributionCount weekday } } } } } }""" % since - - -WEEKDAYS = ("Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat") - - -def calendar_stats(weeks_data): - """Streaks and totals behind the contribution calendar. - - A streak is consecutive days carrying at least one contribution, counted - the way github.com does it: a day that has scored nothing *so far* does - not break the current streak, because it is not over yet. - """ - days = sorted((d["date"], d["contributionCount"], d.get("weekday", 0)) - for wk in weeks_data for d in wk["contributionDays"]) - if not days: - return None - today = datetime.date.today().isoformat() - - longest = run = 0 - for _d, count, _wd in days: - run = run + 1 if count else 0 - longest = max(longest, run) - - done = [x for x in days if x[0] <= today] - if done and not done[-1][1]: - done = done[:-1] # today is still in progress - current = 0 - for _d, count, _wd in reversed(done): - if not count: - break - current += 1 - - per_weekday = collections.Counter() - for _d, count, wd in days: - per_weekday[wd] += count - top_wd = per_weekday.most_common(1)[0][0] if per_weekday else 0 - return { - "today": dict((d, c) for d, c, _ in days).get(today, 0), - "current": current, - "longest": longest, - "active": sum(1 for _d, c, _wd in days if c), - "span": len(days), - "busiest": max(days, key=lambda x: x[1]), - "weekday": (WEEKDAYS[top_wd], per_weekday[top_wd]), - } - - -def heatmap(weeks_data, w): - """The calendar as seven rows of one cell per week.""" - levels = " ░▒▓█" - counts = [d["contributionCount"] for wk in weeks_data - for d in wk["contributionDays"]] - peak = max(counts) if counts else 0 - cols = max(4, min(len(weeks_data), w - 8)) - weeks_data = weeks_data[-cols:] - grid = [[" "] * len(weeks_data) for _ in range(7)] - for x, wk in enumerate(weeks_data): - for d in wk["contributionDays"]: - n = d["contributionCount"] - lvl = 0 if not n else min(4, 1 + int(n / (peak or 1) * 3.99)) - grid[d["weekday"]][x] = levels[lvl] - return grid, peak, sum(counts) - - -def ago(t): - if not t: - return "--" - s = time.time() - t - return "%ds" % s if s < 90 else ("%dm" % (s / 60) if s < 5400 else "%dh" % (s / 3600)) - - -def main(): - maybe_help(__doc__) - global REFRESH - args = sys.argv[1:] - while args and args[0] in ("-n", "--refresh"): - REFRESH = max(30.0, float(args[1])) - args = args[2:] - accounts = args or list(_CFG["accounts"]) - days = int(_CFG["window_days"]) - - setup() - keyboard = Keyboard() - store = Store(accounts, days) - th = threading.Thread(target=store.run) - th.daemon = True - th.start() - - selected = 0 - tick = 0 - settle_t, settle_from = 0, None - while True: - tick += 1 - for key in keyboard.poll(): - if key in ("q", "Q"): - keyboard.restore() - raise SystemExit(0) - if key == "r": - with store.lock: # manual refresh re-reads even past days - store.bust_days = True - store.wake.set() - elif key == "w": - with store.lock: - store.days = cycle(WINDOWS, store.days) - store.wake.set() - elif key == "up": - selected = max(0, selected - 1) - elif key == "down": - selected += 1 - - w, h = size() - stats, rate, err, fetched, calendar = store.snapshot() - # Busiest first: open PRs decide it, and merged-in-window breaks ties - # so an idle backlog ranks below an account of the same size that is - # actually moving. Name last, to keep the order steady frame to frame. - stats.sort(key=lambda x: (-x["open"], -x["merged"], x["account"].lower())) - # Windowed figures are stale until every account has reported for the - # window now selected; rows carry the window they were fetched for. - # The charts are tracked apart from the headline because their data - # costs far more requests and so lands well after it. - stale = not stats or any(x.get("window") != store.days for x in stats) - chart_stale = not stats or any(x.get("hist_window") != store.days - for x in stats) - selected = max(0, min(selected, len(stats) - 1)) if stats else 0 - - rows = [title("github ops", w, PR)] - head = [(DIM, " %d account%s" % (len(stats), "" if len(stats) == 1 else "s")), - (DIM, " updated %s ago" % ago(fetched))] - if rate: - left = rate.get("remaining", 0) - head.append((OK if left > 1000 else WARN, " %d/%d api" % (left, rate.get("limit", 0)))) - rows.append(seg(head, w - 1)) - if err: - rows.append(seg([(BAD, " ! " + err)], w - 1)) - if not stats: - rows.append(seg([(DIM, " collecting…")], w - 1)) - draw(rows, w, h) - time.sleep(0.4) - continue - - # totals across every account - tot = {k: sum(s[k] for s in stats) - for k in ("open", "draft", "review", "issues", "merged", "dropped")} - rate_pct = (100.0 * tot["merged"] / (tot["merged"] + tot["dropped"]) - if tot["merged"] + tot["dropped"] else None) - # What is outstanding right now leads the board: it is the question - # asked most often, and it is the only section that is not windowed. - if tot["open"]: - ready = max(0, tot["open"] - tot["draft"] - tot["review"]) - legend = [x for x in (("awaiting review", tot["review"], WARN), - ("ready to merge", ready, OK), - ("draft", tot["draft"], DIM)) if x[1]] - rows.append(seg([(LBL, " ── OPEN PR STATE ── "), - (PR, "%d" % tot["open"]), (DIM, " PRs · "), - (WARN, "%d" % tot["issues"]), - (DIM, " issues open (any age)")], w - 1)) - parts = [(n / float(tot["open"]), c) for _, n, c in legend] - rows.append(seg([(RST, " ")] + stacked_bar(parts, max(10, w - 3)), - w - 1)) - key = [(RST, " ")] - for label, count, colour in legend: - key += [(colour, "▇ "), (TXT, label), - (DIM, " %d (%.0f%%) " % (count, 100.0 * count / tot["open"]))] - rows.append(seg(key, w - 1)) - - rows.append("") - pct_txt = ("%.0f%%" % rate_pct) if rate_pct is not None else "--" - rcol = heat((rate_pct or 0) / 100.0) if rate_pct is not None else DIM - rows.append(seg([(LBL, " ── MERGE RATE ── "), - (DIM, "last %d days" % store.days)], w - 1)) - bar_w = max(10, w - 34) - if stale: - rows.append(seg([(DIM, " %-5s" % "···")] + skeleton(bar_w, tick) + - [(DIM, " loading %dd…" % store.days)], w - 1)) - else: - rows.append(seg([(rcol, " %-5s" % pct_txt), - (rcol, meter((rate_pct or 0) / 100.0, bar_w)), - (OK, " %d merged" % tot["merged"]), - (DIM, " / "), (BAD, "%d dropped" % tot["dropped"])], - w - 1)) - merged_all, opened_all = collections.Counter(), collections.Counter() - for st in stats: - if st.get("hist_window") != store.days: - continue # covers a different window; adding it lies - merged_all.update(st["hist"]) - opened_all.update(st.get("opened_hist") or {}) - hist_days = store.days - today = datetime.date.today() - - days = [(today - datetime.timedelta(days=n)).isoformat() - for n in range(hist_days - 1, -1, -1)] - - # The chart always fills the pane. Where there is room to spare a day - # takes several columns (with a gap between bars once they are wide - # enough to need one); where there is not, the oldest days are cropped - # rather than the whole chart being squeezed into a corner. - avail = max(10, w - 3) - if len(days) > avail: - days = days[-avail:] - slot = max(1, avail // len(days)) - gap = 1 if slot >= 3 else 0 - barw = slot - gap - - def spread(per_day): - """One value per day, widened to the bar it will be drawn as. - - Everything the chart draws goes through this, the loading - animation included, so the placeholder has exactly the bars the - real chart will have - same count, same width, same gaps. - """ - cols = [] - for n, v in enumerate(per_day): - cols.extend([v] * barw) - if gap and n < len(per_day) - 1: - cols.extend([0] * gap) - return cols - - # One chart, two directions: PRs opened grow up, PRs merged grow down - # from a shared baseline. Read together they answer whether the queue - # is filling faster than it drains - which two separate charts made - # you compare by eye across a heading. - opened_day = [opened_all.get(d, 0) for d in days] - merged_day = [merged_all.get(d, 0) for d in days] - up, down = spread(opened_day), spread(merged_day) - chart_cols = len(up) - # One scale both ways, or the comparison lies. - span_hi = max(up + down) or 1 - # A narrow pane cannot draw 90 columns, so the chart shows the most - # recent days that fit and says so - the totals are of what is drawn, - # not of the window, and would otherwise contradict the merge rate. - span = ("%dd of %dd" % (len(days), hist_days) - if len(days) < hist_days else "%dd" % len(days)) - rows.append("") - if chart_stale: - # totals across a half-updated board would sum two windows - rows.append(seg([(LBL, " ── PR FLOW ── "), - (DIM, "counting %dd…" % hist_days)], w - 1)) - else: - # totals come from the days themselves: a day spans several - # columns now, so summing the columns would multiply by bar width - rows.append(seg([(LBL, " ── PR FLOW ── "), (DIM, "%s · " % span), - (PR, "▲ %d opened" % sum(opened_day)), - (DIM, " · "), - (OK, "▼ %d merged" % sum(merged_day)), - (DIM, " peak %d/day" % span_hi)], w - 1)) - # While the figures are still arriving the bars bounce like a level - # meter in pale versions of their own colours, then settle onto the - # real values rather than cutting to them. Three rows each side, always - # - trimming the unused half would make the chart change height at the - # end of the animation, which is exactly when it should be still. - if chart_stale: - # dance per day, then widen: bouncing each column on its own would - # show a twelve-column day as twelve separate thin bars - hu = spread(dance(len(days), tick)) - hd = spread(dance(len(days), tick, phase=2.1)) - cu, cd = LOAD_PR, LOAD_OK - settle_from, settle_t = (hu, hd), 0 - else: - real_u = [v / float(span_hi) for v in up] - real_d = [v / float(span_hi) for v in down] - if (settle_from and settle_t < SETTLE_FRAMES - and len(settle_from[0]) == chart_cols): - settle_t += 1 - q = settle_t / float(SETTLE_FRAMES) - q = q * q * (3 - 2 * q) # ease in and out of the move - hu = [a + (b - a) * q for a, b in zip(settle_from[0], real_u)] - hd = [a + (b - a) * q for a, b in zip(settle_from[1], real_d)] - cu, cd = mix(GHOST, PR_RGB, 0.45 + 0.55 * q), mix( - GHOST, OK_RGB, 0.45 + 0.55 * q) - else: - hu, hd, cu, cd = real_u, real_d, PR, OK - for line in vbars([(v, cu) for v in hu], 3, hi=1.0): - rows.append(seg([(RST, " ")] + line, w - 1)) - # an explicit baseline: without it the two series abut and the eye - # cannot tell which row the bars grow from - rows.append(seg([(RST, " "), (GRID, "─" * chart_cols)], w - 1)) - for line in vbars_down([(v, cd) for v in hd], 3, hi=1.0): - rows.append(seg([(RST, " ")] + line, w - 1)) - left = "%dd ago" % len(days) - rows.append(seg([(DIM, " " + left), - (DIM, " " * max(1, chart_cols - len(left) - 5)), - (DIM, "today")], w - 1)) - - rows.append("") - - # The account table earns the remaining height: it scrolls within - # whatever is left, while the calendar below it spends eight rows on - # decoration. The calendar keeps its place only where the pane is tall - # enough for both. - if calendar and h > 38: - grid, peak, total = heatmap(calendar["weeks"], w) - total_c = calendar.get("totalContributions", total) - rows.append(seg([(LBL, " ── CONTRIBUTIONS ── "), - (DIM, "%d in %d weeks, peak %d/day" - % (total_c, CONTRIB_WEEKS, peak))], - w - 1)) - for r, line in enumerate(grid): - # Rows are GitHub's own weekday index, where 0 is Sunday - - # grid[d["weekday"]] above - so the labels come off the same - # constant rather than a hand-written tuple. Written out - # Monday-first, they sat one row early and put today under - # yesterday's name. - label = WEEKDAYS[r] if r in (1, 3, 5) else "" - rows.append(seg([(DIM, " %-4s" % label), (OK, "".join(line))], - w - 1)) - cs = calendar_stats(calendar["weeks"]) - if cs: - bd, bc, _bw = cs["busiest"] - cells = [ - ("current streak", "%d days" % cs["current"], - OK if cs["current"] else DIM), - ("longest streak", "%d days" % cs["longest"], TXT), - ("today", "%d" % cs["today"], - OK if cs["today"] else DIM), - ("active days", "%d of %d (%.0f%%)" - % (cs["active"], cs["span"], - 100.0 * cs["active"] / cs["span"]), TXT), - ("busiest", "%s (%d)" % (bd, bc), TXT), - ("most on", "%s (%d)" % cs["weekday"], TXT), - ] - # as many columns as the width honestly allows, never fewer - # than one - the labels are what make these readable - ncols = 3 if w >= 86 else (2 if w >= 58 else 1) - cw = (w - 2) // ncols - for n in range(0, len(cells), ncols): - line = [(RST, " ")] - for label, value, colour in cells[n:n + ncols]: - used = len(label) + 1 + len(value) - line += [(DIM, label + " "), (colour, value), - (RST, " " * max(2, cw - used))] - rows.append(seg(line, w - 1)) - rows.append("") - - # Scroll rather than truncate: the selection has to stay on screen, or - # the arrows move something invisible. Keep it centred where there is - # room either side, and pinned at the ends of the list. Two header - # lines and the footer come out of the height before the rows do. - room = max(1, h - 5 - len(rows)) - first = 0 - if len(stats) > room: - first = min(max(0, selected - room // 2), len(stats) - room) - counter = (" %d-%d of %d" % (first + 1, min(first + room, len(stats)), - len(stats)) - if len(stats) > room else "") - rows.append(seg([(LBL, " ── BY ACCOUNT ──"), (DIM, counter)], w - 1)) - wide = w >= 62 - # No separators between these fields: the row emits %5d/%6s - # back-to-back, so a space here drifts the header one column per - # field - four by the time it reaches RATE. - # MRG takes seven: "MRG60D" is six characters and would sit flush - # against REVW in every window but the seven-day one. - head = " %-20s%5s%5s%7s%6s" % ("ACCOUNT", "OPEN", "REVW", - "MRG%dD" % store.days, "RATE") - bar_cols = max(4, w - 64) - spark_days = [(today - datetime.timedelta(days=n)).isoformat() - for n in range(min(store.days, bar_cols) - 1, -1, -1)] - if wide: - head += "%7s" % "ISSUES" - # Each row is scaled to its own busiest day, so a full block is - # 31 merged on one account and 16 on another. Say what the reader - # may do with it - read the shape - rather than naming the - # mechanism, which is what "OWN PEAK" did until someone asked. - # Pick the longest label that fits rather than clipping one: - # "MERGED/DAY" cut to "MERGED" would be a truncated hint, and the - # scale caveat is worth keeping down to the narrowest width it - # will fit in. - for label in ("MERGED/DAY · SHAPE ONLY, NOT TO SCALE", - "MERGED/DAY · SHAPE ONLY", - "MERGED/DAY (shape)", - "MERGED/DAY", ""): - if len(label) <= bar_cols: - break - head += (" " + label) if label else "" - rows.append(DIM + pad(head, w - 1)) - for i, s in list(enumerate(stats))[first:first + room]: - here = i == selected - tint = bg(38, 56, 76) if here else "" - r = s["rate"] - # this row's own staleness: accounts land one at a time, so an - # account already refetched for the new window shows real numbers - # while the ones behind it still shimmer - old = s.get("window") != store.days - line = [(tint + (ACCENT if here else TXT), - ("▸" if here else " ") + pad(s["account"] + (" (you)" if s["is_me"] else ""), 20)), - (tint + PR, "%5d" % s["open"]), - (tint + (WARN if s["review"] else DIM), "%5d" % s["review"]), - (tint + (DIM if old else OK), - "%7s" % ("···" if old else s["merged"])), - (tint + (DIM if old else - (heat(r / 100.0) if r is not None else DIM)), - "%6s" % ("···" if old else - ("%.0f%%" % r if r is not None else "--")))] - if wide: - line.append((tint + DIM, "%7d" % s["issues"])) - # Each account's own merged-per-day. The columns carry totals - # but no shape, and a fortnight of nothing ending in a spike - # reads very differently from a steady trickle. Scaled to this - # account's own peak: the absolute is in MRG two columns left, - # so the useful thing here is the shape. - hist = s.get("hist") or {} - if s.get("hist_window") != store.days: - line.append((tint + GRID, " " + "·" * len(spark_days))) - else: - top = max(hist.values()) if hist else 0 - marks = "" - for d in spark_days: - v = hist.get(d, 0) - marks += (SPARK[min(7, int(v / float(top) * 7.99))] - if v and top else " ") - line.append((tint + OK, " " + marks)) - if here: - line.append((tint, " " * w)) - rows.append(seg(line, w - 1)) - - hints = [[(ACCENT, "↑↓"), (DIM, " account")], [(DIM, "[w]indow")], - [(DIM, "[r]efresh")], [(DIM, "[q]uit")]] - footer = [" " + line for line in pack_hints(hints, w - 2)] - rows = rows[:h - len(footer)] - while len(rows) < h - len(footer): - rows.append("") - rows.extend(footer) - draw(rows, w, h) - time.sleep(0.3) - - -main() diff --git a/herdr-panes.py b/herdr-panes.py deleted file mode 100755 index f1f6e2a..0000000 --- a/herdr-panes.py +++ /dev/null @@ -1,518 +0,0 @@ -#!/usr/bin/env python3 -# terminal-toys - small dependency-free terminal widgets -# Copyright (C) 2026 William Li -# -# This program is free software: you can redistribute it and/or modify -# it under the terms of the GNU Affero General Public License as published -# by the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU Affero General Public License for more details. -# -# You should have received a copy of the GNU Affero General Public License -# along with this program. If not, see <https://www.gnu.org/licenses/>. -"""Everything running in Herdr, across every workspace. - -Two sections. AGENTS lists recognised coding agents with the lifecycle state -Herdr reports, ordered so the ones wanting a human come first. PROCESSES lists -every other pane that is actually running something — dev servers, monitors, -builds — with what it is running and what it costs. IDLE lists the panes -sitting at a shell prompt, by directory, so they can still be jumped to; -toggle that section with o. - -Enter jumps to whatever is selected: the agent's pane, or the tab holding that -process. - -A Herdr client, not a general agent monitor: the inventory and the lifecycle -states come from `herdr agent list`, the workspace labels from -`herdr workspace list`, and the pid behind each pane from -`herdr pane process-info`. Any agent kind Herdr recognises appears here with -no change to this file. - -On a terminal server hosting many workspaces, agents finish or get stuck in -places you are not currently looking. This lists every agent with the state -Herdr reports, ordered so the ones wanting your attention are at the top: - - blocked waiting on an approval or a question, right now - done finished background work you have not looked at yet - working busy - idle ready for input - unknown an agent is present but Herdr cannot classify it - -Each row also carries the workspace, how long the agent has held its current -state, and the real CPU and memory of its process. A duration is prefixed with -≥ when the state was already in place before this tool started, since then it -is only a lower bound. - - python3 herdr-panes.py [-n SECONDS] - -Keys: up/down select, Enter (or f) focuses that agent's pane so you jump -straight to whatever needs you, l toggles workspace labels vs pane ids, -o shows or hides the idle section, -r refreshes now, q quits. -Requires HERDR_ENV; it shells out to the `herdr` CLI. -""" -import collections -import json -import os -import subprocess -import sys -import threading -import time - -sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) -from common import (cannot_start, missing, RST, Keyboard, bg, draw, heat, load_config, maybe_help, - pack_hints, pad, rgb, seg, setup, size, title) - -_CFG = load_config("herdr_panes", {"refresh": 4.0}) -REFRESH = float(_CFG["refresh"]) # seconds between herdr polls (-n) - -BLOCKED = rgb(255, 105, 115) -DONE = rgb(90, 240, 160) -WORKING = rgb(255, 200, 90) -IDLE = rgb(128, 148, 172) -UNKNOWN = rgb(150, 150, 165) -DIM = rgb(127, 147, 172) -TXT = rgb(225, 235, 245) -LBL = rgb(130, 165, 200) -ACCENT = rgb(150, 210, 255) -PROC = rgb(170, 190, 215) -IDLE_C = rgb(122, 138, 160) - -# ordering: what needs a human first -RANK = {"blocked": 0, "done": 1, "working": 2, "idle": 3, "unknown": 4} -COLOR = {"blocked": BLOCKED, "done": DONE, "working": WORKING, - "idle": IDLE, "unknown": UNKNOWN} -MARK = {"blocked": "⚠", "done": "✓", "working": "◐", "idle": "·", "unknown": "?"} -SPINNER = "◐◓◑◒" - - -def herdr_action(*args): - """Run a herdr command for its effect; True when it succeeded.""" - try: - out = subprocess.run(("herdr",) + args, capture_output=True, text=True, - timeout=15) - return out.returncode == 0 - except Exception: - return False - - -def herdr(*args): - try: - out = subprocess.run(("herdr",) + args, capture_output=True, text=True, - timeout=15) - return json.loads(out.stdout)["result"] - except Exception: - return None - - -def tail_path(path, n): - """Keep the end of a path, marking the cut so it does not read as a name.""" - if len(path) <= n: - return path - return "…" + path[-(n - 1):] - - -def command_label(proc): - """Readable name for what a pane is running. - - "python3" or "node" says nothing useful, so prefer the script they were - handed; otherwise fall back to the executable's own name. - """ - argv = proc.get("argv") or [] - if not argv: - return proc.get("name") or "?" - head = os.path.basename(argv[0]) - if head.split(".")[0] in ("python", "python3", "node", "ruby", "perl", "bun", - "deno", "sh", "bash", "zsh") and len(argv) > 1: - for token in argv[1:]: - if not token.startswith("-"): - return os.path.basename(token) - return head - - -def proc_stats(pid): - """(cpu_ticks, rss_bytes) for a pid, or None.""" - try: - with open("/proc/%d/stat" % pid) as f: - rest = f.read().rpartition(")")[2].split() - return int(rest[11]) + int(rest[12]), int(rest[21]) * 4096 - except (OSError, IndexError, ValueError): - return None - - -class Store(object): - def __init__(self): - self.lock = threading.Lock() - self.agents = [] - self.panels = [] - self.labels = {} - self.error = None - self.wake = threading.Event() - self.since = {} # pane_id -> (state, first_seen, exact) - self.first_poll = True - self.cpu = {} # pid -> (ticks, wall) for delta CPU - - def snapshot(self): - with self.lock: - return (list(self.agents), list(self.panels), dict(self.labels), - self.error) - - def _panels(self, now, hz): - """Non-agent panes that are actually running something. - - A pane sitting at its shell prompt has nothing to report, so those are - skipped: when a command runs, the foreground pid differs from the - pane's own shell pid. - """ - listing = herdr("pane", "list") or {} - out = [] - for pane in (listing.get("panes") or []): - if pane.get("agent"): - continue - pid_info = herdr("pane", "process-info", "--pane", pane["pane_id"]) or {} - info = pid_info.get("process_info") or {} - fg = info.get("foreground_processes") or [] - busy = bool(fg) and fg[0].get("pid") != info.get("shell_pid") - proc = fg[0] if fg else {} - pid = proc.get("pid") if busy else None - entry = {"pane_id": pane.get("pane_id"), "tab_id": pane.get("tab_id"), - "workspace_id": pane.get("workspace_id"), - "command": command_label(proc) if busy else "", - "title": pane.get("terminal_title_stripped") or "", - "idle": not busy, "pid": pid, - "cwd": (proc.get("cwd") if busy else None) - or pane.get("cwd") or "", - "cpu": None, "rss": None} - st = proc_stats(pid) if pid else None - if st: - ticks, rss = st - entry["rss"] = rss - prev = self.cpu.get(pid) - if prev and now - prev[1] > 0: - entry["cpu"] = ((ticks - prev[0]) / float(hz) - / (now - prev[1]) * 100.0) - self.cpu[pid] = (ticks, now) - out.append(entry) - out.sort(key=lambda e: (e["idle"], -(e["cpu"] or 0))) - return out - - def run(self): - # A daemon thread that raises just stops, and a dead poller looks - # exactly like a source with no data - which is how deployments.py - # showed "0 deploys" for a day after an import went missing. - try: - self.poll() - except Exception as e: - with self.lock: - self.error = "poller stopped: %s: %s" % (type(e).__name__, - str(e)[:70]) - - def poll(self): - hz = os.sysconf("SC_CLK_TCK") - while True: - res = herdr("workspace", "list") - labels = {} - if res: - for w in (res.get("workspaces") or []): - labels[w.get("workspace_id")] = w.get("label") or "" - res = herdr("agent", "list") - if res is None: - with self.lock: - self.error = "herdr CLI unavailable (is HERDR_ENV set?)" - self.wake.wait(REFRESH) - self.wake.clear() - continue - - now = time.time() - agents = [] - for a in (res.get("agents") or []): - pane = a.get("pane_id") - state = a.get("agent_status") or "unknown" - was = self.since.get(pane) - if not was or was[0] != state: - # a state already in place when we started is only a lower - # bound - we did not see it begin - self.since[pane] = (state, now, not self.first_poll) - a = dict(a) - a["since"] = now - self.since[pane][1] - a["exact"] = self.since[pane][2] - - info = herdr("pane", "process-info", "--pane", pane) or {} - fg = (info.get("process_info") or {}).get("foreground_processes") or [] - a["pid"] = fg[0]["pid"] if fg else None - a["cpu"] = None - a["rss"] = None - if a["pid"]: - st = proc_stats(a["pid"]) - if st: - ticks, rss = st - a["rss"] = rss - prev = self.cpu.get(a["pid"]) - if prev: - dt = now - prev[1] - if dt > 0: - a["cpu"] = (ticks - prev[0]) / float(hz) / dt * 100.0 - self.cpu[a["pid"]] = (ticks, now) - agents.append(a) - - agents.sort(key=lambda x: (RANK.get(x.get("agent_status"), 9), - -x.get("since", 0))) - panels = self._panels(now, hz) - with self.lock: - self.agents, self.panels = agents, panels - self.labels, self.error = labels, None - self.first_poll = False - self.wake.wait(REFRESH) - self.wake.clear() - - -def ago(s): - s = int(max(0, s)) - if s < 60: - return "%ds" % s - if s < 3600: - return "%dm" % (s / 60) - if s < 86400: - return "%dh%02dm" % (s / 3600, s % 3600 / 60) - return "%dd" % (s / 86400) - - -def mem(b): - if b is None: - return " -- " - for unit in ("B", "K", "M", "G"): - if b < 1024: - return "%4.0f%s" % (b, unit) - b /= 1024.0 - return "%4.1fT" % b - - -def main(): - maybe_help(__doc__) - global REFRESH - args = sys.argv[1:] - if args and args[0] in ("-n", "--refresh"): - REFRESH = max(1.0, float(args[1])) - args = args[2:] - - absent = missing("herdr") - if absent: - cannot_start( - "herdr panes", absent, - ["This reads a running Herdr session through its own CLI: the", - "workspaces, the panes in them, and which agent is in which.", - "There is no other source for any of it.", - "", - "If Herdr is installed but not on PATH, this widget will find", - "it as soon as the shell can."], - "see https://herdr.dev") - - setup() - keyboard = Keyboard() - store = Store() - th = threading.Thread(target=store.run) - th.daemon = True - th.start() - - show_labels = True - show_idle = True - selected = 0 - scroll = 0 - note = "" - note_until = 0 - visible = 1 - tick = 0 - while True: - tick += 1 - for key in keyboard.poll(): - if key in ("q", "Q"): - keyboard.restore() - raise SystemExit(0) - if key == "r": - store.wake.set() - elif key == "l": - show_labels = not show_labels - elif key == "o": - show_idle = not show_idle - selected = 0 - elif key == "up": - selected = max(0, selected - 1) - elif key == "down": - selected += 1 - elif key == "home": - selected = 0 - elif key == "end": - selected = max(0, len(agents_now) - 1) - elif key in ("enter", "f"): - if agents_now: - kind, target = agents_now[min(selected, len(agents_now) - 1)] - pane = target.get("pane_id") - if kind == "agent": - ok = herdr_action("agent", "focus", pane) - what = target.get("agent") - else: - # non-agent panes have no focus-by-id; focusing the tab - # brings the pane into view, since a tab tiles its panes - ok = herdr_action("tab", "focus", target.get("tab_id")) - what = target.get("command") - note = ("→ focused %s in %s" % (what, pane) - if ok else "! could not focus %s" % pane) - note_until = time.time() + 3 - - w, h = size() - agents, panels, labels, err = store.snapshot() - entries = ([("agent", a) for a in agents] + - [("proc", p) for p in panels - if show_idle or not p["idle"]]) - agents_now = entries - selected = max(0, min(selected, len(entries) - 1)) if entries else 0 - if note and time.time() > note_until: - note = "" - counts = collections.Counter(a.get("agent_status") for a in agents) - - rows = [title("herdr panes", w, ACCENT)] - summary = [(DIM, " %d agent%s" % (len(agents), "" if len(agents) == 1 else "s")), - (DIM, " · %d workspace%s" % ( - len({a.get("workspace_id") for a in agents}), - "" if len({a.get("workspace_id") for a in agents}) == 1 else "s"))] - for state in ("blocked", "done", "working", "idle"): - if counts.get(state): - summary.append((COLOR[state], " %d %s" % (counts[state], state))) - rows.append(seg(summary, w - 1)) - if err: - rows.append(seg([(BLOCKED, " ! " + err)], w - 1)) - - wants = counts.get("blocked", 0) + counts.get("done", 0) - if wants: - rows.append(seg([(BLOCKED if counts.get("blocked") else DONE, - " ▸ %d agent%s waiting for you" % - (wants, "" if wants == 1 else "s"))], w - 1)) - else: - rows.append(seg([(DIM, " nothing waiting on you")], w - 1)) - rows.append("") - - wide = w >= 66 - rows.append(LBL + " ── AGENTS ── " + DIM + "%d" % len(agents)) - head = " %-8s %-8s %-6s %-5s" % ("AGENT", "STATE", "FOR", "CPU") - if wide: - head += " %-5s %-18s" % ("MEM", "WORKSPACE") - rows.append(DIM + pad(head, w - 1)) - - visible = max(1, len(entries)) - for i in range(len(agents)): - a = agents[i] - if len(rows) >= h - 6: - break - here = i == selected - state = a.get("agent_status") or "unknown" - col = COLOR.get(state, UNKNOWN) - loud = state in ("blocked", "done") - tint = bg(38, 56, 76) if here else ( - bg(46, 26, 30) if state == "blocked" else ( - bg(22, 46, 34) if state == "done" else "")) - mark = SPINNER[tick % 4] if state == "working" else MARK.get(state, "?") - cpu = a.get("cpu") - line = [(tint + col, ("▸" if here else " ") - + "%s %-6s" % (mark, a.get("agent", "?")[:6])), - (tint + col, " %-8s" % state.upper() if loud else " %-8s" % state), - (tint + DIM, " %-6s" % (("" if a.get("exact") else "≥") - + ago(a.get("since", 0)))), - (tint + (heat(min(1.0, (cpu or 0) / 100.0)) if cpu else DIM), - "%4.0f%%" % cpu if cpu is not None else " -")] - if wide: - place = labels.get(a.get("workspace_id")) or a.get("workspace_id", "") - if not show_labels: - place = a.get("pane_id", "") - line.append((tint + DIM, " " + mem(a.get("rss")))) - line.append((tint + ACCENT, " " + pad(place, 18))) - if loud or here: - line.append((tint, " " * w)) - rows.append(seg(line, w - 1)) - if len(rows) < h - 1: - title_text = (a.get("terminal_title_stripped") or "").strip() - cwd = (a.get("cwd") or "").replace(os.path.expanduser("~/projects/"), "") - rows.append(seg([(tint + DIM, " " + cwd + " "), - (tint + (TXT if (loud or here) else DIM), title_text), - (tint, " " * w if (loud or here) else "")], w - 1)) - if not agents and not err: - rows.append(DIM + " no agents running") - - running = [p for p in panels if not p["idle"]] - idle = [p for p in panels if p["idle"]] - - rows.append("") - rows.append(LBL + " ── PROCESSES ── " + DIM + - "%d pane%s running something" % - (len(running), "" if len(running) == 1 else "s")) - if wide: - rows.append(DIM + pad(" %-20s %-5s %-5s %-18s" % - ("COMMAND", "CPU", "MEM", "WORKSPACE"), w - 1)) - for j, pn in enumerate(running): - if len(rows) >= h - 2: - break - here = (len(agents) + j) == selected - tint = bg(38, 56, 76) if here else "" - cpu = pn.get("cpu") - place = labels.get(pn.get("workspace_id")) or pn.get("workspace_id", "") - if not show_labels: - place = pn.get("pane_id", "") - line = [(tint + PROC, ("▸" if here else " ") + "▪ "), - (tint + TXT, pad(pn.get("command", "?"), 20)), - (tint + (heat(min(1.0, (cpu or 0) / 100.0)) if cpu else DIM), - "%4.0f%%" % cpu if cpu is not None else " -")] - if wide: - line.append((tint + DIM, " " + mem(pn.get("rss")))) - line.append((tint + ACCENT, " " + pad(place, 18))) - if here: - line.append((tint, " " * w)) - rows.append(seg(line, w - 1)) - if not running: - rows.append(DIM + " every other pane is idle at a prompt") - - if show_idle and idle: - rows.append("") - rows.append(LBL + " ── IDLE ── " + DIM + - "%d pane%s at a prompt" % - (len(idle), "" if len(idle) == 1 else "s")) - for j, pn in enumerate(idle): - if len(rows) >= h - 2: - break - here = (len(agents) + len(running) + j) == selected - tint = bg(38, 56, 76) if here else "" - place = labels.get(pn.get("workspace_id")) or pn.get("workspace_id", "") - if not show_labels: - place = pn.get("pane_id", "") - where = (pn.get("cwd") or "").replace( - os.path.expanduser("~/projects/"), "").replace( - os.path.expanduser("~"), "~") - line = [(tint + IDLE_C, ("▸" if here else " ") + "▫ "), - (tint + IDLE_C, pad(tail_path(where, 26), 27)), - (tint + ACCENT, pad(place, 18))] - if here: - line.append((tint, " " * w)) - rows.append(seg(line, w - 1)) - - # The footer must always be the last visible line, so clamp the body - # to the space left for it rather than budgeting inside each section - - # that drifted, and the footer ended up written past the bottom row. - hints = [[(ACCENT, "↑↓"), (DIM, " select")], - [(ACCENT, "↵"), (DIM, " switch to this pane")], - [(DIM, "[o]idle")], [(DIM, "[l]abels")], - [(DIM, "[r]efresh")], [(DIM, "[q]uit")]] - footer = [" " + line for line in pack_hints(hints, w - 2)] - reserve = len(footer) + 1 # +1 for the note line - rows = rows[:h - reserve] - while len(rows) < h - reserve: - rows.append("") - rows.append(seg([(DONE if note.startswith("→") else BLOCKED, " " + note)], - w - 1) if note else "") - rows.extend(footer) - draw(rows, w, h) - time.sleep(0.25) - - -main() diff --git a/latency.py b/latency.py deleted file mode 100755 index 616bcf4..0000000 --- a/latency.py +++ /dev/null @@ -1,512 +0,0 @@ -#!/usr/bin/env python3 -# terminal-toys - small dependency-free terminal widgets -# Copyright (C) 2026 William Li -# -# This program is free software: you can redistribute it and/or modify -# it under the terms of the GNU Affero General Public License as published -# by the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU Affero General Public License for more details. -# -# You should have received a copy of the GNU Affero General Public License -# along with this program. If not, see <https://www.gnu.org/licenses/>. -"""Multi-target latency monitor. - -Continuously pings every target, and shows per-target statistics, a per-target -sparkline, a shared log-scale time graph, and a log of loss/spike events. - - python3 latency.py [-i SECONDS] [-c SECONDS] [host ...] - -Keys while running: i cycles the ping interval (0.2/0.5/1/2/5s, applied to -running pings immediately), g cycles the column aggregation, c cycles seconds -per graph column, q quits. - --i sets the ping interval. -g picks how samples sharing a column combine -(median, mean, min, max, p95; median by default, because latency is -right-skewed and a mean lets one spike misrepresent the whole block). --c sets how many seconds each graph column covers; -the default of one column per ping gives the smoothest motion, while a larger -value trades that for a longer visible history. - -Traffic cost: one 98-byte frame each way per target per interval. At the 1.0s -default with 4 targets that is ~0.8 KB/s (~2.8 MB/hour). - -Measures THIS host -> each target. It cannot measure target-to-target legs; -that needs a probe running on the far end. -""" -import collections -import math -import os -import re -import subprocess -import sys -import threading -import time - -sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) -from common import (cannot_start, missing, RST, Keyboard, cycle, draw, load_config, maybe_help, pad, - rgb, seg, setup, size, title) - -# Defaults are deliberately generic: personal targets belong in config.json, -# which is git-ignored, so this file stays publishable. -_CFG = load_config("latency", { - "hosts": ["1.1.1.1", "8.8.8.8"], - "interval": 0.5, - "seconds_per_column": 0, - "window": 600, - "spike_factor": 3.0, - "aggregate": "median", - "strip_suffixes": [], -}) - -DEFAULT_HOSTS = list(_CFG["hosts"]) -INTERVAL = float(_CFG["interval"]) # seconds between pings; -i overrides -SECONDS_PER_COLUMN = float(_CFG["seconds_per_column"]) -WINDOW = int(_CFG["window"]) # samples retained per target -SPIKE_FACTOR = float(_CFG["spike_factor"]) -STRIP_SUFFIXES = list(_CFG["strip_suffixes"]) - -AGGREGATE = _CFG["aggregate"] # how samples sharing a graph column combine -AGGREGATORS = ("median", "mean", "min", "max", "p95") - -# runtime key bindings cycle through these -INTERVAL_CHOICES = (0.2, 0.5, 1.0, 2.0, 5.0) -COLUMN_CHOICES = (0, 2.0, 5.0, 10.0) -RESTART = threading.Event() # set when INTERVAL changes; readers relaunch ping - -PALETTE = [(90, 220, 255), (255, 170, 80), (140, 255, 160), - (230, 140, 255), (255, 110, 130), (255, 230, 110), - (120, 160, 255), (255, 140, 200), (150, 255, 240)] -DIM = rgb(70, 100, 120) -GRID = rgb(38, 58, 74) -TXT = rgb(215, 235, 250) -LBL = rgb(120, 170, 200) -GOOD = rgb(110, 255, 170) -WARN = rgb(255, 200, 90) -BAD = rgb(255, 95, 105) -SPARK = "▁▂▃▄▅▆▇█" - -TIME_RE = re.compile(r"time[=<]([\d.]+)\s*ms") -IP_RE = re.compile(r"^PING\s+\S+\s+\(([\d.a-fA-F:]+)\)") - - -def short(host): - """Trim configured suffixes so long FQDNs stay readable in a narrow pane.""" - for suffix in STRIP_SUFFIXES: - if host.endswith(suffix): - return host[:-len(suffix)] - return host - - -def fmt_ms(v): - if v is None: - return " -- " - if v < 1.0: - return "%5.0fµs" % (v * 1000.0) - if v < 100: - return "%5.2fms" % v - return "%5.1fms" % v - - -def pct(v): - return "%5.1f%%" % v - - -def aggregate(values, how=None): - """Combine samples that share one graph column. - - Median by default: latency is right-skewed, so a single spike inside a - bucket would drag a mean well above the latency actually experienced most - of the time. - """ - how = how or AGGREGATE - ordered = sorted(values) - n = len(ordered) - if n == 1: - return ordered[0] - if how == "mean": - return sum(ordered) / n - if how == "min": - return ordered[0] - if how == "max": - return ordered[-1] - if how == "p95": - return ordered[min(n - 1, int(n * 0.95))] - mid = n // 2 - return ordered[mid] if n % 2 else (ordered[mid - 1] + ordered[mid]) / 2.0 - - -class Target(object): - def __init__(self, host, palette_rgb): - self.host = host - self.color = rgb(*palette_rgb) - # dimmed variant, used for the min-max spread band behind the line - self.band = rgb(*[int(c * 0.42) for c in palette_rgb]) - self.ip = None - self.samples = collections.deque(maxlen=WINDOW) # (t, rtt|None) - self.lock = threading.Lock() - self.alive = False - self.proc = None # live ping process, so the interval can change - self.restarting = False # True = deliberate relaunch, not an outage - - def add(self, rtt): - with self.lock: - self.samples.append((time.time(), rtt)) - self.alive = rtt is not None - - def snapshot(self): - with self.lock: - return list(self.samples) - - def stats(self): - s = self.snapshot() - got = [r for _, r in s if r is not None] - lost = sum(1 for _, r in s if r is None) - total = len(s) - if not got: - return {"now": None, "avg": None, "min": None, "max": None, - "jit": None, "p95": None, "loss": 100.0 if total else 0.0, - "n": total, "med": None} - ordered = sorted(got) - jit = 0.0 - if len(got) > 1: - jit = sum(abs(got[i] - got[i - 1]) for i in range(1, len(got))) / (len(got) - 1) - return { - "now": s[-1][1], - "avg": sum(got) / len(got), - "min": ordered[0], - "max": ordered[-1], - "jit": jit, - "p95": ordered[min(len(ordered) - 1, int(len(ordered) * 0.95))], - "med": ordered[len(ordered) // 2], - "loss": 100.0 * lost / total if total else 0.0, - "n": total, - } - - -EVENTS = collections.deque(maxlen=40) -EV_LOCK = threading.Lock() - - -def log_event(color, host, kind, detail): - with EV_LOCK: - EVENTS.append((time.strftime("%H:%M:%S"), color, host, kind, detail)) - - -def reader(t): - """Run ping forever, feeding samples into the target. - - Wrapped, because this runs in a daemon thread: if it raises, the thread - vanishes and the host simply stops updating, which reads as a quiet link - rather than as a broken widget. - """ - try: - _reader(t) - except Exception as e: - t.dead = "reader stopped: %s: %s" % (type(e).__name__, str(e)[:50]) - - -def _reader(t): - down_since = None - while True: - try: - proc = subprocess.Popen( - ["ping", "-n", "-O", "-i", str(INTERVAL), t.host], - stdout=subprocess.PIPE, stderr=subprocess.STDOUT, - text=True, bufsize=1) - t.proc = proc - except OSError: - time.sleep(2) - continue - for line in proc.stdout: - m = IP_RE.match(line) - if m: - t.ip = m.group(1) - continue - m = TIME_RE.search(line) - if m: - rtt = float(m.group(1)) - st = t.stats() - if st["med"] and rtt > st["med"] * SPIKE_FACTOR and st["n"] > 10: - log_event(t.color, t.host, "SPIKE", "%s (median %s)" % - (fmt_ms(rtt), fmt_ms(st["med"]))) - if down_since is not None: - log_event(t.color, t.host, "UP", "recovered after %.0fs" % - (time.time() - down_since)) - down_since = None - t.add(rtt) - elif "no answer yet" in line or "Unreachable" in line or "100% packet loss" in line: - if down_since is None: - down_since = time.time() - log_event(t.color, t.host, "LOSS", "no reply") - t.add(None) - proc.wait() - if t.restarting: - # we killed it ourselves to apply a new interval; not an outage - t.restarting = False - continue - # ping exited (bad name, network gone) - record loss and retry - if down_since is None: - down_since = time.time() - log_event(t.color, t.host, "DOWN", "ping exited, retrying") - t.add(None) - time.sleep(2) - - -def apply_interval(targets): - """Restart every ping so a new INTERVAL takes effect immediately.""" - for t in targets: - t.restarting = True - if t.proc and t.proc.poll() is None: - try: - t.proc.terminate() - except OSError: - t.restarting = False - - -def sparkline(samples, n): - pts = samples[-n:] - got = [r for _, r in pts if r is not None] - if not got: - return BAD + "×" * min(n, len(pts)) - lo, hi = min(got), max(got) - span = (hi - lo) or 1.0 - out = [] - last = None - for _, r in pts: - if r is None: - if last != BAD: - out.append(BAD) - last = BAD - out.append("×") - continue - frac = (r - lo) / span - col = GOOD if frac < 0.5 else (WARN if frac < 0.85 else BAD) - if col != last: - out.append(col) - last = col - out.append(SPARK[min(7, int(frac * 7.99))]) - return "".join(out) - - -def build_graph(targets, gw, gh, bucket): - """Log-scale multi-series plot. - - Columns are anchored to a fixed time grid (floor(ts / bucket)) rather than - measured backwards from `now`. A sample therefore never migrates between - columns, so the plot steps left exactly once per bucket instead of - jittering as `now` slides. With bucket == INTERVAL every ping advances the - plot by one column, the finest motion a character grid allows. - - Consecutive samples are joined into a polyline, so each series reads as a - continuous trace rather than scattered dots. - - Column gw-1 is 'now'. Returns (rows, span_seconds). - """ - newest = int(math.floor(time.time() / bucket)) - series = {} - lo = hi = None - for t in targets: - cols = [None] * gw - for ts, r in t.snapshot(): - if r is None: - continue - idx = gw - 1 - (newest - int(math.floor(ts / bucket))) - if 0 <= idx < gw: - if cols[idx] is None: - cols[idx] = [] - cols[idx].append(r) - # each column -> (central value, bucket min, bucket max) - vals = [None if c is None else (aggregate(c), min(c), max(c)) for c in cols] - series[t.host] = vals - for v in vals: - if v is None: - continue - lo = v[1] if lo is None else min(lo, v[1]) - hi = v[2] if hi is None else max(hi, v[2]) - if lo is None: - return [DIM + " collecting…"], bucket * gw - lo = max(0.05, lo * 0.8) - hi = max(hi * 1.25, lo * 1.6) - llo, lhi = math.log10(lo), math.log10(hi) - - grid = [[" "] * gw for _ in range(gh)] - color = [[None] * gw for _ in range(gh)] - - def put(x, y, ch, col): - if 0 <= x < gw and 0 <= y < gh: - grid[y][x] = ch - color[y][x] = col - - def row_of(v): - frac = (math.log10(max(v, 1e-3)) - llo) / (lhi - llo) - return int(round((1.0 - frac) * (gh - 1))) - - # pass 1: min-max spread inside each bucket, dimmed, behind everything - for t in reversed(targets): - for x, v in enumerate(series[t.host]): - if v is None: - continue - top, bot = row_of(v[2]), row_of(v[1]) - if top == bot: - continue # spread smaller than one row - for y in range(min(top, bot), max(top, bot) + 1): - put(x, y, "│", t.band) - - # pass 2: the central-value polyline, drawn over the bands - for t in reversed(targets): # first host in list drawn last (wins) - pts = [(x, row_of(v[0])) for x, v in enumerate(series[t.host]) if v is not None] - for i, (x, y) in enumerate(pts): - if i: - x0, y0 = pts[i - 1] - prev = y0 - for xx in range(x0 + 1, x + 1): - f = (xx - x0) / float(x - x0) - yy = int(round(y0 + (y - y0) * f)) - for k in range(min(prev, yy), max(prev, yy) + 1): - put(xx, k, "·" if k == yy else "│", t.color) - prev = yy - put(x, y, "●", t.color) - - rows = [] - for y in range(gh): - frac = 1.0 - y / float(gh - 1) if gh > 1 else 1.0 - tick = 10 ** (llo + frac * (lhi - llo)) - label = fmt_ms(tick) if y % 3 == 0 else " " - parts = [(LBL, label), (GRID, "│")] - run_col, run = None, [] - for x in range(gw): - c = color[y][x] - ch = grid[y][x] - if ch == " ": - ch = "·" if (x % 12 == 0 and y % 3 == 0) else " " - c = GRID if ch != " " else None - if c != run_col: - if run: - parts.append((run_col or RST, "".join(run))) - run_col, run = c, [] - run.append(ch) - if run: - parts.append((run_col or RST, "".join(run))) - rows.append(seg(parts, gw + 8)) - return rows, bucket * gw - - -def main(): - maybe_help(__doc__) - global INTERVAL, SECONDS_PER_COLUMN, AGGREGATE - args = sys.argv[1:] - while args and args[0] in ("-i", "--interval", "-c", "--column-seconds", - "-g", "--group"): - if args[0] in ("-i", "--interval"): - INTERVAL = max(0.2, float(args[1])) - elif args[0] in ("-c", "--column-seconds"): - SECONDS_PER_COLUMN = max(0.0, float(args[1])) - else: - if args[1] not in AGGREGATORS: - raise SystemExit("-g must be one of: " + ", ".join(AGGREGATORS)) - AGGREGATE = args[1] - args = args[2:] - hosts = args or DEFAULT_HOSTS - targets = [Target(h, PALETTE[i % len(PALETTE)]) for i, h in enumerate(hosts)] - absent = missing("ping") - if absent: - cannot_start( - "latency", absent, - ["Every figure here comes from ping: this widget times replies,", - "it does not send packets itself. With no ping there is nothing", - "to time and nothing to draw.", - "", - "It is in iputils-ping on Debian and Ubuntu, and in iputils on", - "Fedora and Arch."], - "apt install iputils-ping") - - setup() - keyboard = Keyboard() - for t in targets: - th = threading.Thread(target=reader, args=(t,)) - th.daemon = True - th.start() - - while True: - for key in keyboard.poll(): - if key in ("q", "Q"): - keyboard.restore() - raise SystemExit(0) - if key == "i": - INTERVAL = cycle(INTERVAL_CHOICES, INTERVAL) - apply_interval(targets) - elif key == "g": - AGGREGATE = cycle(AGGREGATORS, AGGREGATE) - elif key == "c": - SECONDS_PER_COLUMN = cycle(COLUMN_CHOICES, SECONDS_PER_COLUMN) - - w, h = size() - bucket = SECONDS_PER_COLUMN or INTERVAL - rows = [title("network latency monitor", w, rgb(90, 220, 255))] - rows.append(seg([(DIM, " %d targets · %.1fs interval · " % (len(targets), INTERVAL)), - (TXT, time.strftime("%H:%M:%S")), - (DIM, " · " + ("1 ping/column" if bucket <= INTERVAL - else "%s of %gs blocks" % (AGGREGATE, bucket))), - (GRID, " [i]nterval [g]roup [c]olumns [q]uit" - if keyboard.fd is not None else "")], - w - 1)) - rows.append("") - wide = w >= 72 - show_med = w >= 80 - head = " %-22s %7s %7s%s %7s %7s %7s %6s" % ( - "HOST", "NOW", "AVG", " MEDIAN" if show_med else "", - "MIN", "MAX", "JITTER", "LOSS") - rows.append(LBL + pad(head, w - 1)) - for t in targets: - st = t.stats() - dot = GOOD + "●" if t.alive else BAD + "○" - name = short(t.host) - lossc = GOOD if st["loss"] == 0 else (WARN if st["loss"] < 5 else BAD) - rows.append(seg([(dot, " "), (t.color, pad(name, 22)), - (TXT, " " + fmt_ms(st["now"])), - (TXT, " " + fmt_ms(st["avg"])), - (GOOD, (" " + fmt_ms(st["med"])) if show_med else ""), - (DIM, " " + fmt_ms(st["min"])), - (DIM, " " + fmt_ms(st["max"])), - (TXT, " " + fmt_ms(st["jit"])), - (lossc, " " + pct(st["loss"]))], w - 1)) - if wide: - rows.append(" " + sparkline(t.snapshot(), w - 6)) - rows.append("") - - ev_h = 7 if h - len(rows) > 20 else 0 - gh = max(4, h - len(rows) - ev_h - 4) - gw = max(10, w - 10) - graph, gspan = build_graph(targets, gw, gh, bucket) - rows.extend(graph) - rows.append(LBL + " └" + GRID + "─" * gw) - # The plot occupies columns 8 .. 8+gw-1, so the axis labels must span - # exactly gw cells: oldest flush left, "now" flush right under the - # newest sample. - left = "%ds ago" % int(gspan) - if len(left) + 4 > gw: - left = "" - rows.append(DIM + " " * 8 + left + " " * (gw - len(left) - 3) + "now") - rows.append("") - - if ev_h: - rows.append(DIM + " ── EVENTS ──") - with EV_LOCK: - evs = list(EVENTS)[-(ev_h - 1):] - if not evs: - rows.append(DIM + " (no loss or spikes recorded)") - for ts, col, host, kind, detail in evs: - kc = BAD if kind in ("LOSS", "DOWN") else (WARN if kind == "SPIKE" else GOOD) - rows.append(seg([(DIM, " " + ts + " "), (kc, "%-6s" % kind), - (col, pad(short(host), 22)), - (DIM, detail)], w - 1)) - draw(rows, w, h) - time.sleep(0.5) - - -main() diff --git a/linear.py b/linear.py deleted file mode 100755 index 8f52672..0000000 --- a/linear.py +++ /dev/null @@ -1,710 +0,0 @@ -#!/usr/bin/env python3 -# terminal-toys - small dependency-free terminal widgets -# Copyright (C) 2026 William Li -# -# This program is free software: you can redistribute it and/or modify -# it under the terms of the GNU Affero General Public License as published -# by the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU Affero General Public License for more details. -# -# You should have received a copy of the GNU Affero General Public License -# along with this program. If not, see <https://www.gnu.org/licenses/>. -"""Linear delivery metrics across every team in the workspace. - -What is outstanding, what the running cycles look like, and whether issues are -being closed faster than they arrive. - - python3 linear.py [-n SECONDS] [team-key ...] - -Team keys are the prefixes on issue identifiers - XFY, SYS and so on. With -none given every team is included, minus anything in `linear.exclude_teams`. - -Triage is counted apart from the backlog throughout. An auto-filed intake -queue and a groomed backlog are different populations, and adding them -together produces a number that means nothing. - -Credentials: `linear.token` in config.json, or $LINEAR_API_KEY. A personal API -key from Settings - Security & access - Personal API keys. The API is called -directly, so no CLI is required. - -Keys: up/down select a team, r refreshes now, w cycles the window -(7/14/30/60/90 days), q quits. -""" -import collections -import datetime -import json -import os -import sys -import threading -import time -import urllib.error -import urllib.request - -sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) -from common import (RST, Keyboard, bg, config_token_warning, cycle, dance, - draw, heat, load_config, maybe_help, meter, mix, - pack_hints, pad, rgb, seg, setup, size, skeleton, - stacked_bar, title, vbars, vbars_down) - -_CFG = load_config("linear", { - "token": "", - "token_env": "LINEAR_API_KEY", - "exclude_teams": [], # team keys to drop, e.g. an automated intake queue - "window_days": 14, - "refresh": 120, # seconds; the limit is 2500 requests an hour -}) - -REFRESH = float(_CFG["refresh"]) -WINDOWS = (7, 14, 30, 60, 90) -API = "https://api.linear.app/graphql" -PAGE = 250 # Linear's maximum page size -PAGE_CAP = 12 # pages per query, so one huge team cannot spin forever - -OK = rgb(90, 240, 160) -WARN = rgb(255, 200, 90) -BAD = rgb(255, 100, 110) -DIM = rgb(127, 147, 172) -GRID = rgb(60, 78, 98) -TXT = rgb(225, 235, 245) -LBL = rgb(130, 165, 200) -ACCENT = rgb(150, 210, 255) -NEW = rgb(180, 160, 255) # issues arriving -NEW_RGB, OK_RGB = (180, 160, 255), (90, 240, 160) -GHOST = (96, 106, 124) -LOAD_NEW, LOAD_OK = mix(GHOST, NEW_RGB, 0.45), mix(GHOST, OK_RGB, 0.45) -SETTLE_FRAMES = 8 -CHURN_DAYS = 6 # tail of a cycle's history that counts as "lately" - -# Linear's own vocabulary, in the order work moves through it -STATE_ORDER = ("triage", "backlog", "unstarted", "started") -STATE_LABEL = {"triage": "triage", "backlog": "backlog", - "unstarted": "todo", "started": "in progress"} -STATE_COLOUR = {"triage": BAD, "backlog": DIM, "unstarted": ACCENT, - "started": WARN} - - -def token(): - """A Linear personal API key, from config.json or the environment.""" - if _CFG["token"]: - return _CFG["token"], "config" - tok = os.environ.get(_CFG["token_env"] or "LINEAR_API_KEY") - if tok: - return tok, "env" - return None, "missing" - - -_QUOTA = {"requests": None, "complexity": None} - - -def graphql(query, tok, variables=None): - body = json.dumps({"query": query, - "variables": variables or {}}).encode() - req = urllib.request.Request(API, data=body, headers={ - "Authorization": tok, - "Content-Type": "application/json", - "User-Agent": "terminal-toys", - }) - with urllib.request.urlopen(req, timeout=30) as r: - for key, hdr in (("requests", "X-RateLimit-Requests-Remaining"), - ("complexity", "X-RateLimit-Complexity-Remaining")): - raw = r.headers.get(hdr) - if raw is not None: - try: - _QUOTA[key] = int(raw) - except ValueError: - pass - data = json.load(r) - if data.get("errors"): - raise ValueError(data["errors"][0].get("message", "")[:80]) - return data["data"] - - -def pages(tok, query, node_path, variables=None): - """Follow pageInfo to the end, or to PAGE_CAP, and return every node. - - Linear has no totalCount on connections, so anything counted has to be - walked. Only the fields actually needed are requested: complexity is a - tenth of a point per property against a budget of three million an hour, - so the page count matters and the field count barely does. - """ - out, cursor, seen = [], None, 0 - for _ in range(PAGE_CAP): - v = dict(variables or {}) - v["after"] = cursor - conn = graphql(query, tok, v) - for step in node_path: - conn = conn[step] - out.extend(conn["nodes"]) - info = conn["pageInfo"] - seen += 1 - if not info.get("hasNextPage"): - return out, False - cursor = info.get("endCursor") - return out, True # hit the cap: the caller should say so - - -OPEN_QUERY = """ -query($after: String) { - issues(first: %d, after: $after, - filter: { state: { type: { nin: ["completed", "canceled", - "duplicate"] } } }) { - nodes { identifier estimate startedAt createdAt - state { type } team { key } } - pageInfo { hasNextPage endCursor } - } -}""" % PAGE - -CREATED_QUERY = """ -query($after: String, $since: DateTimeOrDuration!) { - issues(first: %d, after: $after, filter: { createdAt: { gte: $since } }) { - nodes { createdAt team { key } } - pageInfo { hasNextPage endCursor } - } -}""" % PAGE - -DONE_QUERY = """ -query($after: String, $since: DateTimeOrDuration!) { - issues(first: %d, after: $after, filter: { completedAt: { gte: $since } }) { - nodes { identifier completedAt startedAt createdAt team { key } } - pageInfo { hasNextPage endCursor } - } -}""" % PAGE - -CYCLES_QUERY = """ -{ - cycles(first: 50, filter: { isActive: { eq: true } }) { - nodes { - name number startsAt endsAt progress - issueCountHistory completedIssueCountHistory - scopeHistory completedScopeHistory - team { key name } - } - pageInfo { hasNextPage endCursor } - } -}""" - -TEAMS_QUERY = """ -{ teams(first: 100) { nodes { key name } pageInfo { hasNextPage } } }""" - - -def day(ts): - """The calendar day of an ISO timestamp, as Linear returns them.""" - return (ts or "")[:10] - - -def ago(t): - if not t: - return "--" - s = int(time.time() - t) - if s < 60: - return "%ds" % s - if s < 3600: - return "%dm" % (s // 60) - return "%dh" % (s // 3600) - - -class Store(object): - def __init__(self, days, keep): - self.lock = threading.Lock() - self.days = days - self.keep = keep # team keys to include; empty = everything - self.teams = [] - self.states = collections.Counter() - self.by_team = {} - self.cycles = [] - self.created = collections.Counter() - self.completed = collections.Counter() - self.lead = [] # created -> completed, in hours - self.cycle_time = [] # started -> completed, in hours - # extremes, each as (hours, identifier): a median says the shape of - # the distribution, these say which issue to go and look at - self.quickest = self.slowest = None - self.oldest_open = self.oldest_wip = None - self.window = None # which window the counters describe - self.truncated = False - self.error = None - self.fetched = 0 - self.wake = threading.Event() - - def snapshot(self): - with self.lock: - return (list(self.teams), collections.Counter(self.states), - dict(self.by_team), list(self.cycles), - collections.Counter(self.created), - collections.Counter(self.completed), list(self.lead), - list(self.cycle_time), - (self.quickest, self.slowest, self.oldest_open, - self.oldest_wip), - self.window, self.truncated, self.error, self.fetched) - - def wanted(self, key): - if self.keep: - return key in self.keep - return key not in (_CFG["exclude_teams"] or []) - - def run(self): - # A daemon thread that raises just stops, and a dead poller looks - # exactly like a source with no data - which is how deployments.py - # showed "0 deploys" for a day after an import went missing. - try: - self.poll() - except Exception as e: - with self.lock: - self.error = "poller stopped: %s: %s" % (type(e).__name__, - str(e)[:70]) - - def poll(self): - while True: - tok, source = token() - if not tok: - with self.lock: - self.error = ("no key: set linear.token in config.json or " - "$%s" % (_CFG["token_env"] or "LINEAR_API_KEY")) - self.wake.wait(REFRESH) - self.wake.clear() - continue - try: - self.pass_(tok, source) - except urllib.error.HTTPError as e: - with self.lock: - self.error = "HTTP %s from Linear%s" % ( - e.code, " (key rejected?)" if e.code == 401 else "") - except Exception as e: - with self.lock: - self.error = "%s: %s" % (type(e).__name__, str(e)[:60]) - self.wake.wait(REFRESH) - self.wake.clear() - - def pass_(self, tok, source): - with self.lock: - days_now = self.days - since = (datetime.datetime.now(datetime.timezone.utc) - - datetime.timedelta(days=days_now - 1)).strftime( - "%Y-%m-%dT00:00:00.000Z") - - teams = graphql(TEAMS_QUERY, tok)["teams"]["nodes"] - teams = [t for t in teams if self.wanted(t["key"])] - keys = set(t["key"] for t in teams) - with self.lock: - self.teams = teams - - # what is outstanding right now, at any age - rows, capped = pages(tok, OPEN_QUERY, ["issues"]) - states = collections.Counter() - by_team = {} - now = datetime.datetime.now(datetime.timezone.utc) - oldest_open = oldest_wip = None - for it in rows: - key = (it.get("team") or {}).get("key") - if key not in keys: - continue - st = (it.get("state") or {}).get("type") - if st not in STATE_ORDER: - continue - states[st] += 1 - slot = by_team.setdefault(key, collections.Counter()) - slot[st] += 1 - slot["open"] += 1 - born = parse(it.get("createdAt")) - if born: - age = (now - born).total_seconds() / 3600.0 - if oldest_open is None or age > oldest_open[0]: - oldest_open = (age, it.get("identifier")) - began = parse(it.get("startedAt")) - if st == "started" and began: - age = (now - began).total_seconds() / 3600.0 - if oldest_wip is None or age > oldest_wip[0]: - oldest_wip = (age, it.get("identifier")) - - # the running cycles, each already carrying its own burndown - cyc = [c for c in graphql(CYCLES_QUERY, tok)["cycles"]["nodes"] - if (c.get("team") or {}).get("key") in keys] - - # arrivals and departures over the window - made, cap2 = pages(tok, CREATED_QUERY, ["issues"], {"since": since}) - done, cap3 = pages(tok, DONE_QUERY, ["issues"], {"since": since}) - created, completed = collections.Counter(), collections.Counter() - lead, ctime = [], [] - quickest = slowest = None - for it in made: - if (it.get("team") or {}).get("key") in keys: - created[day(it["createdAt"])] += 1 - for it in done: - if (it.get("team") or {}).get("key") not in keys: - continue - completed[day(it["completedAt"])] += 1 - fin = parse(it.get("completedAt")) - if fin and parse(it.get("createdAt")): - hrs = (fin - parse(it["createdAt"])).total_seconds() / 3600.0 - lead.append(hrs) - if quickest is None or hrs < quickest[0]: - quickest = (hrs, it.get("identifier")) - if slowest is None or hrs > slowest[0]: - slowest = (hrs, it.get("identifier")) - if fin and parse(it.get("startedAt")): - ctime.append((fin - parse(it["startedAt"])).total_seconds() / 3600.0) - - for key in by_team: - by_team[key]["done"] = sum( - 1 for it in done - if (it.get("team") or {}).get("key") == key) - - with self.lock: - self.states, self.by_team, self.cycles = states, by_team, cyc - self.created, self.completed = created, completed - self.lead, self.cycle_time = lead, ctime - self.quickest, self.slowest = quickest, slowest - self.oldest_open, self.oldest_wip = oldest_open, oldest_wip - self.window = days_now - self.truncated = capped or cap2 or cap3 - self.fetched = time.time() - self.error = (config_token_warning() if source == "config" else None) - - -def parse(ts): - if not ts: - return None - try: - return datetime.datetime.strptime(ts[:19], "%Y-%m-%dT%H:%M:%S").replace( - tzinfo=datetime.timezone.utc) - except ValueError: - return None - - -def dur(hours): - """A span at whatever unit keeps it readable. - - Rolls over to years because these figures reach them: an issue open for - "1021.6d" is arithmetic, one open for "2.8y" is a decision. - """ - if hours is None: - return "--" - if hours < 1: - return "%dm" % max(1, int(hours * 60)) - if hours < 48: - return "%.1fh" % hours - days = hours / 24.0 - if days < 365: - return "%.1fd" % days - return "%.1fy" % (days / 365.0) - - -def median(xs): - if not xs: - return None - s = sorted(xs) - n = len(s) - return s[n // 2] if n % 2 else (s[n // 2 - 1] + s[n // 2]) / 2.0 - - -def main(): - maybe_help(__doc__) - args = sys.argv[1:] - while args and args[0] in ("-n", "--refresh"): - global REFRESH - REFRESH = float(args[1]) - args = args[2:] - store = Store(int(_CFG["window_days"]), [a.upper() for a in args]) - threading.Thread(target=store.run, daemon=True).start() - setup() - keyboard = Keyboard() - # Two sections scroll, so the arrows need to know which one they are in. - # Tab moves the focus; the focused heading says so and carries the range. - CYCLES, TEAMS = 0, 1 - focus, sel = CYCLES, [0, 0] - tick = 0 - settle_t, settle_from = 0, None - - while True: - tick += 1 - for key in keyboard.poll(): - if key in ("q", "Q"): - raise SystemExit(0) - if key == "r": - store.wake.set() - elif key == "w": - with store.lock: - store.days = cycle(WINDOWS, store.days) - store.wake.set() - elif key == "tab": - focus = TEAMS if focus == CYCLES else CYCLES - elif key == "up": - sel[focus] = max(0, sel[focus] - 1) - elif key == "down": - sel[focus] += 1 - - w, h = size() - (teams, states, by_team, cycles, created, completed, lead, ctime, - extremes, window, truncated, err, fetched) = store.snapshot() - quickest, slowest, oldest_open, oldest_wip = extremes - stale = window != store.days - rows = [title("linear ops", w, NEW)] - - head = [(DIM, " %d team%s" % (len(teams), "" if len(teams) == 1 else "s")), - (DIM, " updated %s ago" % ago(fetched))] - if _QUOTA["requests"] is not None: - left = _QUOTA["requests"] - head.append((OK if left > 500 else WARN, - " %d req left/hr" % left)) - rows.append(seg(head, w - 1)) - if err: - rows.append(seg([(BAD, " ! " + err)], w - 1)) - if not teams: - rows.append(seg([(DIM, " collecting…")], w - 1)) - rows += [""] * max(0, h - len(rows) - 1) - draw(rows, w, h) - time.sleep(0.4) - continue - - # ── how long work takes, across every team ────────────────────── - # Leads the board: it is the one figure that says whether the machine - # is getting faster or slower, and it is an aggregate over all teams - # rather than any one of them - which the heading has to say, or it - # reads as whichever team happens to be selected below. - med_lead, med_cycle = median(lead), median(ctime) - rows.append(seg([(LBL, " ── HOW LONG ── "), - (DIM, "all teams · "), - (DIM, "counting…" if stale - else "median of %d completed in %dd" - % (len(lead), store.days))], w - 1)) - # Every figure here goes through one grid. The medians used to be - # hand-padded and drifted out of step with the extremes beneath them, - # and the arrow definitions floated after the values instead of - # attaching to the terms they define. - def extreme(label, pair, colour): - if stale: - return (label, "···", DIM) - if not pair: - return (label, "--", DIM) - hours, ident = pair - return (label, "%s %s" % (ident or "?", dur(hours)), colour) - - cells = [ - ("lead (created→completed)", - "···" if stale else dur(med_lead), DIM if stale else TXT), - ("cycle (started→completed)", - "···" if stale else dur(med_cycle), DIM if stale else TXT), - extreme("quickest", quickest, OK), - extreme("slowest", slowest, WARN), - extreme("oldest open", oldest_open, BAD), - extreme("oldest in progress", oldest_wip, WARN), - ] - label_w = max(len(x[0]) for x in cells) - # Two columns only when a value still gets room for the longest thing - # it holds - an identifier and a duration. Cells are a fixed width so - # a long value cannot push the next column out of line. - ncols = 2 if (w - 2) // 2 - label_w - 3 >= 15 else 1 - cw = (w - 2) // ncols - val_w = max(6, cw - label_w - 3) - for n in range(0, len(cells), ncols): - line = [(RST, " ")] - for label, value, colour in cells[n:n + ncols]: - line += [(DIM, " " + pad(label, label_w) + " "), - (colour, pad(value, val_w))] - rows.append(seg(line, w - 1)) - rows.append("") - - # ── what is outstanding right now ──────────────────────────────── - total_open = sum(states[s] for s in STATE_ORDER) - rows.append(seg([(LBL, " ── OPEN ── "), - (NEW, "%d" % total_open), (DIM, " issues open"), - (DIM, " (any age)"), - (WARN, " truncated" if truncated else "")], w - 1)) - if total_open: - parts = [(states[s] / float(total_open), STATE_COLOUR[s]) - for s in STATE_ORDER if states[s]] - rows.append(seg([(RST, " ")] + stacked_bar(parts, max(10, w - 3)), - w - 1)) - key = [(RST, " ")] - for s in STATE_ORDER: - if states[s]: - key += [(STATE_COLOUR[s], "▇ "), (TXT, STATE_LABEL[s]), - (DIM, " %d (%.0f%%) " - % (states[s], 100.0 * states[s] / total_open))] - rows.append(seg(key, w - 1)) - - # ── the running cycles, each with its own burndown ─────────────── - rows.append("") - # Busiest first. The burndown arrays already say where the action is: - # day-over-day movement in completed scope and in scope itself, summed - # over the tail. A cycle nothing has touched in a week is not - # interesting however close its deadline, and an empty one scores zero - # and sinks without needing a special case. Deadline breaks ties. - def churn(c): - moved = 0.0 - for series in ("completedScopeHistory", "scopeHistory"): - tail = (c.get(series) or [])[-CHURN_DAYS:] - moved += sum(abs(tail[i] - tail[i - 1]) - for i in range(1, len(tail))) - ends = parse(c.get("endsAt")) - left = ((ends - datetime.datetime.now(datetime.timezone.utc)).days - if ends else 999) - return (-moved, left) - - ranked_cycles = sorted(cycles, key=churn) - if ranked_cycles: - sel[CYCLES] = max(0, min(sel[CYCLES], len(ranked_cycles) - 1)) - shown = max(2, min(6, (h - len(rows)) // 4)) - cfirst = 0 - if len(ranked_cycles) > shown: - cfirst = min(max(0, sel[CYCLES] - shown // 2), - len(ranked_cycles) - shown) - here_now = focus == CYCLES - rows.append(seg([(ACCENT if here_now else LBL, " ── ACTIVE CYCLES ── "), - (DIM, "%d running" % len(cycles)), - (ACCENT if here_now else DIM, - (" %s%d-%d of %d" - % ("↑↓ " if here_now else "", - cfirst + 1, - min(cfirst + shown, len(ranked_cycles)), - len(ranked_cycles))) - if len(ranked_cycles) > shown else "")], w - 1)) - if not cycles: - rows.append(seg([(DIM, " no cycle is running in any team")], w - 1)) - for ci, c in list(enumerate(ranked_cycles))[cfirst:cfirst + shown]: - scope = (c.get("scopeHistory") or [0])[-1] - done = (c.get("completedScopeHistory") or [0])[-1] - opened_at = (c.get("scopeHistory") or [0])[0] - ends = parse(c.get("endsAt")) - left = ((ends - datetime.datetime.now(datetime.timezone.utc)).days - if ends else None) - frac = (done / float(scope)) if scope else 0.0 - name = "%s %s" % ((c.get("team") or {}).get("key", "?"), - c.get("name") or ("Cycle %g" % (c.get("number") or 0))) - on = focus == CYCLES and ci == sel[CYCLES] - tint = bg(38, 56, 76) if on else "" - line = [(tint + (ACCENT if on else TXT), - ("▸" if on else " ") + pad(name, 18)), - (tint + heat(frac), meter(frac, max(8, min(28, w - 54)))), - (tint + (heat(frac) if scope else DIM), - " %3s" % ("%.0f%%" % (frac * 100) if scope else "--")), - (tint + DIM, " %g/%g pts" % (done, scope) if scope - else " nothing scoped")] - if left is not None: - line.append((tint + (WARN if left <= 2 else DIM), - " %dd left" % left)) - # scope added after the cycle opened is the number that explains a - # cycle that is working hard and still slipping - if scope > opened_at: - line.append((tint + BAD, " +%g added" % (scope - opened_at))) - if on: - line.append((tint, " " * w)) - rows.append(seg(line, w - 1)) - - # ── arrivals against departures ───────────────────────────────── - hist_days = store.days - today = datetime.date.today() - days = [(today - datetime.timedelta(days=n)).isoformat() - for n in range(hist_days - 1, -1, -1)] - avail = max(10, w - 3) - if len(days) > avail: - days = days[-avail:] - slot = max(1, avail // len(days)) - gap = 1 if slot >= 3 else 0 - barw = slot - gap - - def spread(per_day): - cols = [] - for n, v in enumerate(per_day): - cols.extend([v] * barw) - if gap and n < len(per_day) - 1: - cols.extend([0] * gap) - return cols - - made_day = [created.get(d, 0) for d in days] - done_day = [completed.get(d, 0) for d in days] - up, down = spread(made_day), spread(done_day) - chart_cols = len(up) - span_hi = max(up + down) or 1 - span = ("%dd of %dd" % (len(days), hist_days) - if len(days) < hist_days else "%dd" % len(days)) - rows.append("") - if stale: - rows.append(seg([(LBL, " ── ISSUE FLOW ── "), - (DIM, "counting %dd…" % hist_days)], w - 1)) - else: - rows.append(seg([(LBL, " ── ISSUE FLOW ── "), (DIM, "%s · " % span), - (NEW, "▲ %d created" % sum(made_day)), - (DIM, " · "), - (OK, "▼ %d completed" % sum(done_day)), - (DIM, " peak %d/day" % span_hi)], w - 1)) - if stale: - hu = spread(dance(len(days), tick)) - hd = spread(dance(len(days), tick, phase=2.1)) - cu, cd = LOAD_NEW, LOAD_OK - settle_from, settle_t = (hu, hd), 0 - else: - real_u = [v / float(span_hi) for v in up] - real_d = [v / float(span_hi) for v in down] - if (settle_from and settle_t < SETTLE_FRAMES - and len(settle_from[0]) == chart_cols): - settle_t += 1 - q = settle_t / float(SETTLE_FRAMES) - q = q * q * (3 - 2 * q) - hu = [a + (b - a) * q for a, b in zip(settle_from[0], real_u)] - hd = [a + (b - a) * q for a, b in zip(settle_from[1], real_d)] - cu = mix(GHOST, NEW_RGB, 0.45 + 0.55 * q) - cd = mix(GHOST, OK_RGB, 0.45 + 0.55 * q) - else: - hu, hd, cu, cd = real_u, real_d, NEW, OK - for line in vbars([(v, cu) for v in hu], 3, hi=1.0): - rows.append(seg([(RST, " ")] + line, w - 1)) - rows.append(seg([(RST, " "), (GRID, "─" * chart_cols)], w - 1)) - for line in vbars_down([(v, cd) for v in hd], 3, hi=1.0): - rows.append(seg([(RST, " ")] + line, w - 1)) - left_lbl = "%dd ago" % len(days) - rows.append(seg([(DIM, " " + left_lbl), - (DIM, " " * max(1, chart_cols - len(left_lbl) - 5)), - (DIM, "today")], w - 1)) - - # ── by team ───────────────────────────────────────────────────── - rows.append("") - ranked = sorted(teams, key=lambda t: ( - -(by_team.get(t["key"], {}).get("open", 0)), t["key"])) - if ranked: - sel[TEAMS] = max(0, min(sel[TEAMS], len(ranked) - 1)) - room = max(1, h - 5 - len(rows)) - first = 0 - if len(ranked) > room: - first = min(max(0, sel[TEAMS] - room // 2), len(ranked) - room) - on_teams = focus == TEAMS - counter = (" %s%d-%d of %d" - % ("↑↓ " if on_teams else "", first + 1, - min(first + room, len(ranked)), len(ranked)) - if len(ranked) > room else "") - rows.append(seg([(ACCENT if on_teams else LBL, " ── BY TEAM ──"), - (ACCENT if on_teams else DIM, counter)], w - 1)) - rows.append(DIM + pad(" %-22s%6s%7s%8s%8s" - % ("TEAM", "OPEN", "TRIAGE", "DOING", "DONE%dD" - % store.days), w - 1)) - for i, t in list(enumerate(ranked))[first:first + room]: - c = by_team.get(t["key"], collections.Counter()) - here = on_teams and i == sel[TEAMS] - tint = bg(38, 56, 76) if here else "" - rows.append(seg([ - (tint + (ACCENT if here else TXT), - ("▸" if here else " ") + pad("%s %s" % (t["key"], t["name"]), 22)), - (tint + NEW, "%6d" % c.get("open", 0)), - (tint + (BAD if c.get("triage") else DIM), "%7d" % c.get("triage", 0)), - (tint + (WARN if c.get("started") else DIM), "%8d" % c.get("started", 0)), - (tint + (OK if c.get("done") else DIM), "%8d" % c.get("done", 0)), - ] + ([(tint, " " * w)] if here else []), w - 1)) - - hints = [[(ACCENT, "↑↓"), (DIM, " scroll")], - [(DIM, "[tab] section")], [(DIM, "[w]indow")], - [(DIM, "[r]efresh")], [(DIM, "[q]uit")]] - footer = [" " + line for line in pack_hints(hints, w - 2)] - rows = rows[:h - len(footer)] - while len(rows) < h - len(footer): - rows.append("") - rows.extend(footer) - draw(rows, w, h) - time.sleep(0.3) - - -main() diff --git a/link.py b/link.py deleted file mode 100755 index 0308502..0000000 --- a/link.py +++ /dev/null @@ -1,778 +0,0 @@ -#!/usr/bin/env python3 -# terminal-toys - small dependency-free terminal widgets -# Copyright (C) 2026 William Li -# -# This program is free software: you can redistribute it and/or modify -# it under the terms of the GNU Affero General Public License as published -# by the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU Affero General Public License for more details. -# -# You should have received a copy of the GNU Affero General Public License -# along with this program. If not, see <https://www.gnu.org/licenses/>. -"""How good the connection is between here and whoever is connected to it. - -Every other network widget in this repo measures a path it chose - ping these -hosts, watch that tailnet. This one measures the path *you* are on: the TCP -socket carrying your session, as the kernel already sees it. - -Nothing is sent. `ss -tin` reports what the kernel has measured for each -established socket - round-trip time and its variance, the best round trip it -has ever seen, retransmitted bytes, the delivery rate it actually achieved - -so this widget can describe the link without adding a single packet to it. - - python3 link.py [-n SECONDS] - -Sessions are every established connection into a port this machine listens on, -which is SSH and anything else that accepts terminals. - -w cycles how much time the chart covers - a minute, five, fifteen, an hour. -Past a minute there are more samples than columns, so each column becomes the -median of its slice: a spike is still counted in the worst column and on the -detail screen, but the line itself smooths. Look at a stall on the short -window. - -Keys: up/down select, enter opens one, w changes the span, o toggles idle -sessions, r refreshes, q quits. -""" -import collections -import os -import re -import subprocess -import sys -import threading -import time - -sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) -from common import (RST, Keyboard, bg, cannot_start, draw, heat, load_config, - maybe_help, pack_hints, pad, rgb, seg, setup, size, - title, vbars) - -_CFG = load_config("link", { - # Every established connection into a port we listen on. Naming ports - # instead pins the set - useful if something else on this machine accepts - # connections you would rather not watch. - "ports": [], - "refresh": 2, - "history": 120, - # The spans w cycles through, in seconds. The first is what opens. - "windows": [60, 300, 900, 3600], -}) - -REFRESH = max(0.5, float(_CFG["refresh"])) -PORTS = [int(p) for p in (_CFG["ports"] or [])] -WINDOWS = [int(s) for s in (_CFG["windows"] or []) if int(s) > 0] or [300] -# Retention has to cover the longest span on offer, or w would cycle to a -# window the samples could never fill. `history` stays a floor rather than -# the figure, so a config asking for more than that still gets it. -HISTORY = max(int(_CFG["history"]), int(max(WINDOWS) / REFRESH) + 2) - -OK = rgb(90, 240, 160) -WARN = rgb(255, 200, 90) -BAD = rgb(255, 100, 110) -DIM = rgb(127, 147, 172) -GRID = rgb(60, 78, 98) -TXT = rgb(225, 235, 245) -LBL = rgb(130, 165, 200) -ACCENT = rgb(150, 210, 255) -LINK = rgb(140, 200, 255) -# One hue per session, distinct from each other and clear of the amber and -# red this widget keeps for trouble. -SESSION_HUES = (rgb(120, 200, 255), rgb(150, 230, 180), rgb(220, 170, 255), - rgb(160, 190, 240), rgb(200, 220, 150), rgb(240, 180, 210)) - -IDLE_AFTER = 300.0 # seconds without traffic before a session is idle -SPARK = "▁▂▃▄▅▆▇█" - - -def run(args): - try: - out = subprocess.run(args, capture_output=True, text=True, timeout=5) - except (OSError, subprocess.SubprocessError): - return "" - return out.stdout if out.returncode == 0 else "" - - -def listening_ports(): - """Ports this machine accepts connections on. - - Inbound is defined as "arrived at a port we listen on" rather than by a - list of port numbers, so SSH, a terminal server and anything else that - accepts sessions are all found without being named. - """ - ports = set(PORTS) - for line in run(["ss", "-tlnH"]).splitlines(): - cols = line.split() - if len(cols) >= 4: - try: - ports.add(int(cols[3].rsplit(":", 1)[1])) - except (ValueError, IndexError): - continue - return ports - - -def parse_metrics(text): - """The kernel's own numbers for one socket. - - `ss` mixes two shapes on that line: `key:value` pairs and space-separated - ones like `delivery_rate 45107960bps`. Both are read; anything unknown is - left alone rather than guessed at. - """ - out = {} - for key in ("send", "pacing_rate", "delivery_rate"): - found = re.search(r"\b%s (\d+)bps" % key, text) - if found: - out[key] = int(found.group(1)) - for token in text.split(): - if ":" not in token: - continue - key, _, value = token.partition(":") - out[key] = value - return out - - -def num(value): - try: - return float(value) - except (TypeError, ValueError): - return None - - -def sessions(): - """One entry per established inbound connection, with its metrics.""" - ports = listening_ports() - if not ports: - return [] - text = run(["ss", "-tinH", "state", "established"]) - if not text: - return [] - found, head = [], None - for line in text.splitlines(): - if not line.startswith(("\t", " ")): - head = line.split() - continue - if head is None or len(head) < 4: - continue - local, peer = head[2], head[3] - try: - lport = int(local.rsplit(":", 1)[1]) - except (ValueError, IndexError): - head = None - continue - peer_ip = peer.rsplit(":", 1)[0].strip("[]") - # ::ffff:10.0.0.1 is an IPv4 address wearing an IPv6 hat - the same - # machine, the same session - so it is unwrapped before anything - # else looks at it. Left wrapped, ::ffff:127.0.0.1 walked straight - # past the loopback filter and put a 22-microsecond local socket on - # the chart, which flattened every real session against the ceiling. - if peer_ip.startswith("::ffff:"): - peer_ip = peer_ip[7:] - if lport not in ports or peer_ip.startswith(("127.", "::1")): - head = None - continue - m = parse_metrics(line) - rtt = (m.get("rtt") or "").split("/") - found.append({ - "peer": "%s:%s" % (peer_ip, peer.rsplit(":", 1)[1]), - "ip": peer_ip, "port": lport, - "rtt": num(rtt[0]) if rtt else None, - "jitter": num(rtt[1]) if len(rtt) > 1 else None, - "floor": num(m.get("minrtt")), - "sent": num(m.get("bytes_sent")) or 0.0, - "recv": num(m.get("bytes_received")) or 0.0, - "retrans_bytes": num(m.get("bytes_retrans")) or 0.0, - "delivery": num(m.get("delivery_rate")), - "cwnd": num(m.get("cwnd")), - "mss": num(m.get("mss")), - "lastsnd": num(m.get("lastsnd")), - "lastrcv": num(m.get("lastrcv")), - "raw": m, - }) - head = None - return found - - -def who(): - """Who is logged in from where, to put a name against an address.""" - seen = {} - for line in run(["who"]).splitlines(): - cols = line.split() - if len(cols) < 2: - continue - host = cols[-1].strip("()") if cols[-1].startswith("(") else "" - if host: - seen.setdefault(host, []).append((cols[0], cols[1])) - return seen - - -def rate(n): - if n is None: - return "--" - for unit, size in (("Gbps", 1e9), ("Mbps", 1e6), ("kbps", 1e3)): - if n >= size: - return "%.1f%s" % (n / size, unit) - return "%dbps" % n - - -def size_of(n): - n = float(n or 0) - for unit, step in (("G", 1e9), ("M", 1e6), ("k", 1e3)): - if n >= step: - return "%.1f%s" % (n / step, unit) - return "%dB" % n - - -def span(ms): - if ms is None: - return "--" - s = ms / 1000.0 - if s < 60: - return "%ds" % s - if s < 3600: - return "%dm" % (s // 60) - if s < 86400: - return "%dh" % (s // 3600) - return "%dd" % (s // 86400) - - -def sparkline(values, n): - """RTT over time, one cell per sample, newest at the right.""" - if not values: - return "" - tail = list(values)[-n:] - hi = max(tail) or 1.0 - return "".join(SPARK[min(7, int(v / hi * 7.99))] for v in tail) - - -class Store(object): - def __init__(self): - self.lock = threading.Lock() - self.rows = [] - self.names = {} - self.error = None - self.fetched = 0 - self.wake = threading.Event() - self.history = collections.defaultdict( - lambda: collections.deque(maxlen=HISTORY)) - self.last = {} - - def snapshot(self): - with self.lock: - return (list(self.rows), dict(self.names), - {k: list(v) for k, v in self.history.items()}, - self.fetched, self.error) - - def run(self): - # A daemon thread that raises just stops, and a dead poller looks - # exactly like a machine with nobody connected to it. - try: - self.poll() - except Exception as e: - with self.lock: - self.error = "poller stopped: %s: %s" % (type(e).__name__, - str(e)[:70]) - - def poll(self): - while True: - rows = sessions() - names = who() - for row in rows: - key = row["peer"] - if row["rtt"] is not None: - self.history[key].append(row["rtt"]) - # Retransmits since the last look, rather than since the - # connection opened: a session hours old has long since - # forgiven whatever went wrong at breakfast. - prev = self.last.get(key) - if prev: - d_sent = row["sent"] - prev["sent"] - d_retrans = row["retrans_bytes"] - prev["retrans_bytes"] - row["recent_loss"] = (100.0 * d_retrans / d_sent - if d_sent > 0 else 0.0) - row["moved"] = d_sent + (row["recv"] - prev["recv"]) - self.last[key] = dict(row) - row["spark"] = sparkline(self.history[key], 0) or "" - with self.lock: - self.rows = rows - self.names = names - self.fetched = time.time() - self.error = None if rows else self.error - self.wake.wait(REFRESH) - self.wake.clear() - - -def quality(row): - """How much worse than this path's best the connection is right now. - - Compared against the socket's own minrtt rather than a fixed threshold: - forty milliseconds is excellent from Hong Kong and poor from the next - rack, and the kernel already knows which this is. - """ - rtt, floor = row.get("rtt"), row.get("floor") - if not rtt or not floor: - return None - return rtt / floor - - -def colour_for(ratio, loss): - if loss is not None and loss >= 2.0: - return BAD - if ratio is None: - return DIM - if ratio >= 3.0 or (loss or 0) >= 0.5: - return BAD - if ratio >= 1.6: - return WARN - return OK - - -SERIES = "●▲■◆✚✦" # one glyph per session, so the plot reads mono - - -def window_label(seconds): - """A span as a person says it: 90s, 5m, 1h.""" - if seconds < 60: - return "%ds" % seconds - if seconds < 3600: - return "%gm" % round(seconds / 60.0, 1) - return "%gh" % round(seconds / 3600.0, 1) - - -def condense(vals, columns): - """Fit a run of samples to the columns available, by median. - - A fifteen-minute window at a two-second poll is 450 readings and a pane - is eighty columns wide, so something has to give. The median of each - bucket is the typical round-trip over that slice, which is what a line - should show; the worst of it is still in the table and the detail view, - which report the peak rather than the middle. - """ - if len(vals) <= columns or columns < 1: - return vals - out = [] - for i in range(columns): - chunk = vals[int(i * len(vals) / columns): - int((i + 1) * len(vals) / columns)] - if chunk: - ordered = sorted(chunk) - out.append(ordered[len(ordered) // 2]) - return out - - -def in_window(history, peer, window, columns): - """One session's samples, cut to the chosen span and to the pane.""" - vals = list(history.get(peer) or []) - if window: - vals = vals[-max(1, int(round(window / REFRESH))):] - else: - vals = vals[-columns:] - return condense(vals, columns) - - -def plotted_span(rows, history, window, columns): - """How much time the drawn columns actually cover, for the axis label.""" - longest = max([len(history.get(r["peer"]) or []) for r in rows] or [0]) - if window: - longest = min(longest, int(round(window / REFRESH))) - return longest * REFRESH - - -def build_graph(rows, history, gw, gh, start=0, window=0): - """Log-scale multi-series plot of round-trip time. - - Log because the sessions on one machine can differ by two orders of - magnitude - a laptop on the same continent and a phone on the other side - of it - and a linear axis renders the near one as a flat line at the - bottom. One column per sample rather than per second: this widget's - samples are whatever the kernel had at each poll, and pretending to a - finer time grid would be inventing resolution. - """ - lo = hi = None - series = [] - for i, row in enumerate(rows): - vals = in_window(history, row["peer"], window, gw) - if not vals: - continue - # `start` keeps a session's glyph and hue the same on its own screen - # as in the list: opening the ▲ row and finding a ● chart reads as a - # different connection. - series.append((start + i, vals)) - lo = min(vals) if lo is None else min(lo, min(vals)) - hi = max(vals) if hi is None else max(hi, max(vals)) - if lo is None: - return [seg([(DIM, " collecting…")], gw)], None, None - lo = max(0.05, lo * 0.8) - hi = max(hi * 1.25, lo * 1.6) - import math - llo, lhi = math.log10(lo), math.log10(hi) - - grid = [[" "] * gw for _ in range(gh)] - tone = [[None] * gw for _ in range(gh)] - - def row_of(v): - frac = (math.log10(max(v, 1e-3)) - llo) / (lhi - llo) - return int(round((1.0 - frac) * (gh - 1))) - - for idx, vals in series: - glyph = SERIES[idx % len(SERIES)] - colour = SESSION_HUES[idx % len(SESSION_HUES)] - start = gw - len(vals) - prev = None - for x, v in enumerate(vals): - y = row_of(v) - col = start + x - if prev is not None and abs(prev - y) > 1: - # join consecutive samples so a series reads as a trace - for fill in range(min(prev, y) + 1, max(prev, y)): - if grid[fill][col] == " ": - grid[fill][col] = "│" - tone[fill][col] = colour - if 0 <= col < gw and 0 <= y < gh: - grid[y][col] = glyph - tone[y][col] = colour - prev = y - return grid, tone, (lo, hi) - - -def graph_rows(rows, history, w, h, start=0, window=0): - gw = max(10, w - 9) - gh = max(4, h) - grid, tone, bounds = build_graph(rows, history, gw, gh, start, window) - if bounds is None: - return grid - import math - lo, hi = bounds - llo, lhi = math.log10(lo), math.log10(hi) - out = [] - for y, line in enumerate(grid): - frac = 1.0 - (y / float(max(1, gh - 1))) - value = 10 ** (llo + frac * (lhi - llo)) - # label only the top, middle and bottom: a number on every row is a - # table pretending to be an axis - label = ("%7s" % ms(value)) if y in (0, gh // 2, gh - 1) else " " * 7 - parts = [(DIM, label), (GRID, "│")] - for x, ch in enumerate(line): - parts.append((tone[y][x] or GRID, ch)) - out.append(seg(parts, w - 1)) - return out - - -def ms(v): - if v >= 100: - return "%dms" % round(v) - if v >= 10: - return "%.0fms" % v - if v >= 1: - return "%.1fms" % v - return "%dµs" % round(v * 1000) - - -def table_rows(rows, names, history, w, selected): - """One line per session: what it is, and how it is behaving.""" - wide = w >= 74 - out = [seg([(DIM, " PEER"), (DIM, " " * 14), - (DIM, " NOW FLOOR JITTER LOSS"), - (DIM, " ACHIEVED" if wide else ""), - (DIM, " IDLE" if wide else "")], w - 1)] - for i, row in enumerate(rows): - here = i == selected - tint = bg(28, 44, 62) if here else "" - ratio = quality(row) - loss = row.get("recent_loss") - tone = colour_for(ratio, loss) - users = names.get(row["ip"]) or [] - who_txt = users[0][0] if users else "" - idle = min([x for x in (row.get("lastsnd"), row.get("lastrcv")) - if x is not None] or [None]) - label = row["ip"] + (" %s" % who_txt if who_txt and wide else "") - line = [(tint + SESSION_HUES[i % len(SESSION_HUES)], - SERIES[i % len(SERIES)] + " "), - (tint + (TXT if here else DIM), pad(label, 18)), - (tint + tone, "%7s" % ms(row["rtt"]) if row["rtt"] else " --"), - (tint + DIM, "%8s" % ms(row["floor"]) if row["floor"] else " --"), - (tint + DIM, "%8s" % ms(row["jitter"]) if row["jitter"] else " --"), - (tint + (BAD if (loss or 0) >= 0.5 else DIM), - "%7s" % ("%.2f%%" % loss if loss is not None else "--"))] - if wide: - line.append((tint + DIM, "%10s" % rate(row.get("delivery")))) - line.append((tint + DIM, "%7s" % span(idle))) - if here: - line.append((tint, " " * w)) - out.append(seg(line, w - 1)) - return out - - -def fit(w, base, options): - """Build a line from a required head plus optional parts, longest first. - - Each option is (short, long): the long form is taken when the whole line - still fits, otherwise the short one, otherwise nothing. Width thresholds - were doing this by eye and getting it wrong - the numbers on this line - vary in length, so a threshold tuned at one pane size clipped "idle 0s" - into "idle 0" at another. - """ - parts = list(base) - - def width(extra): - return sum(len(t) for t, _c in parts + extra) - - for i, (short, long) in enumerate(options): - # Whatever is still to come gets its shortest form reserved before - # this one is allowed to take its longest. Without that, a middle - # option spent the width on "segments" and pushed the idle time off - # the end - dropping a fact to spell out a unit. - rest = sum(len(t) for nxt, _l in options[i + 1:] for t, _c in (nxt or [])) - for candidate in (long, short): - if candidate and width(candidate) + rest <= w - 1: - parts.extend(candidate) - break - return seg([(colour, text) for text, colour in parts], w - 1) - - -def detail_rows(row, names, w, selected=False, hue=None, glyph="●"): - """The selected session in full: who, how much, and how it is going. - - The table above answers "is anything wrong"; this answers "with what". - Lifetime loss lives here rather than in the table because it is a fact - about the whole session and changes by the hour, while the table's loss - column is about the last two seconds. - """ - # `who` maps logins to an address, not to a socket, and two SSH sessions - # from one laptop share the address. Naming both against each socket read - # as "this connection is pts/0 and pts/35", which it is not - so the - # ttys are labelled as what they are: the logins from that address. - users = names.get(row["ip"]) or [] - label = "" - if users: - label = "%s · login%s %s" % ( - users[0][0], "" if len(users) == 1 else "s", - ", ".join(t for _u, t in users[:3])) - lifetime = (100.0 * row["retrans_bytes"] / row["sent"] - if row["sent"] else 0.0) - idle = min([x for x in (row.get("lastsnd"), row.get("lastrcv")) - if x is not None] or [None]) - tint = bg(28, 44, 62) if selected else "" - head = fit(w, [(" " + glyph + " ", tint + (hue or LBL)), - (row["ip"], tint + TXT)], - [([(" · port %d" % row["port"], tint + DIM)], None), - ([(" " + users[0][0], tint + DIM)] if users else [], - [(" " + label, tint + DIM)] if label else [])]) - return [head, - seg([(DIM, " sent "), (TXT, size_of(row["sent"])), - (DIM, " · received "), (TXT, size_of(row["recv"])), - (DIM, " · achieved "), (TXT, rate(row.get("delivery")))], - w - 1), - # Built shortest-first and grown while it fits, rather than - # trimmed by width thresholds: the numbers vary in length, so a - # threshold that held at one window size cut "idle 0s" to - # "idle 0" at another. - fit(w, [(" retransmitted ", DIM), ("%.2f%%" % lifetime, TXT)], - [([(" lifetime", DIM)], [(" over the session", DIM)]), - ([(" · flight ", DIM), - ("%.0f" % row["cwnd"] if row["cwnd"] else "--", TXT)], - [(" · up to ", DIM), - ("%.0f" % row["cwnd"] if row["cwnd"] else "--", TXT), - (" packets in flight", DIM)]), - ([(" · idle ", DIM), (span(idle), TXT)], None)])] - - -def detail_view(row, names, history, w, h, idx=0, window=0): - """One connection, in full. - - The list answers "is anything wrong"; this answers "with what, and how - badly". Everything here is a number the kernel already keeps for this - socket - nothing is derived beyond the two percentages, and both say - what they are measured over. - """ - raw = row.get("raw") or {} - users = names.get(row["ip"]) or [] - rows = [title("connection", w, LINK)] - rows.append(seg([(SESSION_HUES[idx % len(SESSION_HUES)], - " " + SERIES[idx % len(SERIES)] + " "), - (TXT, row["ip"]), - (DIM, " · port %d" % row["port"]), - (DIM, (" " + users[0][0]) if users else "")], w - 1)) - if users: - rows.append(seg([(DIM, " logins from this address: "), - (TXT, ", ".join(t for _u, t in users))], w - 1)) - rows.append("") - - def field(label, value, colour=TXT, note=""): - if value in (None, "", "--"): - return - rows.append(seg([(DIM, " %-16s" % label), (colour, str(value)), - (DIM, " " + note if note else "")], w - 1)) - - ratio = quality(row) - field("round trip", ms(row["rtt"]) if row["rtt"] else None, - colour_for(ratio, row.get("recent_loss")), - "%.1fx this path's best" % ratio if ratio else "") - field("best ever", ms(row["floor"]) if row["floor"] else None, DIM, - "the floor; the gap above it is congestion") - field("jitter", ms(row["jitter"]) if row["jitter"] else None, DIM, - "variation in the round trip") - field("timeout", ms(num(raw.get("rto"))) if raw.get("rto") else None, DIM, - "how long before a lost packet is resent") - rows.append("") - - lifetime = (100.0 * row["retrans_bytes"] / row["sent"] - if row["sent"] else 0.0) - loss = row.get("recent_loss") - field("loss just now", "%.2f%%" % loss if loss is not None else None, - BAD if (loss or 0) >= 0.5 else TXT, "resent since the last look") - field("loss lifetime", "%.2f%%" % lifetime, DIM, - "%s resent of %s" % (size_of(row["retrans_bytes"]), - size_of(row["sent"]))) - field("reordering", raw.get("reord_seen"), DIM, - "times packets arrived out of order") - rows.append("") - - field("sent", size_of(row["sent"]), TXT) - field("received", size_of(row["recv"]), TXT) - field("achieved", rate(row.get("delivery")), TXT, - "what it has delivered, not its capacity") - field("pacing at", rate(num(raw.get("pacing_rate"))), DIM, - "the rate the kernel is willing to send at") - field("in flight", raw.get("cwnd"), DIM, - "packets allowed unacknowledged at once") - field("packet size", "%s bytes" % raw["mss"] if raw.get("mss") else None, - DIM) - idle = min([x for x in (row.get("lastsnd"), row.get("lastrcv")) - if x is not None] or [None]) - field("idle", span(idle), DIM, "since anything crossed either way") - rows.append("") - - room = h - len(rows) - 4 - if room >= 5: - rows.extend(graph_rows([row], history, w, room, idx, window)) - rows.append(seg([(DIM, " " * 7), - (GRID, "└" + "─" * max(10, w - 9))], w - 1)) - oldest = plotted_span([row], history, window, max(10, w - 9)) - rows.append(seg([(DIM, " %s ago" % span(oldest * 1000)), - (DIM, " " * max(1, w - 26)), (DIM, "now")], w - 1)) - return rows - - -def main(): - maybe_help(__doc__) - global REFRESH - args = sys.argv[1:] - while args and args[0] in ("-n", "--refresh"): - REFRESH = max(0.5, float(args[1])) - args = args[2:] - - if not run(["ss", "-V"]): - cannot_start( - "connections", ["ss"], - ["ss reads the kernel's own per-socket metrics, which is where", - "every figure here comes from: round-trip time, retransmits,", - "delivery rate. Nothing else on the machine reports them.", - "", - "It ships in iproute2, which is installed on essentially every", - "Linux system - its absence usually means a very small container", - "image rather than a missing package."], - "apt install iproute2") - - setup() - keyboard = Keyboard() - store = Store() - threading.Thread(target=store.run, daemon=True).start() - selected, hide_idle, tick, view = 0, False, 0, None - span_at = 0 # which of WINDOWS the chart is currently drawn over - - while True: - tick += 1 - for key in keyboard.poll(): - if key in ("q", "Q"): - raise SystemExit(0) - if key in ("up", "k"): - selected -= 1 - elif key in ("down", "j"): - selected += 1 - elif key in ("enter", "i"): - view = None if view else "detail" - elif key == "esc": - view = None - elif key == "o": - hide_idle = not hide_idle - elif key in ("w", "W"): - span_at = (span_at + 1) % len(WINDOWS) - elif key == "r": - store.wake.set() - - w, h = size() - rows_all, names, history, fetched, err = store.snapshot() - shown = [r for r in rows_all - if not (hide_idle and (r.get("lastrcv") or 0) > IDLE_AFTER * 1000)] - selected = max(0, min(selected, len(shown) - 1)) if shown else 0 - - # One connection in full, on its own screen. The list is for - # noticing; this is for looking into, and the two want different - # amounts of room for the same chart. - window = WINDOWS[span_at] - if view and shown: - pick = min(selected, len(shown) - 1) - # The footer is measured before the body is built, and the body - # is told the height it actually has. Appending the hints after - # sizing the chart to the whole pane pushed them off the bottom - # of it - the keys out of this screen were the rows being lost. - foot = [" " + line for line in - pack_hints([[(DIM, "[esc] back")], - [(ACCENT, "[w]"), - (DIM, " %s" % window_label(window))], - [(DIM, "[r]efresh")], - [(DIM, "[q]uit")]], w - 2)] - room = max(1, h - len(foot) - 1) - body = detail_view(shown[pick], names, history, w, room, pick, - window) - while len(body) < room: - body.append("") - draw(body[:room] + foot, w, h) - time.sleep(0.2) - continue - - rows = [title("connections", w, LINK)] - rows.append(seg([(DIM, " %d inbound" % len(rows_all)), - (DIM, " · measured by the kernel, nothing sent"), - (DIM, " every %gs" % REFRESH)], w - 1)) - if err: - rows.append(seg([(BAD, " ! " + err)], w - 1)) - rows.append("") - - if not rows_all: - rows.append(seg([(DIM, " No inbound sessions on a listening" - " port.")], w - 1)) - rows.append(seg([(DIM, " Nothing is connected to this machine," - " or `ss` cannot see it.")], w - 1)) - else: - rows.extend(table_rows(shown, names, history, w, selected)) - rows.append("") - room = h - len(rows) - 4 - if room >= 5: - rows.extend(graph_rows(shown, history, w, room, 0, window)) - rows.append(seg([(DIM, " " * 7), - (GRID, "└" + "─" * max(10, w - 9))], w - 1)) - oldest = plotted_span(shown, history, window, - max(10, w - 9)) - rows.append(seg([(DIM, " %s ago" % span(oldest * 1000)), - (DIM, " " * max(1, w - 26)), - (DIM, "now")], w - 1)) - - while len(rows) < h - 2: - rows.append("") - hints = [[(ACCENT, "↑↓"), (DIM, " select")], - [(DIM, "[↵] open")], - [(ACCENT, "[w]"), (DIM, " %s" % window_label(window))], - [(DIM, "[o]%s idle" % ("show" if hide_idle else "hide"))], - [(DIM, "[r]efresh")], [(DIM, "[q]uit")]] - for line in pack_hints(hints, w - 2): - rows.append(" " + line) - draw(rows, w, h) - time.sleep(0.3) - - -main() diff --git a/matrix.py b/matrix.py deleted file mode 100755 index 13a85be..0000000 --- a/matrix.py +++ /dev/null @@ -1,101 +0,0 @@ -#!/usr/bin/env python3 -# terminal-toys - small dependency-free terminal widgets -# Copyright (C) 2026 William Li -# -# This program is free software: you can redistribute it and/or modify -# it under the terms of the GNU Affero General Public License as published -# by the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU Affero General Public License for more details. -# -# You should have received a copy of the GNU Affero General Public License -# along with this program. If not, see <https://www.gnu.org/licenses/>. -"""Digital rain. - -Falling glyphs with truecolor fade trails: near-white head, bright green -shoulder, and a smooth decay over each drop's length. Glyphs mutate in place -independently of the drops, and the field reflows on terminal resize. - - python3 matrix.py -""" -import os -import random -import sys -import time - -sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) -from common import RST, draw, maybe_help, rgb, setup, size - -GLYPHS = "ｱｲｳｴｵｶｷｸｹｺｻｼｽｾｿﾀﾁﾂﾃﾄﾅﾆﾇﾈﾉﾊﾋﾌﾍﾎﾏﾐﾑﾒﾓﾔﾕﾖﾗﾘﾙﾚﾛﾜﾝ0123456789ABCDEF<>*+=$#%&@" - -HEAD = rgb(210, 255, 225) -NEAR = rgb(120, 255, 170) - - -def shade(level): - # level 0..1 (1 = closest to head) - g = int(60 + 175 * level) - return rgb(int(10 + 20 * level), g, int(30 + 50 * level)) - - -def new_drop(h): - return [-random.uniform(0, h * 1.5), random.uniform(0.25, 1.15), - random.randint(max(4, h // 5), max(6, h))] - - -def main(): - maybe_help(__doc__) - setup() - w, h = size() - chars = [[random.choice(GLYPHS) for _ in range(w)] for _ in range(h)] - drops = [new_drop(h) for _ in range(w)] - while True: - nw, nh = size() - if (nw, nh) != (w, h): - w, h = nw, nh - chars = [[random.choice(GLYPHS) for _ in range(w)] for _ in range(h)] - drops = [new_drop(h) for _ in range(w)] - level = [[0.0] * w for _ in range(h)] - for x, d in enumerate(drops): - y, speed, ln = d - d[0] = y + speed - if y - ln > h: - drops[x] = new_drop(h) - continue - hy = int(y) - for i in range(ln): - yy = hy - i - if 0 <= yy < h: - level[yy][x] = max(level[yy][x], 1.0 - i / float(ln)) - for _ in range(max(6, (w * h) // 90)): - chars[random.randrange(h)][random.randrange(w)] = random.choice(GLYPHS) - - rows = [] - for y in range(h): - parts = [] - last = None - lv = level[y] - cs = chars[y] - for x in range(w): - v = lv[x] - if v <= 0.02: - if last is not None: - parts.append(RST) - last = None - parts.append(" ") - continue - col = HEAD if v > 0.985 else (NEAR if v > 0.9 else shade(v)) - if col != last: - parts.append(col) - last = col - parts.append(cs[x]) - rows.append("".join(parts)) - draw(rows, w, h) - time.sleep(0.07) - - -main() diff --git a/netwatch.py b/netwatch.py deleted file mode 100755 index 6e7e2d7..0000000 --- a/netwatch.py +++ /dev/null @@ -1,1427 +0,0 @@ -#!/usr/bin/env python3 -# terminal-toys - small dependency-free terminal widgets -# Copyright (C) 2026 William Li -# -# This program is free software: you can redistribute it and/or modify -# it under the terms of the GNU Affero General Public License as published -# by the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU Affero General Public License for more details. -# -# You should have received a copy of the GNU Affero General Public License -# along with this program. If not, see <https://www.gnu.org/licenses/>. -"""Which processes are using the network, how much, and how fast. - -`nettop` answers this on macOS and has no equivalent here. What Linux does -have is the kernel's own per-socket accounting: `ss -tine` reports bytes_sent -and bytes_received for every TCP socket along with its inode, and the inode -appears in /proc/<pid>/fd, which is what ties bytes to a process. No packet -capture, no kernel module, no root. - - python3 netwatch.py [-i SECONDS] [-n COUNT] [--sort total|live] - [--external] [--plain] - -Only traffic that leaves the machine is counted. Loopback is excluded, and so -is any connection to one of this machine's own addresses - talking to your own -10.x or tailnet address never reaches a wire, however external it looks in the -socket table. --external is the narrower question of internet-only, and drops -the local network and the tailnet too. - -Totals start at zero: the first sample is a baseline and only what happens -after it is counted. A process that exits keeps what it used, marked so, since -"what has been eating the connection" is usually asked after the thing has -stopped. - -TCP only, which is the honest limit of this method - see docs/netwatch.md. - -Enter opens one process: its command, every connection it holds separately, -and the files it currently has open with how fast each is growing - which is -the closest thing to "which file is it downloading" that exists outside the -encrypted stream. The URL and the remote filename are inside TLS and are not -readable from here by any means. - -Keys: up/down select, enter opens one, esc goes back, 1 sorts by total, -2 by current rate, o shows the daemons you do not own, r rezeroes, -q quits. -""" -import collections -import json -import os -import re -import socket -import subprocess -import sys -import threading -import time - -sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) -from common import (Keyboard, bg, cannot_start, clipboard, draw, load_config, - maybe_help, missing, pack_hints, pad, rgb, seg, setup, - size, title) - -_CFG = load_config("netwatch", { - "interval": 1.0, - "limit": 0, # 0 fills the pane - "sort": "total", - "external": True, - # Only processes you own. Everything else is the machine's own daemons - - # tailscaled, a cloud guest agent, sshd - which are traffic you did not - # ask for and cannot do anything about. - "mine": True, -}) - -INTERVAL = max(0.2, float(_CFG["interval"])) -# Samples kept for the chart. Wider than any pane, so the graph is a window -# on to real history rather than exactly as much as happened to fit. -SERIES = 240 -LIMIT = int(_CFG["limit"]) -SORT = _CFG["sort"] if _CFG["sort"] in ("total", "live") else "total" -# Strict by default: a connection counts only when the other end is a -# globally routable address. The LAN, the tailnet and the machine's own -# addresses are all somewhere other than the internet, and "what is this box -# sending out" is almost always the question being asked. -EXTERNAL = bool(_CFG["external"]) -MINE = bool(_CFG["mine"]) -VERSION = "1.1" -PLAIN = False - -OK = rgb(90, 240, 160) -WARN = rgb(255, 200, 90) -BAD = rgb(255, 100, 110) -DIM = rgb(127, 147, 172) -GRID = rgb(60, 78, 98) -TXT = rgb(225, 235, 245) -LBL = rgb(130, 165, 200) -ACCENT = rgb(150, 210, 255) -DOWN = rgb(120, 200, 255) -UP = rgb(255, 170, 120) - -INO = re.compile(r"\bino:(\d+)") -CGROUP = re.compile(r"\bcgroup:(\S+)") -SENT = re.compile(r"\bbytes_sent:(\d+)") -RECV = re.compile(r"\bbytes_received:(\d+)") -# 10/8, 172.16/12, 192.168/16, 169.254/16 and Tailscale's 100.64/10 are all -# somewhere other than the internet. -PRIVATE = re.compile(r"^(10\.|192\.168\.|169\.254\.|172\.(1[6-9]|2\d|3[01])\.|" - r"100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\.)") -UNATTRIBUTED = "(unattributed)" -# Systemd names the slice, not the thing in it. -SLICES = ("system.slice", "user.slice", "init.scope", "-.slice", "app.slice") - - -def unit_name(cgroup): - """Who owns a socket, from the cgroup the kernel already reports. - - Another user's /proc is closed, but `ss` prints the control group for - every socket regardless, and on a systemd machine that names the unit: - /system.slice/tailscaled.service is tailscaled however unreadable its - /proc happens to be. This is the difference between a row saying - "(unattributed)" and a row saying which daemon it is. - """ - for part in reversed((cgroup or "").strip("/").split("/")): - if not part or part in SLICES: - continue - for suffix in (".service", ".scope", ".slice"): - if part.endswith(suffix): - part = part[:-len(suffix)] - break - # A login session is a person, not a program, and says nothing - # useful about what opened the socket. - if part.startswith("session-") or part.startswith("user-"): - continue - return part - return "" - - -def run(args): - try: - out = subprocess.run(args, capture_output=True, text=True, timeout=5) - except (OSError, subprocess.SubprocessError): - return "" - return out.stdout if out.returncode == 0 else "" - - -def units(n): - """Decimal units, as network equipment and ISPs quote them.""" - n = float(n) - for suffix, scale in (("GB", 1e9), ("MB", 1e6), ("KB", 1e3)): - if n >= scale: - return "%.1f %s" % (n / scale, suffix) - return "%d B" % n - - -def rate(n): - return units(n) + "/s" if n else "-" - - -def elapsed(seconds): - seconds = int(seconds) - if seconds < 60: - return "%ds" % seconds - if seconds < 3600: - return "%dm %02ds" % (seconds // 60, seconds % 60) - return "%dh %02dm" % (seconds // 3600, (seconds % 3600) // 60) - - -def host_of(addr): - """The address out of ss's `addr:port`, brackets stripped from IPv6.""" - host, _, _ = addr.rpartition(":") - return host.strip("[]") - - -_OWN = {"at": 0.0, "addrs": set()} - - -def own_addresses(): - """Every address this machine answers to, refreshed occasionally. - - A connection to one of our own addresses is turned around inside the - kernel and never reaches a wire, so it is not traffic leaving the - machine even though the address is not loopback. Interfaces come and go - - a tailnet address arrives when tailscaled starts, a bridge when a - container does - so this is re-read periodically rather than once. - """ - now = time.time() - if _OWN["addrs"] and now - _OWN["at"] < 30: - return _OWN["addrs"] - found = set() - try: - data = json.loads(run(["ip", "-j", "addr"]) or "[]") - except ValueError: - data = [] - for link in data: - for addr in link.get("addr_info") or []: - if addr.get("local"): - found.add(addr["local"]) - if found: - _OWN["addrs"] = found - _OWN["at"] = now - return _OWN["addrs"] - - -def port_of(addr): - _, _, port = addr.rpartition(":") - try: - return int(port) - except ValueError: - return 0 - - -def service(port): - """What a port number is conventionally for, from /etc/services.""" - if not port: - return "" - try: - return socket.getservbyport(port) - except (OSError, TypeError): - return "" - - -def local_peer(host): - """Whether this traffic never leaves the machine. - - Loopback is the obvious half. The other is a connection to one of this - machine's own addresses - 10.x to itself, or its own tailnet address - - which looks external in the socket table and is not: the kernel routes - it back up the stack without a packet ever reaching an interface. - """ - if (host.startswith("127.") or host in ("::1", "*", "") - or host.startswith("::ffff:127.")): - return True - bare = host[7:] if host.startswith("::ffff:") else host - return bare in own_addresses() - - -def off_box(host): - """Whether a peer is out on the internet rather than nearby.""" - if local_peer(host): - return False - if host.startswith("::ffff:"): - host = host[7:] - return not (PRIVATE.match(host) or host.startswith("fd7a:115c:a1e0") - or host.startswith("fe80:") or host.startswith("fc") - or host.startswith("fd")) - - -def sockets(external=False): - """Every TCP socket's byte counters, keyed by inode. - - -i for the counters, -e for the inode. Without the inode there is no - honest way to reach the process: `ss -p` needs root to name anybody - else's, while /proc/<pid>/fd needs nothing to name our own. - """ - try: - out = subprocess.run(["ss", "-tine"], capture_output=True, text=True, - timeout=5) - except (OSError, subprocess.SubprocessError): - return {}, "ss would not run" - found = {} - inode, peer, port, cgroup, header = None, "", 0, "", True - for line in out.stdout.splitlines(): - if header: - header = False - continue - # A socket is two lines: the addresses and inode, then the counters - # on an indented continuation. Neither is usable without the other. - if not line.startswith((" ", "\t")): - cols = line.split() - peer = host_of(cols[4]) if len(cols) > 4 else "" - port = port_of(cols[4]) if len(cols) > 4 else 0 - seen = INO.search(line) - inode = seen.group(1) if seen else None - unit = CGROUP.search(line) - cgroup = unit.group(1) if unit else "" - # ino:0 is a socket with no inode to own it - a TIME-WAIT - # remnant, say. It cannot be attributed, and worse, every one of - # them shares the key, so they would be merged into a single - # entry whose counters jump about and manufacture deltas. - if inode == "0": - inode = None - continue - if inode is None: - continue - if local_peer(peer) or (external and not off_box(peer)): - inode = None - continue - sent, recv = SENT.search(line), RECV.search(line) - found[inode] = {"sent": int(sent.group(1)) if sent else 0, - "recv": int(recv.group(1)) if recv else 0, - "peer": peer, "port": port, "cgroup": cgroup} - inode = None - return found, "" - - -# Directory names that identify nothing: a binary living under one of these -# is named by whatever encloses it. -GENERIC = {"versions", "bin", "sbin", "libexec", "node_modules", "dist", - "build", "lib", "share", "local", ".local", "current", "releases"} -HAS_LETTER = re.compile(r"[A-Za-z]") - - -def process_name(pid): - """What to call a process, preferring something a person would recognise. - - /proc/<pid>/comm is the kernel's answer and usually right, but it is the - executable's own name, and some are versioned - a binary at - .../claude/versions/2.1.233 reports itself as "2.1.233", which is true - and useless. When the name carries no letters at all, the enclosing path - is walked back for one that does and means something. - """ - try: - with open("/proc/%d/comm" % pid) as f: - name = f.read().strip() - except OSError: - name = "" - if name and HAS_LETTER.search(name): - return name - try: - with open("/proc/%d/cmdline" % pid, "rb") as f: - argv0 = f.read().split(b"\x00")[0].decode("utf8", "replace") - except OSError: - argv0 = "" - for part in reversed(argv0.split("/")): - if part and HAS_LETTER.search(part) and part.lower() not in GENERIC: - return part - return name or "?" - - -# Interfaces that are not the wire: loopback, and anything that is a tunnel -# or a bridge rather than a card. A packet forwarded out of one of these -# leaves through a real interface as well, and counting both would count it -# twice. -VIRTUAL = ("lo", "tailscale0", "docker", "veth", "br-", "virbr", "wg", - "tun", "tap", "cni", "flannel", "kube") - - -def wire_bytes(): - """Bytes in and out of this machine's real interfaces. - - The kernel counts these whatever produced them, which is the point: a - packet this machine routes rather than terminates never touches a - socket, so /proc/net/tcp cannot see it and neither can anything built on - it. On an exit node or a subnet router that is most of the traffic. - """ - rx, tx, names = 0, 0, [] - try: - lines = open("/proc/net/dev").read().splitlines()[2:] - except OSError: - return None - for line in lines: - name, _, rest = line.partition(":") - name = name.strip() - if not rest or name.startswith(VIRTUAL): - continue - fields = rest.split() - if len(fields) < 9: - continue - try: - rx += int(fields[0]) - tx += int(fields[8]) - except ValueError: - continue - names.append(name) - return rx, tx, names - - -def wire_label(names): - """Which interfaces are being counted, for the end of the line. - - The line is called "interfaces" because that is what it is. Naming them - as well answers "which?" - a real question here, tailscale0 being - deliberately absent - and is dropped first when the pane is narrow. - """ - if not names: - return "" - if len(names) <= 3: - return ", ".join(names) - return "%d of them" % len(names) - - -def socket_owners(): - """inode -> (pid, name), for every process this user can read. - - Another user's /proc/<pid>/fd is unreadable, so their sockets arrive - unowned. Their bytes are still counted, under one row that says so: - dropping them would make the total quietly wrong. - """ - owners = {} - for pid in os.listdir("/proc"): - if not pid.isdigit(): - continue - try: - fds = os.listdir("/proc/%s/fd" % pid) - except OSError: - continue - name = "" - for fd in fds: - try: - target = os.readlink("/proc/%s/fd/%s" % (pid, fd)) - except OSError: - continue - if not target.startswith("socket:["): - continue - if not name: - name = process_name(int(pid)) - owners[target[8:-1]] = (int(pid), name or "?") - return owners - - -_NAMES = {} -_WANTED = collections.deque() -_ASKED = set() - - -def resolver(): - """Reverse DNS, off the drawing thread. - - A PTR lookup takes half a second when it works and longer when it does - not, which is several frames. The address is shown until a name arrives, - and an address that has no name is remembered as having none so it is - not asked about again every second. - """ - while True: - try: - ip = _WANTED.popleft() - except IndexError: - time.sleep(0.3) - continue - try: - _NAMES[ip] = socket.gethostbyaddr(ip)[0] - except (OSError, socket.herror, socket.gaierror): - _NAMES[ip] = "" - - -def hostname(ip): - """A name for an address if one is known, queueing a lookup if not.""" - if ip in _NAMES: - return _NAMES[ip] - if ip not in _ASKED: - _ASKED.add(ip) - _WANTED.append(ip) - return "" - - -def running(pid): - """Whether the process still exists. - - Distinct from the `alive` flag on a row, which means "had a socket in - the last sample". A long-running server sitting idle has neither - traffic nor open connections and has certainly not exited, and saying - it had would be worse than saying nothing. - """ - return bool(pid) and os.path.isdir("/proc/%d" % pid) - - -def proc_io(pid): - """Disk bytes this process has read and written, from /proc/<pid>/io.""" - out = {} - try: - with open("/proc/%d/io" % pid) as f: - for line in f: - key, _, value = line.partition(":") - try: - out[key.strip()] = int(value) - except ValueError: - continue - except OSError: - return {} - return out - - -def open_files(pid): - """Regular files this process has open, largest first. - - A download has to land somewhere, and where it lands is a file getting - bigger. This is the closest thing to "which file" that exists outside - the encrypted stream - the name of the thing being written, rather than - the name of the thing being fetched. - """ - found = [] - try: - fds = os.listdir("/proc/%d/fd" % pid) - except OSError: - return found - for fd in fds: - try: - path = os.readlink("/proc/%d/fd/%s" % (pid, fd)) - except OSError: - continue - if not path.startswith("/") or path.startswith(("/dev/", "/proc/", - "/sys/")): - continue - try: - size = os.stat("/proc/%d/fd/%s" % (pid, fd)).st_size - except OSError: - continue - writing = False - try: - with open("/proc/%d/fdinfo/%s" % (pid, fd)) as f: - for line in f: - if line.startswith("flags:"): - writing = int(line.split()[1], 8) & 3 != 0 - except (OSError, ValueError, IndexError): - pass - found.append({"path": path, "size": size, "writing": writing}) - found.sort(key=lambda f: -f["size"]) - return found - - -def process_facts(pid): - """Command, directory and age - what the table has no room for.""" - facts = {"cmdline": "", "cwd": "", "started": None} - try: - with open("/proc/%d/cmdline" % pid, "rb") as f: - facts["cmdline"] = f.read().replace(b"\x00", b" ").decode( - "utf8", "replace").strip() - except OSError: - pass - try: - facts["cwd"] = os.readlink("/proc/%d/cwd" % pid) - except OSError: - pass - try: - facts["started"] = os.stat("/proc/%d" % pid).st_ctime - except OSError: - pass - return facts - - -class Store(object): - """Per-process byte totals, accumulated from per-socket counters. - - The kernel counts per socket, not per process, and a socket's counters - vanish with it. So each sample takes the difference against what that - socket last read and adds it to whatever process owns it - which keeps - the total intact when the socket closes, and when the process does. - """ - - def __init__(self): - self.lock = threading.Lock() - self.wake = threading.Event() - self.totals = collections.OrderedDict() - self.conns = collections.OrderedDict() - self.series = collections.deque(maxlen=SERIES) - self.spots = collections.OrderedDict() - self.last = {} - self.started = time.time() - self.stamp = 0.0 - self.wire = None # last (rx, tx) off the interfaces - self.wire_rate = (0.0, 0.0) - self.wire_names = [] - self.err = "" - self.rezero = False - - def snapshot(self): - with self.lock: - return ([dict(v, key=k) for k, v in self.totals.items()], - self.started, self.err) - - def wire_now(self): - """The interfaces' current rate, in and out, and what they are.""" - with self.lock: - return self.wire_rate + (list(self.wire_names),) - - def rates(self, mine=True): - """Total down and up rate per sample, yours or the whole machine's.""" - with self.lock: - window = list(self.series) - return [(s[0], s[1]) if mine else (s[2], s[3]) for s in window] - - def endpoints(self, pid, name): - """One process's remote hosts, aggregated, busiest first.""" - with self.lock: - found = [dict(s, ports=sorted(s["ports"]), - hist=list(s["hist"])) - for s in self.spots.values() - if s["pid"] == pid and s["name"] == name] - return sorted(found, key=lambda s: (-(s["up"] + s["down"]), - s["peer"])) - - def history(self, pid, name): - """One process's rate history, for its own chart.""" - with self.lock: - row = self.totals.get((pid, name)) - return list(row["hist"]) if row else [] - - def connections(self, pid, name): - """One process's individual connections, busiest first.""" - with self.lock: - found = [dict(c) for c in self.conns.values() - if c["pid"] == pid and c["name"] == name] - return sorted(found, key=lambda c: (-(c["up"] + c["down"]), - c["peer"])) - - def reset(self): - """Make the current counters the new zero. - - Nothing from before the reset may reappear, so the last-seen map is - kept and only the accumulated totals go: the next sample then - differences against counters read before the reset and adds nothing - for traffic that predates it. - """ - with self.lock: - self.totals.clear() - self.conns.clear() - self.spots.clear() - self.series.clear() - self.started = time.time() - - def run(self): - # A daemon thread that raises just stops, and a dead sampler looks - # exactly like a machine using no network at all. - try: - self.poll() - except Exception as exc: - with self.lock: - self.err = "sampler stopped: %s: %s" % (type(exc).__name__, - str(exc)[:70]) - - def poll(self): - while True: - now = time.time() - counters = wire_bytes() - found, err = sockets(EXTERNAL) - owners = socket_owners() if found else {} - gap = max(1e-6, now - self.stamp) if self.stamp else 0.0 - with self.lock: - self.err = err - for row in self.totals.values(): - row["up_rate"] = row["down_rate"] = 0.0 - row["alive"] = False - for conn in self.conns.values(): - conn["up_rate"] = conn["down_rate"] = 0.0 - conn["alive"] = False - for spot in self.spots.values(): - spot["up_rate"] = spot["down_rate"] = 0.0 - spot["alive"] = False - first = not self.stamp - for inode, seen in found.items(): - sent, recv = seen["sent"], seen["recv"] - was = self.last.get(inode) - was = was if was is None else (was["sent"], was["recv"]) - # A socket opened since the last sample started at zero - # when it was created, so all of its counters are traffic - # that happened while we were watching. Only the sockets - # already open at the very first sample are zeroed - the - # difference is a connection that opens and closes inside - # one interval, whose bytes would otherwise never be - # counted at all. - if first: - d_sent = d_recv = 0 - elif was is None: - d_sent, d_recv = sent, recv - # A reused inode reads lower than it did. Taking the - # difference would underflow, so the new socket's own - # figures are used instead. - elif sent < was[0] or recv < was[1]: - d_sent, d_recv = sent, recv - else: - d_sent, d_recv = sent - was[0], recv - was[1] - pid, name = owners.get(inode, (0, "")) - if not name: - name = unit_name(seen.get("cgroup")) or UNATTRIBUTED - key = (pid, name) - row = self.totals.get(key) - if row is None: - row = {"pid": pid, "name": name, "up": 0, "down": 0, - "up_rate": 0.0, "down_rate": 0.0, - "alive": True, "seen": now, - "hist": collections.deque(maxlen=SERIES)} - self.totals[key] = row - row["alive"] = True - row["seen"] = now - row["up"] += d_sent - row["down"] += d_recv - if gap: - row["up_rate"] += d_sent / gap - row["down_rate"] += d_recv / gap - - # The same arithmetic per connection, so the detail - # screen can say which of a process's dozen sockets is - # the one actually moving. - conn = self.conns.get(inode) - if conn is None: - conn = {"pid": pid, "name": name, "peer": seen["peer"], - "port": seen["port"], "up": 0, "down": 0, - "up_rate": 0.0, "down_rate": 0.0, - "alive": True, "seen": now, - "opened": 0 if first else now} - self.conns[inode] = conn - conn["alive"] = True - conn["seen"] = now - conn["up"] += d_sent - conn["down"] += d_recv - if gap: - conn["up_rate"] += d_sent / gap - conn["down_rate"] += d_recv / gap - - # Endpoints aggregate the sockets sharing a peer: a - # browser opening six connections to one host is one - # thing being talked to, not six. - spot = self.spots.setdefault( - (pid, name, seen["peer"]), - {"pid": pid, "name": name, "peer": seen["peer"], - "up": 0, "down": 0, "up_rate": 0.0, - "down_rate": 0.0, "alive": True, "seen": now, - "ports": set(), - "hist": collections.deque(maxlen=SERIES)}) - spot["alive"] = True - spot["seen"] = now - spot["ports"].add(seen["port"]) - spot["up"] += d_sent - spot["down"] += d_recv - if gap: - spot["up_rate"] += d_sent / gap - spot["down_rate"] += d_recv / gap - # What the interfaces actually moved, against what the - # sockets can explain. On a router the two differ by most of - # the traffic, and a widget that only showed the second - # would be quietly answering a different question. - if counters and self.wire and gap: - self.wire_rate = (max(0, counters[0] - self.wire[0]) / gap, - max(0, counters[1] - self.wire[1]) / gap) - if counters: - self.wire = counters[:2] - self.wire_names = counters[2] - - # The whole machine's rate this sample, for the chart. - # Summed from the same per-process figures the table shows, - # so the two can never disagree. - if gap: - self.series.append(( - sum(r["down_rate"] for r in self.totals.values() - if r["pid"]), - sum(r["up_rate"] for r in self.totals.values() - if r["pid"]), - sum(r["down_rate"] for r in self.totals.values()), - sum(r["up_rate"] for r in self.totals.values()))) - for row in self.totals.values(): - row["hist"].append((row["down_rate"], row["up_rate"])) - for spot in self.spots.values(): - spot["hist"].append((spot["down_rate"], - spot["up_rate"])) - self.last = dict(found) - self.stamp = now - # A closed connection is worth keeping - it may be the one - # that did the damage - but not forever. The quiet dead ones - # go once there are enough of them to matter. - if len(self.conns) > 400: - for inode, conn in sorted( - self.conns.items(), - key=lambda kv: kv[1]["seen"])[:100]: - if not conn["alive"]: - self.conns.pop(inode, None) - self.wake.wait(INTERVAL) - self.wake.clear() - - -def ordered(rows, mode): - if mode == "live": - return sorted(rows, key=lambda r: (-(r["up_rate"] + r["down_rate"]), - -(r["up"] + r["down"]))) - return sorted(rows, key=lambda r: (-(r["up"] + r["down"]), - -(r["up_rate"] + r["down_rate"]))) - - -def table(rows, w, limit, selected=-1): - """The process table, dropping columns rather than clipping them. - - Total is the one figure that cannot go: it is the whole question. Then - the combined rate, then the split into down and up, which is a detail - beside knowing something is moving at all. The name keeps a space of its - own so it never runs into the pid. - """ - avail = (w - 1) - 2 - 8 - 11 - wide = avail >= 10 + 11 + 22 - mid = avail >= 10 + 11 - name_w = max(8, min(26, avail - (33 if wide else 11 if mid else 0))) - - head = [(DIM, " " + pad("PROCESS", name_w)), (DIM, "%-8s" % "PID"), - (DIM, "%11s" % "TOTAL")] - if mid: - head.append((DIM, "%11s" % "NOW")) - if wide: - head.append((DIM, "%11s" % "DOWN")) - head.append((DIM, "%11s" % "UP")) - out = [seg(head, w - 1)] - - for i, row in enumerate(rows[:limit]): - live = row["up_rate"] + row["down_rate"] - total = row["up"] + row["down"] - gone = not row["alive"] - here = i == selected - tint = bg(28, 44, 62) if here else "" - line = [(tint + (ACCENT if here else DIM if gone else TXT), - ("▸" if here else " ") + " " - + pad(row["name"][:name_w - 2], name_w - 1)), - (tint + DIM, "%-8s" % (row["pid"] or "-")), - (tint + (TXT if total else DIM), "%11s" % units(total))] - if mid: - line.append((tint + (OK if live else DIM), "%11s" % rate(live))) - if wide: - line.append((tint + (DOWN if row["down_rate"] else DIM), - "%11s" % rate(row["down_rate"]))) - line.append((tint + (UP if row["up_rate"] else DIM), - "%11s" % rate(row["up_rate"]))) - if here: - line.append((tint, " " * w)) - out.append(seg(line, w - 1)) - return out - - -# A braille cell is two dots wide and four tall, so one character holds -# eight addressable points. The bit for each is fixed by the encoding: the -# glyph is U+2800 plus the mask of the dots that are lit. -BRAILLE = ((0x01, 0x08), (0x02, 0x10), (0x04, 0x20), (0x40, 0x80)) - - -def braille_canvas(values, peak, cols, rows, inverted=False): - """Plot a series on a dot canvas eight times finer than the cells. - - Two dots per column and four per row, which is the difference between a - line that steps between character rows and one that reads as a curve. - Consecutive samples are joined with Bresenham rather than left as - points, so a steep climb is a line and not a column of freckles. - """ - px_w, px_h = cols * 2, rows * 4 - grid = [[0] * cols for _ in range(rows)] - vals = list(values)[-px_w:] - if not vals: - return grid - - def point(i): - x = (px_w - 1 if len(vals) == 1 - else int(round(i * (px_w - 1) / float(len(vals) - 1)))) - scaled = min(1.0, max(0.0, vals[i] / peak)) if peak else 0.0 - magnitude = int(round(scaled * (px_h - 1))) - return x, (magnitude if inverted else px_h - 1 - magnitude) - - def dot(x, y): - if 0 <= x < px_w and 0 <= y < px_h: - grid[y // 4][x // 2] |= BRAILLE[y % 4][x % 2] - - if len(vals) == 1: - if vals[0] > 0: - dot(*point(0)) - return grid - for i in range(1, len(vals)): - # An idle stretch draws nothing at all rather than a flat line - # pinned to the axis, which would read as activity at zero. - if vals[i - 1] == 0 and vals[i] == 0: - continue - x0, y0 = point(i - 1) - x1, y1 = point(i) - dx, dy = abs(x1 - x0), -abs(y1 - y0) - sx = 1 if x0 < x1 else -1 - sy = 1 if y0 < y1 else -1 - err = dx + dy - while True: - dot(x0, y0) - if x0 == x1 and y0 == y1: - break - twice = 2 * err - if twice >= dy: - err += dy - x0 += sx - if twice <= dx: - err += dx - y0 += sy - return grid - - -def braille_row(masks, colour): - return [(colour, chr(0x2800 + m) if m else " ") for m in masks] - - -def chart(series, w, h, label="", tint=None): - """Sent above the line, received below it, newest on the right. - - That way round because of the arrows: ↑ means upload and ↓ means - download, so upload has to be the half that goes up. Drawing received - above an arrow pointing down asks the reader to hold two contradictory - directions at once, and they will believe the arrow. - - The two halves are scaled independently and each says what its own peak - is. A shared scale is the obvious choice and the wrong one here: a - download running at ten megabits with acknowledgements going back at - fifty kilobits would draw the upload as a flat nothing, and whether the - upload is flat is often the question. Each label names its own direction - and neither is signed: the lower half is drawn downward, which is a fact - about the drawing rather than about the number. - """ - canvas = max(2, h - 3) - up_h = max(1, canvas // 2) - down_h = max(1, canvas - up_h) - # Sized against the widest label this could need, so the slice does not - # change when the peak's text does. - window = list(series)[-max(12, w - 18) * 2:] - rx = [v[0] for v in window] - tx = [v[1] for v in window] - rx_peak = max(rx or [0]) or 1.0 - tx_peak = max(tx or [0]) or 1.0 - rx_hue, tx_hue = tint or (DOWN, UP) - # The label column is sized to the labels it must hold. A fixed width - # was fine until a peak wanted eleven characters, at which point the - # line grew by one and pushed the frame's closing corner off the edge. - # Each label carries its own direction, so a peak means something on - # its own rather than only in relation to the legend. Neither is - # negative: rx is not negative traffic, it is simply the half drawn - # downward, and a minus sign on it would be a fact about the drawing - # dressed up as a fact about the number. - up_label = "↑ " + rate(tx_peak) - down_label = "↓ " + rate(rx_peak) - lab = min(16, max(9, len(up_label), len(down_label))) - plot = max(12, w - lab - 4) - - out = [seg([(UP, "%*s " % (lab, up_label)), - (GRID, "┌" + "─" * plot + "┐")], w - 1)] - for masks in braille_canvas(tx, tx_peak, plot, up_h): - out.append(seg([(DIM, " " * (lab + 1)), (GRID, "│")] - + braille_row(masks, tx_hue) + [(GRID, "│")], w - 1)) - out.append(seg([(DIM, "%*s " % (lab, "0")), - (GRID, "├" + "─" * plot + "┤")], w - 1)) - for masks in braille_canvas(rx, rx_peak, plot, down_h, inverted=True): - out.append(seg([(DIM, " " * (lab + 1)), (GRID, "│")] - + braille_row(masks, rx_hue) + [(GRID, "│")], w - 1)) - out.append(seg([(DOWN, "%*s " % (lab, down_label)), - (GRID, "└" + "─" * plot + "┘")], w - 1)) - return out - - -def chart_head(series, w, label): - """The line above a chart: what it is, and how far back it reaches.""" - window = list(series) - span = elapsed(len(window) * INTERVAL) if window else "nothing yet" - return seg([(LBL, " ── %s ── " % label), - (UP, "↑ tx above"), (DIM, " · "), (DOWN, "↓ rx below"), - (DIM, " · %s of history" % span)], w - 1) - - -def short(path, room): - """A path that fits, keeping the end - which is the filename.""" - home = os.path.expanduser("~") - if path.startswith(home): - path = "~" + path[len(home):] - if len(path) <= room: - return path - return "…" + path[-(room - 1):] - - -def wrap(text, width): - lines, rest = [], text - while rest and len(lines) < 3: - if len(rest) <= width: - lines.append(rest) - break - cut = rest.rfind(" ", 0, width + 1) - cut = cut if cut > width // 2 else width - lines.append(rest[:cut]) - rest = rest[cut:].lstrip() - return lines or [""] - - -def field(label, value, w, colour=TXT): - out = [] - for i, line in enumerate(wrap(value, max(8, (w - 3) - 10))): - out.append(seg([(DIM, " " + pad(label if not i else "", 10)), - (colour, line)], w - 1)) - return out - - -SECTIONS = ("endpoints", "connections", "files") -# What `c` would put on the clipboard, set while drawing and read when the -# key is pressed - the selection is known in one place and used in another. -pending_copy = [""] - - -def section_head(name, count, note, focused, key, w): - """A section header that says whether it is the one taking the keys.""" - return seg([(ACCENT if focused else LBL, - (" ▏" if focused else " ") + "── %s ── " % name), - (DIM, "%d %s" % (count, note)), - (ACCENT if focused else GRID, " [%s]" % key)], w - 1) - - -def endpoint_rows(spots, at, focused, room, w): - """Remote hosts, ranked by what they have carried since launch.""" - out = [] - host_w = max(14, min(34, (w - 1) - 42)) - for i, spot in enumerate(spots[:max(1, room)]): - here = focused and i == at - name = hostname(spot["peer"]) or spot["peer"] - ports = "/".join(service(p) or str(p) for p in spot["ports"][:2]) - tint = bg(28, 44, 62) if here else "" - out.append(seg([ - (tint + (ACCENT if here else DIM), " ▸ " if here else " "), - (tint + (TXT if spot["alive"] else DIM), pad(name[:host_w - 1], - host_w)), - (tint + DIM, "%-9s" % ports[:9]), - (tint + DOWN, "↓%9s" % units(spot["down"])), - (tint + UP, " ↑%9s" % units(spot["up"])), - (tint + (OK if spot["down_rate"] + spot["up_rate"] else DIM), - "%11s" % rate(spot["down_rate"] + spot["up_rate"])), - (tint, " " * w if here else ""), - ], w - 1)) - return out - - -def connection_rows(conns, at, focused, room, w): - """The sockets open right now, which is a different list from the hosts.""" - out = [] - host_w = max(14, min(38, (w - 1) - 34)) - for i, conn in enumerate(conns[:max(1, room)]): - here = focused and i == at - tint = bg(28, 44, 62) if here else "" - where = "%s:%d" % (conn["peer"], conn["port"]) - out.append(seg([ - (tint + (ACCENT if here else DIM), " ▸ " if here else " "), - (tint + (TXT if conn["alive"] else DIM), pad(where[:host_w - 1], - host_w)), - (tint + (OK if conn["alive"] else DIM), - "%-7s" % ("open" if conn["alive"] else "closed")), - (tint + DOWN, "↓%9s" % units(conn["down"])), - (tint + UP, " ↑%9s" % units(conn["up"])), - (tint, " " * w if here else ""), - ], w - 1)) - return out - - -def file_rows(files, sizes, at, focused, room, w): - """Open files, with how fast each is growing since this screen opened.""" - out = [] - path_w = max(18, (w - 1) - 30) - for i, item in enumerate(files[:max(1, room)]): - here = focused and i == at - tint = bg(28, 44, 62) if here else "" - was = sizes.get(item["path"]) - grew = item["size"] - was[0] if was else 0 - span = time.time() - was[1] if was else 0 - out.append(seg([ - (tint + (ACCENT if here else DIM), " ▸ " if here else " "), - (tint + TXT, pad(short(item["path"], path_w), path_w)), - (tint + DIM, "%10s" % units(item["size"])), - (tint + (OK if grew > 0 else DIM), - "%12s" % (("+" + rate(grew / span)) if grew > 0 and span else "")), - (tint, " " * w if here else ""), - ], w - 1)) - return out - - -def detail_rows(row, hist, spots, conns, files, sizes, focus, at, w, h): - """One process in full: what it is, who it talks to, what it writes.""" - facts = process_facts(row["pid"]) - here_now = running(row["pid"]) - total = row["up"] + row["down"] - out = [title("%s · pid %d" % (row["name"], row["pid"]), w, ACCENT)] - out.append(seg([(TXT, " " + units(total)), - (DIM, " since first seen · "), - (DOWN, "↓ " + rate(row["down_rate"])), (DIM, " "), - (UP, "↑ " + rate(row["up_rate"]))], w - 1)) - if not row["pid"]: - out.append(seg([(DIM, " another user's process - named from its " - "control group, since /proc is closed to us")], - w - 1)) - elif not here_now: - out.append(seg([(WARN, " this process has exited - its total is kept," - " and nothing below is live")], w - 1)) - elif not row["alive"]: - out.append(seg([(DIM, " no connection open at the moment - what is " - "below is the last that was seen")], w - 1)) - out.append("") - - # This process's own traffic, on the same chart as the machine's. - spare = h - len(out) - graph_h = 7 if spare >= 30 else 5 if spare >= 24 else 0 - if graph_h and hist: - out.append(chart_head(hist, w, "THIS PROCESS")) - out.extend(chart(hist, w, graph_h)) - out.append("") - - if h - len(out) >= 12: - out.append(seg([(LBL, " ── PROCESS ── ")], w - 1)) - out += field("command", facts["cmdline"] or "?", w) - if facts["cwd"]: - out += field("directory", short(facts["cwd"], w - 14), w) - out.append("") - - # What is left is split between the three lists, with the focused one - # given the room: it is the one being read, and the others still say - # how much they are holding in their headers. - left = max(3, h - len(out) - 4) - shares = {name: 1 for name in SECTIONS} - shares[focus] = max(1, left - 2 - 3 * 2) - counts = {"endpoints": len(spots), "connections": len(conns), - "files": len(files)} - - for name, key, note in (("TALKING TO", "e", "endpoint"), - ("CONNECTIONS", "tab", "socket"), - ("FILES", "f", "file")): - which = SECTIONS[("TALKING TO", "CONNECTIONS", - "FILES").index(name)] - n = counts[which] - focused = focus == which - out.append(section_head(name, n, note + ("" if n == 1 else "s"), - focused, key, w)) - room = min(shares[which], max(1, h - len(out) - 3)) - if not n: - out.append(seg([(DIM, " none")], w - 1)) - elif which == "endpoints": - out.extend(endpoint_rows(spots, at[which], focused, room, w)) - # The highlighted host gets its own small chart, which is the - # quickest way to see whether it is the one doing the work. - pick = spots[min(at[which], len(spots) - 1)] if spots else None - if focused and pick and pick["hist"] and h - len(out) >= 7: - out.append(seg([(DIM, " ── "), - (ACCENT, hostname(pick["peer"]) - or pick["peer"]), - (DIM, " alone ──")], w - 1)) - out.extend(chart(pick["hist"], w, 4)) - elif which == "connections": - out.extend(connection_rows(conns, at[which], focused, room, w)) - else: - out.extend(file_rows(files, sizes, at[which], focused, room, w)) - out.append("") - - io = proc_io(row["pid"]) if here_now else {} - if io and h - len(out) >= 2: - out.append(seg([(LBL, " ── DISK ── "), - (DIM, "read %s · written %s since it started" - % (units(io.get("read_bytes", 0)), - units(io.get("write_bytes", 0))))], w - 1)) - return out - - -def plain_line(rows, started, mode, limit): - """One block per interval, for a log or a pipe.""" - lines = ["--- %s elapsed · sorted by %s ---" - % (elapsed(time.time() - started), mode)] - for row in rows[:limit]: - lines.append("%-22s %-8s %11s %11s %11s %11s" - % (row["name"], row["pid"] or "-", - units(row["up"] + row["down"]), - rate(row["up_rate"] + row["down_rate"]), - rate(row["down_rate"]), rate(row["up_rate"]))) - return "\n".join(lines) - - -def parse_args(argv): - global INTERVAL, LIMIT, SORT, EXTERNAL, PLAIN, MINE - rest = list(argv) - while rest: - arg = rest.pop(0) - if arg in ("-i", "--interval") and rest: - INTERVAL = max(0.2, float(rest.pop(0))) - elif arg in ("-n", "--limit") and rest: - LIMIT = max(0, int(rest.pop(0))) - elif arg == "--sort" and rest: - want = rest.pop(0) - if want not in ("total", "live"): - sys.stderr.write("--sort takes total or live\n") - raise SystemExit(2) - SORT = want - elif arg == "--external": - EXTERNAL = True - elif arg == "--all-external": - EXTERNAL = False - elif arg == "--all-users": - MINE = False - elif arg in ("-V", "--version"): - print("netwatch.py %s" % VERSION) - raise SystemExit(0) - elif arg == "--plain": - PLAIN = True - else: - sys.stderr.write("unknown option %r - try --help\n" % arg) - raise SystemExit(2) - - -def main(): - global MINE - maybe_help(__doc__) - parse_args(sys.argv[1:]) - absent = missing("ss") - if absent: - cannot_start( - "netwatch", absent, - ["ss reports the per-socket byte counters this is built on:", - "how much each TCP connection has carried, and the inode that", - "ties it to a process. Without it there is nothing to read.", - "", - "It ships in iproute2, which is on essentially every Linux", - "system - its absence usually means a very small container", - "image rather than a missing package."], - "apt install iproute2") - - store = Store() - threading.Thread(target=store.run, daemon=True).start() - mode = SORT - - if PLAIN: - while True: - time.sleep(INTERVAL) - rows, started, err = store.snapshot() - if err: - sys.stderr.write(err + "\n") - if MINE: - rows = [r for r in rows if r["pid"]] - print(plain_line(ordered(rows, mode), started, mode, - LIMIT or len(rows))) - sys.stdout.flush() - - setup() - keyboard = Keyboard() - threading.Thread(target=resolver, daemon=True).start() - selected, detail, sizes = 0, None, {} - focus, at = "endpoints", {k: 0 for k in SECTIONS} - notice = None - while True: - w, h = size() - rows, started, err = store.snapshot() - # A row with no pid is a process we do not own: /proc would not name - # it, which is the same test as "not ours". - if MINE: - rows = [r for r in rows if r["pid"]] - rows = ordered(rows, mode) - - for key in keyboard.poll(): - if detail is not None: - if key in ("esc", "left", "q", "Q", "backspace"): - detail, sizes = None, {} - elif key in ("r", "R"): - store.reset() - detail, sizes = None, {} - elif key in ("up", "k", "K"): - at[focus] -= 1 - elif key in ("down", "j", "J"): - at[focus] += 1 - elif key == "tab": - focus = SECTIONS[(SECTIONS.index(focus) + 1) - % len(SECTIONS)] - elif key in ("e", "E"): - focus = "endpoints" - elif key in ("f", "F"): - focus = "files" - elif key in ("c", "C"): - text = pending_copy[0] - if text: - ok = clipboard(text) - # The value goes in the message either way: OSC 52 - # is refused by some terminals and swallowed by some - # multiplexers, and a copy that quietly did nothing - # would leave nothing on screen to read instead. - notice = (("copied " if ok else "no clipboard ") - + text, OK if ok else WARN, time.time() + 8) - continue - if key in ("q", "Q"): - raise SystemExit(0) - if key == "1": - mode = "total" - elif key == "2": - mode = "live" - elif key in ("up", "k", "K"): - selected -= 1 - elif key in ("down", "j", "J"): - selected += 1 - elif key in ("s", "S", "t", "T"): - mode = "live" if mode == "total" else "total" - elif key in ("o", "O"): - MINE = not MINE - selected = 0 - elif key in ("enter", "right", "i") and rows: - pick = rows[max(0, min(selected, len(rows) - 1))] - detail, sizes = (pick["pid"], pick["name"]), {} - focus, at = "endpoints", {k: 0 for k in SECTIONS} - elif key in ("r", "R"): - store.reset() - selected = 0 - - selected = max(0, min(selected, len(rows) - 1)) if rows else 0 - - # One process in full. Its row is looked up fresh each frame so the - # figures keep moving while the screen is open, and it survives the - # process exiting - which is often when it is being looked at. - if detail is not None: - pid, name = detail - row = next((r for r in rows - if r["pid"] == pid and r["name"] == name), None) - if row is None: - detail, sizes = None, {} - else: - spots = store.endpoints(pid, name) - conns = store.connections(pid, name) - files = open_files(pid) if running(pid) else [] - now = time.time() - for item in files: - if item["path"] not in sizes: - sizes[item["path"]] = (item["size"], now) - sizes_of = {"endpoints": len(spots), - "connections": len(conns), "files": len(files)} - for which in SECTIONS: - at[which] = max(0, min(at[which], - sizes_of[which] - 1)) \ - if sizes_of[which] else 0 - # What c would copy, decided where the selection is rather - # than at the keypress, so the footer can name it. - if focus == "endpoints" and spots: - pick = spots[at["endpoints"]] - pending_copy[0] = hostname(pick["peer"]) or pick["peer"] - elif focus == "connections" and conns: - pick = conns[at["connections"]] - pending_copy[0] = "%s:%d" % (pick["peer"], pick["port"]) - elif focus == "files" and files: - pending_copy[0] = files[at["files"]]["path"] - else: - pending_copy[0] = "" - - foot = [" " + line for line in pack_hints( - [[(ACCENT, "↑↓"), (DIM, " in section")], - [(ACCENT, "tab"), (DIM, " section")], - [(DIM, "[e]ndpoints")], [(DIM, "[f]iles")], - [(DIM, "[c]opy")], [(DIM, "[esc] back")], - [(DIM, "[q]uit")]], w - 2)] - if notice and time.time() >= notice[2]: - notice = None - if notice: - foot = [seg([(notice[1], " " + notice[0])], w - 1)] - room = max(1, h - len(foot) - 1) - body = detail_rows(row, store.history(pid, name), spots, - conns, files, sizes, focus, at, w, room) - while len(body) < room: - body.append("") - draw(body[:room] + foot, w, h) - time.sleep(min(0.5, INTERVAL)) - continue - - moving = sum(1 for r in rows if r["up_rate"] + r["down_rate"]) - down = sum(r["down_rate"] for r in rows) - up = sum(r["up_rate"] for r in rows) - - out = [title("netwatch", w, ACCENT)] - out.append(seg([(DIM, " %d process%s" % (len(rows), - "" if len(rows) == 1 - else "es")), - (DIM, " · %d moving" % moving), - (DIM, " · "), (ACCENT, elapsed(time.time() - started)), - (DIM, " · sorted by "), (ACCENT, mode), - (DIM, " every %gs" % INTERVAL)], w - 1)) - out.append(seg([(DIM, " TCP only · " if MINE - else " TCP only · every user · "), - (DOWN, "↓ " + rate(down)), (DIM, " "), - (UP, "↑ " + rate(up)), - (DIM, " · internet only" if EXTERNAL - else " · everything off-box")], w - 1)) - # What the network card moved, beside what the sockets explain. A - # machine that routes - an exit node, a subnet router, a container - # host - passes traffic that never touches a socket here, and a - # process list presented as the whole picture would be a lie by - # omission on exactly the machines where it matters most. - wire_rx, wire_tx, wire_names = store.wire_now() - wire = wire_rx + wire_tx - if wire > 0: - share = min(1.0, (down + up) / wire) - said = [(LBL, " interfaces"), (DIM, " · "), - (DOWN, "↓ " + rate(wire_rx)), (DIM, " "), - (UP, "↑ " + rate(wire_tx)), (DIM, " · "), - (DIM if share >= 0.9 else WARN, - "%.0f%% of it has a socket" % (share * 100))] - # The percentage is the signal; the sentence explaining it is a - # courtesy, and is dropped rather than truncated mid-word. - tail = " · the rest is routed through, not sent by anything here" - if share < 0.9 and sum(len(t) for _, t in said) + len(tail) <= w - 1: - said.append((DIM, tail)) - which = wire_label(wire_names) - if which: - room = (w - 1) - sum(len(t) for _, t in said) - 3 - if len(which) <= room: - said.append((GRID, " · " + which)) - out.append(seg(said, w - 1)) - if err: - out.append(seg([(BAD, " ! " + err)], w - 1)) - out.append("") - - # The chart takes a share of the pane and the list takes the rest, - # but the list is the point: below a certain height there is no - # chart at all rather than two rows of neither. - spare = h - len(out) - 4 - graph_h = 9 if spare >= 20 else 7 if spare >= 15 else 5 if spare >= 11 else 0 - if graph_h and store.rates(MINE): - # The chart is the sum of the rows below it, so it is named - # for them. Calling it "traffic" claimed the whole machine's, - # which is the one thing it is not - that is the interfaces - # line, and the two disagreeing is the point of having both. - # Which processes are counted is on the line above; the chart - # keeps one name rather than renaming itself under the cursor. - out.append(chart_head(store.rates(MINE), w, "PROCESS WATCH")) - out.extend(chart(store.rates(MINE), w, graph_h)) - out.append("") - - room = max(1, h - len(out) - 3) - limit = min(LIMIT or room, room) - if selected >= limit: - rows = rows[selected - limit + 1:] - if not rows: - out.append(seg([(DIM, " Nothing has moved yet. Totals start at " - "zero, so this fills as traffic " - "happens.")], w - 1)) - else: - out.extend(table(rows, w, limit, selected)) - - while len(out) < h - 2: - out.append("") - hints = [[(ACCENT, "↑↓"), (DIM, " select")], - [(ACCENT, "↵"), (DIM, " details")], - [(ACCENT if mode == "total" else DIM, "[1] total")], - [(ACCENT if mode == "live" else DIM, "[2] live")], - [(DIM, "[o]%s others" % ("show" if MINE else "hide"))], - [(DIM, "[r]ezero")], [(DIM, "[q]uit")]] - for line in pack_hints(hints, w - 2): - out.append(" " + line) - draw(out, w, h) - time.sleep(min(0.3, INTERVAL)) - - -main() diff --git a/ports.py b/ports.py deleted file mode 100755 index cdfb267..0000000 --- a/ports.py +++ /dev/null @@ -1,1363 +0,0 @@ -#!/usr/bin/env python3 -# terminal-toys - small dependency-free terminal widgets -# Copyright (C) 2026 William Li -# -# This program is free software: you can redistribute it and/or modify -# it under the terms of the GNU Affero General Public License as published -# by the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU Affero General Public License for more details. -# -# You should have received a copy of the GNU Affero General Public License -# along with this program. If not, see <https://www.gnu.org/licenses/>. -"""What is listening on this machine, what started it, and who can reach it. - -On a box running several agents at once, "which port is that project on" and -"is this reachable from outside" are asked constantly and answered badly. -`lsof -i` gives a pid and a port and stops there. - -Each row is one listening service: the port, what it is bound to, what kind of -server it is, the project directory it was started from - the label that -actually identifies a dev server - how long it has been up, and whether -anything outside this machine can reach it. A server listening on both IPv4 -and IPv6 is one row, not two. - - python3 ports.py [-n SECONDS] - -Read from /proc alone: the socket table for the ports, and each process's own -cmdline and cwd for the rest. Exposure comes from `tailscale serve status` -where Tailscale is installed. Another user's sockets cannot be tied to a -process without root, so those rows name the owner the socket table gives -and are hidden behind o along with the system ports. - -k stops the selected server, after a confirmation and only for a process you -own: SIGTERM to its process group, which is what Ctrl-C in its own terminal -would have sent, then the offer of SIGKILL if it is still up three seconds -later. - -Enter opens a second screen for one port, where there is more to show than the -table holds: the command behind it, every address it can actually be reached -at - bounded by what the socket is bound to - and c to copy one. From there s -and t publish it over Tailscale, to the tailnet or to the internet, and d -opens a Cloudflare quick tunnel. Each asks first. - -Keys: up/down select, enter opens, esc goes back, c copies, s serves, -t funnels, d tunnels, k kills, o hides the machine's own ports, r refreshes, -q quits. -""" -import getpass -import json -import os -import pwd -import re -import shutil -import signal -import socket -import struct -import subprocess -import sys -import threading -import time - -sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) -from common import (Keyboard, bg, clipboard, draw, load_config, maybe_help, - pack_hints, pad, rgb, seg, setup, size, title) - -_CFG = load_config("ports", { - # Ports that are part of the machine rather than something you started. - # Hidden behind `o` by default: they are never the answer to "which port - # is my dev server on". - "system_ports": [22, 53, 123, 323, 631, 5353], - "refresh": 4, -}) - -REFRESH = max(1.0, float(_CFG["refresh"])) -SYSTEM_PORTS = set(int(p) for p in (_CFG["system_ports"] or [])) - -OK = rgb(90, 240, 160) -WARN = rgb(255, 200, 90) -BAD = rgb(255, 100, 110) -DIM = rgb(127, 147, 172) -GRID = rgb(60, 78, 98) -TXT = rgb(225, 235, 245) -LBL = rgb(130, 165, 200) -ACCENT = rgb(150, 210, 255) -PORT = rgb(160, 220, 255) -OPEN = rgb(255, 170, 120) # bound to every interface -LOCAL = rgb(120, 200, 160) # loopback only - -# Process titles worth recognising. Checked in order, first match wins, so -# the specific ones come before `node` and `python`. -KINDS = ( - (r"^next-server", "Next.js"), - (r"node_modules/\.bin/vite|[/ ]vite(\s|$)", "Vite"), - (r"node_modules/next/dist", "Next.js"), - (r"react-scripts", "React"), - (r"webpack", "webpack"), - (r"nuxt", "Nuxt"), - (r"astro", "Astro"), - (r"remix", "Remix"), - (r"turbo(\s|$)", "Turborepo"), - (r"uvicorn", "uvicorn"), - (r"gunicorn", "gunicorn"), - (r"flask", "Flask"), - (r"django|manage\.py", "Django"), - (r"rails", "Rails"), - (r"postgres", "Postgres"), - (r"redis-server", "Redis"), - (r"mysqld|mariadb", "MySQL"), - (r"mongod", "MongoDB"), - (r"docker-proxy", "Docker"), - (r"ollama", "Ollama"), - (r"code-server|vscode-server", "VS Code"), - (r"^herdr|/herdr", "Herdr"), - (r"tailscaled", "Tailscale"), - (r"sshd", "SSH"), - (r"systemd-resolve", "DNS"), - (r"[/ ]python[0-9.]*(\s|$)", "Python"), - (r"[/ ]node(\s|$)", "Node"), -) - -# Ports whose owner is usually root, so /proc will not say what it is. Naming -# them by convention is a guess, and is marked as one. -BY_PORT = {22: "SSH", 53: "DNS", 80: "HTTP", 123: "NTP", 443: "HTTPS", - 631: "printing", 3306: "MySQL", 5432: "Postgres", 6379: "Redis", - 5353: "mDNS", 27017: "MongoDB"} - -VERSION = re.compile(r"\(v([0-9][0-9a-zA-Z.\-]*)\)") -# Tailscale hands out 100.64.0.0/10 and fd7a:115c:a1e0::/48. A socket bound -# to one is reachable by tailnet peers and nobody else, which is a different -# answer from either "all" or "local". -TAILNET_V4 = re.compile(r"^100\.(6[4-9]|[7-9]\d|1[0-1]\d|12[0-7])\.") - - -def run(args): - try: - out = subprocess.run(args, capture_output=True, text=True, timeout=5) - except (OSError, subprocess.SubprocessError): - return "" - return out.stdout if out.returncode == 0 else "" - - -def hex_addr(text, family): - """The bind address from /proc's little-endian hex.""" - try: - if family == socket.AF_INET: - return socket.inet_ntoa(struct.pack("<I", int(text, 16))) - raw = bytes.fromhex(text) - return socket.inet_ntop( - socket.AF_INET6, - b"".join(raw[i:i + 4][::-1] for i in range(0, 16, 4))) - except (ValueError, OSError, struct.error): - return "?" - - -def bind_class(bind): - """Who can reach a socket bound to this address.""" - if bind in ("0.0.0.0", "::"): - return "all" - if bind.startswith("127.") or bind == "::1": - return "local" - if TAILNET_V4.match(bind) or bind.startswith("fd7a:115c:a1e0"): - return "tailnet" - return bind - - -def listening(): - """Every listening TCP socket, from the kernel's own table.""" - out = [] - for path, family in (("/proc/net/tcp", socket.AF_INET), - ("/proc/net/tcp6", socket.AF_INET6)): - try: - with open(path) as f: - lines = f.read().splitlines()[1:] - except OSError: - continue - for line in lines: - cols = line.split() - if len(cols) < 10 or cols[3] != "0A": - continue - addr, port = cols[1].rsplit(":", 1) - # The uid is in the table even where the process behind it is - # not reachable, which is the difference between "somebody - # else's" and "a mystery". - out.append({"port": int(port, 16), "bind": hex_addr(addr, family), - "inode": cols[9], "uid": int(cols[7])}) - return out - - -def owner_name(uid): - """Whose socket it is, by name where the machine has one.""" - if uid == os.getuid(): - return "" - try: - return pwd.getpwuid(uid).pw_name - except KeyError: - return "uid %d" % uid - - -def theirs(row): - """Whether a row is part of the machine rather than something you started. - - Two kinds qualify and both belong behind the same key: a well-known - system port, and any socket owned by another user - which in practice - means root's daemons, the ones that cannot be signalled without root and - are never the answer to "which port is my dev server on". A port served - by Tailscale with nothing behind it is neither: nobody else configured - that. - """ - if row.get("orphan"): - return False - return row["port"] in SYSTEM_PORTS or bool(row.get("user")) - - -def socket_owners(): - """inode -> pid, for every process this user can read. - - Root's sockets are not readable, so sshd and the like arrive unowned. - That is stated on screen rather than papered over: a widget claiming to - know what is behind port 22 when it cannot is worse than one that says - so. - - The pid is an int, not the string /proc was listed as: it is handed to - os.kill when a row is stopped, and that takes no strings. - """ - owners = {} - for pid in os.listdir("/proc"): - if not pid.isdigit(): - continue - try: - fds = os.listdir("/proc/%s/fd" % pid) - except OSError: - continue - for fd in fds: - try: - target = os.readlink("/proc/%s/fd/%s" % (pid, fd)) - except OSError: - continue - if target.startswith("socket:["): - owners[target[8:-1]] = int(pid) - return owners - - -def project_name(cwd): - """What a directory calls itself, for the label a person would use. - - A deleted directory still names the project it was - a dev server left - running on a worktree that has since been removed is exactly the thing - this widget should surface, and blanking the column hides it. - """ - if cwd and cwd.endswith(" (deleted)"): - return os.path.basename(cwd[:-10].rstrip("/")) + " ✗" - if not cwd: - return "" - try: - with open(os.path.join(cwd, "package.json")) as f: - name = (json.load(f) or {}).get("name") - if name: - return str(name) - except (OSError, ValueError): - pass - return os.path.basename(cwd.rstrip("/")) - - -def kind_of(cmdline, port): - """What sort of server this is. - - From the process title where there is one - Next.js rewrites its own to - `next-server (v16.3.0)`, which is the version as well as the name - and - from the argv path when the title is just `node`, since a dev server - launched through a package manager is several layers of wrapper deep. - """ - if not cmdline: - guess = BY_PORT.get(port) - return ("%s?" % guess, True) if guess else ("", True) - for pattern, name in KINDS: - if re.search(pattern, cmdline): - found = VERSION.search(cmdline) - return ("%s %s" % (name, found.group(1)) if found else name), False - return os.path.basename(cmdline.split()[0]), False - - -def process_info(pid): - try: - with open("/proc/%s/cmdline" % pid, "rb") as f: - cmdline = f.read().replace(b"\x00", b" ").decode( - "utf8", "replace").strip() - except OSError: - cmdline = "" - try: - cwd = os.readlink("/proc/%s/cwd" % pid) - except OSError: - cwd = "" - try: - started = os.stat("/proc/%s" % pid).st_ctime - except OSError: - started = None - return cmdline, cwd, started - - -def interfaces(): - """Every address this machine holds, by interface. - - Link-local is dropped: an fe80:: address needs a zone index to be usable - and is never what somebody wants pasted into a browser. - """ - found = [] - try: - data = json.loads(run(["ip", "-j", "addr"]) or "[]") - except ValueError: - return found - for link in data: - for addr in link.get("addr_info") or []: - ip = addr.get("local") or "" - if not ip or ip.startswith("fe80:"): - continue - found.append((link.get("ifname") or "?", ip, - addr.get("family") == "inet6")) - return found - - -def tailnet_self(): - """This node's tailnet name and addresses, and whether it may Funnel. - - Funnel is off unless the tailnet's policy grants the node the attribute, - and the node knows: the capability is in the map the coordination server - hands it. Asking here means the widget can say so instead of offering a - key that only ever returns an error. - """ - out = {"name": "", "ips": [], "funnel": False, "operator": False} - try: - data = json.loads(run(["tailscale", "status", "--json"]) or "null") - except ValueError: - return out - self_node = (data or {}).get("Self") or {} - out["name"] = (self_node.get("DNSName") or "").rstrip(".") - out["ips"] = list(self_node.get("TailscaleIPs") or []) - out["funnel"] = any("cap/funnel" in cap - for cap in (self_node.get("CapMap") or {})) - # Changing the serve config is a root operation unless this user has been - # named the operator. Worth knowing before the key is pressed, since the - # fix is a one-off command rather than anything the widget can do. - try: - prefs = json.loads(run(["tailscale", "debug", "prefs"]) or "null") - except ValueError: - prefs = None - who = (prefs or {}).get("OperatorUser") - out["operator"] = os.getuid() == 0 or who == getpass.getuser() - return out - - -def host_part(ip, v6): - """An address as it goes in a URL - IPv6 needs its brackets.""" - return "[%s]" % ip if v6 else ip - - -def url_for(host, v6, port): - """A URL for a host and port, with the scheme the port implies.""" - scheme = "https" if port in (443, 8443) else "http" - return "%s://%s:%d" % (scheme, host_part(host, v6), port) - - -def addresses(row, net, cfg): - """Where this port can actually be reached, most local first. - - Bounded by what the socket is bound to, which is the part that gets got - wrong: a server on 127.0.0.1 is not reachable at this machine's LAN - address no matter how many addresses the machine has, and offering one - to copy would hand somebody a URL that cannot work. Only a socket bound - to every interface gets the full list. - - A served port is the exception worth keeping: Tailscale proxies to it - over loopback, so its https URL works even for a loopback-only server. - """ - port, reach = row["port"], bind_class(row["bind"]) - found = [] - url = served_url(cfg, port) - if url: - found.append((url, "tailnet · via serve")) - # Nothing is listening, so every address below would refuse the - # connection. The serve URL above is the only one that exists, and it - # answers 502 - which is the whole reason this row is on screen. - if row.get("orphan"): - return found - if reach == "local": - found.append((url_for("127.0.0.1", False, port), "this machine only")) - return found - if reach == "tailnet": - for ip in net["ips"]: - found.append((url_for(ip, ":" in ip, port), "tailnet")) - if net["name"]: - found.append((url_for(net["name"], False, port), "tailnet · name")) - return found - if reach != "all": - # Bound to one particular address, so that address is the answer. - found.append((url_for(row["bind"], ":" in row["bind"], port), - "this interface")) - return found - found.append((url_for("127.0.0.1", False, port), "this machine")) - tail = set(net["ips"]) - for name, ip, v6 in interfaces(): - if ip.startswith("127.") or ip == "::1": - continue - found.append((url_for(ip, v6, port), "tailnet" if ip in tail else name)) - if net["name"]: - found.append((url_for(net["name"], False, port), "tailnet · name")) - return found - - -def serve_config(): - """Tailscale's own serve configuration, as it reports it. - - The JSON form rather than the text: the detail view needs the URL a - served port answers on, and putting a second port behind the same node - needs to know which mounts are already taken. Both are structure the - text output only implies. - """ - try: - return json.loads(run(["tailscale", "serve", "status", "--json"]) - or "null") or {} - except ValueError: - return {} - - -def served_url(cfg, port): - """The https URL a served port answers on, where one is configured.""" - for mount, web in (cfg.get("Web") or {}).items(): - for path, handler in (web.get("Handlers") or {}).items(): - proxy = handler.get("Proxy") or "" - if re.search(r":%d(/|$)" % port, proxy): - host, _, listen = mount.partition(":") - return "https://%s%s%s" % ( - host, "" if listen in ("", "443") else ":" + listen, - path if path != "/" else "/") - return "" - - -def exposure(): - """Ports Tailscale is serving, and whether the world can see them. - - `serve` is tailnet-only; `funnel` is public and limited to three ports. - Both are reported by the same command, so the funnel list is what - separates them. - """ - served, public = {}, set() - cfg = serve_config() - for web in (cfg.get("Web") or {}).values(): - for handler in (web.get("Handlers") or {}).values(): - found = re.search(r"https?://(?:127\.0\.0\.1|localhost|\[::1\]" - r"|::1):(\d+)", handler.get("Proxy") or "") - if found: - served[int(found.group(1))] = "tailnet" - funnel = run(["tailscale", "funnel", "status"]) - if "tailnet only" not in funnel: - for line in funnel.splitlines(): - found = re.search(r"proxy\s+https?://(?:127\.0\.0\.1|localhost)" - r":(\d+)", line) - if found: - public.add(int(found.group(1))) - for port in public: - served[port] = "public" - return served - - -def span(seconds): - if seconds is None: - return "--" - s = max(0, int(seconds)) - if s < 60: - return "%ds" % s - if s < 3600: - return "%dm" % (s // 60) - if s < 86400: - return "%dh" % (s // 3600) - return "%dd" % (s // 86400) - - -def scan(): - """One entry per listening service, plus anything served but not bound.""" - owners = socket_owners() - served = exposure() - rows, seen, services = [], set(), {} - now = time.time() - for sock in listening(): - pid = owners.get(sock["inode"]) - # A server that listens on both address families is two sockets in - # the kernel table but one thing to know about: 0.0.0.0 alongside ::, - # or a tailnet IPv4 address alongside its IPv6. Same port, same owner - # and the same answer to "who can reach it" means one row. Any of the - # three differing is a real second row - 127.0.0.1:8080 and - # 100.x:8080 are not the same answer even from the same process. - key = (sock["port"], pid, bind_class(sock["bind"])) - if key in services: - services[key]["families"] += 1 - continue - cmdline, cwd, started = process_info(pid) if pid else ("", "", None) - kind, guessed = kind_of(cmdline, sock["port"]) - row = { - "port": sock["port"], "bind": sock["bind"], "families": 1, - "pid": pid, "cmdline": cmdline, "cwd": cwd, - "kind": kind, "guessed": guessed, "user": owner_name(sock["uid"]), - "project": project_name(cwd), - "gone": cwd.endswith("(deleted)") if cwd else False, - "up": (now - started) if started else None, - "exposed": served.get(sock["port"], ""), - } - services[key] = row - rows.append(row) - seen.add(sock["port"]) - # A port Tailscale forwards to with nothing behind it is worth its own - # row: the URL exists, answers 502, and nothing in `lsof` explains why. - for port, how in served.items(): - if port not in seen: - rows.append({"port": port, "bind": "", "families": 0, "pid": None, - "cmdline": "", "cwd": "", "kind": "nothing listening", - "guessed": False, "project": "", "gone": False, - "user": "", "up": None, "exposed": how, - "orphan": True}) - rows.sort(key=lambda r: (r["port"] in SYSTEM_PORTS, r["port"])) - return rows - - -class Store(object): - def __init__(self): - self.lock = threading.Lock() - self.rows = [] - self.error = None - self.fetched = 0 - self.wake = threading.Event() - - def snapshot(self): - with self.lock: - return list(self.rows), self.fetched, self.error - - def run(self): - # A dead poller looks exactly like a machine with nothing running on - # it, which is a plausible enough state to be believed. - try: - self.poll() - except Exception as e: - with self.lock: - self.error = "poller stopped: %s: %s" % (type(e).__name__, - str(e)[:70]) - - def poll(self): - while True: - rows = scan() - with self.lock: - self.rows = rows - self.fetched = time.time() - self.wake.wait(REFRESH) - self.wake.clear() - - -def tunnel_dir(): - """Where a launched quick tunnel's pid and URL are remembered. - - cloudflared holds no listening socket - it dials out - so nothing in - /proc ties it to the port it serves. Without a note on disk the widget - would lose a tunnel the moment it restarted, and leave it running with - no way to find or stop it. - """ - base = (os.environ.get("XDG_STATE_HOME") - or os.path.expanduser("~/.local/state")) - path = os.path.join(base, "terminal-toys", "tunnels") - try: - os.makedirs(path, exist_ok=True) - except OSError: - return "" - return path - - -def tunnel_state(port): - """The quick tunnel for a port: its pid, its URL, whether it still runs.""" - path = tunnel_dir() - if not path: - return None - try: - with open(os.path.join(path, "%d.json" % port)) as f: - note = json.load(f) - except (OSError, ValueError): - return None - if not alive(note.get("pid") or 0): - forget_tunnel(port) - return None - return note - - -def forget_tunnel(port): - try: - os.remove(os.path.join(tunnel_dir(), "%d.json" % port)) - except OSError: - pass - - -def start_tunnel(port, wait=25.0): - """Run a cloudflared quick tunnel for a port and return its URL. - - A quick tunnel needs no account and no DNS: cloudflared picks a random - trycloudflare.com name and prints it. A named tunnel on a domain of your - own needs credentials and a DNS record, which is a setup task rather - than a keypress, and is deliberately not attempted here. - """ - path = tunnel_dir() - if not path: - return "", "no state directory to record the tunnel in" - log = os.path.join(path, "%d.log" % port) - try: - handle = open(log, "w+b") - except OSError as exc: - return "", exc.strerror or "cannot write the log" - try: - proc = subprocess.Popen( - ["cloudflared", "tunnel", "--no-autoupdate", - "--url", "http://127.0.0.1:%d" % port], - stdout=handle, stderr=subprocess.STDOUT, - stdin=subprocess.DEVNULL, start_new_session=True) - except OSError as exc: - handle.close() - return "", exc.strerror or "cloudflared would not start" - deadline = time.time() + wait - found = "" - while time.time() < deadline and not found: - time.sleep(0.4) - try: - with open(log, "rb") as f: - text = f.read().decode("utf8", "replace") - except OSError: - text = "" - match = re.search(r"https://[a-z0-9-]+\.trycloudflare\.com", text) - if match: - found = match.group(0) - elif not alive(proc.pid): - break - handle.close() - if not found: - end(proc.pid, signal.SIGTERM) - return "", "no URL after %ds - see %s" % (int(wait), log) - try: - with open(os.path.join(path, "%d.json" % port), "w") as f: - json.dump({"pid": proc.pid, "url": found, "port": port}, f) - except OSError: - pass - return found, "" - - -def alive(pid): - """Whether a pid is still running. Signal 0 checks without delivering. - - A zombie answers signal 0 and is not running: it is an exit status its - parent has not collected yet. Reporting one as alive would leave the - widget offering to SIGKILL something already dead, forever, since no - signal moves a zombie. /proc knows the difference. - """ - try: - os.kill(pid, 0) - except ProcessLookupError: - return False - except OSError: - pass - try: - with open("/proc/%d/stat" % pid) as f: - return f.read().rsplit(")", 1)[1].split()[0] != "Z" - except (OSError, IndexError): - return True - - -def killable(row): - """Whether this row can be signalled, and why not when it cannot. - - Returns (pid, reason). Only one of the two is ever set. The checks are - all about not doing damage past what was asked for: a row whose owner - /proc would not name is somebody else's process, and a process in this - widget's own group cannot be group-killed without taking the widget - down with it. - """ - pid = row.get("pid") - if not pid: - return None, "not yours - no owner for this socket in /proc" - if pid <= 1: - return None, "refusing to signal pid %d" % pid - try: - if os.stat("/proc/%d" % pid).st_uid != os.getuid(): - return None, "pid %d is not yours" % pid - except OSError: - return None, "pid %d is already gone" % pid - return pid, "" - - -def end(pid, sig): - """Signal the process group, falling back to the process alone. - - A dev server is rarely one process: `npm run dev` is a shell, a package - manager and the server itself, sharing a process group precisely so that - Ctrl-C reaches all three. Signalling the group is what Ctrl-C does. The - fallback covers a process whose group we cannot read, and the guard - covers the case where the group is this widget's own. - """ - try: - group = os.getpgid(pid) - except OSError: - group = None - try: - if group is not None and group != os.getpgrp(): - os.killpg(group, sig) - else: - os.kill(pid, sig) - except ProcessLookupError: - return "already gone" - except PermissionError: - return "not permitted" - except OSError as exc: - return exc.strerror or "failed" - return "" - - -def have(program): - """Whether a command exists, so a key can say so instead of failing.""" - return bool(shutil.which(program)) - - -# Tailscale accepts Funnel traffic on these three public ports and no -# others, so a node can have three funnels at once - not the one that -# defaulting to 443 every time would suggest. -FUNNEL_PORTS = (443, 8443, 10000) - - -def taken_ports(cfg): - """The tailnet-side ports this node's serve config already occupies.""" - used = set() - for key in (cfg.get("TCP") or {}): - try: - used.add(int(key)) - except (TypeError, ValueError): - continue - for mount in (cfg.get("Web") or {}): - _, _, listen = mount.rpartition(":") - try: - used.add(int(listen)) - except ValueError: - continue - return used - - -def free_funnel_port(cfg): - """The first public port free to funnel on, or 0 when all three are used.""" - used = taken_ports(cfg) - return next((p for p in FUNNEL_PORTS if p not in used), 0) - - -def serve_port(port, public=False, cfg=None): - """Put a local port behind this node's HTTPS name. - - Serve listens on the port's own number rather than 443. Nothing forces - that, but 443 is where an unflagged `tailscale serve` lands, so leaving - it as the default would mean the second port published quietly took the - first one's mount. - - Funnel has only the three ports Tailscale accepts from the internet, so - it takes the first of them that is free - a node can hold three at once, - and defaulting all of them to 443 would allow one. - """ - listen = port - if public: - listen = free_funnel_port(serve_config() if cfg is None else cfg) - if not listen: - return ("all three funnel ports are in use (%s) - stop one first" - % ", ".join(str(p) for p in FUNNEL_PORTS)) - cmd = ["tailscale", "funnel" if public else "serve", "--bg"] - cmd += ["--https=%d" % listen, str(port)] - try: - done = subprocess.run(cmd, capture_output=True, text=True, timeout=30) - except (OSError, subprocess.SubprocessError) as exc: - return str(exc) or "tailscale would not run" - if done.returncode: - text = (done.stderr or done.stdout or "").strip() - return " ".join(text.split())[:200] or "tailscale refused" - return "" - - -def listen_for(cfg, port): - """Which tailnet-side port a local port is currently published on.""" - for mount, web in (cfg.get("Web") or {}).items(): - for handler in (web.get("Handlers") or {}).values(): - if re.search(r":%d(/|$)" % port, handler.get("Proxy") or ""): - _, _, listen = mount.rpartition(":") - try: - return int(listen) - except ValueError: - return 0 - return 0 - - -def unserve_port(port, public=False, cfg=None): - """Take back one port, leaving every other mount as it was. - - The mount to remove is looked up rather than assumed: it was chosen when - the port was published, and on a funnel that is whichever of the three - public ports happened to be free at the time. - - Never `serve reset`: that clears the whole configuration, including - whatever was already published before this widget was ever run. - """ - listen = listen_for(serve_config() if cfg is None else cfg, port) - if not listen: - listen = 443 if public else port - cmd = ["tailscale", "funnel" if public else "serve", - "--https=%d" % listen, "off"] - try: - done = subprocess.run(cmd, capture_output=True, text=True, timeout=30) - except (OSError, subprocess.SubprocessError) as exc: - return str(exc) or "tailscale would not run" - if done.returncode: - text = (done.stderr or done.stdout or "").strip() - return " ".join(text.split())[:200] or "tailscale refused" - return "" - - -def kill_label(row, room=999): - """What a kill would take down, in whatever room the pane has. - - Everything here identifies the target, but not equally: the port is the - one thing the person is looking at, and the framework name without the - project it belongs to is no use on a machine running four of them. The - pid is the first to go, then the kind. - """ - # An orphan's kind is the words "nothing listening", which reads badly - # in the middle of a sentence about it. The port is the whole subject. - if row.get("orphan"): - return ":%d" % row["port"] - what = row["kind"] or "unidentified" - where = row["project"] - # Not every row has a pid. A port Tailscale serves with nothing behind - # it has none by definition, and one that exits while its screen is open - # loses the one it had - both can still be the subject of a prompt. - who = " (pid %d)" % row["pid"] if row.get("pid") else "" - full = "%s%s on :%d%s" % (what, " in " + where if where else "", - row["port"], who) - for text in (full, - "%s%s on :%d" % (what, " in " + where if where else "", - row["port"]), - "%s on :%d" % (where or what, row["port"]), - ":%d" % row["port"]): - if len(text) <= room: - return text - return ":%d" % row["port"] - - -def prompt(ask, key, options, w): - """A question and the key that answers it, fitted to the pane. - - On one line where both fit, on two where they do not, because the key is - never the half that may be truncated: a prompt with its `[y]` pushed off - the right edge is a prompt nobody can act on. The wording after the key - has shorter forms for the same reason, longest first. - """ - def answer(room): - text = next((o for o in options if len(key[1]) + len(o) <= room), "") - return [key, (DIM, text)] - - # The bare last form - "[y] yes", with no word on what anything else - # does - is a fallback for a pane too narrow for two lines, not a thing - # to choose while a second line is going spare. - keep = options[-2] if len(options) > 1 else options[-1] - room = (w - 1) - sum(len(t) for _, t in ask) - 2 - if room >= len(key[1]) + len(keep): - return [seg(ask + [(DIM, " ")] + answer(room), w - 1)] - return [seg(ask, w - 1), seg([(DIM, " ")] + answer(w - 2), w - 1)] - - -def bind_note(row): - """What the bound address means for who can reach it. - - The address itself is rarely the answer to that question and is always - too wide for the column - a tailnet IPv6 address is 24 characters and - pushed every field after it off the line. What matters is the class: - every interface, loopback only, or bound to one particular network. - """ - if row.get("orphan"): - return "--", DIM - reach = bind_class(row["bind"]) - if reach == "all": - return "all", OPEN - if reach == "local": - return "local", LOCAL - if reach == "tailnet": - return "tailnet", ACCENT - return reach[:7], TXT - - -ACTIONS = { - "serve": ("publish", "tailnet only"), - "funnel": ("publish publicly", "anyone with the URL"), - "unserve": ("stop serving", ""), - "unfunnel": ("stop the funnel", ""), - "tunnel": ("open a cloudflare tunnel", "anyone with the URL"), - "untunnel": ("close the cloudflare tunnel", ""), -} - - -def do_work(kind, row, done): - """Carry out one exposure change and record how it went.""" - port = row["port"] - if kind in ("serve", "funnel"): - failed = serve_port(port, kind == "funnel") - done.append((failed, BAD, time.time() + 8) if failed - else ("%s now serves :%d" % (kind, port), OK, - time.time() + 6)) - elif kind in ("unserve", "unfunnel"): - failed = unserve_port(port, kind == "unfunnel") - done.append((failed, BAD, time.time() + 8) if failed - else ("stopped serving :%d" % port, OK, time.time() + 5)) - elif kind == "tunnel": - url, failed = start_tunnel(port) - done.append((failed, BAD, time.time() + 10) if failed - else (url, OK, time.time() + 20)) - elif kind == "untunnel": - note = tunnel_state(port) - if note: - end(note["pid"], signal.SIGTERM) - forget_tunnel(port) - done.append(("closed the tunnel on :%d" % port, OK, time.time() + 5)) - - -def start_work(kind, row): - """Run an exposure change on a thread, so the frame keeps drawing.""" - work = {"kind": kind, "row": row, "done": []} - threading.Thread(target=do_work, args=(kind, row, work["done"]), - daemon=True).start() - return work - - -def footer(confirm, watch, working, notice, w, hints): - """The bottom of either screen. - - One of five things, in the order they matter: a question that must be - answered before anything happens, the wait after answering it, a slow - action still running, the outcome of the last one, or the ordinary keys. - """ - if confirm is not None: - verb, cost = ACTIONS.get(confirm["kind"], ("kill", "")) - ask = [(BAD, " " + verb + " "), - (TXT, kill_label(confirm["row"], w - 34 - len(verb)))] - if cost: - ask.append((WARN, " - " + cost)) - return prompt(ask + [(DIM, "?")], (WARN, "[y]"), - [" yes · any other key cancels", - " yes · any key cancels", " yes"], w) - if watch is not None and watch["asked"]: - return prompt([(WARN, " still up: "), - (TXT, kill_label(watch["row"], w - 30))], (BAD, "[f]"), - [" force kill · any other key leaves it", - " SIGKILL · any key leaves it", " SIGKILL"], w) - if watch is not None: - return [seg([(DIM, " SIGTERM sent, waiting for "), - (TXT, kill_label(watch["row"], w - 29))], w - 1)] - if working is not None: - verb = ACTIONS.get(working["kind"], ("working", ""))[0] - return [seg([(WARN, " %s :%d - this can take a moment" - % (verb, working["row"]["port"]))], w - 1)] - if notice is not None: - return [seg([(notice[1], " " + notice[0])], w - 1)] - return [" " + line for line in pack_hints(hints, w - 2)] - - -def has_detail(row): - """Whether there is anything behind this row worth a second screen. - - A process of ours carries a command line, a directory and an age that - the table has no room for, and any row at all can be given an address to - copy or an exposure to set up. Another user's socket carries none of - that: the four columns already say everything /proc will tell us, and - opening a screen to repeat them would be a screen that wastes a press. - """ - return bool(row.get("pid") or row.get("orphan") or row.get("exposed")) - - -def wrap(text, width): - """Break a long value across lines at spaces, then anywhere.""" - lines, rest = [], text - while rest and len(lines) < 4: - if len(rest) <= width: - lines.append(rest) - break - cut = rest.rfind(" ", 0, width + 1) - cut = cut if cut > width // 2 else width - lines.append(rest[:cut]) - rest = rest[cut:].lstrip() - return lines or [""] - - -def field(label, value, w, colour=TXT, label_w=10): - """One `label value` line, wrapped under its own label.""" - rows = [] - for i, line in enumerate(wrap(value, max(8, (w - 3) - label_w))): - rows.append(seg([(DIM, " " + pad(label if not i else "", label_w)), - (colour, line)], w - 1)) - return rows - - -def expose_options(row, net, tunnel): - """The ways this port could be published, and why one is unavailable. - - Each is a key, a name, and the state that decides whether pressing it - does anything. An option that cannot work says so on the line rather - than failing after the keypress - except Funnel, which is offered even - when the capability is missing, because Tailscale's own error names the - setting to change in the admin console better than this can. - """ - how = row.get("exposed") - # One blocker outranks the others: without the operator bit every serve - # and funnel write is refused, whatever else is true of them. - barred = "" if net.get("operator") else "needs: tailscale set --operator" - return [ - ("s", "tailscale serve", - "serving · tailnet only" if how == "tailnet" - else barred or "tailnet only", how == "tailnet"), - ("t", "tailscale funnel", - "public · anyone with the URL" if how == "public" - else barred or ("public" if net["funnel"] - else "not enabled for this node"), - how == "public"), - ("d", "cloudflare tunnel", - "running · %s" % tunnel["url"] if tunnel - else "quick tunnel, random domain" if have("cloudflared") - else "cloudflared not installed", - bool(tunnel)), - ] - - -def detail_rows(row, net, cfg, tunnel, links, sel, w): - """The second screen: everything known about one port, and what to do.""" - rows = [title(":%d" % row["port"], w, PORT)] - head = row["kind"] or ("%s's" % row["user"] if row.get("user") else "") - if row["project"]: - head += " in " + row["project"] - rows.append(seg([(TXT, " " + head.strip()), - (DIM, " · up " + span(row["up"]) if row["up"] - else "")], w - 1)) - rows.append("") - - if row.get("pid"): - rows.append(seg([(LBL, " ── PROCESS ── ")], w - 1)) - rows += field("command", row["cmdline"] or "?", w) - rows += field("directory", row["cwd"] or "?", w, - WARN if row["gone"] else TXT) - group = "" - try: - group = " · group %d" % os.getpgid(row["pid"]) - except OSError: - pass - rows += field("pid", "%d%s" % (row["pid"], group), w) - rows.append("") - - # A lone :: is not an IPv6-only server: Linux maps IPv4 onto it unless - # the process asked for IPV6_V6ONLY, and /proc cannot say which it did. - # Claiming "IPv6 only" here would be a guess dressed as a fact. - note = ("two sockets, IPv4 and IPv6" if row.get("families", 0) > 1 - else "IPv4 too, unless the server turned that off" - if row["bind"] == "::" else "one socket") - rows.append(seg([(LBL, " ── LISTENING ON ── "), - (TXT, row["bind"] or "nothing"), - (DIM, " " + note)], w - 1)) - rows.append("") - rows.append(seg([(LBL, " ── REACHABLE AT ── "), - (DIM, "↑↓ to pick, c copies")], w - 1)) - if not links: - rows.append(seg([(DIM, " nothing is listening to reach")], w - 1)) - for i, (url, note) in enumerate(links): - here = i == sel - rows.append(seg([(ACCENT if here else DIM, " ▸ " if here else " "), - (TXT if here else DIM, url), (DIM, " " + note)], - w - 1)) - rows.append("") - rows.append(seg([(LBL, " ── EXPOSE ── ")], w - 1)) - for key, name, state, on in expose_options(row, net, tunnel): - rows.append(seg([(ACCENT, " [%s] " % key), (TXT, pad(name, 18)), - (OK if on else DIM, state)], w - 1)) - return rows - - -def main(): - maybe_help(__doc__) - global REFRESH - args = sys.argv[1:] - while args and args[0] in ("-n", "--refresh"): - REFRESH = max(1.0, float(args[1])) - args = args[2:] - - setup() - keyboard = Keyboard() - store = Store() - threading.Thread(target=store.run, daemon=True).start() - selected, hide_system, scroll = 0, True, 0 - confirm = None # an action awaiting an explicit yes before it happens - watch = None # what SIGTERM was sent to, and whether it has died - notice = None # (text, colour, expires) - the result of the last one - detail = None # the port whose second screen is open, and its state - working = None # an action too slow to block the frame on - net = cfg = None # tailnet identity and serve config, read on demand - - while True: - w, h = size() - all_rows, fetched, err = store.snapshot() - shown = [r for r in all_rows if not (hide_system and theirs(r))] - selected = max(0, min(selected, len(shown) - 1)) if shown else 0 - - # A process that dies on its own between the prompt and the deadline - # is the normal case, and wants no further questions. - if watch is not None and not watch["asked"]: - if not alive(watch["pid"]): - notice = ("stopped " + kill_label(watch["row"], w - 11), - OK, time.time() + 5) - watch = None - store.wake.set() - elif time.time() >= watch["deadline"]: - watch["asked"] = True - - # An action that talks to tailscaled or cloudflared takes seconds, - # which is far too long to hold a frame for, so it runs on a thread - # and its answer is collected here. - if working is not None and working["done"]: - notice = working["done"][0] - working = None - net = cfg = None - store.wake.set() - - for key in keyboard.poll(): - if confirm is not None: - # Only an explicit yes acts. Every other key cancels, - # deliberately including q: quitting must never double as - # consent to signal something or publish it. - act, confirm = confirm, None - if key not in ("y", "Y"): - notice = ("cancelled", DIM, time.time() + 2) - continue - row, kind = act["row"], act["kind"] - if kind == "kill": - pid, why = killable(row) - if why: - notice = (why, BAD, time.time() + 5) - continue - failed = end(pid, signal.SIGTERM) - if failed: - notice = ("%s: %s" - % (kill_label(row, w - 4 - len(failed)), - failed), BAD, time.time() + 5) - store.wake.set() - else: - watch = {"pid": pid, "row": row, "asked": False, - "deadline": time.time() + 3.0} - else: - working = start_work(kind, row) - continue - if watch is not None and watch["asked"]: - pid, row, watch = watch["pid"], watch["row"], None - if key in ("f", "F"): - failed = end(pid, signal.SIGKILL) - notice = ("%s: %s" % (kill_label(row, w - 4 - len(failed)), - failed) if failed - else "SIGKILL sent to " - + kill_label(row, w - 19), - BAD if failed else WARN, time.time() + 5) - else: - notice = ("left running: " + kill_label(row, w - 17), - DIM, time.time() + 3) - store.wake.set() - continue - if detail is not None: - # The second screen keeps its own selection - of addresses - # rather than rows - and hands every other key back. - if key in ("esc", "left", "q", "Q", "backspace"): - detail = None - continue - if key == "up": - detail["at"] -= 1 - elif key == "down": - detail["at"] += 1 - elif key in ("c", "C"): - links = detail["links"] - if links: - url = links[max(0, min(detail["at"], - len(links) - 1))][0] - # The address goes in the notice either way: OSC 52 - # is refused by some terminals and swallowed by some - # multiplexers, and a copy that silently did nothing - # would leave nothing on screen to read instead. - ok = clipboard(url) - notice = (("copied " if ok else "no clipboard ") - + url, OK if ok else WARN, time.time() + 8) - elif key in ("s", "S", "t", "T", "d", "D"): - kind = {"s": "serve", "t": "funnel", - "d": "tunnel"}[key.lower()] - how = detail["row"].get("exposed") - if kind == "serve" and how == "tailnet": - kind = "unserve" - elif kind == "funnel" and how == "public": - kind = "unfunnel" - elif kind == "tunnel" and detail["tunnel"]: - kind = "untunnel" - elif kind == "tunnel" and not have("cloudflared"): - notice = ("cloudflared is not installed - see " - "the docs for the one-line install", - WARN, time.time() + 8) - continue - if working is None: - confirm = {"kind": kind, "row": detail["row"]} - elif key == "r": - net = cfg = None - store.wake.set() - continue - if key in ("q", "Q"): - raise SystemExit(0) - if key == "up": - selected -= 1 - elif key == "down": - selected += 1 - elif key == "o": - hide_system = not hide_system - elif key == "r": - store.wake.set() - elif key in ("enter", "right", "i") and shown: - row = shown[max(0, min(selected, len(shown) - 1))] - if has_detail(row): - detail = {"port": row["port"], "row": row, "at": 0, - "links": [], "tunnel": None} - net = cfg = None - else: - notice = ("nothing more to show - /proc will not name " - "another user's process", DIM, time.time() + 5) - elif key in ("k", "K") and shown and watch is None: - row = shown[max(0, min(selected, len(shown) - 1))] - pid, why = killable(row) - if why: - notice = (why, BAD, time.time() + 5) - else: - confirm = {"kind": "kill", "row": row} - - # Rebuilt after the keys rather than before them, so that a press of - # o is answered in the frame it was made in and not the next one. - shown = [r for r in all_rows if not (hide_system and theirs(r))] - selected = max(0, min(selected, len(shown) - 1)) if shown else 0 - if notice and time.time() >= notice[2]: - notice = None - - if detail is not None: - # Tailscale is asked once per visit rather than once per frame: - # two subprocesses at 3Hz would cost more than the whole rest of - # the widget. Any change made here clears them. - if net is None: - net, cfg = tailnet_self(), serve_config() - live = next((r for r in all_rows if r["port"] == detail["port"]), - None) - detail["row"] = live or dict(detail["row"], pid=None, gone=True) - detail["tunnel"] = tunnel_state(detail["port"]) - detail["links"] = addresses(detail["row"], net, cfg) - if detail["tunnel"]: - detail["links"] = detail["links"] + [ - (detail["tunnel"]["url"], "public · cloudflare")] - detail["at"] = max(0, min(detail["at"], - len(detail["links"]) - 1)) - rows = detail_rows(detail["row"], net, cfg, detail["tunnel"], - detail["links"], detail["at"], w) - foot = footer(confirm, watch, working, notice, w, - [[(ACCENT, "↑↓"), (DIM, " address")], - [(DIM, "[c]opy")], [(DIM, "[s]erve")], - [(DIM, "[t]unnel")], [(DIM, "[d] cloudflare")], - [(ACCENT, "esc"), (DIM, " back")]]) - while len(rows) < h - len(foot) - 1: - rows.append("") - draw(rows[:h - len(foot) - 1] + foot, w, h) - time.sleep(0.3) - continue - - mine = sum(1 for r in all_rows if r["pid"]) - out = sum(1 for r in all_rows if r.get("exposed")) - - rows = [title("dev servers", w, PORT)] - rows.append(seg([(DIM, " %d listening" % len(all_rows)), - (DIM, " · %d yours" % mine), - (DIM, " · "), - (OK if out else DIM, "%d reachable off-box" % out), - (DIM, " every %gs" % REFRESH)], w - 1)) - if err: - rows.append(seg([(BAD, " ! " + err)], w - 1)) - rows.append("") - - wide = w >= 78 - # The project column takes whatever the fixed ones leave, because it - # is the one that identifies the server and the one whose contents - # are a directory name of any length. - # The WHAT column takes the widest name it has to show, plus a gap. - # It used to be a flat eighteen with nothing after it, so a name of - # exactly that length ran straight into the project and the two read - # as one word - and anything longer was cut, which names a different - # program. Sized to the whole list rather than the visible slice, so - # the columns do not shift as it scrolls. - rest = 1 + 6 + 8 + 2 + 8 + (6 + 8 if wide else 0) - widest = max([len(r["kind"] or "") for r in shown] or [0]) - kind_w = max(4, min(widest, max(4, (w - 1) - rest))) - fixed = 1 + 6 + 8 + kind_w + 2 + (6 + 8 if wide else 0) - name_w = max(8, (w - 1) - fixed) - rows.append(seg([(DIM, " PORT BIND "), - (DIM, pad("WHAT", kind_w) + " "), - (DIM, pad("PROJECT", name_w)), - (DIM, "UP EXPOSED" if wide else "")], w - 1)) - visible = max(1, h - len(rows) - 3) - if selected < scroll: - scroll = selected - elif selected >= scroll + visible: - scroll = selected - visible + 1 - scroll = max(0, min(scroll, max(0, len(shown) - visible))) - - for i in range(scroll, min(len(shown), scroll + visible)): - row = shown[i] - here = i == selected - tint = bg(28, 44, 62) if here else "" - note, note_colour = bind_note(row) - # Another user's row names its owner rather than its project, - # which it has none of that we can read. That is the whole of - # what is knowable about it, and it is more use than the - # "(not ours)" this used to say in the column beside it. - who = row["project"] or row.get("user") or ("—" if row["pid"] - else "") - line = [(tint + (ACCENT if here else PORT), - ("▸" if here else " ") + "%-6d" % row["port"]), - (tint + note_colour, "%-8s" % note), - (tint + (DIM if row["guessed"] or not row["kind"] else TXT), - pad(row["kind"], kind_w) + " "), - (tint + (WARN if row["gone"] else - DIM if row.get("user") else TXT), - pad(who, name_w))] - if wide: - line.append((tint + DIM, "%-6s" % span(row["up"]))) - line.append((tint + (OK if row["exposed"] == "tailnet" - else BAD if row["exposed"] == "public" - else GRID), - row["exposed"] or "-")) - if here: - line.append((tint, " " * w)) - rows.append(seg(line, w - 1)) - - foot = footer(confirm, watch, working, notice, w, - [[(ACCENT, "↑↓"), (DIM, " select")], - # The right arrow has always opened it too, and the - # footer only ever named the return. A key that works - # and is not on screen is a feature nobody finds. - [(ACCENT, "→/↵"), (DIM, " details")], [(DIM, "[k]ill")], - [(DIM, "[o]%s system" - % ("show" if hide_system else "hide"))], - [(DIM, "[r]efresh")], [(DIM, "[q]uit")]]) - - while len(rows) < h - len(foot) - 1: - rows.append("") - rows.extend(foot) - draw(rows, w, h) - time.sleep(0.3) - - -main() diff --git a/pr.py b/pr.py deleted file mode 100755 index a539fb7..0000000 --- a/pr.py +++ /dev/null @@ -1,1073 +0,0 @@ -#!/usr/bin/env python3 -# terminal-toys - small dependency-free terminal widgets -# Copyright (C) 2026 William Li -# -# This program is free software: you can redistribute it and/or modify -# it under the terms of the GNU Affero General Public License as published -# by the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU Affero General Public License for more details. -# -# You should have received a copy of the GNU Affero General Public License -# along with this program. If not, see <https://www.gnu.org/licenses/>. -"""Watch the pull requests you have to follow up on. - -A list of open PRs, and a dashboard for whichever one is selected: checks, -reviews, mergeability, and - when the PR belongs to a stack - the stack it -sits in and the order that stack has to merge in. - - python3 pr.py [-n SECONDS] [search terms ...] - -Extra arguments are appended to the search, so `pr.py org:acme` narrows to one -organisation and `pr.py author:@me` to your own. With none given it uses -`pr.query` from config, which defaults to everything you are involved in. - -Credentials: reuses `github.token` from config.json, or $GITHUB_TOKEN. A -classic token with `repo` and `read:org`, the same one github.py uses. - -Keys: up/down select, enter opens a PR, esc goes back, / filters, s cycles the -sort, o reverses it, r refreshes, q quits. -""" -import datetime -import json -import os -import sys -import threading -import time -import urllib.error -import urllib.request - -sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) -from common import (RST, Keyboard, bg, clipboard, config_token_warning, cycle, - draw, heat, - load_config, maybe_help, pack_hints, pad, rgb, seg, setup, - size, skeleton, stacked_bar, title, vbars) - -_GH = load_config("github", {"token": "", "token_env": "GITHUB_TOKEN"}) -_CFG = load_config("pr", { - "token": "", - "token_env": "GITHUB_TOKEN", - # GitHub search has no OR, so anything that is a union of conditions has - # to be several searches merged. Each entry here is one search; results - # are pooled and de-duplicated. `@mine` expands to every org you belong - # to plus your own account, as owner qualifiers. - "sources": { - "orgs": "is:open is:pr @mine", - "authored": "is:open is:pr author:@me", - "assigned": "is:open is:pr assignee:@me", - }, - "limit": 50, # per source; 3 x 100 nodes returns HTTP 502 - "refresh": 60, -}) - -REFRESH = float(_CFG["refresh"]) -API = "https://api.github.com/graphql" -SORTS = ("updated", "created") -SPINNER = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏" - -SPARK = "▁▂▃▄▅▆▇█" -OPENED_DAYS = 30 # width of the opened-per-day chart - -OK = rgb(90, 240, 160) -WARN = rgb(255, 200, 90) -BAD = rgb(255, 100, 110) -DIM = rgb(127, 147, 172) -GRID = rgb(60, 78, 98) -TXT = rgb(225, 235, 245) -LBL = rgb(130, 165, 200) -ACCENT = rgb(150, 210, 255) -PR = rgb(180, 160, 255) - -# GitHub's vocabulary, rendered as words rather than colour alone so it -# survives a screenshot, a colourblind reader and a `pane read` -REVIEW_LABEL = {"APPROVED": ("approved", OK), - "CHANGES_REQUESTED": ("CHANGES REQ", BAD), - "REVIEW_REQUIRED": ("needs review", WARN), - None: ("—", DIM)} -CHECK_LABEL = {"SUCCESS": ("pass", OK), "FAILURE": ("FAIL", BAD), - "ERROR": ("ERROR", BAD), "PENDING": ("running", WARN), - "EXPECTED": ("waiting", DIM), None: ("—", DIM)} -MERGE_LABEL = {"CLEAN": ("ready", OK), "DIRTY": ("CONFLICT", BAD), - "BLOCKED": ("blocked", WARN), "BEHIND": ("behind", WARN), - "UNSTABLE": ("checks red", WARN), "HAS_HOOKS": ("ready", OK), - "DRAFT": ("draft", DIM), "UNKNOWN": ("…", DIM), - None: ("—", DIM)} - - -def token(): - """The GitHub token, shared with github.py rather than duplicated.""" - for value, src in ((_CFG["token"], "config"), (_GH["token"], "config")): - if value: - return value, src - tok = os.environ.get(_CFG["token_env"] or "GITHUB_TOKEN") - return (tok, "env") if tok else (None, "missing") - - -_RATE = {"remaining": None} - - -def graphql(query, tok, variables=None): - body = json.dumps({"query": query, "variables": variables or {}}).encode() - req = urllib.request.Request(API, data=body, headers={ - "Authorization": "Bearer " + tok, - "Content-Type": "application/json", - "User-Agent": "terminal-toys", - }) - with urllib.request.urlopen(req, timeout=45) as r: - data = json.load(r) - if data.get("errors"): - raise ValueError(data["errors"][0].get("message", "")[:100]) - return data["data"] - - -PR_FIELDS = """ - number title url isDraft createdAt updatedAt - additions deletions changedFiles - author { login } - repository { nameWithOwner } - headRefName baseRefName reviewDecision mergeable - stackEntry { position stack { number size } } - commits(last: 1) { nodes { commit { statusCheckRollup { state } } } }""" - - -def list_query(queries, limit): - """One request, one aliased search per source. - - The ceiling is on result nodes rather than field complexity: three - searches of 100 return HTTP 502 with or without the check rollup, three - of 50 do not. So the page size is per source and deliberately modest. - """ - parts = ["rateLimit { remaining }"] - for i, q in enumerate(queries): - parts.append('s%d: search(query: %s, type: ISSUE, first: %d) ' - '{ issueCount nodes { ... on PullRequest { %s } } }' - % (i, json.dumps(q), limit, PR_FIELDS)) - return "{ %s }" % " ".join(parts) - -DETAIL_QUERY = """ -query($owner: String!, $name: String!, $number: Int!) { - repository(owner: $owner, name: $name) { - pullRequest(number: $number) { - number title url state isDraft createdAt updatedAt - additions deletions changedFiles - author { login } headRefName baseRefName - mergeable mergeStateStatus reviewDecision - commitCount: commits { totalCount } - stack { number size baseRefName - entries(first: 40) { nodes { position pullRequest { - number title isDraft reviewDecision mergeable - additions deletions author { login } headRefName } } } } - reviewThreads(first: 60) { nodes { isResolved } } - reviews(last: 20) { nodes { author { login } state submittedAt } } - reviewRequests(first: 12) { nodes { requestedReviewer { - ... on User { login } ... on Team { name } } } } - commits(last: 1) { nodes { commit { statusCheckRollup { - state contexts(first: 25) { nodes { - ... on CheckRun { name conclusion status startedAt completedAt } - ... on StatusContext { context state } } } } } } } - } - } -}""" - -# every open PR in one repository, for reconstructing a stack that was not -# made with `gh stack` - the API's own stack field is authoritative when it -# is there, and null everywhere else -REPO_PRS_QUERY = """ -query($owner: String!, $name: String!) { - repository(owner: $owner, name: $name) { - pullRequests(states: OPEN, first: 100) { - nodes { number title isDraft headRefName baseRefName - additions deletions author { login } - reviewDecision mergeable } - } - } -}""" - - -def parse(ts): - if not ts: - return None - try: - return datetime.datetime.strptime(ts[:19], "%Y-%m-%dT%H:%M:%S").replace( - tzinfo=datetime.timezone.utc) - except ValueError: - return None - - -def ago(ts): - when = parse(ts) if isinstance(ts, str) else ts - if not when: - return "--" - s = (datetime.datetime.now(datetime.timezone.utc) - when).total_seconds() - if s < 3600: - return "%dm" % max(1, int(s // 60)) - if s < 86400: - return "%dh" % int(s // 3600) - if s < 86400 * 365: - return "%dd" % int(s // 86400) - return "%.1fy" % (s / (86400 * 365.0)) - - -def rollup(pr): - node = (pr.get("commits") or {}).get("nodes") or [] - if not node: - return None - return ((node[0].get("commit") or {}).get("statusCheckRollup") or {}).get( - "state") - - -def stack_of(pr, repo_prs): - """The chain this PR belongs to, newest-first from the trunk. - - GitHub's own `stack` is used when present. Otherwise the chain is - reconstructed: a PR whose base branch is another open PR's head branch is - sitting on top of it. That inference produces a tree rather than a line, - so each PR keeps its list of children. - """ - by_head = {} - for other in repo_prs: - by_head[other["headRefName"]] = other - parent = {} - kids = {} - for other in repo_prs: - up = by_head.get(other["baseRefName"]) - if up and up["number"] != other["number"]: - parent[other["number"]] = up["number"] - kids.setdefault(up["number"], []).append(other["number"]) - if pr["number"] not in parent and pr["number"] not in kids: - return None, {}, {} - root = pr["number"] - seen = set() - while root in parent and root not in seen: - seen.add(root) - root = parent[root] - return root, parent, kids - - -class Store(object): - def __init__(self, extra): - self.lock = threading.Lock() - self.extra = extra - self.viewer = None - self.orgs = [] - self.query = "" - self.prs = [] - self.total = 0 - self.capped = [] - self.target = "" - self.detail = None # the open PR's full record - self.stack_rows = [] # (depth, pr, is_current) for the stack map - self.want = None # (owner, name, number) to fetch detail for - self.loading_detail = False - self.stages = [] # what the open is actually doing, live - self.error = None - self.fetched = 0 - self.wake = threading.Event() - - def snapshot(self): - with self.lock: - return (list(self.prs), self.total, self.detail, - list(self.stack_rows), self.loading_detail, self.error, - self.fetched, self.query, list(self.stages)) - - def searches(self): - """Each configured source, with `@mine` expanded and args appended. - - Repeated qualifiers of the same kind are OR'd by GitHub, so one - search covers every org and your own account at once; relationships - that reach outside them - authored, assigned - need their own. - """ - mine = " ".join(["org:%s" % o for o in self.orgs] - + (["user:%s" % self.viewer] if self.viewer else [])) - out = [] - for name, q in _CFG["sources"].items(): - out.append((name, " ".join([q.replace("@mine", mine)] - + self.extra))) - return out - - def open_detail(self, pr): - with self.lock: - owner, _, name = pr["repository"]["nameWithOwner"].partition("/") - self.want = (owner, name, pr["number"]) - self.detail, self.stack_rows = None, [] - self.loading_detail = True - self.target = "%s/%s #%d" % (owner, name, pr["number"]) - self.stages = [] - self.wake.set() - - def close_detail(self): - with self.lock: - self.want, self.detail, self.stack_rows = None, None, [] - self.loading_detail = False - self.stages = [] - - def run(self): - # A daemon thread that raises just stops, and a dead poller looks - # exactly like a source with no data - which is how deployments.py - # showed "0 deploys" for a day after an import went missing. - try: - self.poll() - except Exception as e: - with self.lock: - self.error = "poller stopped: %s: %s" % (type(e).__name__, - str(e)[:70]) - - def poll(self): - while True: - tok, source = token() - if not tok: - with self.lock: - self.error = ("no token: set github.token in config.json " - "or $GITHUB_TOKEN") - self.wake.wait(REFRESH) - self.wake.clear() - continue - try: - with self.lock: - want = self.want - have = (self.detail or {}).get("number") - if want and want[2] != have: - self.fetch_detail(tok, want) - self.fetch_list(tok, source) - except urllib.error.HTTPError as e: - with self.lock: - self.error = "HTTP %s from GitHub%s" % ( - e.code, " (token scope?)" if e.code == 403 else "") - self.loading_detail = False - except Exception as e: - with self.lock: - self.error = "%s: %s" % (type(e).__name__, str(e)[:70]) - self.loading_detail = False - self.wake.wait(REFRESH) - self.wake.clear() - - def fetch_list(self, tok, source): - if self.viewer is None: - who = graphql("{ viewer { login organizations(first:20)" - " { nodes { login } } } }", tok)["viewer"] - with self.lock: - self.viewer = who["login"] - self.orgs = [o["login"] for o in who["organizations"]["nodes"]] - pairs = self.searches() - d = graphql(list_query([q for _n, q in pairs], int(_CFG["limit"])), tok) - rate = d.get("rateLimit") or {} - if rate.get("remaining") is not None: - _RATE["remaining"] = rate["remaining"] - # pool the sources, remembering which found each PR and noting when a - # source filled its page, so a truncated union is not read as a total - pool, capped = {}, [] - for i, (name, _q) in enumerate(pairs): - block = d["s%d" % i] - got = [n for n in block["nodes"] if n] - if block["issueCount"] > len(got): - capped.append(name) - for n in got: - pool.setdefault(n["url"], dict(n, sources=[]))["sources"].append(name) - nodes = list(pool.values()) - with self.lock: - self.query = ", ".join(n for n, _q in pairs) - self.capped = capped - self.prs = nodes - self.total = len(nodes) - self.fetched = time.time() - self.error = (config_token_warning() if source == "config" else None) - - def stage(self, label, state, started=None): - """Record what the open is doing, so the wait can show real work.""" - with self.lock: - for st in self.stages: - if st["label"] == label: - st["state"] = state - st["took"] = time.time() - (started or st["t0"]) - return st["t0"] - self.stages.append({"label": label, "state": state, - "t0": time.time(), "took": 0.0}) - return self.stages[-1]["t0"] - - def fetch_detail(self, tok, want): - owner, name, number = want - t0 = self.stage("pull request, checks, reviews", "running") - d = graphql(DETAIL_QUERY, tok, {"owner": owner, "name": name, - "number": number}) - self.stage("pull request, checks, reviews", "done", t0) - pr = (d.get("repository") or {}).get("pullRequest") - rows = [] - if pr: - native = pr.get("stack") - if native: - self.stage("stack, from GitHub", "done") - # GitHub hands the order over directly, position 1 nearest the - # base. A native stack is a line, not a tree, so it draws flat - # - eleven levels of indentation would be unreadable and would - # imply a branching that is not there. - entries = sorted(native["entries"]["nodes"], - key=lambda x: x.get("position") or 0) - for i, e in enumerate(entries): - child = e["pullRequest"] - twig = "└─ " if i == len(entries) - 1 else "├─ " - rows.append((twig, child, child["number"] == number, - e.get("position"))) - else: - t1 = self.stage("stack, from open branches", "running") - repo = graphql(REPO_PRS_QUERY, tok, - {"owner": owner, "name": name}) - self.stage("stack, from open branches", "done", t1) - others = (repo.get("repository") or {}).get( - "pullRequests", {}).get("nodes", []) - root, parent, kids = stack_of(pr, others) - if root is not None: - by_num = dict((o["number"], o) for o in others) - - def walk(num, prefix, last): - # an inferred stack really is a tree - one PR here has - # two others branched off it - so draw the connectors - # properly rather than indenting by depth alone - node = by_num.get(num) - if node: - rows.append((prefix + ("└─ " if last else "├─ "), - node, num == number, None)) - children = sorted(kids.get(num, [])) - below = prefix + (" " if last else "│ ") - for i, kid in enumerate(children): - walk(kid, below, i == len(children) - 1) - - walk(root, "", True) - with self.lock: - self.detail = pr - self.stack_rows = rows - self.loading_detail = False - - -def hours_since(ts): - when = parse(ts) - if not when: - return None - return (datetime.datetime.now(datetime.timezone.utc) - - when).total_seconds() / 3600.0 - - -def span(hours): - if hours is None: - return "--" - if hours < 48: - return "%dh" % int(hours) - days = hours / 24.0 - return "%dd" % int(days) if days < 365 else "%.1fy" % (days / 365.0) - - -def ready_to_merge(pr): - """Approved, green, no conflict, not a draft - the actionable count. - - Everything else on this board describes work in flight; this is the one - number that says something can be done right now. - """ - return (pr.get("reviewDecision") == "APPROVED" - and rollup(pr) in ("SUCCESS", None) - and pr.get("mergeable") != "CONFLICTING" - and not pr.get("isDraft")) - - -def stats_view(prs, w): - """Shape and age of every open PR, whatever the list is filtered to. - - Deliberately not the filtered set. Typing in the filter is a search, and - a search should not move the backlog it is searching: watching the age - median and the state bar lurch on every keystroke made them unreadable - and, worse, made them look like statements about the whole board when - they described three matching rows. - - The list below says how many of how many it is showing; these say what - the board is. - """ - rows = [""] - if not prs: - return rows - n = len(prs) - review = {"APPROVED": 0, "CHANGES_REQUESTED": 0, "REVIEW_REQUIRED": 0, - None: 0} - checks = {"SUCCESS": 0, "FAILURE": 0, "PENDING": 0, "other": 0} - drafts = conflicts = ready = 0 - for pr in prs: - review[pr.get("reviewDecision") if pr.get("reviewDecision") in review - else None] += 1 - state = rollup(pr) - checks[state if state in checks else "other"] += 1 - drafts += 1 if pr.get("isDraft") else 0 - conflicts += 1 if pr.get("mergeable") == "CONFLICTING" else 0 - ready += 1 if ready_to_merge(pr) else 0 - - rows.append(seg([(LBL, " ── STATE ── "), (TXT, "%d" % n), - (DIM, " open · "), (DIM, "%d draft" % drafts), - (DIM, " · "), - (BAD if conflicts else DIM, "%d conflicting" % conflicts), - (DIM, " · "), - (OK if ready else DIM, "%d ready to merge" % ready)], - w - 1)) - order = [("APPROVED", OK), ("CHANGES_REQUESTED", BAD), - ("REVIEW_REQUIRED", WARN), (None, DIM)] - parts = [(review[k] / float(n), c) for k, c in order if review[k]] - rows.append(seg([(RST, " ")] + stacked_bar(parts, max(10, w - 3)), w - 1)) - key = [(RST, " ")] - for k, colour in order: - if review[k]: - key += [(colour, "▇ "), (TXT, REVIEW_LABEL[k][0]), - (DIM, " %d " % review[k])] - for k, colour, label in (("SUCCESS", OK, "checks pass"), - ("FAILURE", BAD, "checks FAIL"), - ("PENDING", WARN, "running")): - if checks[k]: - key += [(colour, "· "), (TXT, label), (DIM, " %d " % checks[k])] - rows.append(seg(key, w - 1)) - - ages = sorted((hours_since(p.get("createdAt")), p) for p in prs - if hours_since(p.get("createdAt")) is not None) - idles = [(hours_since(p.get("updatedAt")), p) for p in prs - if hours_since(p.get("updatedAt")) is not None] - - # ── when the open ones arrived ────────────────────────────────────── - today = datetime.date.today() - days = [(today - datetime.timedelta(days=k)).isoformat() - for k in range(OPENED_DAYS - 1, -1, -1)] - per_day = dict((d, 0) for d in days) - inside = 0 - for pr in prs: - key = (pr.get("createdAt") or "")[:10] - if key in per_day: - per_day[key] += 1 - inside += 1 - avail = max(10, w - 3) - slot = max(1, avail // len(days)) - gap = 1 if slot >= 3 else 0 - barw = slot - gap - cols = [] - for i, d in enumerate(days): - cols.extend([(per_day[d], PR)] * barw) - if gap and i < len(days) - 1: - cols.extend([(0, PR)] * gap) - peak = max(per_day.values()) if per_day else 0 - rows.append("") - rows.append(seg([(LBL, " ── OPENED / DAY ── "), - (DIM, "last %dd · " % OPENED_DAYS), - (TXT, "%d" % inside), (DIM, " of %d still open · " % n), - (DIM, "peak %d/day" % peak)], w - 1)) - if peak: - for line in vbars(cols, 3): - rows.append(seg([(RST, " ")] + line, w - 1)) - rows.append(seg([(RST, " "), (GRID, "─" * len(cols))], w - 1)) - left = "%dd ago" % OPENED_DAYS - rows.append(seg([(DIM, " " + left), - (DIM, " " * max(1, len(cols) - len(left) - 5)), - (DIM, "today")], w - 1)) - else: - rows.append(seg([(DIM, " none of the open PRs were opened in the " - "last %dd" % OPENED_DAYS)], w - 1)) - - # ── how old they are ──────────────────────────────────────────────── - def at(pairs, frac): - if not pairs: - return None - vals = sorted(x[0] for x in pairs) - return vals[min(len(vals) - 1, int(len(vals) * frac))] - - def worst(pairs, colour): - if not pairs: - return ("--", DIM) - hours, pr = max(pairs, key=lambda x: x[0]) - return ("#%d %s" % (pr["number"], span(hours)), colour) - - rows.append("") - rows.append(seg([(LBL, " ── AGE ── "), - (DIM, "median "), (TXT, span(at(ages, 0.5))), - (DIM, " p95 "), (TXT, span(at(ages, 0.95))), - (DIM, " max "), (WARN, span(at(ages, 1.0))), - (DIM, " idle median "), (TXT, span(at(idles, 0.5)))], - w - 1)) - if ages: - # One bar per open PR, youngest left to oldest right - the x axis is - # rank, not time. It fills the pane and carries a baseline and end - # labels, because a sparkline that stops in the middle of the screen - # gives no way to tell where the chart ends and the blank begins. - room = max(10, w - 3) - drawn = ages[-room:] if len(ages) > room else ages - # spread the remainder across the leftmost bars so the chart reaches - # the right edge exactly: stopping short of it left no way to tell a - # finished chart from a truncated one - if len(drawn) >= room: - slot, extra = 1, 0 - else: - slot, extra = divmod(room, len(drawn)) - hi = max(x[0] for x in drawn) or 1 - bars = [] - for i, (hours, _pr) in enumerate(drawn): - wide_bar = slot + (1 if i < extra else 0) - bars.extend([SPARK[min(7, int(hours / hi * 7.99))]] * wide_bar) - rows.append(seg([(RST, " "), (heat(0.4), "".join(bars))], w - 1)) - rows.append(seg([(RST, " "), (GRID, "─" * len(bars))], w - 1)) - left = "youngest %s" % span(drawn[0][0]) - right = "oldest %s" % span(drawn[-1][0]) - note = ("%d of %d PRs" % (len(drawn), len(ages)) - if len(drawn) < len(ages) else "%d PRs" % len(drawn)) - mid = max(1, len(bars) - len(left) - len(right) - len(note) - 2) - rows.append(seg([(DIM, " " + left), - (DIM, " " * (mid // 2)), (GRID, note), - (DIM, " " * (mid - mid // 2 + 2)), - (DIM, right)], w - 1)) - fattest = max(prs, key=lambda p: (p.get("additions") or 0) - + (p.get("deletions") or 0)) - old_txt, old_col = worst(ages, WARN) - idle_txt, idle_col = worst(idles, WARN) - rows.append(seg([(DIM, " oldest "), (old_col, pad(old_txt, 12)), - (DIM, " untouched longest "), (idle_col, pad(idle_txt, 12)), - (DIM, " biggest "), - (TXT, "#%d +%d/-%d" % (fattest["number"], - fattest["additions"], - fattest["deletions"]))], w - 1)) - return rows - - -def sort_prs(prs, field, newest_first): - key = "updatedAt" if field == "updated" else "createdAt" - return sorted(prs, key=lambda p: p.get(key) or "", reverse=newest_first) - - -def matches(pr, needle): - if not needle: - return True - hay = " ".join([ - str(pr.get("number") or ""), pr.get("title") or "", - (pr.get("author") or {}).get("login") or "", - (pr.get("repository") or {}).get("nameWithOwner") or "", - pr.get("headRefName") or "", pr.get("baseRefName") or "", - ]).lower() - return needle.lower() in hay - - -def main(): - maybe_help(__doc__) - args = sys.argv[1:] - while args and args[0] in ("-n", "--refresh"): - global REFRESH - REFRESH = float(args[1]) - args = args[2:] - store = Store(args) - threading.Thread(target=store.run, daemon=True).start() - setup() - keyboard = Keyboard() - selected, tick, first = 0, 0, 0 - sort_field, newest_first = SORTS[0], True - needle, typing = "", False - show_stats = True - stack_sel = 0 - copied, copied_at = "", 0.0 - source_filter = "all" - - while True: - tick += 1 - (prs, total, detail, stack_rows, loading, err, fetched, - active_query, stages) = store.snapshot() - shown = [p for p in sort_prs(prs, sort_field, newest_first) - if matches(p, needle) - and (source_filter == "all" - or source_filter in (p.get("sources") or []))] - - for key in keyboard.poll(): - if typing: - # while filtering, keys are text - only escape and enter are - # navigation, or the filter could never contain "q" - if key == "esc": - needle, typing = "", False - elif key == "enter": - typing = False - elif key == "backspace": - needle = needle[:-1] - elif len(key) == 1 and key.isprintable(): - needle += key - continue - if key in ("q", "Q"): - raise SystemExit(0) - if key == "/": - typing = True - elif key == "esc": - if detail or loading: - store.close_detail() - stack_sel = 0 - else: - needle = "" - elif key == "enter": - if detail and stack_rows: - # walk the stack from inside the stack: the row under the - # cursor becomes the PR on screen - node = stack_rows[min(stack_sel, - len(stack_rows) - 1)][1] - owner_repo = "/".join( - (detail.get("url") or "").split("/")[3:5]) - if owner_repo and node["number"] != detail["number"]: - store.open_detail({"repository": - {"nameWithOwner": owner_repo}, - "number": node["number"]}) - stack_sel = 0 - elif shown and not detail and not loading: - store.open_detail(shown[min(selected, len(shown) - 1)]) - elif key == "c": - # the URL of whatever is on screen: the open PR in the - # dashboard, the highlighted row in the list - target = detail if detail else ( - shown[min(selected, len(shown) - 1)] if shown else None) - url = (target or {}).get("url") - if url: - copied = url if clipboard(url) else "no clipboard: " + url - copied_at = time.time() - elif key == "r": - store.wake.set() - elif key == "f": - # every PR remembers which sources found it, so narrowing to - # one is instant and costs no request - names = ["all"] + list(_CFG["sources"].keys()) - source_filter = cycle(names, source_filter) - elif key == "s": - sort_field = cycle(SORTS, sort_field) - elif key == "o": - newest_first = not newest_first - elif key == "t": - show_stats = not show_stats - elif key == "up": - if detail: - stack_sel = max(0, stack_sel - 1) - else: - selected = max(0, selected - 1) - elif key == "down": - if detail: - stack_sel += 1 - else: - selected += 1 - - w, h = size() - rows = [title("pr watch", w, PR)] - head = [(DIM, " %d of %d" % (len(shown), total)), - (DIM, " shown" if needle or source_filter != "all" else " open"), - (DIM, " updated %s ago" % ago( - datetime.datetime.fromtimestamp(fetched, - datetime.timezone.utc) - if fetched else None))] - if _RATE["remaining"] is not None: - head.append((DIM, " %d api" % _RATE["remaining"])) - if copied and time.time() - copied_at < 4: - head.append((OK, " copied ")) - head.append((DIM, copied[:max(10, w - 46)])) - rows.append(seg(head, w - 1)) - if err: - rows.append(seg([(BAD, " ! " + err)], w - 1)) - - if detail or loading: - if stack_rows: - stack_sel = max(0, min(stack_sel, len(stack_rows) - 1)) - rows += detail_view(detail, stack_rows, stack_sel, loading, w, h, - tick, stages, store.target, top=len(rows)) - hints = [[(DIM, "[c]opy url")], [(DIM, "[esc] back")], - [(DIM, "[r]efresh")], [(DIM, "[q]uit")]] - if stack_rows: - hints = ([[(ACCENT, "↑↓"), (DIM, " stack")], - [(DIM, "[↵] open it")]] + hints) - else: - selected = max(0, min(selected, len(shown) - 1)) if shown else 0 - # the stats cost eight rows; below thirty they would leave the - # list too short to be a list, so they stand down without asking - if show_stats and h >= 30: - # every open PR, not `shown`: the filter is a search of the - # board, not a redefinition of it - rows += stats_view(sort_prs(prs, sort_field, newest_first), w) - rows += list_view(shown, selected, sort_field, newest_first, - needle, typing, w, h, tick, not fetched, - source_filter, top=len(rows)) - hints = [[(ACCENT, "↑↓"), (DIM, " select")], [(DIM, "[↵] open")], - [(DIM, "[/]filter")], - [(DIM, "[s]ort %s" % sort_field)], - [(DIM, "[o]rder %s" % ("newest" if newest_first - else "oldest"))], - [(DIM, "[f]rom %s" % source_filter)], - [(DIM, "[t]stats %s" % ("on" if show_stats else "off"))], - [(DIM, "[c]opy url")], [(DIM, "[r]efresh")], - [(DIM, "[q]uit")]] - if typing: - hints = [[(ACCENT, "/" + needle + "▌")], - [(DIM, "[↵] keep")], [(DIM, "[esc] clear")]] - footer = [" " + line for line in pack_hints(hints, w - 2)] - rows = rows[:h - len(footer)] - while len(rows) < h - len(footer): - rows.append("") - rows.extend(footer) - draw(rows, w, h) - time.sleep(0.3) - - -def list_view(prs, selected, sort_field, newest_first, needle, typing, - w, h, tick, waiting, source_filter="all", top=0): - rows = [""] - arrow = "↓" if newest_first else "↑" - rows.append(seg([(LBL, " ── OPEN PRs ── "), - (DIM, "by %s %s" % (sort_field, arrow)), - (DIM, " from %s" % source_filter - if source_filter != "all" else ""), - (ACCENT, " /%s" % needle if needle else "")], w - 1)) - if not prs: - # "collecting" is only true before the first fetch: an empty filter - # or an empty source is a result, not a wait - if needle: - why = " nothing matches /%s" % needle - elif source_filter != "all": - why = " no open PRs from %s" % source_filter - elif waiting: - why = " collecting…" - else: - why = " no open PRs" - rows.append(seg([(DIM, why)], w - 1)) - return rows - - # Columns are budgeted rather than guessed: the fixed ones are summed and - # the title takes exactly what is left, so nothing runs off the right edge - # or into its neighbour. - wide = w >= 96 - repo_w = 18 if wide else 0 - size_w = 12 if wide else 0 - fixed = 8 + repo_w + 13 + 8 + 6 + size_w - title_w = max(16, w - 1 - fixed) - head = " %-7s" % "PR" - if repo_w: - head += "%-*s" % (repo_w, "REPO") - # the time column follows the sort, so the number you ordered by is the - # number you can see. Labelling both "AGE" had it reporting idle time - # while the stats above reported true age, and the two disagreed. - when_label = "AGE" if sort_field == "created" else "IDLE" - head += "%-*s%13s%8s%6s" % (title_w, "TITLE", "REVIEW", "CHECKS", - when_label) - if size_w: - head += "%*s" % (size_w, "SIZE") - rows.append(DIM + pad(head, w - 1)) - - # `top` is what was drawn above this view. Without it the window is sized - # as though the list began at the top of the screen, so it renders far more - # rows than are visible, the caller truncates the overflow, and the - # selection scrolls off the bottom while `first` is still 0. - room = max(1, h - top - len(rows) - 3) - first = 0 - if len(prs) > room: - first = min(max(0, selected - room // 2), len(prs) - room) - for i, pr in list(enumerate(prs))[first:first + room]: - here = i == selected - tint = bg(38, 56, 76) if here else "" - rlabel, rcol = REVIEW_LABEL.get(pr.get("reviewDecision"), - REVIEW_LABEL[None]) - clabel, ccol = CHECK_LABEL.get(rollup(pr), CHECK_LABEL[None]) - stacked = bool(pr.get("stackEntry")) - line = [(tint + (ACCENT if here else PR), - ("▸" if here else " ") + pad("#%d" % pr["number"], 7))] - if repo_w: - # clip one short of the column so it never touches the title - repo = pr["repository"]["nameWithOwner"].split("/")[-1] - line.append((tint + DIM, pad(repo[:repo_w - 1], repo_w))) - name = ("⣿ " if stacked else "") + (pr.get("title") or "") - if pr.get("isDraft"): - name = "draft · " + name - line += [(tint + TXT, pad(name[:title_w - 1], title_w)), - (tint + rcol, "%13s" % rlabel), - (tint + ccol, "%8s" % clabel), - (tint + DIM, "%6s" % ago(pr.get( - "createdAt" if sort_field == "created" - else "updatedAt")))] - if size_w: - line.append((tint + DIM, "%*s" % (size_w, "+%d/-%d" - % (pr["additions"], - pr["deletions"])))) - if here: - line.append((tint, " " * w)) - rows.append(seg(line, w - 1)) - return rows - - -def detail_view(pr, stack_rows, stack_sel, loading, w, h, tick, stages=(), - target="", top=0): - rows = [""] - if loading or not pr: - # A shimmer says "wait" and nothing else. The open really does run in - # stages, so show them: a spinner on the one in flight, a tick and a - # duration on the ones behind it. Honest, and it reads like a machine - # doing something rather than a placeholder. - rows.append(seg([(LBL, " ── OPENING ── "), (ACCENT, target)], w - 1)) - rows.append("") - spin = SPINNER[tick % len(SPINNER)] - for st in stages: - done = st["state"] == "done" - rows.append(seg([ - (OK if done else ACCENT, " %s " % ("✓" if done else spin)), - (TXT if done else DIM, pad(st["label"], max(20, w - 22))), - (DIM, "%6s" % ("%.1fs" % st["took"] if st["took"] else ""))], - w - 1)) - if not stages: - rows.append(seg([(ACCENT, " %s " % spin), - (DIM, "connecting")], w - 1)) - rows.append("") - # one sweeping line rather than four fat bars of shimmer - rows.append(seg([(RST, " ")] + skeleton(max(10, w - 6), tick * 2), - w - 1)) - return rows - - draft = " · draft" if pr.get("isDraft") else "" - rows.append(seg([(PR, " #%d " % pr["number"]), - (TXT, (pr.get("title") or "")[:max(10, w - 24)]), - (DIM, draft)], w - 1)) - rows.append(seg([(DIM, " "), (DIM, (pr.get("author") or {}).get("login") - or "?"), - (DIM, " "), (ACCENT, pr.get("headRefName") or "?"), - (DIM, " → "), (ACCENT, pr.get("baseRefName") or "?")], - w - 1)) - - rlabel, rcol = REVIEW_LABEL.get(pr.get("reviewDecision"), - REVIEW_LABEL[None]) - mlabel, mcol = MERGE_LABEL.get(pr.get("mergeStateStatus"), - MERGE_LABEL[None]) - threads = (pr.get("reviewThreads") or {}).get("nodes") or [] - unresolved = sum(1 for t in threads if not t.get("isResolved")) - rows.append("") - cells = [("review", rlabel, rcol), - ("merge", mlabel, mcol), - ("unresolved threads", str(unresolved), - BAD if unresolved else OK), - ("size", "+%d/-%d in %d files" % (pr["additions"], pr["deletions"], - pr["changedFiles"]), TXT), - ("commits", str((pr.get("commitCount") or {}).get("totalCount") - or 0), TXT), - ("opened / updated", "%s ago / %s ago" % (ago(pr.get("createdAt")), - ago(pr.get("updatedAt"))), - TXT)] - label_w = max(len(c[0]) for c in cells) - ncols = 2 if (w - 2) // 2 - label_w - 3 >= 18 else 1 - cw = (w - 2) // ncols - val_w = max(6, cw - label_w - 3) - for n in range(0, len(cells), ncols): - line = [(RST, " ")] - for label, value, colour in cells[n:n + ncols]: - line += [(DIM, " " + pad(label, label_w) + " "), - (colour, pad(value, val_w))] - rows.append(seg(line, w - 1)) - - # ── who has looked at it ───────────────────────────────────────────── - # last state per person wins: someone who requested changes and later - # approved has approved, and showing both would misreport the gate - latest = {} - for r in (pr.get("reviews") or {}).get("nodes") or []: - who = (r.get("author") or {}).get("login") - if who: - latest[who] = r.get("state") - pending = [] - for n in (pr.get("reviewRequests") or {}).get("nodes") or []: - who = n.get("requestedReviewer") or {} - name = who.get("login") or who.get("name") - if name and name not in latest: - pending.append(name) - groups = [("approved", OK, [k for k, v in latest.items() if v == "APPROVED"]), - ("changes requested", BAD, - [k for k, v in latest.items() if v == "CHANGES_REQUESTED"]), - ("commented", DIM, - [k for k, v in latest.items() if v == "COMMENTED"]), - ("awaiting", WARN, pending)] - rows.append("") - live = [g for g in groups if g[2]] - rows.append(seg([(LBL, " ── REVIEWERS ── "), - (DIM, "nobody has been asked" if not live - else " · ".join("%d %s" % (len(g[2]), g[0]) - for g in live))], w - 1)) - for label, colour, who in live: - rows.append(seg([(DIM, " " + pad(label, 18)), - (colour, ", ".join(sorted(who))[:max(10, w - 24)])], - w - 1)) - - # ── checks ─────────────────────────────────────────────────────────── - node = ((pr.get("commits") or {}).get("nodes") or [{}]) - roll = ((node[0].get("commit") or {}).get("statusCheckRollup") - if node else None) - rows.append("") - if not roll: - rows.append(seg([(LBL, " ── CHECKS ── "), - (DIM, "none on the last commit")], w - 1)) - else: - state, scol = CHECK_LABEL.get(roll.get("state"), CHECK_LABEL[None]) - ctx = [c for c in (roll.get("contexts") or {}).get("nodes") or [] if c] - rows.append(seg([(LBL, " ── CHECKS ── "), (scol, state), - (DIM, " %d total" % len(ctx))], w - 1)) - bad = [c for c in ctx if (c.get("conclusion") or c.get("state")) - not in ("SUCCESS", "NEUTRAL", "SKIPPED", None)] - # failures first: a green wall of passing checks is not why anyone - # opens this view - for c in (bad + [c for c in ctx if c not in bad])[:8]: - name = c.get("name") or c.get("context") or "?" - verdict = c.get("conclusion") or c.get("state") or c.get("status") - lab, col = CHECK_LABEL.get(verdict, (str(verdict or "—").lower(), - DIM)) - took = "" - a, b = parse(c.get("startedAt")), parse(c.get("completedAt")) - if a and b: - took = "%ds" % int((b - a).total_seconds()) - rows.append(seg([(DIM, " "), (TXT, pad(name, max(12, w - 30))), - (col, "%10s" % lab), (DIM, "%8s" % took)], w - 1)) - - # ── the stack, when there is one ───────────────────────────────────── - if stack_rows: - native = bool(pr.get("stack")) - rows.append("") - # the stack scrolls: eleven-deep stacks exist, and a pane that has - # already spent its height on checks cannot show them all - room = max(3, h - top - len(rows) - 4) - first = 0 - if len(stack_rows) > room: - first = min(max(0, stack_sel - room // 2), len(stack_rows) - room) - rows.append(seg([(LBL, " ── STACK ── "), - (DIM, "%d pull requests · %s" % ( - len(stack_rows), - "from GitHub" if native - else "inferred from branches")), - (ACCENT, " ↑↓ %d-%d of %d" - % (first + 1, min(first + room, len(stack_rows)), - len(stack_rows)) - if len(stack_rows) > room else "")], w - 1)) - rows.append(seg([(DIM, " merge bottom-up: "), - (TXT, "the one nearest the base branch first"), - (DIM, " ▸ cursor · ● on screen")], w - 1)) - base = pr.get("baseRefName") if not native else ( - pr["stack"].get("baseRefName") or "") - rows.append(seg([(DIM, " "), (ACCENT, base or "trunk")], w - 1)) - for idx, (twig, node, is_here, position) in list( - enumerate(stack_rows))[first:first + room]: - lab, col = REVIEW_LABEL.get(node.get("reviewDecision"), - REVIEW_LABEL[None]) - merge = node.get("mergeable") - mlab, mcol = (("CONFLICT", BAD) if merge == "CONFLICTING" - else ("ok", OK) if merge == "MERGEABLE" - else ("…", DIM)) - on_cursor = idx == stack_sel - tint = bg(38, 56, 76) if on_cursor else "" - name = (node.get("title") or "") - if position: - name = "%d. %s" % (position, name) - # two gutter marks, because they answer different questions: - # ▸ is where the cursor is, ● is the PR actually on screen. One - # symbol plus a colour could not say both. - gutter = ("▸" if on_cursor else " ") + ("●" if is_here else " ") - rows.append(seg([ - (tint + (ACCENT if on_cursor else DIM), gutter), - (tint + DIM, twig), - (tint + (ACCENT if on_cursor else PR), - "#%-5d " % node["number"]), - (tint + (TXT if (is_here or on_cursor) else DIM), - pad(name[:max(10, w - 34 - len(twig))], - max(10, w - 34 - len(twig)))), - (tint + col, "%13s" % lab), - (tint + mcol, "%10s" % mlab), - ] + ([(tint, " " * w)] if on_cursor else []), w - 1)) - return rows - - -main() diff --git a/rust/.gitignore b/rust/.gitignore deleted file mode 100644 index 2f7896d..0000000 --- a/rust/.gitignore +++ /dev/null @@ -1 +0,0 @@ -target/ diff --git a/start.py b/start.py deleted file mode 100755 index 929751a..0000000 --- a/start.py +++ /dev/null @@ -1,272 +0,0 @@ -#!/usr/bin/env python3 -# terminal-toys - small dependency-free terminal widgets -# Copyright (C) 2026 William Li -# -# This program is free software: you can redistribute it and/or modify -# it under the terms of the GNU Affero General Public License as published -# by the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU Affero General Public License for more details. -# -# You should have received a copy of the GNU Affero General Public License -# along with this program. If not, see <https://www.gnu.org/licenses/>. -"""Every widget here, what it does, and whether it will work on this machine. - -Thirteen scripts in a directory is a list you have to already know. This is -the front door: pick one and it runs, quit it and you are back here. - - python3 start.py [WIDGET] [ARGS...] - -Nothing is described twice. The name and the summary are each widget's own -first docstring line, and the note underneath is the paragraph that follows -it - both already maintained, and already checked by check.py, so a widget -cannot appear here saying something its own file does not. - -Nothing is said here about whether a widget will work. A widget that cannot -run says so itself, on its own screen, in its own words - which is where -somebody who has just tried to start it is already looking, and is the only -place that knows what it actually needs. - -Keys: up/down select, enter launches, r rechecks, q quits. -""" -import ast -import glob -import os -import subprocess -import sys -import termios -import time -import tty - -sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) -from common import (CLEAR, HIDE, HOME, RST, SHOW, Keyboard, bg, draw, flush, - maybe_help, out, pack_hints, pad, rgb, seg, setup, size, - title) - -HERE = os.path.dirname(os.path.abspath(__file__)) -# Not widgets: the shared library, the checker, and this. -NOT_A_WIDGET = ("common.py", "check.py", "start.py", - "__main__.py") - -DIM = rgb(127, 147, 172) -GRID = rgb(60, 78, 98) -TXT = rgb(225, 235, 245) -LBL = rgb(130, 165, 200) -ACCENT = rgb(150, 210, 255) - - - -def wrap(text, width): - """Break a paragraph at spaces, for the note under the list.""" - lines, rest = [], (text or "").strip() - while rest and len(lines) < 3: - if len(rest) <= width: - lines.append(rest) - break - cut = rest.rfind(" ", 0, width + 1) - cut = cut if cut > width // 2 else width - lines.append(rest[:cut]) - rest = rest[cut:].lstrip() - return lines - - -def widgets(): - """Every widget beside this script, with its own description of itself.""" - found = [] - for path in sorted(glob.glob(os.path.join(HERE, "*.py"))): - name = os.path.basename(path) - if name in NOT_A_WIDGET: - continue - try: - doc = ast.get_docstring(ast.parse(open(path).read())) or "" - except (OSError, SyntaxError): - doc = "" - lines = doc.splitlines() - # The first line is the row; the first paragraph under it is the - # aside, which is where each widget explains why it exists. Only - # that paragraph: what follows is the usage synopsis and the key - # list, which are for somebody reading --help, not somebody - # deciding whether this is the thing they want. - para = [] - for line in lines[2:]: - if line.startswith(" "): # an indented usage block - break - if not line.strip(): - if para: - break - continue - para.append(line.strip()) - about = " ".join(para) - found.append({"file": name, "stem": name[:-3], - "summary": lines[0] if lines else "", - "about": about[:400], "sample": sample(name[:-3])}) - return found - - -def sample(stem): - """The picture from this widget's doc page, if it has one. - - Every doc opens with a rendering of the widget it describes, kept by - whoever wrote it and read by whoever is deciding whether to run the - thing. Using that means no second copy of anything - and, more to the - point, no widget has to be started to be looked at. - """ - path = os.path.join(HERE, "docs", "%s.md" % stem) - try: - text = open(path).read() - except OSError: - return [] - block, inside = [], False - for line in text.splitlines(): - if line.startswith("```"): - if inside: - break - inside = True - continue - if inside: - block.append(line) - # Only a block that is actually a picture of the widget: the docs also - # hold shell snippets and JSON, and a config listing is not a preview. - return block if block and block[0].startswith("╺━") else [] - - -def rows_for(items, w, selected): - name_w = max(12, min(18, w - 58)) - # The column exists only if something is in it. With nothing to do on - # this machine - the common case - it takes no width at all and the - # descriptions get it instead. - # Every column keeps a space of its own, so a description that fills its - # width stops short of whatever is beside it rather than running into it. - text_w = max(8, (w - 1) - name_w - 6) - out_rows = [] - for i, item in enumerate(items): - here = i == selected - tint = bg(28, 44, 62) if here else "" - line = [(tint + (ACCENT if here else DIM), " ▸ " if here else " "), - (tint + (TXT if here else LBL), - pad(item["stem"][:name_w - 1], name_w)), - (tint + DIM, pad(item["summary"][:text_w - 1], text_w))] - if here: - line.append((tint, " " * w)) - out_rows.append(seg(line, w - 1)) - return out_rows - - -def run_widget(keyboard, item, extra=()): - """Hand the terminal over, and take it back when the widget exits.""" - keyboard.restore() - out(SHOW + RST + CLEAR + HOME) - flush() - try: - subprocess.call([sys.executable, - os.path.join(HERE, item["file"])] + list(extra)) - except OSError as exc: - out("%s\r\n" % exc) - flush() - # The widget left the terminal however it left it, so take it back - # rather than assuming: raw mode again, cursor away again, screen clear. - if keyboard.fd is not None: - try: - tty.setcbreak(keyboard.fd) - except (termios.error, ValueError): - pass - out(HIDE + CLEAR + HOME) - flush() - - -def collect(): - return widgets() - - -def main(): - args = sys.argv[1:] - items = collect() - # A widget name is resolved before --help is looked at, so that - # `start.py netwatch --help` is netwatch's help, not this one's. Every - # argument after the name belongs to the widget, including that one. - if args and not args[0].startswith("-"): - # A name, so run it straight away and pass the rest through: the menu - # is for browsing, not something to sit between you and a widget you - # already know the name of. - wanted = args[0][:-3] if args[0].endswith(".py") else args[0] - match = next((i for i in items if i["stem"] == wanted), None) - if match is None: - sys.stderr.write("no widget called %r - try: %s\n" - % (args[0], ", ".join(i["stem"] for i in items))) - raise SystemExit(2) - os.execv(sys.executable, [sys.executable, - os.path.join(HERE, match["file"])] + args[1:]) - - maybe_help(__doc__) - setup() - keyboard = Keyboard() - selected = 0 - while True: - for key in keyboard.poll(): - if key in ("q", "Q"): - raise SystemExit(0) - if key in ("up", "k", "K"): - selected -= 1 - elif key in ("down", "j", "J"): - selected += 1 - elif key in ("r", "R"): - items = collect() - elif key in ("enter", "right", "i") and items: - run_widget(keyboard, items[min(selected, len(items) - 1)]) - items = collect() - - w, h = size() - selected = max(0, min(selected, len(items) - 1)) if items else 0 - - body = [title("terminal toys", w, ACCENT)] - body.append(seg([(DIM, " %d widgets ↵ starts one, q leaves" - % len(items))], w - 1)) - body.append("") - if not items: - body.append(seg([(DIM, " No widgets beside this script.")], - w - 1)) - else: - body.extend(rows_for(items, w, selected)) - body.append("") - # What the highlighted one is for, in its own words - the rest of - # its opening paragraph, which the row has no room for. Not the - # command to run it: that is this screen's job, not the reader's. - pick = items[selected] if items else None - if pick and h - len(body) >= 3: - body.append(seg([(LBL, " ── %s ── " % pick["stem"].upper())], - w - 1)) - tall = h - len(body) >= 12 - for line in wrap(pick["about"], w - 4)[:1 if tall else 3]: - body.append(seg([(DIM, " " + line)], w - 1)) - - # And what it looks like. A picture from the docs rather than the - # widget itself: starting one to look at it would ping hosts, spend - # API quota and read the whole agent transcript tree, and browsing a - # menu should cost nothing at all. - # Measured against the footer that will actually be drawn, rather - # than a guess at its height. - hints = [[(ACCENT, "↑↓"), (DIM, " select")], - [(ACCENT, "↵"), (DIM, " launch")], - [(DIM, "[r]echeck")], [(DIM, "[q]uit")]] - foot = [" " + line for line in pack_hints(hints, w - 2)] - room = h - len(body) - len(foot) - shown = pick["sample"] if pick else [] - if shown and room >= 6 and w >= 44: - rule = "─" * max(1, w - 15) - body.append(seg([(GRID, " ┌── "), (DIM, "example"), - (GRID, " " + rule + "┐")], w - 1)) - for line in shown[:room - 1]: - body.append(seg([(GRID, " │"), (DIM, line[:w - 4])], w - 1)) - - while len(body) < h - len(foot): - body.append("") - body.extend(foot) - draw(body[:h], w, h) - time.sleep(0.15) - - -main() diff --git a/tailnet.py b/tailnet.py deleted file mode 100755 index 8bdefdf..0000000 --- a/tailnet.py +++ /dev/null @@ -1,893 +0,0 @@ -#!/usr/bin/env python3 -# terminal-toys - small dependency-free terminal widgets -# Copyright (C) 2026 William Li -# -# This program is free software: you can redistribute it and/or modify -# it under the terms of the GNU Affero General Public License as published -# by the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU Affero General Public License for more details. -# -# You should have received a copy of the GNU Affero General Public License -# along with this program. If not, see <https://www.gnu.org/licenses/>. -"""Tailscale network: who is online, and how you are reaching them. - -RX and TX are traffic between *this* host and that peer, counted by the local -WireGuard engine — not the peer's own totals. They reset when tailscaled -restarts, so they cover that window rather than all time. - -The column that matters is PATH. A peer is either DIRECT, meaning NAT traversal -succeeded and traffic goes peer-to-peer, or it is relayed through a named DERP -region, meaning every packet round-trips through Tailscale's infrastructure. -Relayed peers can be dramatically slower and the difference is invisible in -`tailscale status` output unless you look for it. - -Peers advertising subnet routes are flagged, since those only reach you if this -node runs with --accept-routes. - -The info view names each peer's home DERP region — the Tailscale POP nearest to -it — as a location hint. That comes from the local DERP map, so no address is -ever sent to a geolocation service. - - python3 tailnet.py [-n SECONDS] - -A live throughput section graphs peers currently moving data (toggle with g), -and the info view carries the same graph for the selected machine plus ICMP -latency over the tunnel — current, average, median, min, max, jitter, loss and -a sparkline — measured the same way the latency monitor does. Only the selected -peer is probed, so this costs one ping process regardless of tailnet size. - -n cycles the poll interval while running (1/2/5/10/30s), the same way the -latency monitor's i key does; the graph resolution follows it. -n sets the -starting value, and `tailnet.refresh` in config.json sets the default. - -Keys: up/down select a peer, Enter or i opens a full machine info view (every address, -routes, tags, owner, handshake times), c or Enter opens a copy sheet offering its -Tailscale IP, MagicDNS name, public IP and LAN IP, r refreshes now, o hides -offline peers, q quits. Copying uses OSC 52, so it reaches the clipboard of -the machine you are typing at even over SSH. - -Needs the `tailscale` CLI. Peer LAN addresses come from `tailscale debug -netmap`, which needs root; it is attempted with `sudo -n` and simply omitted -when that would prompt, so nothing here requires privilege. -""" -import collections -import json -import os -import re -import subprocess -import sys -import threading -import time - -sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) -from common import (RST, Keyboard, bg, clipboard, cycle, draw, load_config, - maybe_help, pack_hints, pad, rgb, seg, setup, size, title) - -_CFG = load_config("tailnet", {"refresh": 2.0, "history": 180}) -REFRESH = float(_CFG["refresh"]) -HISTORY = int(_CFG["history"]) # rate samples kept per peer -REFRESH_CHOICES = (1.0, 2.0, 5.0, 10.0, 30.0) # cycled at runtime with n -SPARK = "▁▂▃▄▅▆▇█" - -ONLINE = rgb(90, 240, 160) -OFFLINE = rgb(120, 130, 150) -DIRECT = rgb(90, 240, 160) -RELAY = rgb(255, 190, 90) -DIM = rgb(127, 147, 172) -TXT = rgb(225, 235, 245) -LBL = rgb(130, 165, 200) -ACCENT = rgb(120, 200, 255) -ROUTE = rgb(200, 160, 255) -EXIT = rgb(255, 140, 200) - - -def daemon_uptime(): - """Seconds since tailscaled started. - - Its byte counters live in memory and reset with it, so RX/TX cover this - window rather than all time — a peer reading 0B may just predate a restart. - """ - try: - for pid in os.listdir("/proc"): - if not pid.isdigit(): - continue - try: - with open("/proc/%s/comm" % pid) as f: - if f.read().strip() != "tailscaled": - continue - with open("/proc/%s/stat" % pid) as f: - started = int(f.read().rpartition(")")[2].split()[19]) - with open("/proc/uptime") as f: - up = float(f.read().split()[0]) - except (OSError, IndexError, ValueError): - continue - return up - started / float(os.sysconf("SC_CLK_TCK")) - except OSError: - pass - return None - - -def peer_name(peer): - """Tailnet-unique display name. - - HostName is whatever the device calls itself and is frequently useless: - iPads, Chromecasts and Pixels all report "localhost", and two Apple TVs - report the same "apple-tv". The first label of the MagicDNS name is unique - across the tailnet and matches what the admin console shows. - """ - dns = (peer.get("DNSName") or "").rstrip(".") - if dns: - return dns.split(".")[0] - return peer.get("HostName") or "?" - - -def classify(ip): - """public | private | tailscale | other, from the address alone.""" - ip = ip.split("%")[0] - if ":" in ip: - return "tailscale" if ip.lower().startswith("fd7a:") else "other" - try: - a, b = (int(x) for x in ip.split(".")[:2]) - except ValueError: - return "other" - if a == 100 and 64 <= b <= 127: - return "tailscale" # CGNAT range Tailscale itself uses - if a == 10 or (a == 172 and 16 <= b <= 31) or (a == 192 and b == 168): - return "private" - if a == 169 and b == 254: - return "other" # link-local - if a == 127: - return "other" - return "public" - - -def in_network(ip, cidr): - """Is an IPv4 address inside a CIDR block?""" - net, _, bits = cidr.partition("/") - if ":" in net or not bits: - return False - try: - bits = int(bits) - to_int = lambda a: sum(int(o) << (24 - 8 * i) - for i, o in enumerate(a.split("."))) - mask = (0xffffffff << (32 - bits)) & 0xffffffff - return (to_int(ip) & mask) == (to_int(net) & mask) - except (ValueError, IndexError): - return False - - -def lan_rank(ip, routes): - """Lower is better. Prefers a real LAN address over a virtual bridge. - - A peer often exposes several private endpoints, and docker0 (172.17.0.1) - or a k8s bridge is not the address anyone wants to copy. An address inside - a subnet the peer advertises is almost certainly its real LAN address. - """ - if any(in_network(ip, r) for r in routes): - return 0 - first, second = (int(x) for x in ip.split(".")[:2]) - if first == 192 and second == 168: - return 1 - if first == 10: - return 2 - return 3 # 172.16-31: usually docker/virtual - - -def endpoints_by_peer(): - """Peer LAN/public endpoints from the netmap, which needs root. - - Optional enrichment: `tailscale status` does not carry peer endpoints, so - without this the panel simply offers fewer addresses to copy. Uses sudo -n - so it fails instantly rather than prompting when sudo needs a password. - """ - try: - out = subprocess.run(["sudo", "-n", "tailscale", "debug", "netmap"], - capture_output=True, text=True, timeout=25) - data = json.loads(out.stdout) - except Exception: - return {} - found = {} - for peer in (data.get("Peers") or []): - name = (peer.get("Name") or "").rstrip(".") - if name: - found[name] = [e.split(":")[0] for e in (peer.get("Endpoints") or [])] - return found - - -_DERP = {} - - -def derp_regions(): - """DERP region code -> city, from the local map. - - A peer's home region is the Tailscale POP nearest to it, so this gives a - location hint without sending anyone's IP to a geolocation service. Cached: - the map changes rarely and is the same for every peer. - """ - if _DERP: - return _DERP - try: - out = subprocess.run(["tailscale", "debug", "derp-map"], - capture_output=True, text=True, timeout=20) - data = json.loads(out.stdout) - except Exception: - return _DERP - for region in (data.get("Regions") or {}).values(): - code = region.get("RegionCode") - if code: - _DERP[code] = region.get("RegionName") or code - return _DERP - - -def ts_status(): - try: - out = subprocess.run(["tailscale", "status", "--json"], - capture_output=True, text=True, timeout=15) - return json.loads(out.stdout) - except Exception: - return None - - -def _sample_rates(store, data): - """Turn cumulative byte counters into per-second rates.""" - now = time.time() - for peer in (data.get("Peer") or {}).values(): - key = peer_name(peer) - rx, tx = peer.get("RxBytes", 0), peer.get("TxBytes", 0) - prev = store._counters.get(key) - store._counters[key] = (rx, tx, now) - if not prev: - continue - dt = now - prev[2] - if dt <= 0: - continue - # a tailscaled restart zeroes the counters; report no traffic rather - # than a large negative spike - drx = max(0, rx - prev[0]) / dt - dtx = max(0, tx - prev[1]) / dt - hist = store.rates.setdefault(key, collections.deque(maxlen=HISTORY)) - hist.append((drx, dtx)) - - -def spark(values, n, peak=None): - """Sparkline of the last n values, scaled to `peak` or their own max.""" - vals = list(values)[-n:] - if not vals: - return "" - hi = peak if peak else max(vals) - if not hi: - return "·" * len(vals) - return "".join(SPARK[min(7, int(v / hi * 7.99))] for v in vals) - - -def ago(s): - s = int(max(0, s)) - if s < 3600: - return "%dm ago" % (s / 60) - if s < 172800: - return "%dh ago" % (s / 3600) - return "%dd ago" % (s / 86400) - - -def human(n): - """Byte count in exactly five cells, so columns stay aligned.""" - n = float(n or 0) - for u in ("B", "K", "M", "G", "T"): - if n < 1024: - body = "%.0f%s" % (n, u) if (n >= 10 or u == "B") else "%.1f%s" % (n, u) - return "%5s" % body - n /= 1024.0 - return "%5s" % ("%.0fP" % n) - - -def seen(iso): - """Age of an ISO-8601 timestamp, coarsely.""" - if not iso: - return " -" - try: - t = time.mktime(time.strptime(iso[:19], "%Y-%m-%dT%H:%M:%S")) - except ValueError: - return " -" - s = max(0, time.time() - t - time.timezone) - if s < 90: - return "now" - if s < 5400: - return "%dm" % (s / 60) - if s < 172800: - return "%dh" % (s / 3600) - return "%dd" % (s / 86400) - - -TIME_RE = re.compile(r"time[=<]([\d.]+)\s*ms") - - -class Prober(object): - """Pings whichever peer is selected, keeping per-peer history. - - Probing every peer continuously would mean two dozen ping processes for - data nobody is looking at, so exactly one runs at a time and follows the - selection. History is kept per peer, so returning to one still shows its - earlier samples. - """ - - def __init__(self): - self.lock = threading.Lock() - self.samples = {} # machine -> deque of rtt|None - self.want = None # (machine, ip) - self.proc = None - - def watch(self, machine, ip): - with self.lock: - if self.want and self.want[0] == machine: - return - self.want = (machine, ip) if ip else None - if self.proc and self.proc.poll() is None: - try: - self.proc.terminate() - except OSError: - pass - - def history(self, machine): - with self.lock: - return list(self.samples.get(machine) or []) - - def run(self): - # A daemon thread that raises just stops, and a dead poller looks - # exactly like a source with no data - which is how deployments.py - # showed "0 deploys" for a day after an import went missing. - try: - self.poll() - except Exception as e: - with self.lock: - self.error = "poller stopped: %s: %s" % (type(e).__name__, - str(e)[:70]) - - def poll(self): - while True: - with self.lock: - target = self.want - if not target: - time.sleep(0.4) - continue - machine, ip = target - try: - self.proc = subprocess.Popen( - ["ping", "-n", "-O", "-i", "1", ip], - stdout=subprocess.PIPE, stderr=subprocess.STDOUT, - text=True, bufsize=1) - except OSError: - time.sleep(2) - continue - for line in self.proc.stdout: - with self.lock: - if not self.want or self.want[0] != machine: - break - hist = self.samples.setdefault( - machine, collections.deque(maxlen=120)) - m = TIME_RE.search(line) - if m: - hist.append(float(m.group(1))) - elif "no answer yet" in line or "Unreachable" in line: - hist.append(None) - try: - self.proc.terminate() - except OSError: - pass - - -class Store(object): - def __init__(self): - self.lock = threading.Lock() - self.data = None - self.endpoints = {} - self.error = None - self.wake = threading.Event() - self._endpoints_at = 0 - self.rates = {} # machine -> deque of (rx_per_s, tx_per_s) - self._counters = {} # machine -> (rx, tx, when) - - def snapshot(self): - with self.lock: - return (self.data, dict(self.endpoints), self.error, - {k: list(v) for k, v in self.rates.items()}) - - def _sample(self, data): - _sample_rates(self, data) - - def run(self): - while True: - d = ts_status() - eps = None - if time.time() - self._endpoints_at > 60: - eps = endpoints_by_peer() - self._endpoints_at = time.time() - with self.lock: - if d is None: - self.error = "tailscale CLI unavailable or not logged in" - else: - self.data, self.error = d, None - if eps: - self.endpoints = eps - if d: - self._sample(d) - self.wake.wait(REFRESH) - self.wake.clear() - - -def addresses(peer, eps): - """The addresses worth copying for a peer, as (label, value) pairs.""" - out = [] - ips = peer.get("TailscaleIPs") or [] - v4 = [i for i in ips if ":" not in i] - v6 = [i for i in ips if ":" in i] - if v4: - out.append(("Tailscale IP", v4[0])) - dns = (peer.get("DNSName") or "").rstrip(".") - if dns: - out.append(("MagicDNS name", dns)) - - seen_pub, seen_priv = [], [] - cur = (peer.get("CurAddr") or "").rsplit(":", 1)[0] - if cur and classify(cur) == "public": - seen_pub.append(cur) - for ip in eps.get(dns, []): - kind = classify(ip) - if kind == "public" and ip not in seen_pub: - seen_pub.append(ip) - elif kind == "private" and ip not in seen_priv: - seen_priv.append(ip) - # PrimaryRoutes only: AllowedIPs also carries 0.0.0.0/0 for exit nodes, - # which would match every address and defeat the ranking entirely. - routes = [r for r in (peer.get("PrimaryRoutes") or []) - if r not in ("0.0.0.0/0", "::/0")] - seen_priv.sort(key=lambda i: lan_rank(i, routes)) - if seen_pub: - out.append(("Public IP", seen_pub[0])) - if seen_priv: - out.append(("Private IP (LAN)", seen_priv[0])) - if len(seen_priv) > 1: - out.append(("Other private IP", seen_priv[1])) - if v6: - out.append(("Tailscale IPv6", v6[0])) - return out - - -def stamp(iso): - """ISO-8601 to a readable local time, or None when unset.""" - if not iso or iso.startswith("0001-01-01"): - return None - try: - t = time.mktime(time.strptime(iso[:19], "%Y-%m-%dT%H:%M:%S")) - time.timezone - except ValueError: - return None - return time.strftime("%Y-%m-%d %H:%M", time.localtime(t)) - - -def rate(v): - """Per-second byte rate in six cells.""" - return "%s/s" % human(v).strip().rjust(5) - - -def activity_rows(rates, w, limit): - """Live throughput for peers that are actually moving data.""" - active = [] - for name, hist in rates.items(): - if not hist: - continue - recent = hist[-30:] - if max((r + t for r, t in recent), default=0) < 64: # ignore keepalives - continue - active.append((max(r + t for r, t in recent), name, hist)) - active.sort(reverse=True) - if not active: - return [DIM + " no peer traffic in the last few minutes"] - - sw = max(8, min(28, w - 42)) - peak = max(a[0] for a in active) - out = [] - for _, name, hist in active[:limit]: - rx = [r for r, _ in hist] - tx = [t for _, t in hist] - out.append(seg([(TXT, " " + pad(name[:18], 19)), - (ONLINE, "↓" + spark(rx, sw, peak)), - (RELAY, " ↑" + spark(tx, sw, peak)), - (DIM, " " + rate(rx[-1]) + " " + rate(tx[-1]))], w - 1)) - return out - - -def info_overlay(peer, eps, users, w, h, rates=None, latency=None): - """Everything known about one machine, including every address.""" - rows = [title("machine info", w, ACCENT)] - dns = (peer.get("DNSName") or "").rstrip(".") - ips = peer.get("TailscaleIPs") or [] - owner = (users.get(str(peer.get("UserID"))) or {}).get("LoginName", "") - - def field(label, value, color=TXT): - if value in (None, "", []): - return - rows.append(seg([(DIM, " %-13s" % label), (color, str(value))], w - 1)) - - field("machine", peer_name(peer), ACCENT) - field("dns name", dns) - if (peer.get("HostName") or "") != peer_name(peer): - field("hostname", peer.get("HostName") + " (self-reported)", DIM) - field("os", peer.get("OS")) - region = peer.get("Relay") or "" - if region: - city = derp_regions().get(region) - field("region", "%s — %s" % (region, city) if city else region, ROUTE) - field("owner", owner) - field("tags", ", ".join(peer.get("Tags") or []), ROUTE) - rows.append("") - - up = bool(peer.get("Online")) - field("status", "online" if up else "offline", ONLINE if up else OFFLINE) - if peer.get("CurAddr"): - field("path", "DIRECT via " + peer["CurAddr"], DIRECT) - else: - relay = peer.get("Relay") or "?" - city = derp_regions().get(relay, "") - field("path", "relayed through DERP %s%s" % (relay, - " (%s)" % city if city else ""), - RELAY) - field("rx / tx", "%s / %s" % (human(peer.get("RxBytes")).strip(), - human(peer.get("TxBytes")).strip())) - field("handshake", stamp(peer.get("LastHandshake"))) - field("last seen", stamp(peer.get("LastSeen")) or ("connected" if up else "-")) - field("added", stamp(peer.get("Created"))) - rows.append("") - - rows.append(LBL + " addresses") - for ip in ips: - field(" tailscale", ip, ACCENT) - pub, priv, other = [], [], [] - cur = (peer.get("CurAddr") or "").rsplit(":", 1)[0] - if cur: - pub.append(cur) - for ip in eps.get(dns, []): - kind = classify(ip) - bucket = {"public": pub, "private": priv}.get(kind, other) - if ip not in bucket: - bucket.append(ip) - routes = [r for r in (peer.get("PrimaryRoutes") or []) - if r not in ("0.0.0.0/0", "::/0")] - priv.sort(key=lambda i: lan_rank(i, routes)) - for ip in pub: - field(" public", ip) - for ip in priv: - tag = " (in advertised subnet)" if any(in_network(ip, r) for r in routes) else "" - field(" private", ip + tag) - for ip in other: - field(" other", ip, DIM) - if not eps: - rows.append(DIM + " endpoints need sudo; only the current path is shown") - - if routes: - rows.append("") - rows.append(LBL + " advertises") - for r in routes[:6]: - rows.append(seg([(ROUTE, " " + r)], w - 1)) - if len(routes) > 6: - rows.append(DIM + " +%d more" % (len(routes) - 6)) - pings = [x for x in (latency or []) if x is not None] - if latency: - rows.append("") - loss = 100.0 * (len(latency) - len(pings)) / len(latency) - if pings: - ordered = sorted(pings) - jit = (sum(abs(pings[i] - pings[i - 1]) for i in range(1, len(pings))) - / (len(pings) - 1)) if len(pings) > 1 else 0.0 - rows.append(LBL + " latency " + DIM + "(icmp over tailscale, %d samples)" - % len(latency)) - rows.append(seg([(DIM, " now "), (TXT, "%7.2fms" % pings[-1]), - (DIM, " avg "), (TXT, "%7.2fms" % (sum(pings) / len(pings))), - (DIM, " med "), (TXT, "%7.2fms" % ordered[len(ordered) // 2])], - w - 1)) - rows.append(seg([(DIM, " min "), (TXT, "%7.2fms" % ordered[0]), - (DIM, " max "), (TXT, "%7.2fms" % ordered[-1]), - (DIM, " jit "), (TXT, "%7.2fms" % jit)], w - 1)) - rows.append(seg([(DIM, " loss"), (ONLINE if loss == 0 else RELAY, - "%7.1f%%" % loss)], w - 1)) - lo, hi = ordered[0], ordered[-1] - span = (hi - lo) or 1.0 - sw = max(10, w - 8) - marks = [] - for v in latency[-sw:]: - if v is None: - marks.append((RELAY, "×")) - else: - marks.append((ONLINE, SPARK[min(7, int((v - lo) / span * 7.99))])) - rows.append(" " + "".join(c + ch for c, ch in marks)) - else: - rows.append(LBL + " latency " + RELAY + "no replies") - elif peer.get("Online"): - rows.append("") - rows.append(LBL + " latency " + DIM + "probing…") - - hist = (rates or {}).get(peer_name(peer)) or [] - if hist: - rows.append("") - rows.append(LBL + " throughput " + DIM + "(last %d samples)" % len(hist[-60:])) - rx = [r for r, _ in hist] - tx = [t for _, t in hist] - peak = max(max(rx), max(tx), 1) - sw = max(10, w - 22) - rows.append(seg([(DIM, " down "), (ONLINE, spark(rx, sw, peak)), - (DIM, " " + rate(rx[-1]))], w - 1)) - rows.append(seg([(DIM, " up "), (RELAY, spark(tx, sw, peak)), - (DIM, " " + rate(tx[-1]))], w - 1)) - rows.append(seg([(DIM, " peak %s" % rate(peak))], w - 1)) - - if peer.get("ExitNodeOption"): - rows.append("") - rows.append(seg([(EXIT, " offers itself as an exit node")], w - 1)) - - while len(rows) < h - 1: - rows.append("") - rows.append(seg([(DIM, " [c]opy addresses · esc, ↵ or i to close")], w - 1)) - return rows - - -def wrap(text, width): - return [text[i:i + width] for i in range(0, len(text), width)] or [""] - - -def copy_overlay(peer, eps, w, h, note): - rows = [title("copy address", w, ROUTE)] - rows.append("") - rows.append(seg([(TXT, " " + peer_name(peer)), - (DIM, " " + (peer.get("OS") or "")), - (DIRECT if peer.get("CurAddr") else RELAY, - " " + ("DIRECT" if peer.get("CurAddr") - else "relay " + str(peer.get("Relay") or "?")))], w - 1)) - rows.append("") - pairs = addresses(peer, eps) - for i, (label, value) in enumerate(pairs, 1): - rows.append(seg([(ONLINE, " [%d] " % i), (TXT, label)], w - 1)) - for line in wrap(value, max(10, w - 6)): - rows.append(ACCENT + " " + line) - rows.append("") - if not pairs: - rows.append(DIM + " (no addresses available for this peer)") - if not eps: - rows.append(DIM + " LAN addresses need `sudo tailscale debug netmap`;") - rows.append(DIM + " passwordless sudo is unavailable, so they are omitted.") - while len(rows) < h - 2: - rows.append("") - rows.append(seg([(DIM, " press 1-%d to copy · esc or c to close" % max(1, len(pairs)))], - w - 1)) - rows.append(seg([(ONLINE, " " + note) if note else (DIM, "")], w - 1)) - return rows - - -def main(): - maybe_help(__doc__) - global REFRESH - args = sys.argv[1:] - if args and args[0] in ("-n", "--refresh"): - REFRESH = max(1.0, float(args[1])) - - setup() - keyboard = Keyboard() - store = Store() - th = threading.Thread(target=store.run) - th.daemon = True - th.start() - prober = Prober() - pt = threading.Thread(target=prober.run) - pt.daemon = True - pt.start() - - hide_offline = False - show_graph = True - selected = 0 - scroll = 0 - view = None # None | "copy" | "info" - note = "" - note_until = 0 - listed = [] - visible = 1 - while True: - for key in keyboard.poll(): - if view: - if key == "esc" or key in ("q", "Q"): - view = None - elif key in ("i", "enter"): - view = "info" if view != "info" else None - elif key == "c": - view = "copy" if view != "copy" else None - elif view == "copy" and key.isdigit() and listed: - pairs = addresses(listed[min(selected, len(listed) - 1)], eps_now) - idx = int(key) - 1 - if 0 <= idx < len(pairs): - label, value = pairs[idx] - note = ("✓ copied %s" % label.lower()) if clipboard(value) \ - else "! no clipboard; select the text with the mouse" - note_until = time.time() + 3 - continue - if key in ("q", "Q"): - keyboard.restore() - raise SystemExit(0) - if key == "r": - store.wake.set() - elif key == "o": - hide_offline = not hide_offline - selected = 0 - elif key == "g": - show_graph = not show_graph - elif key == "n": - REFRESH = cycle(REFRESH_CHOICES, REFRESH) - store.wake.set() # apply the new interval immediately - elif key == "up": - selected = max(0, selected - 1) - elif key == "down": - selected += 1 - elif key == "pgup": - selected = max(0, selected - visible) - elif key == "pgdn": - selected += visible - elif key == "home": - selected = 0 - elif key == "end": - selected = max(0, len(listed) - 1) - elif key == "c": - if listed: - view = "copy" - note = "" - elif key in ("i", "enter"): - if listed: - view = "info" - - w, h = size() - data, eps_now, err, rates = store.snapshot() - if note and time.time() > note_until: - note = "" - rows = [title("tailnet", w, ACCENT)] - - if not data: - rows.append(seg([(RELAY, " " + (err or "connecting…"))], w - 1)) - draw(rows, w, h) - time.sleep(0.4) - continue - - me = data.get("Self") or {} - peers = list((data.get("Peer") or {}).values()) - online = [p for p in peers if p.get("Online")] - direct = [p for p in online if p.get("CurAddr")] - relayed = [p for p in online if not p.get("CurAddr")] - routers = [p for p in peers if p.get("PrimaryRoutes")] - exits = [p for p in peers if p.get("ExitNode")] - - rows.append(seg([(TXT, " " + (me.get("DNSName") or "").rstrip(".").split(".")[0]), - (DIM, " " + (me.get("TailscaleIPs") or ["?"])[0]), - (DIM, " " + (data.get("MagicDNSSuffix") or ""))], w - 1)) - rows.append(seg([(ONLINE, " %d online" % len(online)), - (DIM, " / %d peers" % len(peers)), - (DIRECT, " %d direct" % len(direct)), - (RELAY, " %d relayed" % len(relayed)), - (DIM, " every %gs" % REFRESH)], w - 1)) - line = [(ROUTE, " %d advertising routes" % len(routers))] - line.append((EXIT, " exit node: " + (peer_name(exits[0]) if exits - else "none"))) - rows.append(seg(line, w - 1)) - rows.append("") - - if view and listed: - chosen = listed[min(selected, len(listed) - 1)] - if view == "info": - users = {str(k): v for k, v in (data.get("User") or {}).items()} - draw(info_overlay(chosen, eps_now, users, w, h, rates, - prober.history(peer_name(chosen))), w, h) - else: - draw(copy_overlay(chosen, eps_now, w, h, note), w, h) - time.sleep(0.1) - continue - - if show_graph: - rows.append(LBL + " ── LIVE THROUGHPUT ── " + DIM + "peers moving data") - rows.extend(activity_rows(rates, w, 4)) - rows.append("") - - wide = w >= 62 - # machine names are long; spend spare width on them rather than padding - namew = max(16, min(32, w - 45)) if wide else max(12, w - 22) - head = " %s %-8s %-7s" % (pad("MACHINE", namew + 1), "OS", "PATH") - if wide: - head += " %5s %5s %5s" % ("RX", "TX", "SEEN") - rows.append(LBL + pad(head, w - 1)) - if wide: - span = daemon_uptime() - rows.append(seg([(DIM, " rx/tx = this host ↔ peer, since tailscaled " - "started" + ((" " + ago(span)) if span else ""))], - w - 1)) - - def order(p): - return (not p.get("Online"), not p.get("CurAddr"), - -(p.get("RxBytes", 0) + p.get("TxBytes", 0))) - - if listed: - sel_peer = listed[min(selected, len(listed) - 1)] - ip4 = [i for i in (sel_peer.get("TailscaleIPs") or []) if ":" not in i] - # Nothing is learned by pinging ourselves, and the round trip - # would read as a suspiciously good link. - prober.watch(peer_name(sel_peer), - ip4[0] if (ip4 and sel_peer.get("Online") - and not sel_peer.get("_self")) else None) - - listed = [p for p in sorted(peers, key=order) - if not (hide_offline and not p.get("Online"))] - # This machine belongs in the list of machines - it was only ever in - # the header - but never in the counts above it: "3 direct, 2 - # relayed" describes connections out of here, and there is no - # connection from here to here. It pins to the top rather than - # sorting by traffic, because where you are is not a ranking. - if me: - listed.insert(0, dict(me, _self=True)) - selected = max(0, min(selected, len(listed) - 1)) if listed else 0 - visible = max(1, h - len(rows) - 2) - if selected < scroll: - scroll = selected - elif selected >= scroll + visible: - scroll = selected - visible + 1 - scroll = max(0, min(scroll, max(0, len(listed) - visible))) - - for idx in range(scroll, min(len(listed), scroll + visible)): - p = listed[idx] - if len(rows) >= h - 2: - break - mine = bool(p.get("_self")) - up = True if mine else bool(p.get("Online")) - here = idx == selected - tint = bg(28, 44, 62) if here else "" - path_direct = bool(p.get("CurAddr")) - # "this" rather than DIRECT or a relay name: the path column - # answers how the traffic gets there, and for this machine it - # does not go anywhere. - path = "this" if mine else ( - "DIRECT" if path_direct else (p.get("Relay") or "?")) - name = peer_name(p) - line = [(tint + (ACCENT if mine else (ONLINE if up else OFFLINE)), - ("▸" if here else " ") - + "%s " % ("◆" if mine else ("●" if up else "○"))), - (tint + (TXT if up else OFFLINE), - pad(name[:namew - 1], namew)), - (tint + DIM, "%-8s" % (p.get("OS") or "?")[:8]), - (tint + (ACCENT if mine else - (DIRECT if path_direct else RELAY)), - "%-7s" % (path if up else "-"))] - if wide: - line.append((tint + DIM, " %5s %5s" % (human(p.get("RxBytes")), - human(p.get("TxBytes"))))) - line.append((tint + DIM, " %5s" % (seen(p.get("LastSeen")) - if not up else "now"))) - if p.get("PrimaryRoutes"): - line.append((tint + ROUTE, " ⇄")) - if here: - line.append((tint, " " * w)) - rows.append(seg(line, w - 1)) - - while len(rows) < h - 2: - rows.append("") - if routers: - first = routers[0] - rts = first.get("PrimaryRoutes") or [] - rows.append(seg([(ROUTE, " ⇄ "), (DIM, "%s routes " % first.get("HostName")), - (TXT, ", ".join(rts[:2])), - (DIM, (" +%d more" % (len(rts) - 2)) if len(rts) > 2 else "")], - w - 1)) - hints = [[(ACCENT, "↑↓"), (DIM, " select")], - [(DIM, "↵/[i]nfo")], [(DIM, "[c]opy")], [(DIM, "[g]raph")], - [(DIM, "[o]ffline")], [(DIM, "[n]=%gs" % REFRESH)], - [(DIM, "[r]efresh")], [(DIM, "[q]uit")]] - for line in pack_hints(hints, w - 2): - rows.append(" " + line) - draw(rows, w, h) - time.sleep(0.3) - - -main() diff --git a/usage.py b/usage.py deleted file mode 100755 index 998702d..0000000 --- a/usage.py +++ /dev/null @@ -1,3607 +0,0 @@ -#!/usr/bin/env python3 -# terminal-toys - small dependency-free terminal widgets -# Copyright (C) 2026 William Li -# -# This program is free software: you can redistribute it and/or modify -# it under the terms of the GNU Affero General Public License as published -# by the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU Affero General Public License for more details. -# -# You should have received a copy of the GNU Affero General Public License -# along with this program. If not, see <https://www.gnu.org/licenses/>. -"""How much the coding agents on this machine have been used. - -One tab per agent, because they do not agree on what usage even means: one -counts tokens, another counts lines it wrote, and several publish nothing at -all outside their own session. A single table would need a shared schema that -does not exist, so each tab shows that agent's own shape - and an agent that -exposes nothing says so rather than showing a plausible zero. - - python3 usage.py [-n SECONDS] - -Most of this is read from local state files. The exception is the remaining -quota, which no agent writes to disk in a current form: Claude, Codex, Cursor -and Copilot each publish one over an endpoint, fetched with the credential -that agent already holds and sent only to that agent's own host. Nothing here is -inferred from a number that was not published. - -Keys: left/right or tab switch agent, up/down scroll it, pgup/pgdn by -the page, home/end to either edge, r refreshes now, q quits. -""" -import datetime -import json -import os -import glob -import re -import shutil -import sqlite3 -import sys -import urllib.error -import urllib.request -import threading -import time - -sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) -from common import (RST, Keyboard, bg, draw, heat, load_config, maybe_help, mix, - meter, pack_hints, pad, rgb, seg, setup, size, spread, - stacked_bar, title, vbars) - -_CFG = load_config("usage", { - # Empty discovers whatever this machine has, which is the default and - # what most people want. Naming agents instead pins the set and its order - # - listing one is how you say "keep the tab even though it is not - # installed yet", and it is also how you turn discovery off. The same - # empty-means-discover idiom as github.accounts and linear.exclude_teams. - "agents": [], - "exclude_agents": [], - # US$ per million tokens, keyed by model. Empty by design - see RATES. - "rates": {}, - # What each subscription costs per month, keyed by agent. Nothing to - # ship: Anthropic lists Max as "from $100" because it varies by tier, - # and nobody's invoice is on this machine. Set it and the metered - # section can say what the plan saved. - "plan_cost": {}, - "refresh": 30, -}) - -REFRESH = float(_CFG["refresh"]) -# US$ per million tokens, keyed by model. Nothing is shipped here on purpose: -# only Cursor publishes what it charges, so every other agent's "what would -# this have cost" is arithmetic on a rate card the user supplies. A price this -# repo invented would be exactly the fabricated denominator it exists to avoid. -RATES = _CFG["rates"] or {} -PLAN_COST = _CFG["plan_cost"] or {} -RATE_KINDS = ("input", "output", "cache_read", "cache_write", - "cache_write_1h") - -# Anthropic's published list prices, US$ per million tokens, copied from -# platform.claude.com/docs/en/docs/about-claude/pricing on the date below. -# They are shipped because they are published facts with a citable source, -# not a guess - but they go stale silently, so the date is carried onto the -# screen with them and config overrides any line. -# -# Cache writes come in two durations at different prices - 1.25x input for a -# five-minute write, 2x for an hour - and the transcripts record which was -# taken, per iteration, so both are carried and neither is assumed. -LIST_RATES_AS_OF = "Aug 2026" -LIST_RATES_SOURCE = "platform.claude.com and developers.openai.com pricing" -# Models known to have no published price: prefix matching would otherwise -# hand gpt-5.3-codex-spark its family's rate, and Spark is explicitly not on -# the API (supported_in_api: false in Codex's own model cache). Naming them -# here makes them report as unpriced rather than as a number nobody published. -NO_PUBLISHED_PRICE = ("gpt-5.3-codex-spark", "codex-auto-review") - -# OpenAI's published list prices, from developers.openai.com/api/docs/pricing -# on the same date. OpenAI does not charge for cache writes, so there is no -# cache_write entry and one would be wrong rather than merely absent. -LIST_RATES = { - "gpt-5.6-sol": {"input": 5, "output": 30, "cache_read": 0.50}, - "gpt-5.6-terra": {"input": 2, "output": 12, "cache_read": 0.20}, - "gpt-5.6-luna": {"input": 0.20, "output": 1.20, "cache_read": 0.02}, - "gpt-5.5-pro": {"input": 30, "output": 180}, - "gpt-5.5": {"input": 5, "output": 30, "cache_read": 0.50}, - "gpt-5.4-mini": {"input": 0.75, "output": 4.50, "cache_read": 0.075}, - "gpt-5.4-nano": {"input": 0.20, "output": 1.25, "cache_read": 0.02}, - "gpt-5.4-pro": {"input": 30, "output": 180}, - "gpt-5.4": {"input": 2.50, "output": 15, "cache_read": 0.25}, - "gpt-5.3-codex": {"input": 1.75, "output": 14, "cache_read": 0.175}, - "gpt-5.2-pro": {"input": 21, "output": 168}, - "gpt-5.2": {"input": 1.75, "output": 14, "cache_read": 0.175}, - "gpt-5.1": {"input": 1.25, "output": 10, "cache_read": 0.125}, - "gpt-5-mini": {"input": 0.25, "output": 2, "cache_read": 0.025}, - "gpt-5-nano": {"input": 0.05, "output": 0.40, "cache_read": 0.005}, - "gpt-5-pro": {"input": 15, "output": 120}, - "gpt-5": {"input": 1.25, "output": 10, "cache_read": 0.125}, - "claude-fable-5": {"input": 10, "output": 50, "cache_write": 12.50, - "cache_read": 1, - "cache_write_1h": 20}, - "claude-mythos-5": {"input": 10, "output": 50, "cache_write": 12.50, - "cache_read": 1, - "cache_write_1h": 20}, - "claude-opus-5": {"input": 5, "output": 25, "cache_write": 6.25, - "cache_read": 0.50, - "cache_write_1h": 10}, - "claude-opus-4-8": {"input": 5, "output": 25, "cache_write": 6.25, - "cache_read": 0.50, - "cache_write_1h": 10}, - "claude-opus-4-7": {"input": 5, "output": 25, "cache_write": 6.25, - "cache_read": 0.50, - "cache_write_1h": 10}, - "claude-opus-4-6": {"input": 5, "output": 25, "cache_write": 6.25, - "cache_read": 0.50, - "cache_write_1h": 10}, - "claude-opus-4-5": {"input": 5, "output": 25, "cache_write": 6.25, - "cache_read": 0.50, - "cache_write_1h": 10}, - "claude-opus-4-1": {"input": 15, "output": 75, "cache_write": 18.75, - "cache_read": 1.50, - "cache_write_1h": 30}, - "claude-sonnet-5": {"input": 2, "output": 10, "cache_write": 2.50, - "cache_read": 0.20, - "cache_write_1h": 4}, - "claude-sonnet-4-6": {"input": 3, "output": 15, "cache_write": 3.75, - "cache_read": 0.30, - "cache_write_1h": 6}, - "claude-sonnet-4-5": {"input": 3, "output": 15, "cache_write": 3.75, - "cache_read": 0.30, - "cache_write_1h": 6}, - "claude-haiku-4-5": {"input": 1, "output": 5, "cache_write": 1.25, - "cache_read": 0.10, - "cache_write_1h": 2}, - "claude-haiku-3-5": {"input": 0.80, "output": 4, "cache_write": 1, - "cache_read": 0.08, - "cache_write_1h": 1.6}, -} - -OK = rgb(90, 240, 160) -WARN = rgb(255, 200, 90) -BAD = rgb(255, 100, 110) -DIM = rgb(127, 147, 172) -GRID = rgb(60, 78, 98) -TXT = rgb(225, 235, 245) -LBL = rgb(130, 165, 200) -ACCENT = rgb(150, 210, 255) -AGENT = rgb(180, 160, 255) - -# One hue, four steps, the way /stats and the contribution calendar do it. -# heat() runs green to amber to red, which reads as a change of *kind* rather -# than of amount - wrong for "more of the same thing". -# Claude keeps the terracotta of its own /stats. Codex gets a white ramp, so -# two calendars side by side are told apart by hue rather than by reading the -# heading - the steps are the same four, only the colour differs. -HEAT_STEPS = ((74, 52, 46), (140, 78, 58), (196, 100, 66), (240, 132, 84)) -CODEX_STEPS = ((66, 72, 82), (122, 130, 144), (182, 190, 202), (240, 244, 250)) -GROK_STEPS = ((44, 62, 88), (62, 104, 156), (86, 150, 210), (120, 196, 250)) -CURSOR_STEPS = ((48, 74, 66), (72, 124, 104), (100, 172, 142), (140, 220, 184)) -# One hue per provider, for the summary's group headings. Each is the colour -# that agent's own tab already uses - Claude the terracotta of its /stats, -# Codex its white ramp, Grok its blue, Cursor its included-lane green - so the -# same agent looks the same wherever you meet it. Copilot and Antigravity have -# no calendar to borrow from and get their own, chosen to sit clear of the -# amber and red this widget reserves for trouble. -AGENT_HUE = {"claude": (240, 132, 84), "codex": (206, 214, 228), - "cursor": (126, 208, 176), "grok": (120, 196, 250), - "copilot": (186, 166, 255), "antigravity": (232, 158, 200)} -EMPTY_CELL = rgb(58, 66, 80) - - -def shade(frac, steps=HEAT_STEPS): - """Which of the four steps a day falls in.""" - return rgb(*steps[min(3, max(0, int(frac * 3.999)))]) - - -CLAUDE_STATS = os.path.expanduser("~/.claude/stats-cache.json") -CLAUDE_CREDS = os.path.expanduser("~/.claude/.credentials.json") -CLAUDE_CONFIG = os.path.expanduser("~/.claude.json") -CLAUDE_USAGE_API = "https://api.anthropic.com/api/oauth/usage" -CLAUDE_PROFILE_API = "https://api.anthropic.com/api/oauth/profile" -# a plan does not change between refreshes; the windows do -PLAN_TTL = 3600 -# The windows are not stated in limits[], but the same response names them in -# its own top-level keys: five_hour and seven_day. -CLAUDE_WINDOW = {"session": "5h", "weekly": "7d"} -CLAUDE_WINDOW_SECS = {"session": 5 * 3600, "weekly": 7 * 86400} - - -def claude_lane_rank(limit): - """Where a Claude limit belongs in the list, shortest leash first. - - The server returns them in no order worth keeping. Read top to bottom - they should widen: the five-hour session is what stops you this - afternoon, the weekly total is what stops you this week, and a - model-scoped weekly limit stops only one model. - """ - if limit.get("kind") == "session": - return 0 - scoped = ((limit.get("scope") or {}).get("model") or {}).get("display_name") - return 2 if scoped else 1 - - -CODEX_SESSIONS = os.path.expanduser("~/.codex/sessions/**/*.jsonl") -# Recursive on purpose: subagent transcripts live a further two levels down, -# in <project>/<session>/subagents/, and that is where Haiku and most of -# Sonnet actually run. Globbing one level deep found 38 files of 520MB and -# silently missed 257 of them. -CLAUDE_TRANSCRIPTS = os.path.expanduser("~/.claude/projects/**/*.jsonl") -RATE_FILES = 3 # newest transcripts to sample for a rate -MIN_GAP = 1.0 # seconds; below this the timestamps are not a turn -ANTIGRAVITY_DIR = os.path.expanduser("~/.gemini/antigravity-cli") -ANTIGRAVITY_TOKEN = os.path.join(ANTIGRAVITY_DIR, "antigravity-oauth-token") -ANTIGRAVITY_CONVERSATIONS = os.path.join(ANTIGRAVITY_DIR, "conversations/*.db") -ANTIGRAVITY_HISTORY = os.path.join(ANTIGRAVITY_DIR, "history.jsonl") -CODE_ASSIST_API = ("https://cloudcode-pa.googleapis.com" - "/v1internal:loadCodeAssist") -COPILOT_DB = os.path.expanduser("~/.copilot/session-store.db") -COPILOT_CONFIG = os.path.expanduser("~/.copilot/config.json") -COPILOT_USER_API = "https://api.github.com/copilot_internal/user" -TAIL = 256 * 1024 # enough to reach the last token_count in a rollout -CURSOR_DB = os.path.expanduser("~/.cursor/ai-tracking/ai-code-tracking.db") -# One hue per lane, as cursor-agent's own Usage view does it. These are -# categories rather than one gauge, so a green-to-red severity ramp would -# imply a relationship between them that does not exist - and each bar is -# labelled and carries its own percentage, so the colour is decoration. -# Three tints of Cursor's own colour rather than three unrelated hues. They -# are still categories, not a severity ramp, so they stay distinguishable - -# but they now read as Cursor's, which three borrowed colours never did. -CURSOR_LANE_STOPS = (("included", 1.0), ("auto", 0.80), ("api", 0.62)) -GROK_SESSIONS = os.path.expanduser("~/.grok/sessions/**/updates.jsonl") -# the quota is not in the session transcripts: it arrives on the client log -GROK_LOG = os.path.expanduser("~/.grok/logs/unified.jsonl") -CURSOR_AUTH = os.path.expanduser("~/.config/cursor/auth.json") -CURSOR_RPC = "https://api2.cursor.sh/aiserver.v1.DashboardService/%s" -CURSOR_USAGE_API = CURSOR_RPC % "GetCurrentPeriodUsage" - - -def span_ms(ms): - """A duration in milliseconds as days, hours and minutes.""" - s = int((ms or 0) / 1000) - d, s = divmod(s, 86400) - h, s = divmod(s, 3600) - m = s // 60 - if d: - return "%dd %dh %dm" % (d, h, m) - if h: - return "%dh %dm" % (h, m) - # a couple of seconds of generation is not "0m" - return "%dm" % m if m else "%.1fs" % ((ms or 0) / 1000.0) - - -def big_num(n): - """Token counts run to billions; nobody reads eleven digits.""" - n = float(n or 0) - for unit, size in (("B", 1e9), ("M", 1e6), ("k", 1e3)): - if abs(n) >= size: - return "%.1f%s" % (n / size, unit) - return "%d" % n - - -def ago(when): - if not when: - return "never" - s = time.time() - when - if s < 60: - return "%ds" % int(s) - if s < 3600: - return "%dm" % int(s // 60) - if s < 86400: - return "%dh" % int(s // 3600) - if s < 365 * 86400: - return "%dd" % int(s // 86400) - # a subscription can be years old, and "890d" is not a span anyone reads - return "%.1fy" % (s / (365.0 * 86400)) - - -def claude_live(): - """Rate-limit utilization, live from the endpoint /usage itself calls. - - The OAuth token is the one Claude Code already holds. It goes only to - Anthropic, is never printed, and an expired one is not used at all: the - refresh token sits beside it, but spending it would race Claude Code's - own credential handling for a number that has a local cache anyway. - """ - try: - with open(CLAUDE_CREDS) as f: - o = (json.load(f) or {}).get("claudeAiOauth") or {} - except (OSError, ValueError): - return None - tok = o.get("accessToken") - if not tok or (o.get("expiresAt") or 0) / 1000.0 <= time.time(): - return None - req = urllib.request.Request(CLAUDE_USAGE_API, headers={ - "Authorization": "Bearer " + tok, "User-Agent": "terminal-toys"}) - try: - with urllib.request.urlopen(req, timeout=20) as r: - return {"u": json.load(r), "source": "live", "at": time.time(), - "plan": o.get("subscriptionType") or ""} - except (urllib.error.URLError, ValueError, OSError): - return None - - -def claude_profile(): - """Which subscription the windows belong to. - - A separate endpoint from the usage one, and near-static, so it is held - far longer - a plan does not change between refreshes, and the usage - endpoint answers 429 if these are called at usage cadence. - """ - try: - with open(CLAUDE_CREDS) as f: - o = (json.load(f) or {}).get("claudeAiOauth") or {} - except (OSError, ValueError): - return None - tok = o.get("accessToken") - if not tok or (o.get("expiresAt") or 0) / 1000.0 <= time.time(): - return None - req = urllib.request.Request(CLAUDE_PROFILE_API, headers={ - "Authorization": "Bearer " + tok, "User-Agent": "terminal-toys"}) - try: - with urllib.request.urlopen(req, timeout=20) as r: - d = json.load(r) - except (urllib.error.URLError, ValueError, OSError): - return None - d["_plan"] = o.get("subscriptionType") or "" - return d - - -def claude_creds_plan(): - """What the credentials file alone can say about the plan. - - The profile endpoint is richer, but this needs no network and is always - there, so the section degrades to two true lines instead of vanishing. - """ - try: - with open(CLAUDE_CREDS) as f: - o = (json.load(f) or {}).get("claudeAiOauth") or {} - except (OSError, ValueError): - return None - if not o.get("subscriptionType"): - return None - return {"_plan": o["subscriptionType"], "_local": True, - "organization": {"rate_limit_tier": o.get("rateLimitTier") or ""}} - - -def claude_plan_rows(prof, w): - org = (prof.get("organization") or {}) - pairs = [] - since = iso_epoch(org.get("subscription_created_at") or "") - day = iso_day(org.get("subscription_created_at") or "") - if since and day: - pairs.append(("member since", "%s · %s ago" % (day, ago(since)))) - if org.get("subscription_status"): - pairs.append(("status", org["subscription_status"])) - if org.get("rate_limit_tier"): - pairs.append(("rate limit tier", org["rate_limit_tier"])) - if org.get("billing_type"): - pairs.append(("billing", org["billing_type"].replace("_", " "))) - return plan_rows(prof.get("_plan") or org.get("organization_type"), - pairs, w, - note="from credentials" if prof.get("_local") else "") - - -def claude_stale(): - """What Claude Code last fetched, for when the live call cannot run. - - It is a cache with a timestamp, so it is shown with its age - and a - window whose reset has already gone by is said to have passed rather - than counted down to, because a stale five-hour window describes a - period that has ended. - """ - try: - with open(CLAUDE_CONFIG) as f: - c = (json.load(f) or {}).get("cachedUsageUtilization") or {} - except (OSError, ValueError): - return None - if not c.get("utilization"): - return None - return {"u": c["utilization"], "source": "cached", - "at": (c.get("fetchedAtMs") or 0) / 1000.0, "plan": ""} - - -def read_claude(): - """Claude Code's own stats cache, plus what is left of the limits. - - The cache records what was spent - tokens, messages, sessions - and - carries no limit at all. The remaining quota is a separate reading - entirely, and account-wide rather than about this machine. - """ - quota = cached("claude", lambda: claude_live() or claude_stale()) - profile = (cached("claude-plan", claude_profile, ttl=PLAN_TTL) - or claude_creds_plan()) - try: - stat = os.stat(CLAUDE_STATS) - with open(CLAUDE_STATS) as f: - d = json.load(f) - except (OSError, ValueError) as e: - return {"ok": False, "why": "%s" % type(e).__name__, - "quota": quota, "profile": profile} - rates, sampled = claude_rates() - return {"ok": True, "mtime": stat.st_mtime, "data": d, "quota": quota, - "profile": profile, "rates": rates, "sampled": sampled, - "daily_models": claude_daily()} - - -def iso_epoch(s): - """ISO-8601 to epoch seconds. - - fromisoformat rejects a trailing Z before Python 3.11, and these APIs mix - Z with +00:00 in the same response. A value carrying no zone at all is - read as local time, which is why the callers here pass zoned strings. - """ - try: - # Go writes nanoseconds; fromisoformat takes 3 or 6 digits, not 9 - s = re.sub(r"(\.\d{6})\d+", r"\1", re.sub(r"Z$", "+00:00", s)) - return datetime.datetime.fromisoformat(s).timestamp() - except (ValueError, TypeError, AttributeError): - return None - - -def iso_day(s): - """A date, kept in the zone it arrived in. - - assigned_date carries the account's own offset. Converting it to this - machine's zone can move it a day - 3 Jun at 12:10 -07:00 is 4 Jun in UTC - - and then the pane disagrees with what GitHub shows for the same seat. - """ - try: - d = datetime.datetime.fromisoformat(re.sub(r"Z$", "+00:00", s)) - except (ValueError, TypeError, AttributeError): - return "" - return d.strftime("%-d %b %Y") - - -def scope_phrase(w, used): - """The scope note, shortened before it can push a reset off the line. - - "not this machine" is the point of the sentence, but it is also sixteen - characters, and seg() clips whatever runs past the pane. Losing the - clause leaves a shorter true line; losing the end of "resets in 15d" - leaves "resets in 1", which is a different and wrong number. - """ - full = " · account-wide, not this machine " - return full if used + len(full) <= w - 1 else " · account-wide " - - -PACE_FLOOR = 3.0 # below this much of a window, the figure is noise - - -def lead(pct_used, window_secs, reset_ts): - """How far ahead of the clock a quota is, as a signed percentage. - - The share of the window already gone minus the share of the allowance - already spent. Positive is headroom - CodexBar calls the same quantity - "in reserve" - and negative means this runs out before the window does. - - Note the sign is the opposite of CodexBar's separate pace token, where - +X% means burning too fast. The cushion reading is the one that matches - the phrase, so the column is labelled rather than left to be guessed. - - Nothing is fetched for it: the window length and the reset are already - on screen. Below PACE_FLOOR of a window it is not shown at all, because - ten minutes into a week every number looks like a catastrophe or a - triumph. CodexBar gates it the same way and for the same reason. - """ - if not window_secs or not reset_ts: - return None - left = reset_ts - time.time() - gone = window_secs - left - if gone <= 0 or gone > window_secs: - return None - elapsed = 100.0 * gone / window_secs - if elapsed < PACE_FLOOR: - return None - return elapsed - (pct_used or 0) - - -def ahead_of(value): - """True when a pace figure says ahead, False when behind, None if unknown.""" - return None if value is None else value >= 0 - - -def pct_colour(pct, ahead, hue): - """What colour a quota's percentage is written in. - - The agent's own colour, so the number matches the bar it sits beside - rather than being tinted by a gradient that made every figure faintly - warm and said nothing about time. - - Red is the one exception, at 90% spent, because nearly empty is trouble - whatever the pace. Behind-the-clock deliberately does *not* colour this: - the pace cell beside it is already amber for exactly that, and a number - and its own explanation both turning yellow reads as two problems. - """ - if pct >= 90: - return BAD - return rgb(*hue) if hue else heat(pct / 100.0) - - -def pct_text(pct): - """A percentage with enough precision to prove it is not a placeholder. - - Every Antigravity lane rounded to "0%" - which is what an empty section - looks like - while one of them was genuinely 0.4% spent and another - 0.03%. A real small number and no number at all have to be tellable - apart, so below 10% the figure keeps a decimal, and below 1% it keeps - two. A true zero stays a bare 0%. - """ - pct = float(pct or 0) - if pct <= 0: - return " 0%" - if pct < 1: - return "%5.2f%%" % pct - if pct < 10: - return "%5.1f%%" % pct - return "%5.0f%%" % pct - - -def pace_cell(value): - """The signed cushion, coloured by whether it is one.""" - if value is None: - return (DIM, "") - return (OK if value >= 0 else WARN, " %+.0f%%" % value) - - -def quota_window(reset_ts): - """The span a monthly quota covers, worked back from its reset. - - Copilot states when the quota resets but never how long the window is. - It can be derived, but only safely when the reset lands on midnight UTC - on the first of a month - which is what a calendar-month cycle looks - like, and what this account shows. Anything else and the window is not - known, so nothing is claimed about it. - """ - if not reset_ts: - return None - end = datetime.datetime.fromtimestamp(reset_ts, datetime.timezone.utc) - if (end.day, end.hour, end.minute, end.second) != (1, 0, 0, 0): - return None - start = (end.replace(year=end.year - 1, month=12) if end.month == 1 - else end.replace(month=end.month - 1)) - return "%s → %s" % (start.strftime("%-d %b"), end.strftime("%-d %b")) - - -def left_span(secs): - d, r = divmod(int(secs), 86400) - h, r = divmod(r, 3600) - if d: - return "%dd %dh" % (d, h) - return "%dh %dm" % (h, r // 60) if h else "%dm" % (r // 60) - - -def claude_quota(q, w): - """The windows Claude Code's own /usage shows. - - Read from limits[], which is the server's own curated list: the rest of - the response carries a dozen null pools with names like nimbus_quill and - iguana_necktie that /usage does not render either. Each entry names - itself, so a model-scoped weekly limit arrives labelled Fable or Opus - without this having to know either name. - """ - if not q: - return [] - u = q.get("u") or {} - lanes = sorted((l for l in (u.get("limits") or []) - if l.get("percent") is not None), key=claude_lane_rank) - if not lanes: - return [] - live = q.get("source") == "live" - src = "live" if live else "cached %s ago" % ago(q.get("at")) - plan = q.get("plan") or "" - rows = [seg([(LBL, " ── QUOTA ── "), (OK if live else WARN, src), - (DIM, scope_phrase(w, 13 + len(src) + len(plan))), - (DIM, plan)], w - 1)] - - def label(l): - scope = ((l.get("scope") or {}).get("model") or {}).get("display_name") - group = l.get("group") or "" - name = scope or ("overall" if l.get("kind") == "weekly_all" - else group or l.get("kind") or "?") - return ("%s %s" % (name, CLAUDE_WINDOW.get(group, ""))).strip() - - texts = [label(l) for l in lanes] - label_w = max(9, max(len(t) for t in texts)) - for l, text in zip(lanes, texts): - pct = float(l.get("percent") or 0) - used = max(0.0, min(1.0, pct / 100.0)) - ts = iso_epoch(l.get("resets_at")) - when = "" - if ts: - left = ts - time.time() - when = ("resets in " + left_span(left) if left > 0 - else "resetting" if live else "already reset") - sev = (l.get("severity") or "normal").lower() - window = CLAUDE_WINDOW_SECS.get(l.get("group") or "") - # is_active marks the limit currently doing the binding - the one that - # will stop you first - so it is the one worth reading brightly. - rows.append(seg([(TXT if l.get("is_active") else DIM, - " " + pad(text, label_w) + " ")] - + paced_bar(used, elapsed_of(window, ts), - max(8, w - 35 - label_w), - AGENT_HUE["claude"]) - + [(pct_colour(pct, ahead_of(lead(pct, window, ts)), AGENT_HUE["claude"]), - pct_text(pct)), - pace_cell(lead(pct, window, ts)), - (BAD if sev not in ("normal", "") else DIM, - " " + (when if sev in ("normal", "") - else "%s · %s" % (sev, when)))], w - 1)) - extra = u.get("extra_usage") or {} - spend = u.get("spend") or {} - if extra.get("is_enabled") and spend.get("limit"): - def money(m): - return "%.2f" % ((m.get("amount_minor") or 0) / - (10.0 ** (m.get("exponent") or 2))) - rows.append(seg([(DIM, " extra usage "), - (TXT, money(spend.get("used") or {})), - (DIM, " of "), (TXT, money(spend["limit"])), - (DIM, " " + ((spend["limit"].get("currency")) or "")), - (DIM, " monthly")], w - 1)) - rows.append("") - return rows - - -_TRANSCRIPT_CACHE = {} - - -def usage_kinds(u): - """Token counts from one transcript usage block, by priced kind. - - A block's top-level numbers can all be zero while its `iterations` carry - the real figures, so the iterations win where they exist. Cache writes - are split by duration because they are priced differently, and the flat - cache_creation_input_tokens is only used when that split is absent. - """ - out = dict.fromkeys(RATE_KINDS, 0) - for x in (u.get("iterations") or [u]): - out["input"] += x.get("input_tokens") or 0 - out["output"] += x.get("output_tokens") or 0 - out["cache_read"] += x.get("cache_read_input_tokens") or 0 - split = x.get("cache_creation") or {} - if split: - out["cache_write"] += split.get("ephemeral_5m_input_tokens") or 0 - out["cache_write_1h"] += split.get("ephemeral_1h_input_tokens") or 0 - else: - out["cache_write"] += x.get("cache_creation_input_tokens") or 0 - return out - - -def scan_transcript(path): - """Per-record token counts from one transcript, keyed by record uuid. - - Keyed rather than summed because the same message appears in more than - one file: resuming or forking a session replays its history into the new - transcript, and subagent turns are written twice over. Left raw that - inflated Fable by 29% and Opus 5 by 13% against Claude Code's own totals; - de-duplicated on uuid they land within a point. - - Cached on (mtime, size): the corpus here is 520MB across 295 files and a - finished transcript never changes, so each is parsed once. - """ - try: - st = os.stat(path) - except OSError: - return {} - key = (st.st_mtime, st.st_size) - hit = _TRANSCRIPT_CACHE.get(path) - if hit and hit[0] == key: - return hit[1] - records = {} - try: - with open(path, errors="replace") as fh: - for line in fh: - if '"usage"' not in line: - continue - try: - r = json.loads(line) - except ValueError: - continue - msg = r.get("message") or {} - u = msg.get("usage") - model = msg.get("model") - uid = r.get("uuid") - stamp = r.get("timestamp") - if not u or not model or not stamp or not uid: - continue - when = iso_epoch(stamp) - if not when: - continue - got = usage_kinds(u) - if not any(got.values()): - continue - records[uid] = (datetime.date.fromtimestamp(when).isoformat(), - model, got) - except OSError: - return {} - _TRANSCRIPT_CACHE[path] = (key, records) - return records - - -def claude_daily(): - """Every transcript's per-day, per-model tokens, de-duplicated. - - stats-cache.json has dailyModelTokens, but only one total per model per - day - and input, output and the two cache kinds differ in price by up to - fifty times, so a total cannot be costed. The transcripts carry the - split, which is why the money comes from here and not from the cache. - """ - seen = {} - for path in glob.glob(CLAUDE_TRANSCRIPTS, recursive=True): - seen.update(scan_transcript(path)) - merged = {} - for day, model, tokens in seen.values(): - bucket = merged.setdefault(day, {}).setdefault( - model, dict.fromkeys(RATE_KINDS, 0)) - for kind in RATE_KINDS: - bucket[kind] += tokens[kind] - return merged - - -def window_models(daily, days): - """Per-model token totals over the last N days (1 = today only).""" - today = datetime.date.today() - first = (today - datetime.timedelta(days=days - 1)).isoformat() - out = {} - for day, models in (daily or {}).items(): - if day < first: - continue - for model, tokens in models.items(): - bucket = out.setdefault(model, dict.fromkeys(RATE_KINDS, 0)) - for kind in RATE_KINDS: - bucket[kind] += tokens.get(kind) or 0 - return sorted(out.items()) - - -def claude_rates(): - """Output tokens per second, from the newest transcripts. - - A turn is a `user` record followed by an `assistant` one, and the rate is - that assistant's output tokens over the gap between them. Measuring from - *any* previous record instead inflates it wildly - two assistant records - can be milliseconds apart while the second reports a whole turn's output - - and even with the right boundary a few gaps are impossible, 1073 tokens in - 0.07s among them, where the timestamps plainly do not bracket generation. - - So the median is what gets shown. It sits at 74-75 whichever way the - outliers are trimmed, which is the reason to trust it; the maximum moves - from 15328 to 800 on the same data, which is the reason not to show one. - """ - files = sorted(glob.glob(CLAUDE_TRANSCRIPTS, recursive=True), - key=os.path.getmtime, reverse=True)[:RATE_FILES] - out, sampled = [], 0 - for path in files: - prev, prev_type = None, None - lines = tail_lines(path, 4 * 1024 * 1024) - sampled += 1 - for line in lines: - if '"timestamp"' not in line: - continue - try: - d = json.loads(line) - except ValueError: - continue - ts, typ = d.get("timestamp"), d.get("type") - if (typ == "assistant" and ts and prev and prev_type == "user" - and not d.get("isAbortedMidStream")): - tok = ((d.get("message") or {}).get("usage") - or {}).get("output_tokens") or 0 - if tok: - try: - a = datetime.datetime.fromisoformat( - prev.replace("Z", "+00:00")) - b = datetime.datetime.fromisoformat( - ts.replace("Z", "+00:00")) - except ValueError: - prev, prev_type = ts, typ - continue - gap = (b - a).total_seconds() - if MIN_GAP <= gap < 300: - out.append(tok / gap) - if ts: - prev, prev_type = ts, typ - out.sort() - return out, sampled - - -def cursor_live(): - """Plan usage, from the endpoint cursor-agent's own Usage view calls. - - Not the documented cursor.com dashboard API - that one wants a browser - cookie and returns 401 to anything this machine has. The CLI talks Connect - to aiserver.v1.DashboardService with the bearer token it stores in - ~/.config/cursor/auth.json, which is the credential this reuses. - - Undocumented and versioned only by the CLI bundle it was read out of, so - every failure is silent and the tab simply falls back to authorship. - """ - try: - with open(CURSOR_AUTH) as f: - tok = json.load(f).get("accessToken") - except (OSError, ValueError): - return None - if not tok: - return None - return cursor_rpc("GetCurrentPeriodUsage", {}, tok) - - -def cursor_token(): - try: - with open(CURSOR_AUTH) as f: - return json.load(f).get("accessToken") - except (OSError, ValueError): - return None - - -def cursor_rpc(method, body, tok=None): - tok = tok or cursor_token() - if not tok: - return None - req = urllib.request.Request(CURSOR_RPC % method, - data=json.dumps(body).encode(), headers={ - "Authorization": "Bearer " + tok, - "Content-Type": "application/json", - "Connect-Protocol-Version": "1", - "User-Agent": "terminal-toys"}) - try: - with urllib.request.urlopen(req, timeout=25) as r: - return json.load(r) - except (urllib.error.URLError, ValueError, OSError): - return None - - -def cursor_plan(): - """Which Cursor plan the percentages are percentages of. - - GetPlanInfo is where the plan's name and price live - the usage call - carries neither, and its $400 limit is meaningless without knowing that - is what Ultra includes. Found in the CLI bundle the same way the usage - endpoint was. - """ - return cursor_rpc("GetPlanInfo", {}) - - -def cursor_plan_rows(info, w): - plan = (info or {}).get("planInfo") or {} - if not plan: - return [] - pairs = [] - if plan.get("price"): - pairs.append(("price", plan["price"])) - inc = plan.get("includedAmountCents") - if inc: - pairs.append(("included", "$%.2f per cycle" % (int(inc) / 100.0))) - owner = (plan.get("planOwner") or "").replace("PLAN_OWNER_", "").lower() - if owner: - pairs.append(("billing", owner)) - return plan_rows(plan.get("planName"), pairs, w) - - -def cursor_spend(days=30): - """Per-model tokens and real cost over a window. - - This is what the plan percentages are made of: which model spent the - money. `totalCents` is Cursor's own figure, not an estimate. - """ - now = int(time.time() * 1000) - return cursor_rpc("GetAggregatedUsageEvents", - {"startDate": str(now - days * 86400 * 1000), - "endDate": str(now)}) - - -CURSOR_EVENT_PAGE = 1000 # the RPC's own ceiling per request -CURSOR_EVENT_PAGES = 8 # enough to reach past any sane window -EVENTS_TTL = 1800 - - -def cursor_events(days=30): - """Per-day spend, from the raw events cursor.com's own dashboard uses. - - GetAggregatedUsageEvents totals by model and carries no timestamp at all, - so no calendar can be built from it. GetFilteredUsageEvents returns the - individual events - each with a timestamp, a model and its cents - newest - first, a thousand at a time. - - Paging stops as soon as a page reaches past the window, so the cost is - proportional to the window rather than to the account's whole history: - thirty days is five pages and about eleven seconds here. Held for half an - hour, because that is far too slow to repeat on a redraw. - """ - cut = time.time() - days * 86400 - days_cents, days_tokens, by_day_model = {}, {}, {} - vendor_cents = 0.0 - tokens = 0 - counted = 0 - for page in range(1, CURSOR_EVENT_PAGES + 1): - got = cursor_rpc("GetFilteredUsageEvents", - {"page": page, "pageSize": CURSOR_EVENT_PAGE}) - events = (got or {}).get("usageEventsDisplay") or [] - if not events: - break - oldest = time.time() - for e in events: - try: - when = int(e["timestamp"]) / 1000.0 - except (KeyError, ValueError, TypeError): - continue - oldest = min(oldest, when) - if when < cut: - continue - use = e.get("tokenUsage") or {} - cents = float(use.get("totalCents") or 0) - n = int(use.get("inputTokens") or 0) + int(use.get("outputTokens") or 0) - day = datetime.date.fromtimestamp(when) - days_cents[day] = days_cents.get(day, 0.0) + cents - days_tokens[day] = days_tokens.get(day, 0) + n - slot = by_day_model.setdefault(day.isoformat(), {}).setdefault( - str(e.get("model") or "?"), {"cents": 0.0, "tokens": 0}) - slot["cents"] += cents - slot["tokens"] += n - vendor_cents += cents - tokens += n - counted += 1 - if oldest < cut or len(events) < CURSOR_EVENT_PAGE: - break - if not counted: - return None - return {"by_day": days_cents, "tokens_by_day": days_tokens, - "by_day_model": by_day_model, "vendor_cents": vendor_cents, - "tokens": tokens, "events": counted, "days": days} - - -def read_cursor(): - """Cursor's AI code tracking: how much code it wrote, not what it cost.""" - if not os.path.exists(CURSOR_DB): - return {"ok": False, "why": "no tracking database", - "live": cached("cursor", cursor_live), - "plan": cached("cursor-plan", cursor_plan, ttl=PLAN_TTL), - "events": cached("cursor-events", cursor_events, - ttl=EVENTS_TTL), - "spend": cached("cursor-spend", cursor_spend)} - try: - con = sqlite3.connect("file:%s?mode=ro" % CURSOR_DB, uri=True) - rows = con.execute( - "select count(*), count(distinct conversationId)," - " count(distinct model) from ai_code_hashes").fetchone() - by_model = con.execute( - "select model, count(*) from ai_code_hashes" - " group by model order by 2 desc limit 8").fetchall() - commits = con.execute( - "select count(*), sum(linesAdded), sum(humanLinesAdded)" - " from scored_commits").fetchone() - recent = con.execute( - "select max(timestamp) from ai_code_hashes").fetchone()[0] - con.close() - except sqlite3.Error as e: - return {"ok": False, "why": str(e)[:40]} - return {"ok": True, "live": cached("cursor", cursor_live), - "plan": cached("cursor-plan", cursor_plan, ttl=PLAN_TTL), - "events": cached("cursor-events", cursor_events, - ttl=EVENTS_TTL), - "spend": cached("cursor-spend", cursor_spend), - "hashes": rows[0], "conversations": rows[1], - "models": rows[2], "by_model": by_model, - "commits": commits[0] or 0, "lines": commits[1] or 0, - "human_lines": commits[2] or 0, "last": recent} - - -def tail_lines(path, size=TAIL): - """The last `size` bytes as lines, for files that run to tens of MB. - - A rollout carries its running total on every token_count event, so the - newest one is all that is needed - reading 30MB per refresh to learn a - number that is repeated at the end would be daft. - """ - try: - with open(path, "rb") as f: - f.seek(0, 2) - end = f.tell() - f.seek(max(0, end - size)) - return f.read().decode("utf-8", "ignore").split("\n") - except OSError: - return [] - - -CODEX_AUTH = os.path.expanduser("~/.codex/auth.json") -CODEX_USAGE_API = "https://chatgpt.com/backend-api/wham/usage" -_CODEX_CACHE = {} - -LIVE_TTL = 120 -_LIVE = {} - - -def cached(key, fn, ttl=LIVE_TTL): - """Hold a reading for a while, but never hold a failure that long. - - The pane redraws every 30 seconds; these windows move over hours, and - three tabs between them were making six requests a minute to say the - same thing. A failure is cached too, so a dead endpoint is retried - occasionally rather than on every frame - but only ever for the short - interval, never the long one. A subscription is held an hour because it - does not change; one transient 429 should not blank its section for an - hour, which is exactly what happened here. - """ - now = time.time() - hit = _LIVE.get(key) - if hit and now - hit[0] < hit[2]: - return hit[1] - val = fn() - _LIVE[key] = (now, val, ttl if val else min(ttl, LIVE_TTL)) - return val - - -def codex_live(): - """Account-wide quota, live from the same endpoint the Codex CLI uses. - - The rollouts carry a rate_limits snapshot, but only from whenever Codex - last ran - it can be days stale. This is the current figure, and it is the - account rather than this machine. - - The token comes from ~/.codex/auth.json and goes to the same host Codex - itself talks to; it is never printed. Any failure falls back to the - snapshot, so an expired token costs nothing but freshness. - - Found by reading how CodexBar does it (github.com/steipete/CodexBar), - which documents this endpoint. - """ - try: - with open(CODEX_AUTH) as f: - auth = json.load(f) - except (OSError, ValueError): - return None - tok = (auth.get("tokens") or {}).get("access_token") or auth.get("access_token") - if not tok: - return None - req = urllib.request.Request(CODEX_USAGE_API, headers={ - "Authorization": "Bearer " + tok, "User-Agent": "terminal-toys"}) - try: - with urllib.request.urlopen(req, timeout=20) as r: - return json.load(r) - except (urllib.error.URLError, ValueError, OSError): - return None - - -def scan_rollout(path): - """Per-day tokens, the running total, and the newest quota snapshot. - - Cached on (mtime, size): a finished rollout never changes, and some run to - 30MB, so the full parse happens once per file rather than every refresh. - """ - try: - st = os.stat(path) - except OSError: - return None - key = (st.st_mtime, st.st_size) - hit = _CODEX_CACHE.get(path) - if hit and hit[0] == key: - return hit[1] - daily = {} - total, limits, limits_at = None, None, None - try: - with open(path, errors="ignore") as f: - for line in f: - if '"token_count"' not in line: - continue - try: - d = json.loads(line) - except ValueError: - continue - info = (d.get("payload") or {}).get("info") or {} - last = info.get("last_token_usage") or {} - ts = d.get("timestamp") or "" - if last.get("total_tokens") and ts[:10]: - daily[ts[:10]] = daily.get(ts[:10], 0) + last["total_tokens"] - if info.get("total_token_usage"): - total = info["total_token_usage"] - rl = d.get("payload", {}).get("rate_limits") or info.get("rate_limits") - if rl: - limits, limits_at = rl, ts - except OSError: - return None - out = {"daily": daily, "total": total, "limits": limits, - "limits_at": limits_at, "mtime": st.st_mtime} - _CODEX_CACHE[path] = (key, out) - return out - - -_ROLLOUT_MODELS = {} - - -def scan_rollout_models(path): - """Per-day, per-model token counts from one rollout. - - The model is not on the token counts: it arrives in `turn_context`, one - per turn, and applies to the `token_count` events that follow it. So the - file is walked in order, carrying the model forward. - - `last_token_usage` is the per-turn delta - the running total is on every - event and summing those would count the session once per turn. Within - input_tokens, cached_input_tokens is the cheaper subset, and within - output_tokens the reasoning tokens are already included, so only the - uncached remainder is charged at the input rate. - - Keyed by (session, ordinal) so a rollout replayed into a resumed session - is not counted twice - the same fault that inflated Claude's figures. - """ - try: - st = os.stat(path) - except OSError: - return {} - key = (st.st_mtime, st.st_size) - hit = _ROLLOUT_MODELS.get(path) - if hit and hit[0] == key: - return hit[1] - # session_id, not the filename: a resumed session replays into a new - # file, and two rollouts in different directories can share a basename. - # The sequence number is counted here because `ordinal` is absent from - # older rollouts - keying on it collapsed every file to one record. - # session_id + timestamp, not the filename and not a sequence: a resumed - # session replays its earlier events into a new file, so the same turn is - # written twice with the same stamp. Sequence numbers restart per file and - # would pair unrelated events; `ordinal` is absent from older rollouts. - records, model, session = {}, None, os.path.basename(path) - try: - with open(path, errors="replace") as fh: - for line in fh: - if ('"model"' not in line and '"token_count"' not in line - and '"session_meta"' not in line): - continue - try: - r = json.loads(line) - except ValueError: - continue - payload = r.get("payload") or {} - if r.get("type") == "session_meta": - session = payload.get("session_id") or session - continue - if r.get("type") == "turn_context": - model = payload.get("model") or model - continue - if payload.get("type") != "token_count": - continue - use = (payload.get("info") or {}).get("last_token_usage") or {} - if not use or not model: - continue - when = iso_epoch(r.get("timestamp") or "") - if not when: - continue - cached = use.get("cached_input_tokens") or 0 - got = dict.fromkeys(RATE_KINDS + ("reasoning",), 0) - got["input"] = max(0, (use.get("input_tokens") or 0) - cached) - got["cache_read"] = cached - got["cache_write"] = use.get("cache_write_input_tokens") or 0 - got["output"] = use.get("output_tokens") or 0 - got["reasoning"] = use.get("reasoning_output_tokens") or 0 - if not any(got.values()): - continue - records[(session, r.get("timestamp"))] = ( - datetime.date.fromtimestamp(when).isoformat(), model, got) - except OSError: - return {} - _ROLLOUT_MODELS[path] = (key, records) - return records - - -def codex_daily(): - """Every rollout's per-day, per-model tokens, de-duplicated.""" - seen = {} - for path in glob.glob(CODEX_SESSIONS, recursive=True): - seen.update(scan_rollout_models(path)) - merged = {} - for day, model, tokens in seen.values(): - bucket = merged.setdefault(day, {}).setdefault( - model, dict.fromkeys(RATE_KINDS + ("reasoning",), 0)) - for kind in tokens: - bucket[kind] = bucket.get(kind, 0) + tokens[kind] - return merged - - -def codex_session_count(): - """Distinct sessions, not rollout files. - - Thirty rollouts here hold eight sessions: resuming writes a new file for - a session that already existed. Counting files and calling them sessions - was the same mistake that made the totals wrong, in the label. - """ - ids = set() - for path in glob.glob(CODEX_SESSIONS, recursive=True): - ids.update(key[0] for key in scan_rollout_models(path)) - return len(ids) - - -def codex_totals(daily): - """Totals from the de-duplicated per-turn deltas. - - Not from the rollout tails. `total_token_usage` is cumulative for the - *session*, and a session spans several files - thirty rollouts here hold - only eight sessions - so summing one tail per file counted most sessions - two or three times over: 664.5M against a true 370.0M for the primary - model. Summing the per-turn deltas instead reproduces Codex's own - cumulative figure exactly on four of those eight sessions, and picks up - the review model besides, which the session total never included. - """ - out = {"input_tokens": 0, "output_tokens": 0, "reasoning_output_tokens": 0, - "cached_input_tokens": 0, "total_tokens": 0} - for models in (daily or {}).values(): - for tokens in models.values(): - out["input_tokens"] += tokens.get("input", 0) + tokens.get("cache_read", 0) - out["cached_input_tokens"] += tokens.get("cache_read", 0) - out["output_tokens"] += tokens.get("output", 0) - out["reasoning_output_tokens"] += tokens.get("reasoning", 0) - out["total_tokens"] = out["input_tokens"] + out["output_tokens"] - return out - - -def read_codex(): - """Codex rollouts carry token_count events with running and per-turn use. - - ~/.codex/logs is diagnostics and has no counters, which is where an - earlier look stopped. The sessions directory is the one that counts. - """ - files = sorted(glob.glob(CODEX_SESSIONS, recursive=True), - key=os.path.getmtime) - if not files: - return {"ok": False, "why": "no session rollouts"} - total = {"input_tokens": 0, "output_tokens": 0, - "reasoning_output_tokens": 0, "total_tokens": 0, - "cached_input_tokens": 0} - counted = 0 - daily = {} - limits, limits_at = None, "" - for path in files: - got = scan_rollout(path) - if not got: - continue - if got["total"]: - counted += 1 - for day, n in got["daily"].items(): - daily[day] = daily.get(day, 0) + n - if got["limits"] and (got["limits_at"] or "") > limits_at: - limits, limits_at = got["limits"], got["limits_at"] - # Totals come from the de-duplicated per-turn deltas, not from summing - # each file's cumulative tail - see codex_totals for why that was wrong. - daily_models = codex_daily() - total = codex_totals(daily_models) - - # per-turn rate, from the newest rollout only - rates, prev = [], None - for line in tail_lines(files[-1], 4 * 1024 * 1024): - if '"token_count"' not in line: - continue - try: - d = json.loads(line) - except ValueError: - continue - u = ((d.get("payload") or {}).get("info") or {}).get( - "last_token_usage") or {} - out, ts = u.get("output_tokens") or 0, d.get("timestamp") - if ts and prev and out: - try: - a = datetime.datetime.fromisoformat(prev.replace("Z", "+00:00")) - b = datetime.datetime.fromisoformat(ts.replace("Z", "+00:00")) - except ValueError: - prev = ts - continue - gap = (b - a).total_seconds() - if 0.5 < gap < 300: - rates.append(out / gap) - prev = ts or prev - rates.sort() - return {"ok": True, "sessions": codex_session_count() or counted, - "files": len(files), - "total": total, "rates": rates, "daily": daily, - "daily_models": daily_models, - "limits": limits, "limits_at": limits_at, "live": cached("codex", codex_live), - "last": os.path.getmtime(files[-1])} - - -def codex_plan_rows(state, w): - """Plan type and a credit balance - all Codex publishes about the plan. - - Three lines rather than the section Copilot and Cursor get, because - three lines is genuinely all there is. Credits belong here rather than - under the quota bars: they are what the plan grants, not a window. - """ - live = state.get("live") or {} - plan = live.get("plan_type") or (state.get("limits") or {}).get("plan_type") - credits = (live.get("credits") - or (state.get("limits") or {}).get("credits") or {}) - pairs = [] - if credits: - pairs.append(("credits", "unlimited" if credits.get("unlimited") - else str(credits.get("balance") or "0"))) - if (live.get("spend_control") or {}).get("individual_limit"): - pairs.append(("spend limit", - str(live["spend_control"]["individual_limit"]))) - if not plan and not pairs: - return [] - return plan_rows(plan, pairs, w) - - -def codex_metered(state, w): - daily = state.get("daily_models") or {} - return metered_rows([("today", window_models(daily, 1)), - ("30 days", window_models(daily, 30))], w, - agent="codex", scope="this machine", - caveat="CLI rollouts only. Codex bills Cloud, Web," - " Desktop and the rest to the same account," - " and none of those leave anything on this" - " disk to count.") - - -def codex_tab(state, w, h): - if not state.get("ok"): - return no_local("No session rollouts on this machine.", - RUN_HINT["codex"], w) - t = state["total"] - rows = [] - # The one genuine quota figure any of these agents publishes: the server - # sends it back with each response and the rollout records it. It is a - # snapshot from whenever Codex last ran, not a live reading, so it is - # dated. - live = state.get("live") or {} - lanes, source, plan = [], "", live.get("plan_type") or "" - if live.get("rate_limit"): - source = "live" - for key in ("primary_window", "secondary_window"): - win = (live["rate_limit"] or {}).get(key) - if win and win.get("used_percent") is not None: - lanes.append(("", win["used_percent"], - win.get("limit_window_seconds"), - win.get("reset_at"))) - # Some features meter separately from the account's general usage - - # Spark is one - and each arrives named, with its own window and - # reset. Rendering the list rather than the one name we know keeps - # any future feature working without an edit. - for extra in live.get("additional_rate_limits") or []: - win = ((extra.get("rate_limit") or {}).get("primary_window") or {}) - if win.get("used_percent") is None: - continue - lanes.append((extra.get("limit_name") or "?", win["used_percent"], - win.get("limit_window_seconds"), win.get("reset_at"))) - elif (state.get("limits") or {}).get("primary"): - source = "from the last session" - win = state["limits"]["primary"] - lanes.append(("", win.get("used_percent"), - (win.get("window_minutes") or 0) * 60, - win.get("resets_at"))) - if lanes: - rows.append(seg([(LBL, " ── QUOTA ── "), - (OK if source == "live" else WARN, source), - (DIM, scope_phrase(w, 13 + len(source) + len(plan))), - (DIM, plan)], w - 1)) - prepared = [] - for name, pct, window, reset in lanes: - secs = int(window or 0) - wname = ("%dd" % (secs // 86400) if secs >= 86400 - else "%dh" % (secs // 3600) if secs else "?") - when = "" - if reset: - left = reset - time.time() - when = ("resets in %dd %dh" % (left // 86400, - (left % 86400) // 3600) - if left > 0 else "resetting") - prepared.append((name, wname, pct, when, secs, reset)) - - # Alone, the account-wide lanes are told apart by their window and a - # bare "7d" is clear enough. Beside a named one it is not, so it says - # what it covers only when there is something to confuse it with. - named = any(name for name, _, _, _, _, _ in prepared) - - def labels(short): - """Spell a feature out while there is room; below that the last - segment carries it - GPT-5.3-Codex-Spark is Spark.""" - out = [] - for name, wname, _, _, _, _ in prepared: - n = name.rsplit("-", 1)[-1] if (short and name) else name - out.append(("%s %s" % (n or ("overall" if named else ""), - wname)).strip()) - return out - - lab = labels(False) - if w - 32 - max(len(x) for x in lab) < 20: - lab = labels(True) - label_w = max(9, max(len(x) for x in lab)) - for (_, _, pct, when, secs, reset), text in zip(prepared, lab): - used = (pct or 0) / 100.0 - # heat(used), not heat(1 - used): red belongs at a quota nearly - # spent, and the inverse painted a 26%-used week amber - rows.append(seg([(DIM, " " + pad(text, label_w) + " ")] - + paced_bar(used, elapsed_of(secs, reset), - max(8, w - 34 - label_w), - AGENT_HUE["codex"]) - + [(pct_colour(pct, ahead_of(lead(pct, secs, reset)), AGENT_HUE["codex"]), - pct_text(pct)), - pace_cell(lead(pct, secs, reset)), - (DIM, " " + when)], w - 1)) - rows.append("") - # Everything Codex publishes about the subscription itself: a plan - # word and a credit balance, which is why this is three lines and - # not the section Copilot and Cursor get. Credits live here rather - rows.append(seg([(LBL, " ── TOTALS ── "), - (DIM, "%d sessions · newest %s ago" - % (state["sessions"], ago(state["last"])))], w - 1)) - cells = [("input tokens", big_num(t["input_tokens"]), TXT), - ("output tokens", big_num(t["output_tokens"]), AGENT), - ("reasoning tokens", big_num(t["reasoning_output_tokens"]), TXT), - ("cached input", big_num(t["cached_input_tokens"]), DIM), - ("all tokens", big_num(t["total_tokens"]), TXT), - ("rollout files", "%d" % state["files"], DIM)] - label_w = max(len(c[0]) for c in cells) - ncols = 2 if (w - 2) // 2 - label_w - 3 >= 8 else 1 - cw = (w - 2) // ncols - val_w = max(5, cw - label_w - 3) - for i in range(0, len(cells), ncols): - line = [(RST, " ")] - for label, value, colour in cells[i:i + ncols]: - line += [(DIM, " " + pad(label, label_w) + " "), - (colour, pad(value, val_w))] - rows.append(seg(line, w - 1)) - - rates = state["rates"] - rows.append("") - if rates: - med = rates[len(rates) // 2] - p90 = rates[min(len(rates) - 1, int(len(rates) * 0.9))] - rows.append(seg([(LBL, " ── OUTPUT RATE ── "), - (DIM, "newest session, %d turns" % len(rates))], w - 1)) - rows.append(seg([(DIM, " median "), (AGENT, "%.0f" % med), - (DIM, " tok/s p90 "), (TXT, "%.0f" % p90), - (DIM, " max "), (TXT, "%.0f" % rates[-1])], w - 1)) - hi = rates[-1] or 1 - # The bucket count stays tied to the sample count - twenty-eight - # turns spread over fifty columns is a comb, not a distribution - - # but each bucket is then drawn as wide as the pane allows, so the - # chart fills its line instead of stopping a third of the way in. - buckets = [0] * max(10, min(len(rates), w - 6)) - for r in rates: - buckets[min(len(buckets) - 1, - int(r / hi * (len(buckets) - 1)))] += 1 - cols = [] - for b, wide in zip(buckets, spread(len(buckets), max(10, w - 3))): - cols.extend([(b, AGENT)] * wide) - for line in vbars(cols, 3): - rows.append(seg([(RST, " ")] + line, w - 1)) - rows.append(seg([(RST, " "), (GRID, "─" * len(cols))], w - 1)) - right = "%.0f tok/s" % rates[-1] - rows.append(seg([(DIM, " 0 tok/s"), - (DIM, " " * max(1, len(cols) - 8 - len(right))), - (DIM, right)], w - 1)) - grid, peak, best, facts = day_calendar(state.get("daily") or {}, w, - CODEX_STEPS) - if grid: - rows.append("") - rows.append(seg([(LBL, " ── TOKENS / DAY ── "), - (DIM, "peak "), (AGENT, big_num(peak)), - (DIM, " on %s" % (best.strftime("%b %-d") if best - else "--"))], w - 1)) - for line in grid: - rows.append(seg(line, w - 1)) - rows.append(seg([(DIM, " Less ")] - + [(rgb(*c), "█") for c in CODEX_STEPS] - + [(DIM, " More")], w - 1)) - rows.append("") - rows.append(seg([(DIM, " Tokens and rate are measured here, from the" - " rollouts. Quota is")], w - 1)) - rows.append(seg([(DIM, " the account's, fetched from the same endpoint" - " the Codex CLI uses.")], w - 1)) - return rows - - -_GROK_CACHE = {} - - -def grok_quota(): - """Grok's weekly credit window, as its own CLI receives it. - - Not hidden and not inferred: the server sends it, and the CLI writes it - into the session log under `.ctx.config`. An earlier pass here concluded - no quota existed, having grepped for limit/quota/remaining/reset - the - keys are `creditUsagePercent` and `currentPeriod`, so the search missed - them and the tab said so in print for a day. - """ - best = None - for path in [GROK_LOG] if os.path.exists(GROK_LOG) else []: - for line in tail_lines(path, 2 * 1024 * 1024): - if "creditUsagePercent" not in line: - continue - try: - d = json.loads(line) - except ValueError: - continue - ctx = d.get("ctx") if isinstance(d, dict) else None - cfg = (ctx or {}).get("config") if isinstance(ctx, dict) else None - if not isinstance(cfg, dict) or "creditUsagePercent" not in cfg: - continue - period = cfg.get("currentPeriod") or {} - when = period.get("start") or "" - if best is None or when >= best["start"]: - best = {"percent": cfg.get("creditUsagePercent"), - "kind": period.get("type") or "", - "start": when, "end": period.get("end") or "", - "tier": (ctx or {}).get("subscriptionTier") or "", - "on_demand_used": (cfg.get("onDemandUsed") or {}).get("val"), - "on_demand_cap": (cfg.get("onDemandCap") or {}).get("val"), - "prepaid": (cfg.get("prepaidBalance") or {}).get("val")} - if best: - break - return best - - -def read_grok(): - """Grok logs a running totalTokens on each session event. - - Deltas between consecutive events, bucketed by the event's own timestamp, - give per-day figures; the running total alone would credit an entire - session to whichever day it happened to be read on. Cached per file on - mtime and size, like the Codex rollouts. - """ - files = glob.glob(GROK_SESSIONS, recursive=True) - if not files: - return {"ok": False, "why": "no sessions on disk"} - total, daily, sessions, newest = 0, {}, 0, 0 - for path in files: - try: - st = os.stat(path) - except OSError: - continue - key = (st.st_mtime, st.st_size) - hit = _GROK_CACHE.get(path) - if hit and hit[0] == key: - got = hit[1] - else: - got, prev = {"total": 0, "daily": {}}, 0 - try: - with open(path, errors="ignore") as f: - for line in f: - m = re.search(r'"totalTokens":(\d+)', line) - if not m: - continue - value = int(m.group(1)) - step = value - prev - prev = max(prev, value) - if step <= 0: - continue - when = re.search(r'"agentTimestampMs":(\d+)', line) - if not when: - continue - day = datetime.datetime.fromtimestamp( - int(when.group(1)) / 1000.0, - datetime.timezone.utc).date().isoformat() - got["daily"][day] = got["daily"].get(day, 0) + step - got["total"] += step - except OSError: - continue - _GROK_CACHE[path] = (key, got) - if got["total"]: - sessions += 1 - total += got["total"] - for day, n in got["daily"].items(): - daily[day] = daily.get(day, 0) + n - newest = max(newest, st.st_mtime) - return {"ok": True, "sessions": sessions, "files": len(files), - "total": total, "daily": daily, "last": newest, - "quota": grok_quota()} - - -def grok_plan_rows(q, w): - """Grok states its tier and the kind of period it bills in, and no more. - - Both arrive on the client log beside the credit percentage, so this - costs nothing extra to show. - """ - if not q: - return [] - pairs = [] - kind = (q.get("kind") or "").replace("USAGE_PERIOD_TYPE_", "").lower() - if kind: - pairs.append(("billing period", kind)) - cap = q.get("on_demand_cap") - if cap is not None: - pairs.append(("on-demand", "%s of %s used" - % (q.get("on_demand_used") or 0, cap))) - if q.get("prepaid") is not None: - pairs.append(("prepaid balance", str(q["prepaid"]))) - return plan_rows(q.get("tier"), pairs, w) - - -def grok_tab(state, w, h): - if not state.get("ok"): - return no_local("No Grok sessions on this machine.", - RUN_HINT["grok"], w) - rows = [] - q = state.get("quota") - if q and q.get("percent") is not None: - # The one real remaining-quota figure in this widget: everything else - # here counts what was spent. It leads the tab for that reason. - used = float(q["percent"]) / 100.0 - left = None - try: - end = datetime.datetime.fromisoformat(q["end"]) - left = (end - datetime.datetime.now( - datetime.timezone.utc)).total_seconds() / 86400.0 - except (ValueError, TypeError): - pass - period = ("weekly" if "WEEKLY" in (q.get("kind") or "") - else (q.get("kind") or "").replace( - "USAGE_PERIOD_TYPE_", "").lower() or "current") - rows.append(seg([(LBL, " ── %s QUOTA ── " % period.upper()), - (DIM, "resets in %.1f days" % left - if left is not None and left >= 0 else "")], w - 1)) - span, reset_ts = None, None - begin, finish = iso_epoch(q.get("start") or ""), iso_epoch(q.get("end") or "") - if begin and finish and finish > begin: - span, reset_ts = finish - begin, finish - rows.append(seg([(pct_colour(float(q["percent"]), - ahead_of(lead(float(q["percent"]), span, - reset_ts)), - AGENT_HUE["grok"]), - " %-5s" % ("%.0f%%" % q["percent"]))] - + paced_bar(used, elapsed_of(span, reset_ts), - max(10, w - 38), AGENT_HUE["grok"]) - + [(DIM, " credits used"), - pace_cell(lead(float(q["percent"]), span, - reset_ts))], w - 1)) - span = "" - for key, label in (("start", ""), ("end", " → ")): - try: - span += label + datetime.datetime.fromisoformat( - q[key]).strftime("%-d %b") - except (ValueError, TypeError, KeyError): - span = "" - break - extras = [] - if q.get("on_demand_cap"): - extras.append("on-demand %s/%s" % (q.get("on_demand_used"), - q["on_demand_cap"])) - if q.get("prepaid"): - extras.append("prepaid %s" % q["prepaid"]) - rows.append(seg([(DIM, " window "), (TXT, span or "?"), - (DIM, " " + " · ".join(extras) if extras else "")], - w - 1)) - rows.append("") - rows.append(seg([(LBL, " ── TOTALS ── "), - (DIM, "%d sessions · newest %s ago" - % (state["sessions"], ago(state["last"])))], w - 1)) - rows.append(seg([(DIM, " tokens "), (AGENT, big_num(state["total"])), - (DIM, " across %d session files" % state["files"])], - w - 1)) - grid, peak, best, facts = day_calendar(state.get("daily") or {}, w, - GROK_STEPS) - if grid: - rows.append("") - rows.append(seg([(LBL, " ── TOKENS / DAY ── "), - (DIM, "peak "), (AGENT, big_num(peak)), - (DIM, " on %s" % (best.strftime("%b %-d") if best - else "--"))], w - 1)) - for line in grid: - rows.append(seg(line, w - 1)) - rows.append(seg([(DIM, " Less ")] - + [(rgb(*c), "█") for c in GROK_STEPS] - + [(DIM, " More")], w - 1)) - rows.append("") - rows.append(seg([(DIM, " Totals are a running count per session, summed" - " as deltas so a")], w - 1)) - rows.append(seg([(DIM, " session spanning days lands on the right one." - " The quota above is")], w - 1)) - rows.append(seg([(DIM, " the server's own figure, read from the client" - " log - not inferred.")], w - 1)) - return rows - - -# Agents whose usage exists but is not readable from outside their session. -# Naming where the number actually lives beats showing an empty gauge. -ELSEWHERE = {} - - -ANTIGRAVITY_RPC = ("/exa.language_server_pb.LanguageServerService" - "/RetrieveUserQuotaSummary") - - -def antigravity_ports(): - """TCP ports the running Antigravity language server listens on. - - The quota never reaches disk, but the process holding it serves an RPC - on localhost, so the port is the way in. Found by matching the process - then reading its listening sockets out of /proc - no lsof, no guessing - at a range, and nothing touched but our own machine. - """ - pids = [] - for entry in os.listdir("/proc"): - if not entry.isdigit(): - continue - try: - with open("/proc/%s/cmdline" % entry, "rb") as f: - cmd = f.read().replace(b"\x00", b" ").decode("utf8", "replace") - except OSError: - continue - if re.search(r"(^|/)(agy|antigravity)\b|language_server", cmd): - pids.append(entry) - inodes = set() - for pid in pids: - for fd in glob.glob("/proc/%s/fd/*" % pid): - try: - target = os.readlink(fd) - except OSError: - continue - if target.startswith("socket:["): - inodes.add(target[8:-1]) - ports = [] - for table in ("/proc/net/tcp", "/proc/net/tcp6"): - try: - with open(table) as f: - rows = f.read().splitlines()[1:] - except OSError: - continue - for row in rows: - cols = row.split() - if len(cols) > 9 and cols[3] == "0A" and cols[9] in inodes: - ports.append(int(cols[1].split(":")[1], 16)) - return sorted(set(ports)) - - -def antigravity_quota(): - """Weekly and five-hour limits, from the language server on localhost. - - The same figures Antigravity's own TUI prints. It speaks Connect over - plain HTTP on a loopback port - its TLS listener answers with a wrong - version number, so http is not a downgrade here, it is the protocol - - and the call leaves this machine no more than reading a file would. - - Found by reading how CodexBar does it (github.com/steipete/CodexBar), - after chasing the Google endpoint in the binary to a 404: the quota was - never a remote call to make, it was a local one. - """ - for port in antigravity_ports(): - req = urllib.request.Request( - "http://127.0.0.1:%d%s" % (port, ANTIGRAVITY_RPC), data=b"{}", - method="POST", headers={"Content-Type": "application/json"}) - try: - with urllib.request.urlopen(req, timeout=5) as r: - got = json.load(r) - except (urllib.error.URLError, ValueError, OSError): - continue - groups = ((got.get("response") or got).get("groups") or []) - if groups: - return groups - return None - - -def antigravity_live(): - """Which Code Assist tier the account is on. - - Antigravity keeps no quota and no token counts on disk - its language - server refreshes a quota into memory and is not even installed between - runs - so this endpoint is the only thing that can answer anything, and - what it answers is the subscription rather than the spend. - - The access token expires hourly and Antigravity refreshes it; an expired - one is skipped rather than refreshed here, for the same reason Claude's - is: that is the CLI's job and racing it would be rude. - """ - try: - with open(ANTIGRAVITY_TOKEN) as f: - tok = (json.load(f) or {}).get("token") or {} - except (OSError, ValueError): - return None - access = tok.get("access_token") - exp = iso_epoch(tok.get("expiry") or "") - if not access or (exp and exp <= time.time()): - return None - req = urllib.request.Request( - CODE_ASSIST_API, method="POST", - data=json.dumps({"metadata": {"pluginType": "GEMINI"}}).encode(), - headers={"Authorization": "Bearer " + access, - "Content-Type": "application/json", - # Google gates this response on the client string. Sent as - # plain terminal-toys it answers UNSUPPORTED_CLIENT and - # returns no tier at all; the parenthesised form is the - # conventional way to name the client being spoken for - # while still saying who is actually calling. - "User-Agent": "terminal-toys (antigravity-cli)"}) - try: - with urllib.request.urlopen(req, timeout=20) as r: - return json.load(r) - except (urllib.error.URLError, ValueError, OSError): - return None - - -def read_antigravity(): - """What the conversation stores record, which is activity and not cost. - - Each conversation is its own SQLite file with a `steps` table - one row - per step the agent took - so the counts are real work done. No table - anywhere carries a token count. - """ - out = {"ok": True, "live": cached("antigravity", antigravity_live, - ttl=PLAN_TTL), - "quota": cached("antigravity-quota", antigravity_quota), - "sessions": 0, "steps": 0, "prompts": 0, "last": 0} - files = glob.glob(ANTIGRAVITY_CONVERSATIONS) - out["sessions"] = len(files) - for path in files: - try: - out["last"] = max(out["last"], os.path.getmtime(path)) - con = sqlite3.connect("file:%s?mode=ro" % path, uri=True) - out["steps"] += con.execute( - "select count(*) from steps").fetchone()[0] - con.close() - except (sqlite3.Error, OSError): - continue - try: - with open(ANTIGRAVITY_HISTORY) as f: - out["prompts"] = sum(1 for line in f if line.strip()) - out["last"] = max(out["last"], os.path.getmtime(ANTIGRAVITY_HISTORY)) - except OSError: - pass - if not files and not out["prompts"]: - out["why"] = "no conversations recorded" - return out - - -def antigravity_plan_rows(state, w): - live = state.get("live") or {} - cur = live.get("currentTier") or {} - paid = live.get("paidTier") or {} - if not cur and not paid: - return [] - pairs = [] - if cur.get("id"): - pairs.append(("code assist tier", cur["id"])) - # paidTier is the Google AI subscription behind the account, which is a - # different thing from the Code Assist tier and can disagree with it - - # free-tier here, while the account is on Ultra. Both are stated. - if paid.get("name"): - pairs.append(("google ai plan", paid["name"])) - if live.get("cloudaicompanionProject"): - pairs.append(("project", live["cloudaicompanionProject"])) - try: - with open(ANTIGRAVITY_TOKEN) as f: - method = (json.load(f) or {}).get("auth_method") or "" - if method: - pairs.append(("auth", method)) - except (OSError, ValueError): - pass - # The two tiers can disagree - free-tier beside Google AI Ultra is - # normal, since one is GCP licensing and the other a consumer plan - but - # that is a paragraph the docs can carry, not four lines on every frame. - return plan_rows(cur.get("name") or paid.get("name"), pairs, w) - - -ANTIGRAVITY_WINDOWS = {"weekly": 7 * 86400, "5h": 5 * 3600} - - -def antigravity_quota_rows(groups, w): - """One bar per limit, grouped by the model family it covers. - - Shown as spent rather than the remaining fraction the RPC returns, so - red means the same here as on every other tab. Every plan reports every - family it covers, so a Gemini-only account still gets a Claude/GPT pair - sitting at 0% - they are real limits, not padding, and are left in. - """ - if not groups: - return [] - # The long form names where the number comes from, which matters here - # more than elsewhere; the short one still says it is not this machine's - # own tally. Shortened before it can clip, as the other headers are. - note = " · account-wide, from the local language server" - for shorter in (" · from the local server", " · local"): - if 13 + len("live") + len(note) <= w - 1: - break - note = shorter - rows = [seg([(LBL, " ── QUOTA ── "), (OK, "live"), (DIM, note)], w - 1)] - for group in groups: - buckets = [b for b in (group.get("buckets") or []) - if b.get("remainingFraction") is not None] - if not buckets: - continue - rows.append(seg([(TXT, " " + str(group.get("displayName") or "?"))], - w - 1)) - label_w = max(len(str(b.get("window") or "?")) for b in buckets) - for b in buckets: - pct = 100.0 * (1.0 - float(b["remainingFraction"])) - used = max(0.0, min(1.0, pct / 100.0)) - window = str(b.get("window") or "?") - reset = iso_epoch(b.get("resetTime") or "") - when = "" - if reset: - left = reset - time.time() - when = ("resets in " + left_span(left) if left > 0 - else "resetting") - room = w - 36 - label_w - if room < 8: - # Below the bar's floor the row cannot shrink further, so the - # reset stands down rather than being cut in half. - when = "" - room = w - 20 - label_w - rows.append(seg([(DIM, " " + pad(window, label_w) + " ")] - + paced_bar(used, elapsed_of( - ANTIGRAVITY_WINDOWS.get(window), reset), - max(8, room), AGENT_HUE["antigravity"]) - + [(pct_colour(pct, ahead_of(lead( - pct, ANTIGRAVITY_WINDOWS.get(window), reset)), - AGENT_HUE["antigravity"]), - pct_text(pct)), - pace_cell(lead(pct, - ANTIGRAVITY_WINDOWS.get(window), - reset)), - (DIM, " " + when)], w - 1)) - rows.append("") - return rows - - -def antigravity_tab(state, w, h): - rows = antigravity_quota_rows(state.get("quota"), w) - if state.get("live") is None: - rows.append(seg([(WARN, " no tier: the CLI's access token has" - " expired or the call failed")], w - 1)) - rows.append("") - rows.append(seg([(LBL, " ── ACTIVITY ── "), - (DIM, "local · %s" % ("last %s ago" % ago(state["last"]) - if state.get("last") - else "never run here"))], w - 1)) - cells = [("conversations", "%d" % state.get("sessions", 0), TXT), - ("agent steps", "%d" % state.get("steps", 0), AGENT), - ("prompts", "%d" % state.get("prompts", 0), TXT)] - label_w = max(len(c[0]) for c in cells) - for label, value, colour in cells: - rows.append(seg([(DIM, " " + pad(label, label_w) + " "), - (colour, value)], w - 1)) - rows.append("") - # The absence is only worth explaining while it is one. With the quota - # drawn above, a paragraph about why there is no quota contradicts the - # screen. - if state.get("quota"): - rows += no_local("No per-token usage is recorded locally - the" - " conversations and steps above are what there is.", - "", w) - else: - rows += no_local("No tokens are recorded locally, and no quota" - " either: it comes from the language server while" - " Antigravity is running, so start it and this fills" - " in.", "", w) - return rows - - -def copilot_token(): - """The CLI keeps its OAuth token in ~/.copilot/config.json. - - That file is JSON with `//` comments on top, which json.load refuses, so - the comments come off first. Keyed by host and login, because one machine - can be signed in to github.com and an Enterprise host at once. - """ - try: - with open(COPILOT_CONFIG) as f: - raw = re.sub(r"^\s*//.*$", "", f.read(), flags=re.M) - toks = (json.loads(raw) or {}).get("copilotTokens") or {} - except (OSError, ValueError): - return None - for host, tok in toks.items(): - if tok: - return tok - return None - - -def copilot_live(): - """Entitlement and quota, from the endpoint the Copilot CLI itself uses. - - This is where Copilot's remaining quota actually lives. The session store - records what was spent per turn and is empty on plenty of machines; this - is the account's standing, and it answers the only question a limit pane - is really asked. - """ - tok = copilot_token() - if not tok: - return {"why": "no token in ~/.copilot/config.json"} - req = urllib.request.Request(COPILOT_USER_API, headers={ - "Authorization": "token " + tok, "User-Agent": "terminal-toys", - "Accept": "application/json"}) - try: - with urllib.request.urlopen(req, timeout=20) as r: - return {"data": json.load(r)} - except (urllib.error.URLError, ValueError, OSError) as e: - # Which of the two went wrong matters: blaming the config file for a - # dropped connection sends the reader to edit a file that is fine. - return {"why": "quota request failed: %s" % str(e)[:40]} - - -def read_copilot(): - """Live quota, plus whatever the local session store has recorded. - - The two halves are independent: the quota is the account's and arrives - over the network, while the per-turn detail is this machine's and is - frequently empty. Either can be present without the other. - """ - got = cached("copilot", copilot_live) or {} - out = {"ok": True, "live": got.get("data"), "live_why": got.get("why"), - "sessions": 0, "events": 0, "usage": None} - if not os.path.exists(COPILOT_DB): - out["why"] = "no session store" - return out - try: - con = sqlite3.connect("file:%s?mode=ro" % COPILOT_DB, uri=True) - out["sessions"] = con.execute( - "select count(*) from sessions").fetchone()[0] - row = con.execute( - "select count(*), sum(input_tokens), sum(output_tokens)," - " sum(cache_read_tokens), sum(reasoning_tokens)," - " sum(total_nano_aiu), avg(time_to_first_token_ms)," - " avg(inter_token_latency_ms), sum(duration_ms)" - " from assistant_usage_events").fetchone() - out["events"] = row[0] or 0 - if out["events"]: - out["usage"] = { - "input": row[1] or 0, "output": row[2] or 0, - "cache": row[3] or 0, "reasoning": row[4] or 0, - "nano_aiu": row[5] or 0, "ttft": row[6] or 0, - "itl": row[7] or 0, "ms": row[8] or 0, - } - for day, model, i_tok, o_tok, cr, cw in con.execute( - "select date(created_at), model, sum(input_tokens)," - " sum(output_tokens), sum(cache_read_tokens)," - " sum(cache_write_tokens) from assistant_usage_events" - " group by 1, 2"): - bucket = out.setdefault("daily_models", {}).setdefault( - str(day), {}).setdefault( - model, dict.fromkeys(RATE_KINDS, 0)) - bucket["input"] += i_tok or 0 - bucket["output"] += o_tok or 0 - bucket["cache_read"] += cr or 0 - bucket["cache_write"] += cw or 0 - out["models"] = con.execute( - "select model, count(*), sum(output_tokens)," - " sum(input_tokens), sum(cache_read_tokens)," - " sum(cache_write_tokens)" - " from assistant_usage_events group by model" - " order by 3 desc limit 6").fetchall() - con.close() - except sqlite3.Error as e: - out["why"] = str(e)[:40] - return out - - -# The account's own description of itself. Names are what the API returns, -# shortened only where it repeats itself. -COPILOT_FEATURES = (("chat_enabled", "chat"), - ("cli_enabled", "cli"), - ("is_mcp_enabled", "mcp"), - ("cli_remote_control_enabled", "remote control"), - ("cloud_session_storage_enabled", "cloud sessions"), - ("copilot_app_enabled", "app"), - ("editor_preview_features_enabled", "editor previews"), - ("copilotignore_enabled", "copilotignore")) - - -def wrap_text(text, budget): - """Plain text flowed to a width. Clipping a sentence loses its end.""" - lines, line = [], "" - for word in str(text).split(): - if line and len(line) + 1 + len(word) > budget: - lines.append(line) - line = word - else: - line = (line + " " + word) if line else word - if line: - lines.append(line) - return lines or [""] - - -def wrap_pair(key, value, label_w, w): - """A labelled value flowed onto as many lines as it needs. - - Only text can be wrapped. A bar chart broken across two lines is not a - bar chart, and a table row wrapped mid-row loses the columns that made - it a table - which is why those still adapt to the width instead. A - value like an enterprise sku is just words, so it wraps, and the - continuation lines sit under the value rather than under the label. - """ - budget = max(8, w - label_w - 5) - words, lines, line = str(value).split(), [], "" - for word in words: - if line and len(line) + 1 + len(word) > budget: - lines.append(line) - line = word - else: - # A single word longer than the column is split rather than - # allowed to run off; a sku is one word and still has to fit. - while len(word) > budget: - lines.append(word[:budget]) - word = word[budget:] - line = (line + " " + word).strip() if line else word - if line: - lines.append(line) - return [(key if not i else "", part) for i, part in enumerate(lines)] - - -# What to run to make each agent start recording. An empty tab that only -# says "nothing here" leaves the reader to guess whether it is broken. -RUN_HINT = {"claude": "claude", "codex": "codex", "cursor": "cursor-agent", - "grok": "grok", "copilot": "copilot"} - - -def no_local(what, run, w): - """The empty state: what is missing, and the one command that fixes it. - - These tabs used to explain the schema they would have used - the tables, - the column names, why it would have been the best data of the lot. That - is interesting exactly once, and after that it is a wall of text sitting - where the numbers should be. Two lines say as much and answer the only - question an empty tab actually raises. - """ - rows = [seg([(DIM, " " + line)], w - 1) - for line in wrap_text(what, max(20, w - 4))] - if run: - rows.append(seg([(DIM, " run "), (ACCENT, run), - (DIM, " here and this fills in")], w - 1)) - return rows - - -def rate_for(model): - """The rate for a model, and where it came from. - - Config wins outright, then the published list prices. Keyed by model - rather than by agent, because a model has one list price wherever it - ran - the same claude-sonnet-5 entry prices Copilot's turns and Claude - Code's. Longest matching name wins, so claude-opus-4 does not shadow - claude-opus-4-8, and a "*" entry catches anything left over. - """ - name = str(model or "") - if name in NO_PUBLISHED_PRICE and name not in RATES: - return None, None - for table, origin in ((RATES, "config"), (LIST_RATES, "list")): - if name in table: - return table[name], origin - best = None - for key, rate in table.items(): - if key != "*" and key in name: - if best is None or len(key) > len(best[0]): - best = (key, rate) - if best: - return best[1], origin - if table.get("*"): - return table["*"], origin - return None, None - - -def cost_of(tokens, rate): - return sum((tokens.get(kind) or 0) / 1e6 * float(rate.get(kind) or 0) - for kind in RATE_KINDS) - - -def metered_block(where, windows, w, extras=None, note="", scope="", - caveat=""): - """The metered section: one row per window, each with its models under it. - - `windows` is [(label, cost, tokens, [(model, cost)])]. Two of them - - today and thirty days - because a month's total says what an agent costs - and today says whether that is still true. A single all-time figure - answered neither question. - """ - # Windows are kept even when empty, as long as something is. A zero - # today against a busy month is the answer to "have I used this today", - # and dropping the row leaves the reader to wonder which it was. - if not any(x[1] or x[2] for x in windows): - return [] - # Scope first, because it is the thing most easily got wrong: this - # section sits under a QUOTA labelled "account-wide", and a local figure - # beside it reads as the same scope unless it says otherwise. Codex's - # own dashboard reports every surface - Desktop, Cloud, Web, the rest - - # and none of those leave anything on this disk. - rows = [seg([(LBL, " ── METERED ── "), - (TXT, scope + " · " if scope else ""), - (DIM, "at " + where), - (DIM, " %s" % note if note else "")], w - 1)] - for line in (wrap_text(caveat, max(20, w - 4)) if caveat else []): - rows.append(seg([(DIM, " " + line)], w - 1)) - extras = [x for x in (extras or []) if x[1] is not None] - label_w = max([len(x[0]) for x in windows] + [len(x[0]) for x in extras]) - for label, cost, tokens, models in windows: - rows.append(seg([(TXT, " " + pad(label, label_w) + " "), - (AGENT, pad("$%.2f" % cost, 11)), - (DIM, big_num(tokens) + " tokens")], w - 1)) - top = models[:5] - name_w = max([len(m) for m, _ in top] or [0]) - for model, model_cost in top: - rows.append(seg([(DIM, " " + " " * label_w + " "), - (DIM, pad(model, name_w) + " "), - (TXT, "$%.2f" % model_cost)], w - 1)) - if len(models) > len(top): - rows.append(seg([(DIM, " " + " " * label_w + " "), - (DIM, "+%d more" % (len(models) - len(top)))], - w - 1)) - # Summary rows below the windows rather than in the header, which had - # grown long enough to clip the moment a scope word joined it. - for label, value, colour in extras: - rows.append(seg([(DIM, " " + pad(label, label_w) + " "), - (colour, "$%.2f" % value)], w - 1)) - rows.append("") - return rows - - -def metered_rows(windows, w, note="", agent=None, scope="", caveat=""): - """Cost a set of windows against the rate card. - - Each window is (label, [(model, tokens)]). Only models with a rate are - counted and the unpriced ones are named, so a half-filled card cannot - read as a total. - """ - origins, missing, built = set(), set(), [] - for label, entries in windows: - cost = tokens = 0.0 - models = [] - for model, counts in entries: - if not any(counts.values()): - continue - rate, origin = rate_for(model) - tokens += sum(counts.get(k) or 0 for k in RATE_KINDS) - if not rate: - missing.add(model) - continue - this = cost_of(counts, rate) - cost += this - origins.add(origin) - models.append((model, this)) - built.append((label, cost, tokens, sorted(models, key=lambda x: -x[1]))) - if not any(x[1] for x in built): - if not RATES: - return [seg([(LBL, " ── METERED ── "), - (DIM, "no published rates for these models")], - w - 1)] + no_local( - "Set usage.rates in config.json - US$ per million tokens," - " keyed by model.", "", w) + [""] - return [] - # Where the prices came from belongs on screen: a list price is a dated - # fact that goes stale in silence, and a configured one is the reader's - # own assertion. Neither should be mistaken for the other. - where = ("your configured rates" if origins == {"config"} - else "list prices · %s" % LIST_RATES_AS_OF if origins == {"list"} - else "list prices · %s, some configured" % LIST_RATES_AS_OF) - # A month's list cost against what the month actually cost you. Shown - # only when the plan price is configured, because it is the one figure - # in this section that no machine here knows. - saves = None - paid = PLAN_COST.get(agent) if agent else None - month = next((x[1] for x in built if x[0] == "30 days"), None) - if paid and month: - saves = month - float(paid) - rows = metered_block(where, built, w, note=note, scope=scope, - caveat=caveat, - extras=[("the plan saves", saves, OK)]) - if missing and rows: - rows.insert(len(rows) - 1, - seg([(WARN, " %d model%s unpriced: " - % (len(missing), "" if len(missing) == 1 else "s")), - (DIM, ", ".join(sorted(missing)[:3]))], w - 1)) - return rows - - -def plan_rows(headline, pairs, w, note="", wrapped=None, caveat=""): - """A subscription block: what the plan is, then the facts about it. - - Shared by four tabs so the same question is answered in the same shape - wherever you are on the wall - a percentage means little without the - subscription it is a percentage of. - """ - rows = [seg([(LBL, " ── SUBSCRIPTION ── "), (TXT, headline or "unknown"), - (DIM, " " + note if note else "")], w - 1)] - for line in (wrap_text(caveat, max(20, w - 4)) if caveat else []): - rows.append(seg([(DIM, " " + line)], w - 1)) - labels = [k for k, _ in pairs] + ([wrapped[0]] if wrapped else []) - label_w = max([len(x) for x in labels] or [0]) - for key, value in pairs: - for lab, part in wrap_pair(key, value, label_w, w): - rows.append(seg([(DIM, " " + pad(lab, label_w) + " "), - (TXT, part)], w - 1)) - if wrapped and wrapped[1]: - # Wrapped rather than clipped: a truncated list reads as a shorter - # one, and only the first line takes the label. - budget = max(10, w - label_w - 6) - lines, line = [], [] - for name in wrapped[1]: - if line and len(" · ".join(line + [name])) > budget: - lines.append(line) - line = [] - line.append(name) - if line: - lines.append(line) - for i, part in enumerate(lines): - rows.append(seg([(DIM, " " + pad(wrapped[0] if not i else "", - label_w) + " "), - (OK, " · ".join(part))], w - 1)) - return rows - - -def add_section(rows, block): - """Append a section with exactly one blank line before it. - - The separator is owned here rather than by callers who each end - differently - some finish on a blank line and would otherwise leave two, - and plain concatenation leaves none at all, which is what METERED did - when it was bolted on after the tab body. - """ - if not block: - return rows - while rows and rows[-1] == "": - rows.pop() - return rows + [""] + block - - -def copilot_plan_rows(live, w): - """Which subscription this quota belongs to, and since when. - - An enterprise seat is why two of the three pools come back unlimited, - and assigned_date is the only field saying how long it has been so. - """ - pairs = [] - since = iso_epoch(live.get("assigned_date") or "") - day = iso_day(live.get("assigned_date") or "") - if since and day: - pairs.append(("seat since", "%s · %s ago" % (day, ago(since)))) - orgs = [o.get("name") or o.get("login") - for o in (live.get("organization_list") or []) if o] - if orgs: - pairs.append(("organisation", ", ".join(orgs))) - if live.get("login"): - pairs.append(("account", live["login"])) - if live.get("access_type_sku"): - pairs.append(("sku", live["access_type_sku"])) - if live.get("token_based_billing"): - pairs.append(("billing", "token-based")) - on = [name for flag, name in COPILOT_FEATURES if live.get(flag)] - return plan_rows(live.get("copilot_plan"), pairs, w, - note="upgradeable" if live.get("can_upgrade_plan") else "", - wrapped=("enabled", on)) - - -def copilot_metered(state, w): - daily = state.get("daily_models") or {} - return metered_rows([("today", window_models(daily, 1)), - ("30 days", window_models(daily, 30))], w, - agent="copilot", scope="this machine", - caveat="Counted from the local session store. Copilot" - " in an editor, on another machine or on" - " github.com is not in here.") - - -def copilot_tab(state, w, h): - live = state.get("live") or {} - rows = [] - snaps = live.get("quota_snapshots") or {} - if snaps: - # A monthly quota reset arrives as a bare date; days remaining is the - # form every other tab here uses, and the one anyone reads. - # quota_reset_date_utc, not quota_reset_date: the bare date carries - # no zone, so it parses as local midnight and the countdown drifts by - # the machine's UTC offset. Zero on this server, which is exactly why - # it would have gone unnoticed here. - stamp = iso_epoch(live.get("quota_reset_date_utc") or "") - when = "" - if stamp: - days = int((stamp - time.time()) // 86400) - when = "resets in %dd" % days if days > 0 else "resets today" - rows.append(seg([(LBL, " ── QUOTA ── "), (OK, "live"), - (DIM, " · account-wide")], w - 1)) - # The reset sits with the window rather than on the header: they are - # two halves of the same cycle, and the header had no room for it. - span = quota_window(stamp) - if span or when: - rows.append(seg([(DIM, " window "), (TXT, span or "—"), - (DIM, " · monthly · " if span else " "), - (DIM, when)], w - 1)) - label_w = max(9, max(len(k) for k in snaps)) - for key in sorted(snaps, key=lambda k: (snaps[k].get("unlimited"), k)): - q = snaps[key] or {} - name = pad(key.replace("_", " "), label_w) - if q.get("unlimited"): - # No denominator, so no bar. An unlimited pool drawn as an - # empty gauge invents a limit that was explicitly denied. - rows.append(seg([(DIM, " " + name + " "), - (OK, "unlimited")], w - 1)) - continue - ent = q.get("entitlement") or 0 - used_n = q.get("credits_used") - # percent_remaining is what the API gives; every other tab here - # shows what is spent, and red belongs at the empty end. - pct = 100.0 - float(q.get("percent_remaining") or 0) - used = max(0.0, min(1.0, pct / 100.0)) - # The window is a calendar month, so its length is the gap - # between this reset and the one before it. - span = None - if stamp: - prev = datetime.datetime.fromtimestamp( - stamp, datetime.timezone.utc) - back = (prev.replace(year=prev.year - 1, month=12) - if prev.month == 1 else prev.replace(month=prev.month - 1)) - span = stamp - back.timestamp() - rows.append(seg([(DIM, " " + name + " ")] - + paced_bar(used, elapsed_of(span, stamp), - max(8, w - 38 - label_w), - AGENT_HUE["copilot"]) - + [(pct_colour(pct, ahead_of(lead(pct, span, stamp)), - AGENT_HUE["copilot"]), - pct_text(pct)), - pace_cell(lead(pct, span, stamp))], w - 1)) - # A pool can carry its own reset, in which case it is not on the - # account-wide cycle in the header and has to say so itself. - own = q.get("quota_reset_at") or 0 - own_when = "" - if own and abs(own - (stamp or 0)) > 3600: - left_s = own - time.time() - own_when = (" resets in " + left_span(left_s) - if left_s > 0 else " resetting") - if ent: - left_part = [(DIM, " · "), - (TXT, "{:,}".format(int(q.get("remaining") or 0))), - (DIM, " left")] - if label_w + 34 > w - 1: # no room for the remainder - left_part = [] - rows.append(seg([(DIM, " " + " " * label_w + " "), - (TXT, "{:,}".format(int(used_n or 0))), - (DIM, " of "), (TXT, "{:,}".format(int(ent)))] - + left_part + [ - (WARN, " %d over" % q["overage_count"] - if q.get("overage_count") else ""), - (DIM, own_when)], w - 1)) - rows.append("") - elif state.get("live_why"): - rows.append(seg([(WARN, " no quota: " + state["live_why"])], w - 1)) - rows.append("") - - use = state.get("usage") - if use: - rows.append(seg([(LBL, " ── SPENT ── "), - (DIM, "%d turns across %d sessions" - % (state["events"], state["sessions"]))], w - 1)) - cells = [("input tokens", big_num(use["input"]), TXT), - ("output tokens", big_num(use["output"]), AGENT), - ("cache read", big_num(use["cache"]), DIM), - ("reasoning tokens", big_num(use["reasoning"]), TXT), - # total_nano_aiu is billionths of an AI unit - ("AI units", "%.3f" % (use["nano_aiu"] / 1e9), TXT), - ("time generating", span_ms(use["ms"]), DIM)] - label_w = max(len(c[0]) for c in cells) - ncols = 2 if (w - 2) // 2 - label_w - 3 >= 8 else 1 - cw = (w - 2) // ncols - val_w = max(5, cw - label_w - 3) - for i in range(0, len(cells), ncols): - line = [(RST, " ")] - for lab, value, colour in cells[i:i + ncols]: - line += [(DIM, " " + pad(lab, label_w) + " "), - (colour, pad(value, val_w))] - rows.append(seg(line, w - 1)) - rows.append("") - # The one agent that measures this rather than leaving it to be - # inferred from timestamps, which is why it is stated flatly. - rows.append(seg([(LBL, " ── LATENCY ── "), - (DIM, "measured by Copilot, not inferred")], w - 1)) - rows.append(seg([(DIM, " first token "), - (TXT, "%.0f ms" % use["ttft"]), - (DIM, " between tokens "), - (TXT, "%.1f ms" % use["itl"])], w - 1)) - rows.append("") - models = state.get("models") or [] - if models: - rows.append(seg([(LBL, " ── BY MODEL ── "), - (DIM, "output tokens")], w - 1)) - for model, n, out_tok, _in, _cr, _cw in models: - rows.append(seg([(TXT, " " + pad(str(model or "?"), 28)), - (DIM, "%5d turns " % n), - (AGENT, big_num(out_tok))], w - 1)) - else: - rows.append(seg([(LBL, " ── SPENT ── "), - (DIM, "no local sessions")], w - 1)) - rows.append("") - rows += no_local("Nothing recorded in the local session store yet.", - RUN_HINT["copilot"], w) - return rows - - -class Store(object): - def __init__(self): - self.lock = threading.Lock() - self.claude = {} - self.cursor = {} - self.codex = {} - self.grok = {} - self.copilot = {} - self.antigravity = {} - self.installed = {} - self.error = None - self.fetched = 0 - self.wake = threading.Event() - - def snapshot(self): - with self.lock: - return (dict(self.claude), dict(self.cursor), dict(self.codex), - dict(self.grok), dict(self.copilot), - dict(self.antigravity), dict(self.installed), - self.fetched, self.error) - - def run(self): - # A daemon thread that raises just stops, and a dead poller looks - # exactly like a source with no data - which is how deployments.py - # showed "0 deploys" for a day after an import went missing. - try: - self.poll() - except Exception as e: - with self.lock: - self.error = "poller stopped: %s: %s" % (type(e).__name__, - str(e)[:70]) - - def poll(self): - while True: - claude, cursor, codex = read_claude(), read_cursor(), read_codex() - grok, copilot = read_grok(), read_copilot() - antigravity = read_antigravity() - found = detect_agents() - with self.lock: - self.claude, self.cursor, self.codex = claude, cursor, codex - self.grok, self.copilot = grok, copilot - self.antigravity = antigravity - self.installed = found - self.fetched = time.time() - self.wake.wait(REFRESH) - self.wake.clear() - - -# What we know how to read, and how to tell it is here. An agent counts as -# present if its CLI is on PATH *or* it has left state behind: an uninstalled -# agent whose history is still on disk is worth showing, and a CLI installed -# under a different name would otherwise vanish. -AGENTS = { - "claude": {"label": "Claude Code", "bins": ("claude",), - "paths": (CLAUDE_STATS,)}, - "codex": {"label": "OpenAI Codex", "bins": ("codex",), - "paths": (os.path.expanduser("~/.codex/sessions"),)}, - "cursor": {"label": "Cursor", "bins": ("cursor-agent", "cursor"), - "paths": (CURSOR_DB,)}, - "grok": {"label": "Grok", "bins": ("grok",), - "paths": (os.path.expanduser("~/.grok"),)}, - "copilot": {"label": "GitHub Copilot", "bins": ("copilot",), - "paths": (COPILOT_DB, COPILOT_CONFIG)}, - # No binary on PATH to look for: the CLI is launched by the IDE and its - # server is fetched per run, so the state directory is the only proof it - # is here - which is exactly why detection takes paths as well as bins. - "antigravity": {"label": "Antigravity", "bins": ("antigravity",), - "paths": (ANTIGRAVITY_DIR,)}, -} -ORDER = ("claude", "codex", "cursor", "grok", "copilot", "antigravity") - - -def detect_agents(): - """Which agents this machine has, by binary or by leftover state.""" - found = {} - for name, spec in AGENTS.items(): - binary = next((b for b in spec["bins"] if shutil.which(b)), None) - data = next((p for p in spec["paths"] if os.path.exists(p)), None) - found[name] = {"bin": binary, "data": data, - "present": bool(binary or data)} - return found - - -SUMMARY_TAB = "+" -SPINNER = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏" - - -def loading_rows(w, tick): - """What to show before the first poll lands. - - Every tab's empty state is a statement of fact - no stats cache, no - rollouts, no agent publishing a quota - and each of them is false while - the first read is still running. The first read is also the slow one: - 520MB of Claude transcripts and five pages of Cursor events, some fifteen - seconds of it, which is more than long enough for a wrong answer to be - read and believed. - """ - rows = [seg([(ACCENT, " " + SPINNER[tick % len(SPINNER)]), - (TXT, " reading local state and quotas")], w - 1), ""] - for line in ("The first pass is the slow one: Claude's transcripts run to" - " hundreds of megabytes and Cursor's usage events are paged" - " a thousand at a time. Both are cached afterwards.",): - for part in wrap_text(line, max(20, w - 4)): - rows.append(seg([(DIM, " " + part)], w - 1)) - return rows - - -def elapsed_of(secs, reset): - """How much of a window has gone, from its length and its reset.""" - if not secs or not reset: - return None - left = reset - time.time() - if left <= 0 or left > secs: - return None - return (secs - left) / secs - - -# The dark end of every agent ramp. The two stops above it are measured, not -# picked: 0.51 keeps the dimmest filled cell at 3:1 against the background for -# the darkest agent hue, and 0.34 leaves the empty track at least as visible -# as the flat GRID it replaces (2.20:1 against 2.16:1). -BAR_FLOOR = (30, 38, 52) -# The notch is white on its own dark cell rather than a bare foreground -# colour. Plain white manages 1.2:1 against a full bar - the agent hues are -# light themselves, so it disappears exactly where it matters - while giving -# the cell a dark background makes the mark read the same on a full bar, an -# empty track, or the boundary between them. -PACE_MARK = bg(10, 12, 18) + rgb(238, 244, 252) -NOBG = "\x1b[49m" # default background again, and only that - - -def blend(hue, t): - """A tint of an agent's colour as a tuple, t running dark to full.""" - return tuple(int(round(BAR_FLOOR[i] + (hue[i] - BAR_FLOOR[i]) * t)) - for i in range(3)) - - -def tint(hue, t): - """A tint of an agent's colour, t running dark to full. - - Not `shade` - that name is taken by the calendars' four-step ramp, and - two functions of the same name meant the heatmaps drew with this one. - """ - return rgb(*blend(hue, t)) - - -def paced_bar(used, elapsed, room, hue=None): - """A quota bar with a mark where an even burn would have reached by now. - - The percentage alone cannot separate a lane that is 71% spent with three - weeks left from one that is 71% spent with three days left, and colour - alone cannot either - both are the same red. The mark is the window's - own progress, so a fill short of it is spending slower than the clock - and a fill past it is not. - - Returned as coloured segments rather than a string because the mark has - to be tinted against whichever side of it the fill lands on, and it is a - different glyph from the bar so it survives without colour at all. - """ - bar = meter(used, room) - filled = bar.count("█") - at = None - if elapsed is not None: - at = max(0, min(room - 1, int(round(elapsed * room)))) - parts = [] - for i, ch in enumerate(bar): - if i == at: - # One colour for the mark on every bar. It is a reference line - - # where an even burn would have reached - and a line that changes - # colour looks like it has a state of its own, when the state - # being reported is the fill's position relative to it. Copilot - # in amber beside five in green read as Copilot's mark meaning - # something different, rather than Copilot being behind. - # - # Near-black rather than a light neutral: the agent hues are - # themselves light, so white vanishes inside a full bar (1.04:1) - # while this holds 8.1:1 there and 2.5:1 on the empty track. - parts.append((PACE_MARK, "┃")) - elif i < filled: - # Filled cells run dark to full across the fill, so the bar is - # recognisably its agent's colour and still reads as a quantity - # without counting cells. - t = 0.51 + 0.49 * (i / float(max(1, filled - 1))) - parts.append((NOBG + (tint(hue, t) if hue else heat(used)), ch)) - else: - parts.append((NOBG + (tint(hue, 0.34) if hue else GRID), ch)) - # Runs of one colour are merged so a row is a handful of escapes rather - # than one per cell. - merged = [] - for colour, ch in parts: - if merged and merged[-1][0] == colour: - merged[-1] = (colour, merged[-1][1] + ch) - else: - merged.append((colour, ch)) - # The mark is the one thing here that sets a background, so the run ends - # by putting it back. Without this the dark cell bled through everything - # drawn after it on the row - the rest of the bar, the percentage, the - # reset - which is exactly what a stray background looks like: broken. - return merged + [(NOBG, "")] - - -def summary_tab(states, w, h): - """Every agent's quotas on one screen, worst first. - - Not a concatenation of the other tabs: those answer "how am I using this - agent", and this answers the only question that spans them - what runs - out first. So the lanes are ranked by what is spent rather than grouped - by agent, and an agent that publishes no quota is named at the bottom - instead of being silently missing. - """ - lanes, quiet = [], [] - for name in ORDER: - got = quota_lanes(name, states.get(name) or {}) - if got: - lanes.extend((name,) + tuple(lane) + (False,) * (5 - len(lane)) - for lane in got) - else: - quiet.append(name) - if not lanes: - return no_local("No agent is publishing a quota right now.", "", w) - # Grouped by provider, but the groups are ordered by their worst lane and - # so are the lanes inside them: the structure says who owns what, the - # ordering still answers which one runs out first. - groups = {} - for lane in lanes: - groups.setdefault(lane[0], []).append(lane) - order = sorted(groups, key=lambda n: -max(x[2] for x in groups[n])) - label_w = min(16, max(len(x[1]) for x in lanes)) - head = "%d limits across %d agents" % (len(lanes), - len(ORDER) - len(quiet)) - # Sized against the suffix actually being added, so changing the wording - # cannot quietly start clipping the line. - suffix = " · ranked by usage" - if 14 + len(head) + len(suffix) <= w - 1: - head += suffix - rows = [seg([(LBL, " ── QUOTAS ── "), (DIM, head)], w - 1)] - # 2 lead + label + 1 + pct(6) + pace(6). The reset needs 16 more and is - # the first thing dropped, being the only part a reader can infer from - # the bar beside it - but a stale marker is not droppable, since a number - # nobody labelled as old reads as current. - fixed = 15 + label_w - show_reset = (w - 1) - fixed - 8 >= 16 - tail = 16 if show_reset else (8 if any(x[5] for x in lanes) else 0) - bar_room = max(8, (w - 1) - fixed - tail) - for i, name in enumerate(order): - if i: - rows.append("") - rows.append(seg([(rgb(*AGENT_HUE.get(name, (225, 235, 245))), - " " + name.upper())], w - 1)) - # Ranked by usage, except where the lanes nest. Claude's five-hour - # window sits inside its weekly one, which contains the model-scoped - # limit in turn, and reading them widest-last says more than reading - # them by percentage - which also reorders itself as the numbers - # move, so the bar under the cursor is not the one that was there a - # refresh ago. - inner = (groups[name] if name == "claude" - else sorted(groups[name], key=lambda x: -x[2])) - for _, label, pct, secs, reset, stale in inner: - used = max(0.0, min(1.0, pct / 100.0)) - gone = None - if secs and reset: - left = reset - time.time() - if 0 < left <= secs: - gone = (secs - left) / secs - when, tint = "", DIM - if stale: - when, tint = " cached", WARN - elif show_reset and reset: - left = reset - time.time() - when = (" " + left_span(left)) if left > 0 else " resetting" - rows.append(seg([(DIM, " " + pad(label, label_w) + " ")] - + paced_bar(used, gone, bar_room, - AGENT_HUE.get(name)) - + [(pct_colour(pct, ahead_of(lead(pct, secs, reset)), - AGENT_HUE.get(name)), - pct_text(pct)), - pace_cell(lead(pct, secs, reset)), - (tint, when)], w - 1)) - if quiet: - rows.append("") - rows += no_local("No quota published by: " + ", ".join(quiet) - + ".", "", w) - return rows - - -def quota_lanes(name, state): - """Every quota an agent publishes, flattened to (label, pct, window, reset). - - Read here rather than borrowed from each tab's renderer, because those - render six different shapes - Cursor's coloured lanes, Antigravity's - groups, Codex's per-feature windows - and only the four numbers below are - common to all of them. The field names are the same ones the tabs use, so - a change to an API shows up in both places at once. - """ - lanes = [] - if name == "claude": - # A cached reading can describe windows that have since closed, so - # its lanes are marked rather than counted down to - the agent's own - # tab says "cached 18h ago" and this must not quietly disagree. - stale = (state.get("quota") or {}).get("source") != "live" - q = (state.get("quota") or {}).get("u") or {} - for l in sorted(q.get("limits") or [], key=claude_lane_rank): - if l.get("percent") is None: - continue - scope = ((l.get("scope") or {}).get("model") or {}).get( - "display_name") - group = l.get("group") or "" - label = scope or ("session" if l.get("kind") == "session" - else "overall") - lanes.append(("%s %s" % (label, CLAUDE_WINDOW.get(group, "")), - float(l["percent"]), - None if stale else CLAUDE_WINDOW_SECS.get(group), - None if stale else iso_epoch(l.get("resets_at")), - stale)) - elif name == "codex": - live = state.get("live") or {} - for key in ("primary_window", "secondary_window"): - win = (live.get("rate_limit") or {}).get(key) - if win and win.get("used_percent") is not None: - secs = win.get("limit_window_seconds") - lanes.append((window_name(secs), float(win["used_percent"]), - secs, win.get("reset_at"))) - for extra in live.get("additional_rate_limits") or []: - win = (extra.get("rate_limit") or {}).get("primary_window") or {} - if win.get("used_percent") is None: - continue - short = (extra.get("limit_name") or "?").rsplit("-", 1)[-1] - secs = win.get("limit_window_seconds") - lanes.append(("%s %s" % (short, window_name(secs)), - float(win["used_percent"]), secs, - win.get("reset_at"))) - elif name == "cursor": - live = state.get("live") or {} - plan = live.get("planUsage") or {} - start, end = live.get("billingCycleStart"), live.get("billingCycleEnd") - secs = reset = None - if start and end and int(end) > int(start): - secs = (int(end) - int(start)) / 1000.0 - reset = int(end) / 1000.0 - for label, key in (("included", "totalPercentUsed"), - ("auto", "autoPercentUsed"), - ("api", "apiPercentUsed")): - if plan.get(key) is not None: - lanes.append((label, float(plan[key]), secs, reset)) - elif name == "grok": - q = state.get("quota") or {} - if q.get("percent") is not None: - begin, end = iso_epoch(q.get("start") or ""), iso_epoch(q.get("end") or "") - secs = (end - begin) if (begin and end and end > begin) else None - lanes.append(("credits", float(q["percent"]), secs, end)) - elif name == "copilot": - live = state.get("live") or {} - stamp = iso_epoch((live.get("quota_reset_date_utc") or "")) - span = None - if stamp: - end = datetime.datetime.fromtimestamp(stamp, datetime.timezone.utc) - back = (end.replace(year=end.year - 1, month=12) if end.month == 1 - else end.replace(month=end.month - 1)) - span = stamp - back.timestamp() - for key, snap in (live.get("quota_snapshots") or {}).items(): - if (snap or {}).get("unlimited") or snap.get("percent_remaining") is None: - continue - lanes.append((key.replace("_", " ").replace("interactions", "reqs"), - 100.0 - float(snap["percent_remaining"]), span, stamp)) - elif name == "antigravity": - for group in state.get("quota") or []: - short = str(group.get("displayName") or "?").split()[0].lower() - for b in group.get("buckets") or []: - if b.get("remainingFraction") is None: - continue - window = str(b.get("window") or "?") - lanes.append(("%s %s" % (short, window), - 100.0 * (1.0 - float(b["remainingFraction"])), - ANTIGRAVITY_WINDOWS.get(window), - iso_epoch(b.get("resetTime") or ""))) - return lanes - - -def window_name(secs): - secs = int(secs or 0) - if secs >= 86400: - return "%dd" % (secs // 86400) - return "%dh" % (secs // 3600) if secs else "?" - - -def visible_agents(found): - """The tabs to draw. - - Empty `agents` discovers: every agent this machine actually has. Naming - them instead fixes both the set and the order, whether or not they are - installed - if you listed it, you want the tab. `exclude_agents` drops one - either way. - - Falls back to everything known if the result would be empty, because a - widget with no tabs teaches nothing and the likeliest cause is a typo in - the config rather than a machine with no agents on it. - """ - drop = set(_CFG["exclude_agents"] or []) - named = [n for n in (_CFG["agents"] or []) if n in AGENTS] - chosen = named or [n for n in ORDER if found.get(n, {}).get("present")] - shown = tuple(n for n in chosen if n not in drop) - # The summary leads and is never discovered or excluded: it is not an - # agent, it is the view across whichever agents there turn out to be. - return (SUMMARY_TAB,) + (shown or ORDER) - - -def config_complaints(found): - """Names in the config that match no agent we know how to read.""" - known = set(AGENTS) - bad = [n for n in (list(_CFG["agents"] or []) - + list(_CFG["exclude_agents"] or [])) if n not in known] - return ("unknown agent in config: %s (known: %s)" - % (", ".join(sorted(set(bad))), ", ".join(ORDER))) if bad else None - - -def tab_bar(active, installed, tabs, w): - # brackets as well as the tint: which tab is open must not depend on a - # background colour surviving. A dot marks an agent that is installed. - parts = [(RST, " ")] - for name in tabs: - here = name == active - have = (installed.get(name) or {}).get("present", False) - parts.append((bg(38, 56, 76) + ACCENT if here else DIM, - ("[%s]" if here else " %s ") % name.upper())) - if name == SUMMARY_TAB: - parts.append((GRID, " ")) - continue - parts.append((OK if have else GRID, "·" if have else " ")) - return seg(parts, w - 1) - - -WEEKDAYS = ("Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun") - - -MONTHS = ("Jan", "Feb", "Mar", "Apr", "May", "Jun", - "Jul", "Aug", "Sep", "Oct", "Nov", "Dec") - - -def token_heatmap(daily, w): - """Claude's shape: a list of {date, tokensByModel} records.""" - return day_calendar( - dict((e["date"], sum((e.get("tokensByModel") or {}).values())) - for e in daily if e.get("date")), w) - - -def day_calendar(totals_by_date, w, steps=HEAT_STEPS, weeks=None): - """Tokens per day, drawn the way Claude Code's own /stats draws it. - - Weekday rows with only Mon, Wed and Fri labelled; one cell per day; months - named across the top; solid blocks in four steps of a single hue, and a dim - dot for a day the file has no entry for. - - The grid spans the whole window even where there is no data, because the - emptiness is information: this cache retains about four weeks, and a year - of dots with a fortnight of colour at the right-hand end says that plainly. - """ - totals = {} - for key, value in (totals_by_date or {}).items(): - try: - totals[datetime.date.fromisoformat(key)] = value - except (ValueError, TypeError): - continue - if not totals: - return [], 0, None, {} - peak = max(totals.values()) or 1 - best = max(totals, key=totals.get) - - last = max(totals) - # A caller with a bounded window says so, rather than having its month - # of data stretched across a year of empty dots. Left unset the grid - # fills the pane, which is right for a cache whose emptiness is itself - # information. - weeks_fit = max(4, min(w - 7, weeks or w - 7)) - end_week = last - datetime.timedelta(days=last.weekday()) - starts = [end_week - datetime.timedelta(days=7 * i) - for i in range(weeks_fit - 1, -1, -1)] - - # month names sit over the week their month starts in, three characters - # wide like /stats - a single initial is not a label, it is a hint - # a month label needs three clear cells; without checking where the last - # one ended, a short month writes over its neighbour and produces "JJul" - strip = [" "] * len(starts) - seen, wrote_to = None, -1 - for x, wk in enumerate(starts): - if wk.month != seen and x > wrote_to and x + 3 <= len(strip): - seen = wk.month - for k, ch in enumerate(MONTHS[wk.month - 1]): - strip[x + k] = ch - wrote_to = x + 3 - rows = [[(DIM, " " + "".join(strip))]] - for i in range(7): - label = {0: "Mon", 2: "Wed", 4: "Fri"}.get(i, "") - line = [(DIM, " %-4s" % label)] - for wk in starts: - day = wk + datetime.timedelta(days=i) - n = totals.get(day) - if n is None: - line.append((EMPTY_CELL, "·")) - else: - line.append((shade((n / float(peak)) ** 0.5, steps), "█")) - rows.append(line) - - # active out of days in the range, not out of days the file happens to - # list - otherwise every day is active by construction and the ratio says - # nothing - span = (max(totals) - min(totals)).days + 1 - active = sum(1 for v in totals.values() if v) - run = best_run = 0 - for i in range(span): - day = min(totals) + datetime.timedelta(days=i) - run = run + 1 if totals.get(day) else 0 - best_run = max(best_run, run) - current = 0 - for i in range(span): - day = max(totals) - datetime.timedelta(days=i) - if not totals.get(day): - break - current += 1 - facts = {"active": active, "span": span, - "longest": best_run, "current": current} - return rows, peak, best, facts - - -def stats_lag(data, room): - """How far behind today the stats cache's own reckoning is. - - `room` is the columns actually left on the line, measured by the caller - rather than guessed from the pane width - the text before this varies, - so a width threshold clipped at some widths and not others. The longest - phrasing that fits wins; the day count is the half that must survive. - """ - last = (data or {}).get("lastComputedDate") or "" - try: - when = datetime.date.fromisoformat(last) - except (ValueError, TypeError): - return "" - days = (datetime.date.today() - when).days - if days <= 0: - return "" - for text in (" cache is %dd behind, to %s" - % (days, when.strftime("%b %-d")), - " cache %dd behind" % days, - " -%dd" % days): - if len(text) <= room: - return text - return "" - - -def claude_metered(state, w): - daily = state.get("daily_models") or {} - return metered_rows([("today", window_models(daily, 1)), - ("30 days", window_models(daily, 30))], w, - agent="claude", scope="this machine", - caveat="Counted from transcripts, which are written" - " where the agent ran. Claude used on another" - " machine, or on claude.ai, is not in here.") - - -def claude_tab(state, w, h): - rows = claude_quota(state.get("quota"), w) - if not state.get("ok"): - return rows + no_local("No stats cache yet (%s)." - % state.get("why"), - RUN_HINT["claude"], w) - d = state["data"] - mu = d.get("modelUsage") or {} - daily = d.get("dailyActivity") or [] - - out_tok = sum(v.get("outputTokens") or 0 for v in mu.values()) - in_tok = sum(v.get("inputTokens") or 0 for v in mu.values()) - cache_r = sum(v.get("cacheReadInputTokens") or 0 for v in mu.values()) - cache_w = sum(v.get("cacheCreationInputTokens") or 0 for v in mu.values()) - - # the heatmap is computed first: its streaks and active-day counts belong - # in the summary above it, not only beside the calendar - grid, peak, best, facts = token_heatmap(d.get("dailyModelTokens") or [], w) - - ls = d.get("longestSession") or {} - fav = max(mu, key=lambda k: mu[k].get("outputTokens") or 0) if mu else "—" - all_tokens = in_tok + out_tok + cache_r + cache_w - rows.append(seg([(LBL, " ── SUMMARY ── "), - (DIM, "all time · since %s" - % (d.get("firstSessionDate") or "")[:10])], w - 1)) - pairs = [ - ("Favorite model", fav.replace("claude-", ""), AGENT, - "Total tokens", big_num(all_tokens), AGENT), - ("Sessions", "%d" % (d.get("totalSessions") or 0), TXT, - "Longest session", span_ms(ls.get("duration")), TXT), - ("Active days", "%d/%d" % (facts.get("active", 0), facts.get("span", 0)) - if facts else "—", TXT, - "Longest streak", "%d days" % facts.get("longest", 0) if facts else "—", - TXT), - ("Most active day", best.strftime("%b %-d") if best else "—", TXT, - "Current streak", "%d days" % facts.get("current", 0) if facts else "—", - OK if facts.get("current") else DIM), - ] - lw = max(max(len(a), len(c)) for a, _b, _bc, c, _d2, _dc in pairs) - half = (w - 3) // 2 - vw = max(6, half - lw - 2) - for a, b, bc, c, e, ec in pairs: - rows.append(seg([(DIM, " " + pad(a, lw) + " "), (bc, pad(b, vw)), - (DIM, " " + pad(c, lw) + " "), (ec, pad(e, vw))], - w - 1)) - rows.append(seg([(DIM, " Input "), (TXT, big_num(in_tok)), - (DIM, " · Output "), (TXT, big_num(out_tok)), - (DIM, " · Cache read "), (TXT, big_num(cache_r)), - (DIM, " · Cache written "), (TXT, big_num(cache_w))], - w - 1)) - # which model did the work - rows.append("") - ranked = sorted(mu.items(), key=lambda kv: -(kv[1].get("outputTokens") or 0)) - ranked = [(k, v) for k, v in ranked if (v.get("outputTokens") or 0) > 0] - rows.append(seg([(LBL, " ── BY MODEL ── "), - (DIM, "output tokens")], w - 1)) - if ranked: - top = ranked[0][1].get("outputTokens") or 1 - for name, v in ranked[:5]: - tok = v.get("outputTokens") or 0 - share = tok / float(top) - bar = meter(share, max(6, w - 34)) - filled = bar.count("█") - rows.append(seg([(TXT, " " + pad(name.replace("claude-", ""), 20)), - (AGENT, "%7s " % big_num(tok)), - (AGENT, bar[:filled]), (GRID, bar[filled:])], - w - 1)) - - # 26 days of activity, straight from the file - if daily: - rows.append("") - counts = [x.get("messageCount") or 0 for x in daily] - peak = max(counts) or 1 - # Both charts on this tab come from stats-cache.json, which Claude - # Code recomputes on its own schedule - lastComputedDate can sit a - # day or two back. Unlabelled, that gap reads as idle days rather - # than as days the cache has not caught up with. - head, tail = " ── MESSAGES / DAY ── ", "%dd · peak %s" % ( - len(daily), f"{peak:,}") - rows.append(seg([(LBL, head), (DIM, tail), - (WARN, stats_lag(d, w - 1 - len(head) - len(tail)))], - w - 1)) - avail = max(10, w - 3) - cols = [] - for c, wide in zip(counts, spread(len(counts), avail)): - cols.extend([(c, AGENT)] * wide) - for line in vbars(cols, 3): - rows.append(seg([(RST, " ")] + line, w - 1)) - rows.append(seg([(RST, " "), (GRID, "─" * len(cols))], w - 1)) - left = daily[0].get("date", "")[5:] - right = daily[-1].get("date", "")[5:] - rows.append(seg([(DIM, " " + left), - (DIM, " " * max(1, len(cols) - len(left) - len(right))), - (DIM, right)], w - 1)) - - # ── how fast it generates ─────────────────────────────────────────── - rates = state.get("rates") or [] - if rates: - med = rates[len(rates) // 2] - p90 = rates[min(len(rates) - 1, int(len(rates) * 0.9))] - rows.append("") - rows.append(seg([(LBL, " ── OUTPUT RATE ── "), - (DIM, "%d turns across %d transcripts" - % (len(rates), state.get("sampled", 0)))], w - 1)) - rows.append(seg([(DIM, " median "), (AGENT, "%.0f" % med), - (DIM, " tok/s p90 "), (TXT, "%.0f" % p90), - (DIM, " request to response, tools included")], - w - 1)) - - # ── tokens per day, as a calendar ─────────────────────────────────── - if grid: - rows.append("") - head = " ── TOKENS / DAY ── peak " - tail = "%s on %s" % (big_num(peak), - best.strftime("%b %-d") if best else "--") - rows.append(seg([(LBL, " ── TOKENS / DAY ── "), - (DIM, "peak "), (AGENT, big_num(peak)), - (DIM, " on %s" % (best.strftime("%b %-d") if best - else "--")), - (WARN, stats_lag(d, w - 1 - len(head) - - len(tail)))], w - 1)) - for line in grid: - rows.append(seg(line, w - 1)) - rows.append(seg([(DIM, " Less ")] - + [(rgb(*c), "█") for c in HEAT_STEPS] - + [(DIM, " More")], w - 1)) - - - return rows - - -def cursor_quota(live, w): - """The three lanes cursor-agent's Usage view shows, plus the cycle.""" - plan = (live or {}).get("planUsage") or {} - if not plan: - return [] - rows = [] - ends = live.get("billingCycleEnd") - when = "" - if ends: - left = int(ends) / 1000.0 - time.time() - when = ("resets in %dd" % (left // 86400)) if left > 0 else "resetting" - start = live.get("billingCycleStart") - elapsed, cycle_secs, reset_ts = None, None, None - if start and ends and int(ends) > int(start): - cycle_secs = (int(ends) - int(start)) / 1000.0 - reset_ts = int(ends) / 1000.0 - gone = time.time() * 1000 - int(start) - elapsed = max(0.0, min(100.0, 100.0 * gone / (int(ends) - int(start)))) - rows.append(seg([(LBL, " ── QUOTA ── "), (OK, "live"), - (DIM, scope_phrase(w, 17 + len(when))), - (DIM, when)], w - 1)) - if elapsed is not None: - # Just the fact; the +/- column it explains is on every tab now, so - # a per-tab legend was both redundant and the thing that clipped. - rows.append(seg([(DIM, " %.0f%% of the cycle gone" % elapsed)], - w - 1)) - values = {"included": plan.get("totalPercentUsed"), - "auto": plan.get("autoPercentUsed"), - "api": plan.get("apiPercentUsed")} - for name, stop in CURSOR_LANE_STOPS: - pct = values.get(name) - if pct is None: - continue - used = max(0.0, min(1.0, pct / 100.0)) - hue = blend(AGENT_HUE["cursor"], stop) - # How far ahead of the clock you are: the share of the billing period - # already gone, minus the share of the allowance spent. Positive is a - # cushion, negative means this lane runs out before the cycle does. - # It is what CodexBar calls "in reserve", and it is pure arithmetic on - # the cycle dates - nothing new is fetched for it. - rows.append(seg([(DIM, " %-9s" % name)] - + paced_bar(used, elapsed_of(cycle_secs, reset_ts), - max(8, w - 40), hue) - + [(pct_colour(pct, ahead_of(lead(pct, cycle_secs, - reset_ts)), hue), - pct_text(pct)), - pace_cell(lead(pct, cycle_secs, reset_ts))], w - 1)) - limit, spend = plan.get("limit"), plan.get("totalSpend") - if limit: - # Deliberately dollars rather than a fourth bar. This is spend against - # the plan limit - a different denominator from the three lanes above, - # which are the server's own percentages - and drawing it as a bar - # beside them would invite reading 12% and 2% as the same scale. - left = plan.get("remaining") - rows.append(seg([(DIM, " spend "), - (TXT, "$%.2f" % ((spend or 0) / 100.0)), - (DIM, " of "), (TXT, "$%.2f" % (limit / 100.0)), - (DIM, " $%.2f left" % (left / 100.0) - if left is not None else "")], w - 1)) - rows.append("") - return rows - - -def cursor_metered_rows(state, w): - """What Cursor charges, beside what the same traffic costs at list. - - Cursor is the one agent that publishes both, so no rate card is needed: - GetAggregatedUsageEvents returns what it meters against the plan, and - the raw events carry their own vendor-rate cents. The gap is what the - subscription is worth, and every event states its own discount. - """ - ev = state.get("events") or {} - spend = state.get("spend") or {} - metered = float(spend.get("totalCostCents") or 0) - by = ev.get("by_day_model") or {} - if not by and not metered: - return [] - - def window(days): - first = (datetime.date.today() - - datetime.timedelta(days=days - 1)).isoformat() - cents, tokens, models = 0.0, 0, {} - for day, entries in by.items(): - if day < first: - continue - for model, got in entries.items(): - cents += got["cents"] - tokens += got["tokens"] - models[model] = models.get(model, 0.0) + got["cents"] - - return (cents / 100.0, tokens, - sorted([(m, c / 100.0) for m, c in models.items()], - key=lambda x: -x[1])) - - windows = [] - for label, days in (("today", 1), ("30 days", ev.get("days") or 30)): - cost, tokens, models = window(days) - windows.append((label, cost, tokens, models)) - vendor = float(ev.get("vendor_cents") or 0) - saves = (vendor - metered) / 100.0 if vendor and metered else None - return metered_block("vendor rates", windows, w, scope="account-wide", - extras=[("cursor meters", metered / 100.0 if metered - else None, TXT), - ("the plan saves", saves, OK)], - caveat="From Cursor's own API, so it covers every" - " device on the account, not just this one.") - - -def cursor_daily_rows(events, w): - """Spend per day, one column per day, the way the usage page shows it. - - A bar chart rather than the calendar the token tabs use: this window is - thirty days, and thirty cells of a year-wide grid is six columns of - colour in a field of dots. Money over a month reads better as a profile, - and it is the shape Cursor's own dashboard draws. - """ - by_day = (events or {}).get("by_day") or {} - if not by_day: - return [] - days = events.get("days") or 30 - today = datetime.date.today() - series = [(today - datetime.timedelta(days=n)) for n in range(days - 1, -1, -1)] - cents = [by_day.get(d, 0.0) for d in series] - peak = max(cents) or 1.0 - best = series[cents.index(peak)] if peak in cents else None - rows = [seg([(LBL, " ── SPEND / DAY ── "), - (DIM, "%dd · peak " % days), (AGENT, "$%.0f" % (peak / 100.0)), - (DIM, " on %s" % (best.strftime("%b %-d") if best else "--")), - (DIM, " · today "), (TXT, "$%.2f" - % (by_day.get(today, 0.0) / 100.0))], - w - 1)] - avail = max(10, w - 3) - cols = [] - for c, wide in zip(cents, spread(len(cents), avail)): - cols.extend([(c, AGENT)] * wide) - for line in vbars(cols, 3, hi=peak): - rows.append(seg([(RST, " ")] + line, w - 1)) - rows.append(seg([(RST, " "), (GRID, "─" * len(cols))], w - 1)) - left, right = series[0].strftime("%b %-d"), series[-1].strftime("%b %-d") - rows.append(seg([(DIM, " " + left), - (DIM, " " * max(1, len(cols) - len(left) - len(right))), - (DIM, right)], w - 1)) - rows.append("") - return rows - - -def cursor_spend_rows(spend, w): - """Where the money went, per model, over the last 30 days.""" - if not spend or not spend.get("aggregations"): - return [] - rows = [seg([(LBL, " ── SPEND ── "), (DIM, "last 30d · "), - (AGENT, "$%.2f" % (float(spend.get("totalCostCents") or 0) / 100)), - (DIM, " in "), (TXT, big_num(int(spend.get("totalInputTokens") or 0))), - (DIM, " · out "), (TXT, big_num(int(spend.get("totalOutputTokens") or 0))), - (DIM, " · cache "), - (TXT, big_num(int(spend.get("totalCacheReadTokens") or 0)))], - w - 1)] - models = sorted(spend["aggregations"], - key=lambda a: -float(a.get("totalCents") or 0)) - top = float(models[0].get("totalCents") or 1) - for a in models[:6]: - cents = float(a.get("totalCents") or 0) - bar = meter(cents / top if top else 0, max(6, w - 44)) - filled = bar.count("█") - rows.append(seg([(TXT, " " + pad(str(a.get("modelIntent") or "?"), 26)), - (AGENT, "%9s " % ("$%.2f" % (cents / 100))), - (AGENT, bar[:filled]), (GRID, bar[filled:])], w - 1)) - rows.append("") - return rows - - -def cursor_tab(state, w, h): - if not state.get("ok"): - return (cursor_quota(state.get("live"), w) - + cursor_spend_rows(state.get("spend"), w) - or no_local("No Cursor tracking database on this machine.", - RUN_HINT["cursor"], w)) - rows = cursor_quota(state.get("live"), w) - rows += cursor_daily_rows(state.get("events"), w) - rows += cursor_spend_rows(state.get("spend"), w) - rows.append(seg([(LBL, " ── AI-WRITTEN CODE ── "), - (DIM, "last seen %s ago" - % ago((state.get("last") or 0) / 1000.0 - if state.get("last") else None))], w - 1)) - ai, human = state["lines"], state["human_lines"] - total = ai + human - cells = [("tracked edits", f"{state['hashes']:,}", AGENT), - ("conversations", f"{state['conversations']:,}", TXT), - ("scored commits", f"{state['commits']:,}", TXT), - ("lines by agent", f"{ai:,}", AGENT), - ("lines by hand", f"{human:,}", TXT), - ("models used", "%d" % state["models"], DIM)] - label_w = max(len(c[0]) for c in cells) - ncols = 2 if (w - 2) // 2 - label_w - 3 >= 8 else 1 - cw = (w - 2) // ncols - val_w = max(5, cw - label_w - 3) - for i in range(0, len(cells), ncols): - line = [(RST, " ")] - for label, value, colour in cells[i:i + ncols]: - line += [(DIM, " " + pad(label, label_w) + " "), - (colour, pad(value, val_w))] - rows.append(seg(line, w - 1)) - if total: - rows.append("") - rows.append(seg([(LBL, " ── WHO WROTE IT ── "), - (DIM, "%s lines scored" % f"{total:,}")], w - 1)) - rows.append(seg([(RST, " ")] + stacked_bar( - [(ai / float(total), AGENT), (human / float(total), DIM)], - max(10, w - 3)), w - 1)) - rows.append(seg([(AGENT, " ▇ agent %s (%.0f%%)" - % (f"{ai:,}", 100.0 * ai / total)), - (DIM, " ▇ hand %s (%.0f%%)" - % (f"{human:,}", 100.0 * human / total))], w - 1)) - if state["by_model"]: - rows.append("") - rows.append(seg([(LBL, " ── BY MODEL ── "), (DIM, "tracked edits")], - w - 1)) - top = state["by_model"][0][1] or 1 - for name, n in state["by_model"][:5]: - bar = meter(n / float(top), max(6, w - 36)) - filled = bar.count("█") - rows.append(seg([(TXT, " " + pad(str(name or "?"), 22)), - (AGENT, "%7s " % f"{n:,}"), - (AGENT, bar[:filled]), (GRID, bar[filled:])], - w - 1)) - rows.append("") - rows.append(seg([(DIM, " Authorship, not spend: this is how much code the" - " agent wrote,")], w - 1)) - rows.append(seg([(DIM, " which is a different question from what it" - " cost.")], w - 1)) - return rows - - -def elsewhere_tab(name, installed, w, h): - # Every agent in AGENTS now has a reader, so this is a backstop for one - # added without one - it says so rather than raising in the draw loop. - label, lines = ELSEWHERE.get( - name, (name, ["No reader for this agent yet."])) - have = (installed.get(name) or {}).get("present") - rows = [seg([(LBL, " ── %s ── " % label.upper()), - (OK if have else DIM, - "installed" if have else "not installed")], w - 1), ""] - for line in lines: - rows.append(seg([(DIM if line else RST, " " + line)], w - 1)) - rows.append("") - rows.append(seg([(WARN, " Nothing is shown for it because nothing is" - " published.")], w - 1)) - rows.append(seg([(DIM, " A plausible-looking zero would be worse than an" - " empty tab.")], w - 1)) - return rows - - -def main(): - maybe_help(__doc__) - args = sys.argv[1:] - while args and args[0] in ("-n", "--refresh"): - global REFRESH - REFRESH = float(args[1]) - args = args[2:] - store = Store() - threading.Thread(target=store.run, daemon=True).start() - setup() - keyboard = Keyboard() - active = 0 - tick = 0 - # One offset per tab. Switching away and back keeps your place, which - # matters when a tab is forty rows and you were reading the bottom of it. - offsets = {} - - while True: - tick += 1 - # Scrolling is applied after the frame is built, not here: a page is - # however many body rows this pane turned out to have, and that is - # not known until the tab has been rendered and the footer packed. - moves = [] - for key in keyboard.poll(): - if key in ("q", "Q"): - raise SystemExit(0) - if key in ("right", "tab", "l"): - active += 1 - elif key in ("left", "h"): - active -= 1 - elif key in ("up", "k"): - moves.append(-1) - elif key in ("down", "j"): - moves.append(1) - elif key == "pgup": - moves.append("-page") - elif key == "pgdn": - moves.append("+page") - elif key == "home": - moves.append("top") - elif key == "end": - moves.append("bottom") - elif key == "r": - store.wake.set() - - w, h = size() - (claude, cursor, codex, grok, copilot, antigravity, - installed, fetched, err) = store.snapshot() - rows = [title("agent usage", w, AGENT)] - tabs = visible_agents(installed) - active %= len(tabs) # wraps in both directions - extra = [n for n in ORDER - if (installed.get(n) or {}).get("present") and n not in tabs] - def status(where=""): - # The scroll position goes last on this line but matters most, - # so the legend stands down to make room rather than letting it - # be clipped - which is what had been happening at 58 columns, - # leaving the footer offering a scroll with nothing saying where - # in the tab you were. - base = " local state · live quota · read %s ago" % ago(fetched) - hidden = " %d hidden by config" % len(extra) if extra else "" - legend = " · = detected" - if len(base) + len(hidden) + len(legend) + len(where) > w - 1: - legend = "" - return seg([(DIM, base), (DIM, legend), (DIM, hidden), - (ACCENT, where)], w - 1) - - status_at = len(rows) # filled in once the scroll is resolved - rows.append(status()) - gripe = err or config_complaints(installed) - if gripe: - rows.append(seg([(BAD, " ! " + gripe)], w - 1)) - rows.append(tab_bar(tabs[active], installed, tabs, w)) - rows.append("") - - # Every agent ends on the same section, in the same place. Which - # subscription a quota belongs to is context for the whole tab, not - # the headline, so it sits under the numbers it explains - and it is - # appended here rather than by five tabs that each end differently. - name = tabs[active] - sub = [] - if not fetched: - body = loading_rows(w, tick) - elif name == SUMMARY_TAB: - body = summary_tab({"claude": claude, "codex": codex, - "cursor": cursor, "grok": grok, - "copilot": copilot, - "antigravity": antigravity}, w, h) - elif name == "claude": - body = add_section(claude_tab(claude, w, h), - claude_metered(claude, w)) - if claude.get("profile"): - sub = claude_plan_rows(claude["profile"], w) - elif name == "cursor": - # METERED sits last-but-one on every tab, so Cursor's - which - # is published rather than configured - lands in the same place - # as everyone else's rather than floating up beside its quota. - body = add_section(cursor_tab(cursor, w, h), - cursor_metered_rows(cursor, w)) - sub = cursor_plan_rows(cursor.get("plan"), w) - elif name == "codex": - body = add_section(codex_tab(codex, w, h), - codex_metered(codex, w)) - sub = codex_plan_rows(codex, w) - elif name == "grok": - body = grok_tab(grok, w, h) - sub = grok_plan_rows(grok.get("quota"), w) - elif name == "copilot": - body = add_section(copilot_tab(copilot, w, h), - copilot_metered(copilot, w)) - sub = copilot_plan_rows(copilot.get("live") or {}, w) - elif name == "antigravity": - body = antigravity_tab(antigravity, w, h) - sub = antigravity_plan_rows(antigravity, w) - else: - body = elsewhere_tab(name, installed, w, h) - body = add_section(body, sub) - - hints = [[(ACCENT, "←→"), (DIM, " agent")], - [(ACCENT, "↑↓"), (DIM, " scroll")], - [(DIM, "[r]efresh")], [(DIM, "[q]uit")]] - # The footer is packed once, with the scroll hint always counted, so - # the body's height does not change when scrolling becomes possible. - # Sizing it against a shorter footer and then growing the footer would - # move the fold under the reader's cursor. - reserved = len(pack_hints(hints, w - 2)) - avail = max(1, h - len(rows) - reserved) - top = max(0, len(body) - avail) - off = min(offsets.get(name, 0), top) - for move in moves: - if move == "top": - off = 0 - elif move == "bottom": - off = top - elif move == "-page": - off -= max(1, avail - 1) - elif move == "+page": - off += max(1, avail - 1) - else: - off += move - off = max(0, min(off, top)) - offsets[name] = off - - view = body[off:off + avail] - if top: - # Never let a partial view read as the whole tab, and say which - # way there is more: an arrow that is simply absent at the top of - # a long tab looks the same as a tab that ends there. - rows[status_at] = status(" %d-%d of %d %s%s" - % (off + 1, off + len(view), len(body), - "▲" if off else " ", - "▼" if off < top else " ")) - else: - hints = [x for x in hints if x[0][1] != "↑↓"] - footer = [" " + line for line in pack_hints(hints, w - 2)] - # Padded back to the height already reserved, so dropping the scroll - # hint does not lift the footer off the bottom of the pane. - footer = [""] * (reserved - len(footer)) + footer - rows += view - while len(rows) < h - len(footer): - rows.append("") - rows.extend(footer) - draw(rows[:h], w, h) - time.sleep(0.3) - - -main() diff --git a/rust/widgets/Cargo.toml b/widgets/Cargo.toml similarity index 100% rename from rust/widgets/Cargo.toml rename to widgets/Cargo.toml diff --git a/rust/widgets/src/bin/clocks.rs b/widgets/src/bin/clocks.rs similarity index 100% rename from rust/widgets/src/bin/clocks.rs rename to widgets/src/bin/clocks.rs diff --git a/rust/widgets/src/bin/clocks_help.txt b/widgets/src/bin/clocks_help.txt similarity index 100% rename from rust/widgets/src/bin/clocks_help.txt rename to widgets/src/bin/clocks_help.txt diff --git a/rust/widgets/src/bin/deployments.rs b/widgets/src/bin/deployments.rs similarity index 100% rename from rust/widgets/src/bin/deployments.rs rename to widgets/src/bin/deployments.rs diff --git a/rust/widgets/src/bin/deployments_help.txt b/widgets/src/bin/deployments_help.txt similarity index 100% rename from rust/widgets/src/bin/deployments_help.txt rename to widgets/src/bin/deployments_help.txt diff --git a/rust/widgets/src/bin/github.rs b/widgets/src/bin/github.rs similarity index 100% rename from rust/widgets/src/bin/github.rs rename to widgets/src/bin/github.rs diff --git a/rust/widgets/src/bin/github_help.txt b/widgets/src/bin/github_help.txt similarity index 100% rename from rust/widgets/src/bin/github_help.txt rename to widgets/src/bin/github_help.txt diff --git a/rust/widgets/src/bin/herdr-panes.rs b/widgets/src/bin/herdr-panes.rs similarity index 100% rename from rust/widgets/src/bin/herdr-panes.rs rename to widgets/src/bin/herdr-panes.rs diff --git a/rust/widgets/src/bin/herdr-panes_help.txt b/widgets/src/bin/herdr-panes_help.txt similarity index 100% rename from rust/widgets/src/bin/herdr-panes_help.txt rename to widgets/src/bin/herdr-panes_help.txt diff --git a/rust/widgets/src/bin/latency.rs b/widgets/src/bin/latency.rs similarity index 100% rename from rust/widgets/src/bin/latency.rs rename to widgets/src/bin/latency.rs diff --git a/rust/widgets/src/bin/latency_help.txt b/widgets/src/bin/latency_help.txt similarity index 100% rename from rust/widgets/src/bin/latency_help.txt rename to widgets/src/bin/latency_help.txt diff --git a/rust/widgets/src/bin/linear.rs b/widgets/src/bin/linear.rs similarity index 100% rename from rust/widgets/src/bin/linear.rs rename to widgets/src/bin/linear.rs diff --git a/rust/widgets/src/bin/linear_help.txt b/widgets/src/bin/linear_help.txt similarity index 100% rename from rust/widgets/src/bin/linear_help.txt rename to widgets/src/bin/linear_help.txt diff --git a/rust/widgets/src/bin/link.rs b/widgets/src/bin/link.rs similarity index 100% rename from rust/widgets/src/bin/link.rs rename to widgets/src/bin/link.rs diff --git a/rust/widgets/src/bin/link_help.txt b/widgets/src/bin/link_help.txt similarity index 100% rename from rust/widgets/src/bin/link_help.txt rename to widgets/src/bin/link_help.txt diff --git a/rust/widgets/src/bin/matrix.rs b/widgets/src/bin/matrix.rs similarity index 100% rename from rust/widgets/src/bin/matrix.rs rename to widgets/src/bin/matrix.rs diff --git a/rust/widgets/src/bin/matrix_help.txt b/widgets/src/bin/matrix_help.txt similarity index 100% rename from rust/widgets/src/bin/matrix_help.txt rename to widgets/src/bin/matrix_help.txt diff --git a/rust/widgets/src/bin/netwatch.rs b/widgets/src/bin/netwatch.rs similarity index 100% rename from rust/widgets/src/bin/netwatch.rs rename to widgets/src/bin/netwatch.rs diff --git a/rust/widgets/src/bin/netwatch_help.txt b/widgets/src/bin/netwatch_help.txt similarity index 100% rename from rust/widgets/src/bin/netwatch_help.txt rename to widgets/src/bin/netwatch_help.txt diff --git a/rust/widgets/src/bin/ports.rs b/widgets/src/bin/ports.rs similarity index 100% rename from rust/widgets/src/bin/ports.rs rename to widgets/src/bin/ports.rs diff --git a/rust/widgets/src/bin/ports_help.txt b/widgets/src/bin/ports_help.txt similarity index 100% rename from rust/widgets/src/bin/ports_help.txt rename to widgets/src/bin/ports_help.txt diff --git a/rust/widgets/src/bin/pr.rs b/widgets/src/bin/pr.rs similarity index 100% rename from rust/widgets/src/bin/pr.rs rename to widgets/src/bin/pr.rs diff --git a/rust/widgets/src/bin/pr_help.txt b/widgets/src/bin/pr_help.txt similarity index 100% rename from rust/widgets/src/bin/pr_help.txt rename to widgets/src/bin/pr_help.txt diff --git a/rust/widgets/src/bin/start.rs b/widgets/src/bin/start.rs similarity index 96% rename from rust/widgets/src/bin/start.rs rename to widgets/src/bin/start.rs index 429de68..535c005 100644 --- a/rust/widgets/src/bin/start.rs +++ b/widgets/src/bin/start.rs @@ -39,37 +39,37 @@ const WIDGETS: &[Widget] = &[ Widget { stem: "clocks", help: include_str!("clocks_help.txt"), - doc: include_str!("../../../../docs/clocks.md"), + doc: include_str!("../../../docs/clocks.md"), }, Widget { stem: "deployments", help: include_str!("deployments_help.txt"), - doc: include_str!("../../../../docs/deployments.md"), + doc: include_str!("../../../docs/deployments.md"), }, Widget { stem: "github", help: include_str!("github_help.txt"), - doc: include_str!("../../../../docs/github.md"), + doc: include_str!("../../../docs/github.md"), }, Widget { stem: "herdr-panes", help: include_str!("herdr-panes_help.txt"), - doc: include_str!("../../../../docs/herdr-panes.md"), + doc: include_str!("../../../docs/herdr-panes.md"), }, Widget { stem: "latency", help: include_str!("latency_help.txt"), - doc: include_str!("../../../../docs/latency.md"), + doc: include_str!("../../../docs/latency.md"), }, Widget { stem: "linear", help: include_str!("linear_help.txt"), - doc: include_str!("../../../../docs/linear.md"), + doc: include_str!("../../../docs/linear.md"), }, Widget { stem: "link", help: include_str!("link_help.txt"), - doc: include_str!("../../../../docs/link.md"), + doc: include_str!("../../../docs/link.md"), }, Widget { stem: "matrix", @@ -81,27 +81,27 @@ const WIDGETS: &[Widget] = &[ Widget { stem: "netwatch", help: include_str!("netwatch_help.txt"), - doc: include_str!("../../../../docs/netwatch.md"), + doc: include_str!("../../../docs/netwatch.md"), }, Widget { stem: "ports", help: include_str!("ports_help.txt"), - doc: include_str!("../../../../docs/ports.md"), + doc: include_str!("../../../docs/ports.md"), }, Widget { stem: "pr", help: include_str!("pr_help.txt"), - doc: include_str!("../../../../docs/pr.md"), + doc: include_str!("../../../docs/pr.md"), }, Widget { stem: "tailnet", help: include_str!("tailnet_help.txt"), - doc: include_str!("../../../../docs/tailnet.md"), + doc: include_str!("../../../docs/tailnet.md"), }, Widget { stem: "usage", help: include_str!("usage_help.txt"), - doc: include_str!("../../../../docs/usage.md"), + doc: include_str!("../../../docs/usage.md"), }, ]; @@ -306,6 +306,9 @@ fn main() { let args: Vec<String> = std::env::args().skip(1).collect(); if let Some(first) = args.first() { if !first.starts_with('-') { + // `.py` is still accepted, and only for that: every widget here + // answered to that name for years and the muscle memory outlives + // the files. It resolves to the binary of the same stem. let wanted = first.strip_suffix(".py").unwrap_or(first); let Some(found) = WIDGETS.iter().find(|w| w.stem == wanted) else { eprintln!( diff --git a/rust/widgets/src/bin/start_help.txt b/widgets/src/bin/start_help.txt similarity index 100% rename from rust/widgets/src/bin/start_help.txt rename to widgets/src/bin/start_help.txt diff --git a/rust/widgets/src/bin/tailnet.rs b/widgets/src/bin/tailnet.rs similarity index 100% rename from rust/widgets/src/bin/tailnet.rs rename to widgets/src/bin/tailnet.rs diff --git a/rust/widgets/src/bin/tailnet_help.txt b/widgets/src/bin/tailnet_help.txt similarity index 100% rename from rust/widgets/src/bin/tailnet_help.txt rename to widgets/src/bin/tailnet_help.txt diff --git a/rust/widgets/src/bin/usage.rs b/widgets/src/bin/usage.rs similarity index 100% rename from rust/widgets/src/bin/usage.rs rename to widgets/src/bin/usage.rs diff --git a/rust/widgets/src/bin/usage/antigravity.rs b/widgets/src/bin/usage/antigravity.rs similarity index 100% rename from rust/widgets/src/bin/usage/antigravity.rs rename to widgets/src/bin/usage/antigravity.rs diff --git a/rust/widgets/src/bin/usage/claude.rs b/widgets/src/bin/usage/claude.rs similarity index 100% rename from rust/widgets/src/bin/usage/claude.rs rename to widgets/src/bin/usage/claude.rs diff --git a/rust/widgets/src/bin/usage/codex.rs b/widgets/src/bin/usage/codex.rs similarity index 100% rename from rust/widgets/src/bin/usage/codex.rs rename to widgets/src/bin/usage/codex.rs diff --git a/rust/widgets/src/bin/usage/copilot.rs b/widgets/src/bin/usage/copilot.rs similarity index 100% rename from rust/widgets/src/bin/usage/copilot.rs rename to widgets/src/bin/usage/copilot.rs diff --git a/rust/widgets/src/bin/usage/cursor.rs b/widgets/src/bin/usage/cursor.rs similarity index 100% rename from rust/widgets/src/bin/usage/cursor.rs rename to widgets/src/bin/usage/cursor.rs diff --git a/rust/widgets/src/bin/usage/grok.rs b/widgets/src/bin/usage/grok.rs similarity index 100% rename from rust/widgets/src/bin/usage/grok.rs rename to widgets/src/bin/usage/grok.rs diff --git a/rust/widgets/src/bin/usage/shared.rs b/widgets/src/bin/usage/shared.rs similarity index 100% rename from rust/widgets/src/bin/usage/shared.rs rename to widgets/src/bin/usage/shared.rs diff --git a/rust/widgets/src/bin/usage/vendors.rs b/widgets/src/bin/usage/vendors.rs similarity index 100% rename from rust/widgets/src/bin/usage/vendors.rs rename to widgets/src/bin/usage/vendors.rs diff --git a/rust/widgets/src/bin/usage_help.txt b/widgets/src/bin/usage_help.txt similarity index 100% rename from rust/widgets/src/bin/usage_help.txt rename to widgets/src/bin/usage_help.txt diff --git a/rust/widgets/tests/check.rs b/widgets/tests/check.rs similarity index 99% rename from rust/widgets/tests/check.rs rename to widgets/tests/check.rs index 28d784d..6ddd4f5 100644 --- a/rust/widgets/tests/check.rs +++ b/widgets/tests/check.rs @@ -42,14 +42,14 @@ use std::path::PathBuf; /// The repo root, from this crate's own location. fn root() -> PathBuf { PathBuf::from(env!("CARGO_MANIFEST_DIR")) - .join("../..") + .join("..") .canonicalize() .expect("the repo root") } /// Every widget binary, by stem, with its source. fn widgets() -> BTreeMap<String, String> { - let dir = root().join("rust/widgets/src/bin"); + let dir = root().join("widgets/src/bin"); let mut found = BTreeMap::new(); for entry in std::fs::read_dir(&dir).expect("the bin directory").flatten() { let path = entry.path(); @@ -492,7 +492,7 @@ fn every_key_the_help_text_names_is_answered() { const VERBS: &[&str] = &[ "opens", "cycles", "toggles", "quits", "refreshes", "closes", "copies", ]; - let dir = root().join("rust/widgets/src/bin"); + let dir = root().join("widgets/src/bin"); let mut wrong = Vec::new(); for (name, src) in widgets() { let help = dir.join(format!("{}_help.txt", name)); From d629275474d54581acae244eb050226e064ecdab Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Tue, 25 Aug 2026 21:27:19 +0800 Subject: [PATCH 114/147] docs: fourteen binaries, and no second implementation The tree stopped having two implementations one commit ago; this is everything that still said otherwise. The README's table named the widgets `start.py`, `latency.py` and so on - not as links but in the identity column, which is what they are called. They are called `start` and `latency` now. Run instructions become `cargo build --release` and `./target/release/<widget>`, the requirements lose Python 3.9+ and gain "a Rust toolchain to build, nothing to run", and the paragraph about self-contained scripts becomes one about self-contained binaries. All fourteen widget docs had run examples in the old form. `docs/start.md` needed more than a substitution: it described a launcher that read the directory at startup to find its widgets and their descriptions, which is how the Python one worked. This one compiles every widget's help text and doc page in with `include_str!`, so a doc page and the launcher's description of it cannot drift - they are the same bytes. What is written down instead is the list of widgets, because a binary cannot enumerate its siblings the way a directory of scripts could. AGENTS.md loses the two-implementations framing, the paragraph explaining that the Python had no build step to absorb a dependency into - rewritten around the build step that now exists, and what may not come through it - and `python3 check.py` from "Before you commit". The gotchas stay: they were paid for in Python and they are about how to work here, not about a language. `docs/rust-vs-python.md` is `docs/port-decisions.md`, which is what its own title already said. Its tense goes with it: it described a peer, and now describes a thing that was here. It names the commit the Python is behind, so a claim in it can still be checked. One thing deliberately left: `start netwatch.py` still works. Every widget answered to that name for years and the muscle memory outlives the files. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- AGENTS.md | 48 +++++----- README.md | 93 ++++++++++--------- docs/clocks.md | 2 +- docs/deployments.md | 8 +- docs/github.md | 6 +- docs/herdr-panes.md | 6 +- docs/latency.md | 6 +- docs/linear.md | 6 +- docs/link.md | 4 +- docs/netwatch.md | 6 +- docs/{rust-vs-python.md => port-decisions.md} | 17 ++-- docs/ports.md | 2 +- docs/pr.md | 12 +-- docs/start.md | 51 +++++----- docs/tailnet.md | 4 +- docs/usage.md | 4 +- 16 files changed, 139 insertions(+), 136 deletions(-) rename docs/{rust-vs-python.md => port-decisions.md} (93%) diff --git a/AGENTS.md b/AGENTS.md index 18f3740..98c4050 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,25 +10,26 @@ filed and already decided against. ## What this repo is -Terminal widgets that look like sci-fi movie panels and show only real -data, in two implementations: Python 3 scripts sharing `common.py`, and a -Rust port under `rust/` sharing `toys-core`. The Python has no package and -no build step; the Rust builds fourteen binaries with `cargo build ---release`. +Terminal widgets that look like sci-fi movie panels and show only real data. +Fourteen Rust binaries sharing `toys-core`, built with `cargo build +--release` from the root. + +They began as Python scripts and were ported widget by widget; the Python is +gone, and `docs/port-decisions.md` records what the port changed and why. The founding rule, and the one worth defending: **every number on screen is real.** Widgets that could not be wired to a true source were deleted rather -than faked. `matrix.py` is the sole exception and computes nothing on purpose. +than faked. `matrix` is the sole exception and computes nothing on purpose. ## Conventions - **What ships must carry what it needs.** Third-party dependencies are allowed; a dependency that has to be installed separately before a widget - runs is not. The Rust has a build step that can absorb one - `rusqlite` - is taken with `bundled` so SQLite is compiled in, and `ldd` on a release - binary shows only libc, libm and libgcc. The Python has no build step, so - in practice it stays on the 3.9+ standard library: there is nowhere for a - pip install to be absorbed into. If a widget needs an external *tool* + runs is not. The build step is what absorbs them - `rusqlite` is taken + with `bundled` so SQLite is compiled in, and `ldd` on a release binary + shows only libc, libm and libgcc. Keep it that way: a crate that wants a + system library at run time is the one kind that cannot come in. If a + widget needs an external *tool* (`ping`, `tailscale`, `herdr`) it degrades gracefully when that tool is absent - that is a different thing from a library and the rule is unchanged. @@ -50,7 +51,7 @@ than faked. `matrix.py` is the sole exception and computes nothing on purpose. ## Before you commit -Run `cargo test` from `rust/`. Alongside each widget's own tests it runs +Run `cargo test` from the root. Alongside each widget's own tests it runs `widgets/tests/check.rs`, which checks the things the compiler cannot, and every check in it exists because something shipped broken and looked, on screen, exactly like "there is no data": @@ -76,15 +77,14 @@ have been wrong before — three versions of this check cried wolf in one day, and a checker that cries wolf gets turned off — so when it fires, read the flag before believing it, and when it is quiet, that is not proof. -The Python keeps `python3 check.py` while it exists; it covers the same -ground for `*.py`, plus unbound names, which the Rust compiler makes -impossible. +`check.py` covered the same ground for the Python, plus unbound names - +which the compiler now makes impossible. It went with the Python. ## Gotchas paid for already - **A background thread that dies is invisible.** Wrap every poller so it records why it stopped; otherwise the pane shows no data and no error, which - is indistinguishable from a source that has none. `deployments.py` sat like + is indistinguishable from a source that has none. `deployments` sat like that for a day. - **Never let a bare `except` swallow a programming error.** `discover_teams` turned a `TypeError` from passing the wrong type into "no teams found", and @@ -132,20 +132,18 @@ impossible. ## Layout of the code -`common.py` holds everything shared: terminal sizing, full-frame `draw()`, +`toys-core` holds everything shared: terminal sizing, full-frame `draw()`, 24-bit `rgb()`, `seg()` for clipping coloured segments to a cell budget, -`pack_hints()`, bar and chart helpers (`vbars`, `vbars_down`, `braille_plot`, +`pack_hints()`, `follow()` for a window that keeps a cursor in view, bar +and chart helpers (`vbars`, `vbars_down`, `braille_plot`, `stacked_bar`, `meter`, `skeleton`), `config_token_warning()` for widgets holding a secret, non-blocking `Keyboard`, and OSC 52 `clipboard()`. -`docs/rust-vs-python.md` records where the two implementations answer -differently on purpose. Anything not listed there is a finding rather than a -decision, and a new deliberate divergence belongs in it. - -`docs/rust-vs-python.md` records where the two implementations answer -differently on purpose. Anything not listed there is a finding rather than a -decision, and a new deliberate divergence belongs in it. +`docs/port-decisions.md` records what the port changed from the Python and +why - the keys it consolidated, the two it renamed, the charts it draws +differently. It is history rather than a comparison now, and it is the answer +to most questions beginning *why does this key do that*. `docs/building-herdr-panels.md` records what was learned driving these from Herdr: resize semantics, focus, and the layout mistakes worth skipping. diff --git a/README.md b/README.md index aa09f56..0fe2086 100644 --- a/README.md +++ b/README.md @@ -26,43 +26,47 @@ impossible to unsee. One by one the fakes came down, each replaced by something that answers a real question. What survived is the aesthetic with the lying removed. -Some of the theatre is still here, unapologetically. `matrix.py` computes +Some of the theatre is still here, unapologetically. `matrix` computes nothing at all — it just looks good, and it knows it. ## The widgets | Widget | What it does | Needs | Docs | |---|---|---|---| -| **`start.py`** | The front door: every widget, what it does, and whether it will work on this machine — pick one and it runs, quit it and you are back. | — | [read →](docs/start.md) | -| **`latency.py`** | Continuous latency to a list of hosts: median, jitter, loss and a log-scale graph, so a slow link and an *unsteady* one look different. | `ping` | [read →](docs/latency.md) | -| **`deployments.py`** | Vercel deployments over time — activity per hour, build-time drift, and a copy sheet for the dashboard, preview and PR URLs. | a Vercel token | [read →](docs/deployments.md) | -| **`tailnet.py`** | Tailscale peers, and whether each is reached directly or through a relay. Live throughput, full machine info, copyable addresses. | `tailscale` | [read →](docs/tailnet.md) | -| **`herdr-panes.py`** | Every agent and process across all workspaces, ordered by which one needs a human. Enter jumps you there. | `herdr` | [read →](docs/herdr-panes.md) | -| **`github.py`** | Pull requests across every org: merge rate, opened-vs-merged per day, review backlog and the contribution calendar. | a GitHub token | [read →](docs/github.md) | -| **`pr.py`** | The pull requests you have to follow up on: checks, reviews, mergeability, and a stack map with the order a stack has to merge in. | a GitHub token | [read →](docs/pr.md) | -| **`linear.py`** | Linear across every team: what is outstanding, the running cycles and their scope creep, and issues created against completed. | a Linear API key | [read →](docs/linear.md) | -| **`usage.py`** | How much each coding agent on the machine has been used — tokens, sessions, AI-written code — and what is left of each one's rate limit, one tab per agent. | the agents' own logins | [read →](docs/usage.md) | -| **`ports.py`** | What is listening on this machine — the dev servers you have running, which project each was started from, how long it has been up, and whether anything outside the box can reach it. `k` stops the selected one; `↵` opens it to copy an address or publish it over Tailscale or Cloudflare. | — | [read →](docs/ports.md) | -| **`netwatch.py`** | Which processes are using the network — total since it started, current rate, up and down, per process — read from the kernel's own per-socket counters rather than by capturing packets. | `ss` | [read →](docs/netwatch.md) | -| **`link.py`** | How good the connection is between this machine and whoever is connected to it — round-trip time, jitter, loss and achieved rate for every inbound session, read from the kernel rather than probed. | `ss` | [read →](docs/link.md) | -| **`clocks.py`** | Server clock, countdowns to the next hour / end of office hours / end of day, a pomodoro, and a world clock. | — | [read →](docs/clocks.md) | -| **`matrix.py`** | Nothing whatsoever. Digital rain, with truecolor fade trails. | — | — | - -Each is a single self-contained script with no dependencies — pure Python 3 -standard library, 24-bit colour, and a full redraw each frame so everything -reflows when you resize the pane. +| **`start`** | The front door: every widget, what it does, and whether it will work on this machine — pick one and it runs, quit it and you are back. | — | [read →](docs/start.md) | +| **`latency`** | Continuous latency to a list of hosts: median, jitter, loss and a log-scale graph, so a slow link and an *unsteady* one look different. | `ping` | [read →](docs/latency.md) | +| **`deployments`** | Vercel deployments over time — activity per hour, build-time drift, and a copy sheet for the dashboard, preview and PR URLs. | a Vercel token | [read →](docs/deployments.md) | +| **`tailnet`** | Tailscale peers, and whether each is reached directly or through a relay. Live throughput, full machine info, copyable addresses. | `tailscale` | [read →](docs/tailnet.md) | +| **`herdr-panes`** | Every agent and process across all workspaces, ordered by which one needs a human. Enter jumps you there. | `herdr` | [read →](docs/herdr-panes.md) | +| **`github`** | Pull requests across every org: merge rate, opened-vs-merged per day, review backlog and the contribution calendar. | a GitHub token | [read →](docs/github.md) | +| **`pr`** | The pull requests you have to follow up on: checks, reviews, mergeability, and a stack map with the order a stack has to merge in. | a GitHub token | [read →](docs/pr.md) | +| **`linear`** | Linear across every team: what is outstanding, the running cycles and their scope creep, and issues created against completed. | a Linear API key | [read →](docs/linear.md) | +| **`usage`** | How much each coding agent on the machine has been used — tokens, sessions, AI-written code — and what is left of each one's rate limit, one tab per agent. | the agents' own logins | [read →](docs/usage.md) | +| **`ports`** | What is listening on this machine — the dev servers you have running, which project each was started from, how long it has been up, and whether anything outside the box can reach it. `k` stops the selected one; `↵` opens it to copy an address or publish it over Tailscale or Cloudflare. | — | [read →](docs/ports.md) | +| **`netwatch`** | Which processes are using the network — total since it started, current rate, up and down, per process — read from the kernel's own per-socket counters rather than by capturing packets. | `ss` | [read →](docs/netwatch.md) | +| **`link`** | How good the connection is between this machine and whoever is connected to it — round-trip time, jitter, loss and achieved rate for every inbound session, read from the kernel rather than probed. | `ss` | [read →](docs/link.md) | +| **`clocks`** | Server clock, countdowns to the next hour / end of office hours / end of day, a pomodoro, and a world clock. | — | [read →](docs/clocks.md) | +| **`matrix`** | Nothing whatsoever. Digital rain, with truecolor fade trails. | — | — | + +Each is a single self-contained binary — everything it needs is compiled in, +`ldd` shows only libc, libm and libgcc, and there is nothing to install +alongside. 24-bit colour, and a full redraw each frame so everything reflows +when you resize the pane. ```sh -python3 terminal-toys # the front door: pick one and it runs -./start.py # the same thing from inside the directory -./start.py latency # or name one and skip the menu +cargo build --release # fourteen binaries in ./target/release +``` + +```sh +./target/release/start # the front door: pick one and it runs +./target/release/start latency # or name one and skip the menu ``` Each widget is also an ordinary program, if you would rather go direct: ```sh -./latency.py # each runs standalone -./clocks.py -h # every widget documents itself +./target/release/latency # each runs standalone +./target/release/clocks -h # every widget documents itself ``` They are built to sit side by side and fill a wall, but nothing assumes a @@ -95,16 +99,17 @@ This keeps hostnames, ping targets, city lists and tokens out of the source tree: the repo ships generic defaults, and `config.json` is git-ignored along with `.env` files and anything else likely to hold a secret. -**Three widgets need a token:** `deployments.py` wants a Vercel token from -Account Settings → Tokens, `github.py` a *classic* GitHub PAT with `repo` and -`read:org` (fine-grained tokens reach only one org each), and `linear.py` a -personal API key from Settings → Security & access. `pr.py` reuses the GitHub +**Three widgets need a token:** `deployments` wants a Vercel token from +Account Settings → Tokens, `github` a *classic* GitHub PAT with `repo` and +`read:org` (fine-grained tokens reach only one org each), and `linear` a +personal API key from Settings → Security & access. `pr` reuses the GitHub token rather than asking for its own. Every other widget runs with no configuration at all. ## Requirements -- Python **3.9+** (`clocks.py` uses `zoneinfo`); developed on 3.12 +- A Rust toolchain to build; **nothing** to run. The binaries carry what + they need, SQLite included - A terminal with 24-bit colour - Per-widget: `ping`, `tailscale` or `herdr` as listed above. Each needs only its own, and **none needs root** @@ -121,7 +126,7 @@ before changing one: - **A directional glyph points the way the thing goes.** `▲`/`▼` mark which half of a diverging chart a series occupies — `▲ opened` above the baseline, `▼ merged` below it. `↑`/`↓` mean upload and download. Where both meanings - meet, in `netwatch.py`'s chart, the halves are arranged so they agree: tx + meet, in `netwatch`'s chart, the halves are arranged so they agree: tx above and rx below, because a `↓` label over a line that climbs asks the reader to hold two directions at once, and they will believe the arrow. - **Measure contrast, do not eyeball it.** Every colour that draws text clears @@ -161,23 +166,23 @@ was learned building these against Herdr: resize semantics, focus, detecting what a pane is running, notification gating, and the layout mistakes worth skipping. -[`docs/rust-vs-python.md`](docs/rust-vs-python.md) records where the two -implementations answer differently **on purpose** — the keys the Rust -consolidated, the two it renamed, the charts it draws differently, and the -features that exist only on one side. Anything not listed there is a finding -rather than a decision. +These began as Python and were ported to Rust widget by widget; +[`docs/port-decisions.md`](docs/port-decisions.md) records what the port +changed and why — the keys it consolidated, the two it renamed, the charts it +draws differently. It is history now rather than a comparison, but it is the +answer to most questions beginning *why does this key do that*. -Both implementations are checked the same way. `cargo test` from `rust/` runs -each widget's tests plus `widgets/tests/check.rs`, which reads the sources and -fails on a poller that dies without saying why, a footer hint naming a key -nothing answers, a hint missing from the widget's doc, and a config key read -but never documented in `config.example.json`. `python3 check.py` covers the -same ground for the Python. +`cargo test` from the root runs each widget's tests plus +`widgets/tests/check.rs`, which reads the sources and fails on a poller that +dies without saying why, a footer hint naming a key nothing answers, a hint +missing from the widget's doc, and a config key read but never documented in +`config.example.json`. -`common.py` holds the shared pieces — terminal sizing, a full-frame `draw()`, +`toys-core` holds the shared pieces — terminal sizing, a full-frame `draw()`, 24-bit colour, a green→amber→red `heat()` ramp, `seg()` for clipping coloured -text to a cell budget, `pack_hints()` for wrapping footers, non-blocking -`Keyboard` input with arrow-key decoding, and `clipboard()` over OSC 52. +text to a cell budget, `pack_hints()` for wrapping footers, `follow()` for a +window that keeps a cursor in view, non-blocking `Keyboard` input with +arrow-key decoding, and `clipboard()` over OSC 52. The chart helpers are worth knowing before drawing anything new: `vbars()` and its mirror `vbars_down()` (pair them on a shared scale for a diverging chart), diff --git a/docs/clocks.md b/docs/clocks.md index 23e78e7..b51cd6d 100644 --- a/docs/clocks.md +++ b/docs/clocks.md @@ -1,4 +1,4 @@ -# `clocks.py` +# `clocks` This server's clock, the clocks counting down, a pomodoro, and everyone else's clock — the four things you need to know about time while working across diff --git a/docs/deployments.md b/docs/deployments.md index 2778b35..3500919 100644 --- a/docs/deployments.md +++ b/docs/deployments.md @@ -1,4 +1,4 @@ -# `deployments.py` +# `deployments` Vercel deployments — how they are going over time, not just what shipped last. @@ -121,7 +121,7 @@ on the way out rather than on the way in. | `c` | copy the selected PR's… (in the detail view, the copy page) | | `r` | refresh now, and in the detail view fetch it again | | `q` | quit, from either screen | -| `f` `p` | the state filter and the project cycle — **`deployments.py` only**; the Rust build has `s` and `/` instead | +| `f` `p` | the state filter and the project cycle — **`deployments` only**; the Rust build has `s` and `/` instead | ## Filtering @@ -192,6 +192,6 @@ Empty `teams` discovers every team you can see; empty `projects` shows all. Polling every 15s is 4 requests/min per team. ```sh -./deployments.py # every project, 15s -./deployments.py -n 60 my-project # one project, slower +./target/release/deployments # every project, 15s +./target/release/deployments -n 60 my-project # one project, slower ``` diff --git a/docs/github.md b/docs/github.md index 0a278a8..3406cfc 100644 --- a/docs/github.md +++ b/docs/github.md @@ -1,4 +1,4 @@ -# `github.py` +# `github` Pull requests across every org you work in — not what shipped, but whether work is actually moving. @@ -305,6 +305,6 @@ Friday moves every figure on the board: a merge rate, a per-day average and a queue trend all read as noise when a single day is a seventh of the sample. ```sh -./github.py # discovered accounts, 120s -./github.py -n 300 acme @me # two accounts, slower +./target/release/github # discovered accounts, 120s +./target/release/github -n 300 acme @me # two accounts, slower ``` diff --git a/docs/herdr-panes.md b/docs/herdr-panes.md index 31f4cc6..f890463 100644 --- a/docs/herdr-panes.md +++ b/docs/herdr-panes.md @@ -1,4 +1,4 @@ -# `herdr-panes.py` +# `herdr-panes` Everything running under [Herdr](https://herdr.dev), across every workspace — and one keypress to get to any of it. @@ -19,7 +19,7 @@ and one keypress to get to any of it. ── PROCESSES ── 7 panes running something COMMAND CPU MEM WORKSPACE - ▪ tailnet.py 3% 16M infra + ▪ tailnet 3% 16M infra ▪ pnpm 0% 116M some-cli ── IDLE ── 13 panes at a prompt @@ -68,7 +68,7 @@ with `herdr integration status`. **Idle panes are detected exactly**, not guessed: a busy pane's foreground pid differs from its own shell pid. Command names come from `argv`, so a pane shows -`tailnet.py` rather than `python3`. +`tailnet` rather than `python3`. **Durations are marked `≥`** when the state was already in place before the widget started — we did not see it begin, so it is only a lower bound. Herdr diff --git a/docs/latency.md b/docs/latency.md index 4050a4b..ab901cb 100644 --- a/docs/latency.md +++ b/docs/latency.md @@ -1,4 +1,4 @@ -# `latency.py` +# `latency` Continuous latency to a list of hosts, with the statistics that actually explain a bad connection. @@ -108,8 +108,8 @@ baseline, not a path measurement. `studio` rather than clipping the interesting half. ```sh -./latency.py # config targets, 0.5s -./latency.py -i 2 1.1.1.1 example.com # override both +./target/release/latency # config targets, 0.5s +./target/release/latency -i 2 1.1.1.1 example.com # override both ``` It measures *this host → each target*. Target-to-target legs need a probe on the diff --git a/docs/linear.md b/docs/linear.md index 31b09e2..e25d082 100644 --- a/docs/linear.md +++ b/docs/linear.md @@ -1,4 +1,4 @@ -# `linear.py` +# `linear` Linear across every team at once — what is outstanding, which cycles are running, and whether issues are being closed faster than they arrive. @@ -364,6 +364,6 @@ dropping it is sometimes the difference between a readable board and one number swamping the rest. ```sh -./linear.py # every team, 14-day window -./linear.py -n 300 WEB APP # two teams by key, slower +./target/release/linear # every team, 14-day window +./target/release/linear -n 300 WEB APP # two teams by key, slower ``` diff --git a/docs/link.md b/docs/link.md index 7960a5c..9d0147a 100644 --- a/docs/link.md +++ b/docs/link.md @@ -1,4 +1,4 @@ -# `link.py` +# `link` How good the connection is between this machine and whoever is connected to it — measured, not probed. @@ -23,7 +23,7 @@ it — measured, not probed. ## Why this is not the latency monitor -`latency.py` measures paths it was told to measure, by sending pings. This one +`latency` measures paths it was told to measure, by sending pings. This one measures the path **you are on**, and sends nothing at all. Every established TCP connection has a kernel that has been timing it since it diff --git a/docs/netwatch.md b/docs/netwatch.md index f266080..abd1d19 100644 --- a/docs/netwatch.md +++ b/docs/netwatch.md @@ -1,4 +1,4 @@ -# `netwatch.py` +# `netwatch` Which processes are using the network, how much they have used, and how fast they are going right now. @@ -425,7 +425,7 @@ the number is never a mystery, and the **totals** are untouched by it. | `esc` / `←` | back to the list | | `tab` | focus the next section, and from the last one back to scrolling | | `c` | copy the selected host, socket or path | -| `e` `f` | jump straight to the endpoints or the files — **`netwatch.py` only**; the Rust build reaches every section with `tab` alone | +| `e` `f` | jump straight to the endpoints or the files — **`netwatch` only**; the Rust build reaches every section with `tab` alone | | `s` | switch sort mode (`t` also works) | | `o` | show or hide processes you do not own | | `1` | sort by total data used | @@ -436,7 +436,7 @@ the number is never a mystery, and the **totals** are untouched by it. ## Options ``` -netwatch.py [-i SECONDS] [-n COUNT] [--sort total|live] [--external] [--plain] +netwatch [-i SECONDS] [-n COUNT] [--sort total|live] [--external] [--plain] ``` | Option | Meaning | diff --git a/docs/rust-vs-python.md b/docs/port-decisions.md similarity index 93% rename from docs/rust-vs-python.md rename to docs/port-decisions.md index 62ab473..41b222d 100644 --- a/docs/rust-vs-python.md +++ b/docs/port-decisions.md @@ -6,15 +6,14 @@ never a transliteration: some of it answers differently on purpose. Telling side-by-side review ([TOY-8](https://linear.app/stealth-company/issue/TOY-8)), and this page is what that review produced. -**The Python goes when [#31](https://github.com/stealth-factory/terminal-toys/pull/31) -merges.** This page outlives it, because most of what is here is not a -comparison — it is the reason a key is the key it is, the reason a rate is -averaged, the reason a braille cell belongs to one trace. The Python is how -those reasons are explained, not why they matter. - -Until it merges, both implementations are still in the tree, and anything not -listed here and not obviously a Rust-only feature should be treated as a -finding rather than a decision. +**The Python is gone.** This page outlives it, because most of what is here +is not a comparison — it is the reason a key is the key it is, the reason a +rate is averaged, the reason a braille cell belongs to one trace. The Python +is how those reasons are explained, not why they matter. + +Everything below is in the past tense on purpose: it describes a thing that +was here, against which these decisions were made. `git log` still has it, at +`22a9bc7^`, if a claim here ever needs checking. **Reviewed against `ac02b90`.** Verified by reading both sources, not by diffing them: three attempts at a mechanical key-differ each reported diff --git a/docs/ports.md b/docs/ports.md index c1c6f2e..4e071c8 100644 --- a/docs/ports.md +++ b/docs/ports.md @@ -1,4 +1,4 @@ -# `ports.py` +# `ports` What is listening on this machine, what started it, and who can reach it. diff --git a/docs/pr.md b/docs/pr.md index 8a2f0b9..ac093fb 100644 --- a/docs/pr.md +++ b/docs/pr.md @@ -1,4 +1,4 @@ -# `pr.py` +# `pr` The pull requests you have to follow up on, and a dashboard for whichever one you open. @@ -93,7 +93,7 @@ diff. Heights are **linear against the oldest PR**, which is worth knowing when the spread is wide: with an outlier at 3.9 years, everything under a couple of -months lands on the same lowest block. `latency.py` solves the same problem +months lands on the same lowest block. `latency` solves the same problem with a log scale; this chart has not adopted one yet. ## Which PRs, and why it takes three searches @@ -283,7 +283,7 @@ one you open — so the view paints a loading shimmer and fills in. **Reuses `github.token`** from `config.json`, or `$GITHUB_TOKEN`. No second credential: it is the same classic token with `repo` and `read:org` that -`github.py` uses. Set `pr.token` only to point this widget at a different +`github` uses. Set `pr.token` only to point this widget at a different account. ## Configuration @@ -303,9 +303,9 @@ account. Add, remove or rename sources freely — `review-requested:@me` and `is:open is:pr org:acme` are both reasonable entries, and the names are what `f` cycles through. Anything on the command line is appended to *every* source, -so `./pr.py org:acme` narrows the lot without editing config. +so `./target/release/pr org:acme` narrows the lot without editing config. ```sh -./pr.py # everything you are involved in -./pr.py -n 120 review-requested:@me # only what is waiting on your review +./target/release/pr # everything you are involved in +./target/release/pr -n 120 review-requested:@me # only what is waiting on your review ``` diff --git a/docs/start.md b/docs/start.md index 154c919..65dbc80 100644 --- a/docs/start.md +++ b/docs/start.md @@ -1,4 +1,4 @@ -# `start.py` +# `start` The front door: every widget, what it does, and whether it will work on this machine. @@ -15,7 +15,7 @@ machine. usage How much the coding agents have been used… reads what is logged in … - ── NETWATCH ── python3 netwatch.py + ── NETWATCH ── ./target/release/netwatch needs `ss` ↑↓ select ↵ launch [r]echeck [q]uit @@ -26,19 +26,22 @@ and it runs; quit it and you are back here. ## Nothing is described twice -The launcher holds no list of widgets, no descriptions, and no requirements -of its own. All three are read at startup from where they already live: - -- **Which widgets exist** — every `.py` in the directory that is not - `common.py`, `check.py`, or the launcher itself. The same rule `check.py` - uses, so the two can never disagree about what a widget is. -- **What each one does** — its own first docstring line, the one you get from - `python3 <widget> --help`. +The launcher writes none of this down twice. Every widget's description and +requirements are the ones that already exist elsewhere, compiled in at build +time rather than restated here: + +- **What each one does** — the same help text the binary itself answers + `--help` with, and its doc page from `docs/`, both taken with + `include_str!`. A doc page and the launcher's description of it cannot + drift apart, because they are the same bytes. +- **Which widgets exist** — a list in the launcher's own source, one entry + per binary. It is the one thing that is written down, because a binary + cannot enumerate its siblings the way a directory of scripts could. - **What each one needs** — the Needs column of the README's widget table. That last one is deliberate. It could have been restated here, and then there would be two descriptions of every requirement, drifting apart quietly. The -README's version cannot rot: `check.py` fails any widget missing a row in +README's version cannot rot: `check.rs` fails any widget missing a row in that table. The practical effect is that adding a widget adds it here. There is no list @@ -63,7 +66,7 @@ highlighted widget — its doc page's own opening example, marked as one. Every widget's doc page opens with a rendering of the widget it describes, maintained by whoever wrote it, so there is no second copy of anything here -either — the same arrangement as the descriptions. `matrix.py` has no doc +either — the same arrangement as the descriptions. `matrix` has no doc page on purpose and so has no picture; it gets the description alone. It says `example` on the frame because it is one. Static numbers in a live @@ -127,8 +130,8 @@ explanation with it — and in a tiled wall, or started from this menu, a line on stderr has nowhere to go. So it draws the reason and waits, answering `q` like everything else. -`link.py`, `netwatch.py`, `latency.py` and `herdr-panes.py` all do this, via -`cannot_start` in `common.py`. The first two used to exit; the second two used +`link`, `netwatch`, `latency` and `herdr-panes` all do this, via +`cannot_start` in `toys-core`. The first two used to exit; the second two used to run and quietly show nothing, which was worse. ## Launching## Launching @@ -146,20 +149,18 @@ Naming one skips the menu entirely, and anything after it is passed straight through: ```sh -python3 terminal-toys # the directory itself is runnable -./start.py # the menu, from inside it -./start.py netwatch # straight into one -./start.py netwatch -i 2 -n 5 # arguments go to the widget -./start.py link --help # including --help +./target/release/start # the menu +./target/release/start netwatch # straight into one +./target/release/start netwatch -i 2 -n 5 # arguments go to the widget +./target/release/start link --help # including --help ``` -The first form works because of `__main__.py`, which is Python's own -convention for an entry point: a directory containing one can be run by -name. It holds three lines and hands straight over to this script, so the -collection can be started without knowing which file inside it to name. +A widget is looked for beside the launcher's own binary, so a release +unpacked anywhere works without a path being configured. -That form uses `exec`, so the launcher replaces itself rather than sitting in -the middle of a pipeline it adds nothing to. +`start netwatch.py` is still accepted, and only for that: every widget here +answered to that name for years and the muscle memory outlives the files. +The suffix is stripped and the binary of the same stem runs. ## Keys diff --git a/docs/tailnet.md b/docs/tailnet.md index 4bd0b05..c64c8d1 100644 --- a/docs/tailnet.md +++ b/docs/tailnet.md @@ -1,4 +1,4 @@ -# `tailnet.py` +# `tailnet` Tailscale peers, and — the part plain `tailscale status` buries — *how* you are reaching each one. @@ -70,7 +70,7 @@ geolocation service), every address it has, its advertised routes, and whether it offers itself as an exit node. It also carries **live latency** for that peer — current, average, median, min, -max, jitter, loss and a sparkline, the same statistics `latency.py` reports, +max, jitter, loss and a sparkline, the same statistics `latency` reports, measured by ICMP over the tunnel. Only the selected peer is probed, so this costs one ping process no matter how large the tailnet, and history is kept per peer so returning to one still shows its earlier samples. diff --git a/docs/usage.md b/docs/usage.md index 763cdc9..e823085 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -1,4 +1,4 @@ -# `usage.py` +# `usage` How much the coding agents on this machine have actually been used — one tab per agent, from each agent's own local state, plus a live quota reading for @@ -124,7 +124,7 @@ cache had settled — 31 sessions, a longest session of `4d 10h 52m`, a longest streak of 21 days, Aug 1 as the busiest day. The **tokens-per-day calendar** is laid out like the contribution calendar in -`github.py` — weekdays down the side, weeks across — so the two read the same +`github` — weekdays down the side, weeks across — so the two read the same way on one wall. The only difference is cell width. That pane spans a year, so its cells are one From a2e96e5d877a0af6d093470a36597c9b0387f522 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Wed, 26 Aug 2026 02:52:14 +0800 Subject: [PATCH 115/147] README: fourteen, not ten The layout example still opened by counting the widgets there were when it was written. There have been fourteen since the port finished. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 0fe2086..2d5d642 100644 --- a/README.md +++ b/README.md @@ -74,8 +74,8 @@ multiplexer — each is an ordinary terminal program. Tile them however you like ## Building the wall -Ten widgets tile into whatever space you have. A layout that works on a wide -screen: +Fourteen widgets tile into whatever space you have. A layout that works on a +wide screen: ``` ┌────────────────────┬──────────────────┬────────────┐ From 51b1d734919d5ce3449c7c1080d762dff4ee4144 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Wed, 26 Aug 2026 03:18:15 +0800 Subject: [PATCH 116/147] ports, latency: a dead poller says so, and the check can tell MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CLAUDE.md's central rule is that a thread which stops must record why, because a pane with nothing in it is indistinguishable from a source with nothing to say. Nine of the eleven widgets that spawn a poller did that. Two did not, and both passed the check that exists to catch exactly this. ports caught its panic and threw the reason away. `catch_unwind(scan) .unwrap_or_default()` hands the table an empty list, so the pane reads "0 listening · 0 yours" - a machine with nothing running on it, which is a thing this widget is supposed to be able to say truthfully. The comment directly above it said an empty table would look exactly like a machine with nothing listening. It was describing what it did. It passed because the check accepted the presence of `catch_unwind` as proof that a reason was recorded. One of the two sites was added yesterday, by me, copying the shape above it without noticing the shape above it was wrong. latency passed on a coincidence. The check looked for `err =`; latency.rs contains it exactly once, as `let mut err = dx + dy`, the Bresenham variable in its line drawing. That was the whole reason it passed. What it actually did when ping would not start was sleep two seconds and try again, for as long as the widget was up, with the row empty - identical to a host that is simply not answering, which is the one distinction this widget exists to draw. Both now do what usage and herdr-panes do, in the same words. ports carries "poller stopped - see the pane it was started from" under the counts it has stopped updating, and its traffic sampler says so separately, because the ports themselves are still being found. latency puts the reason on the row and turns the name red, keeping the figures beside it - they were true when they were taken, and they are the last thing that target was known to be doing. The check is tightened three ways, and every one of them was arrived at by a version of it being wrong first: A reason has to look like a reason. A field called `err` holds one whatever it is assigned from - netwatch hands over a String built further up - but a bare local has to be assigned something with words in it, or arithmetic counts. It has to reach a row. Recording one nobody draws is the same silence with more code behind it. And `catch_unwind` ending in `unwrap_or_default()` is flagged on its own line, whatever else the widget records. Without that the first attempt let the regression through: ports had one good guard and one bad one, and "the widget records a reason somewhere" was true. Verified by breaking both: ports' scan made to panic draws the line instead of an empty table, and a target pointed at a ping that does not exist shows its reason while the other five carry on. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- AGENTS.md | 7 ++++- docs/latency.md | 11 +++++++ docs/ports.md | 11 +++++++ widgets/src/bin/latency.rs | 35 +++++++++++++++++++-- widgets/src/bin/ports.rs | 43 +++++++++++++++++++++++--- widgets/tests/check.rs | 63 +++++++++++++++++++++++++++++++++++--- 6 files changed, 159 insertions(+), 11 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 98c4050..da7b5ec 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -57,7 +57,12 @@ every check in it exists because something shipped broken and looked, on screen, exactly like "there is no data": - **a poller that dies without recording why** — a thread that stops is - invisible, and the pane it feeds is indistinguishable from a quiet source; + invisible, and the pane it feeds is indistinguishable from a quiet source. + Recording it is not enough: the reason has to reach a row, and a caught + panic ending in `unwrap_or_default()` is flagged on its own line, because + that shape hands the pane an empty list and draws a source with nothing in + it. Two widgets passed this check on accidents - one on the presence of + `catch_unwind` alone, one on a Bresenham variable called `err`; - **a footer hint naming a key no match arm answers** — a hint bound to nothing says the feature is there; - **a footer hint missing from the widget's doc**; diff --git a/docs/latency.md b/docs/latency.md index ab901cb..62ee352 100644 --- a/docs/latency.md +++ b/docs/latency.md @@ -23,6 +23,17 @@ explain a bad connection. 300s ago now ``` +## A host that will not answer, and a ping that will not run + +They are not the same thing and no longer look the same. A host that does not +reply is a result — it shows as loss, which is what the widget is for. A +`ping` this widget could not start is a failure of its own, and the row now +carries the reason and turns its name red, rather than sitting empty and +being retried every two seconds in silence for as long as the widget is up. + +The figures beside it stay. They were true when they were taken, and they are +the last thing that target was known to be doing. + ## Why the shape of it **The graph is log-scale**, because a useful target list spans three orders of diff --git a/docs/ports.md b/docs/ports.md index 4e071c8..cf15008 100644 --- a/docs/ports.md +++ b/docs/ports.md @@ -167,6 +167,17 @@ last and leave first. A port nothing is calling shows nothing in the rates column rather than `0 B/s` — a column of zeroes down the table reads as a measurement that has failed. +## When the scan itself breaks + +If the poller stops, the header carries `! poller stopped - see the pane it +was started from` and the table holds whatever it last knew. It used to catch +the failure and return an empty list, so the pane read `0 listening` — a +machine with nothing running on it, which is a thing this widget is supposed +to be able to say truthfully. + +The traffic sampler is separate: if it stops, the columns it feeds go quiet +and the line says so, while the table below carries on being found. + ## What it cannot see Sockets owned by another user, which on a normal machine means everything root diff --git a/widgets/src/bin/latency.rs b/widgets/src/bin/latency.rs index 6012c50..b58e273 100644 --- a/widgets/src/bin/latency.rs +++ b/widgets/src/bin/latency.rs @@ -79,6 +79,12 @@ struct Target { /// Set while we are killing our own ping on purpose, so its exit is not /// logged as an outage. restarting: bool, + /// Why this target has no reading, when the reason is this widget's own + /// rather than the network's. A host that does not answer is a result; + /// a `ping` that will not start is a failure, and the two used to look + /// identical - an empty row either way, retried every two seconds for + /// as long as the widget was up, saying nothing. + err: String, } /// Everything the table says about one target over the retained window. @@ -307,11 +313,20 @@ fn watch( .spawn(); let mut child = match child { Ok(c) => c, - Err(_) => { + Err(e) => { + let why = format!("ping will not start: {}", e); + if let Ok(mut guard) = shared.lock() { + guard[index].err = why; + guard[index].alive = false; + } std::thread::sleep(Duration::from_secs(2)); continue; } }; + // It started, so whatever stopped it last time is over. + if let Ok(mut guard) = shared.lock() { + guard[index].err.clear(); + } if let Ok(mut guard) = shared.lock() { guard[index].pid = Some(child.id() as i32); } @@ -966,7 +981,11 @@ fn main() { // which is what link puts its glyph in, and the name is free // to swing between two colours that are both readable. ( - tinted(if here { &p.txt } else { &p.dim_lit }), + tinted(if t.err.is_empty() { + if here { &p.txt } else { &p.dim_lit } + } else { + &p.bad + }), tc::pad(&t.label, name_w), ), // Red when there is no round trip to report, which is the @@ -988,6 +1007,18 @@ fn main() { (tinted(dim), format!(" {}", fmt_ms(st.max))), (tinted(&p.txt), format!(" {}", fmt_ms(st.jit))), (tinted(loss_c), format!(" {:>5.1}%", st.loss)), + // The reason, when there is one. It sits after the figures + // rather than replacing them: the numbers from before it + // broke are still true, and still the last thing this + // target was known to be doing. + ( + tinted(&p.bad), + if t.err.is_empty() { + String::new() + } else { + format!(" ! {}", t.err) + }, + ), ]; // Carry the tint to the edge. Left ragged it stops wherever the // last number happens to end, and a highlight that stops short diff --git a/widgets/src/bin/ports.rs b/widgets/src/bin/ports.rs index 06561c2..e8fbb6c 100644 --- a/widgets/src/bin/ports.rs +++ b/widgets/src/bin/ports.rs @@ -2084,6 +2084,11 @@ fn footer( struct Store { rows: Mutex<Vec<Row>>, + /// Why the poller stopped, if it did. A caught panic used to be thrown + /// away here: the scan returned an empty list and the table drew as if + /// nothing were listening, which is the one thing this widget must + /// never say by accident. + err: Mutex<String>, /// What has moved on each listening port, sampled by the same poll that /// finds the ports. One `ss` call per scan rather than a second thread: /// a thread that dies is invisible, and this needs no finer resolution @@ -2131,20 +2136,43 @@ fn main() { let ok = rgb_ok(); let store = Arc::new(Store { rows: Mutex::new(Vec::new()), + err: Mutex::new(String::new()), traffic: Mutex::new(Traffic::default()), wake: (Mutex::new(false), Condvar::new()), }); let poller = Arc::clone(&store); std::thread::spawn(move || loop { // A thread that dies takes its explanation with it, so the scan is - // caught rather than left to unwind: an empty table would look - // exactly like a machine with nothing listening. - let found = std::panic::catch_unwind(scan).unwrap_or_default(); + // caught - but catching it is only half of the rule. It used to end + // in `unwrap_or_default()`, which handed the table an empty list and + // drew a machine with nothing listening. The reason goes on screen + // and the thread stops, the way usage and herdr-panes do it. + let found = match std::panic::catch_unwind(scan) { + Ok(found) => found, + Err(_) => { + let why = "poller stopped - see the pane it was started from"; + if let Ok(mut guard) = poller.err.lock() { + *guard = why.into(); + } + return; + } + }; // The ports to tally against, taken from the scan that just ran, so // a port that has just appeared is measured from its next sample // rather than never. let listening: Vec<u16> = found.iter().filter(|r| !r.gone).map(|r| r.port).collect(); - let counters = std::panic::catch_unwind(|| run(&["ss", "-tine"])).unwrap_or_default(); + let counters = match std::panic::catch_unwind(|| run(&["ss", "-tine"])) { + Ok(text) => text, + Err(_) => { + let why = "traffic poller stopped - the table below is still current"; + if let Ok(mut guard) = poller.err.lock() { + *guard = why.into(); + } + // Traffic is one column of many; the ports themselves are + // still being found, so this one says so and carries on. + String::new() + } + }; if let Ok(mut guard) = poller.rows.lock() { *guard = found; } @@ -2517,6 +2545,13 @@ fn main() { ], w - 1, )); + // A dead poller says so, right under the counts it has stopped + // updating. Same line, same shape and same words as herdr-panes and + // usage, so it reads the same wherever you meet it. + let err = store.err.lock().map(|g| g.clone()).unwrap_or_default(); + if !err.is_empty() { + rows.push(tc::seg(&[(ok.bad.as_str(), format!(" ! {}", err))], w - 1)); + } rows.push(String::new()); let wide = w >= 78; diff --git a/widgets/tests/check.rs b/widgets/tests/check.rs index 6ddd4f5..8ae0b8d 100644 --- a/widgets/tests/check.rs +++ b/widgets/tests/check.rs @@ -539,15 +539,70 @@ fn a_poller_that_dies_records_why() { if !src.contains("thread::spawn") { continue; } - let records = src.contains("err =") - || src.contains(".err =") - || src.contains("why =") - || src.contains("catch_unwind"); + // Two accidents used to satisfy this, and both were found by reading + // the widgets rather than by the check failing. + // + // `catch_unwind` on its own counted as recording a reason. It is + // not: ports caught its panic and threw the reason away with + // `unwrap_or_default()`, drawing an empty table - the exact thing + // this rule exists to prevent, under a comment saying so. + // + // And a bare `err =` matched `let mut err = dx + dy`, the Bresenham + // variable in latency's line drawing. That one accident was the + // whole reason latency passed. + // + // So a reason has to look like a reason - assigned something with + // words in it - and it has to reach a row. Recording one nobody + // draws is the same silence with more code behind it. + let reason = |line: &str| { + // A field called `err` holds a reason whatever it is assigned + // from - netwatch's `state.err = err` hands over a String built + // further up. A bare local is where the Bresenham variables + // live, so that one has to be assigned something with words in + // it. + if line.contains(".err =") || line.contains(".why =") { + return true; + } + let Some(at) = line.find("err =").or_else(|| line.find("why =")) else { + return false; + }; + let rhs = &line[at..]; + rhs.contains('"') || rhs.contains("format!") || rhs.contains("to_string") + }; + let records = src + .lines() + .any(|l| !l.trim_start().starts_with("//") && reason(l)); + // On screen, not on stderr: netwatch writes one to stderr *and* + // draws it, and only the drawn one is any use behind a full-screen + // redraw. + let drawn = src.contains("err.is_empty()") + || src.contains("&err") + || src.contains("why.is_empty()"); + // One shape is always wrong, whatever else the widget records: a + // caught panic whose reason goes straight to `unwrap_or_default()`. + // That returns an empty list and the pane draws as if the source had + // nothing in it. Checked on its own, because "the widget records a + // reason somewhere" is true of a widget with one good guard and one + // bad one - which is exactly what ports was. + for (n, line) in src.lines().enumerate() { + if line.contains("catch_unwind") && line.contains("unwrap_or_default") { + wrong.push(format!( + "{}:{}: catches a panic and throws the reason away", + name, + n + 1 + )); + } + } if !records { wrong.push(format!( "{}: spawns a poll thread with nowhere to record why it stopped", name )); + } else if !drawn { + wrong.push(format!( + "{}: records why its poller stopped and never puts it on screen", + name + )); } } assert!(wrong.is_empty(), "\n{}", wrong.join("\n")); From cbe60086466a13f8c295b75e3d081fc34434d48b Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Wed, 26 Aug 2026 04:16:49 +0800 Subject: [PATCH 117/147] four widgets: a grey you can read on a selected row `dim` at (127, 147, 172) measures 3.81 against the selected-row tint `bg(38, 56, 76)`, under the 4.5 CLAUDE.md asks for against the tint as well as the background. github, herdr-panes, linear and pr all draw it there. A lighter grey at (140, 170, 195) measures 4.94, and is used only where the tint is on, so an unselected row is exactly the colour it always was. The name is latency's, which solved this for itself a while ago; the value is not, because latency's tint is darker and its (120, 155, 180) only reaches 4.08 on this one. Each widget's lighter grey is for its own tint. The substitution happens inside the closure that composes the tint rather than at the call sites. Seventeen sites were counted when this was found and there were twenty-three by the time it was fixed - linear grew tinted rows twice this week - and more than half reach `dim` through a condition that has nothing to do with selection, `if count > 0 { loud } else { dim }`, where a zero count is the normal state. Fixed a call site at a time, the obvious half gets fixed and the common half does not. Two checks, because prose did not hold this for the length of a port. The first measures WCAG contrast for whatever is actually drawn on a tint. Its first version paired every `bg()` in a file with every grey in it and reported two widgets that were fine - one on a tint that only exists in a test fixture, the other on a tint only ever drawn with `accent`. A check that cries wolf gets turned off, so it now compares colours that meet. The second counts the substitution, because the first cannot see wiring: delete it from the closure and `dim` goes back on the tint while `dim_lit` sits in the palette measuring beautifully. Checked on screen as well as in the palette: the greys drawn on a tinted linear row are now (140, 170, 195), and the old one appears on none of them. The other three colours that reach that tint measure 7.40, 9.93 and 7.80. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- widgets/src/bin/github.rs | 34 +++++++++- widgets/src/bin/herdr-panes.rs | 43 ++++++++++++- widgets/src/bin/linear.rs | 43 ++++++++++++- widgets/src/bin/pr.rs | 34 +++++++++- widgets/tests/check.rs | 114 +++++++++++++++++++++++++++++++++ 5 files changed, 258 insertions(+), 10 deletions(-) diff --git a/widgets/src/bin/github.rs b/widgets/src/bin/github.rs index 4f0ce57..1594909 100644 --- a/widgets/src/bin/github.rs +++ b/widgets/src/bin/github.rs @@ -355,7 +355,14 @@ fn account_detail( title }; let tint = if here { tc::bg(38, 56, 76) } else { String::new() }; - let c = |colour: &str| format!("{}{}", tint, colour); + let c = |colour: &str| { + let colour = if tint.is_empty() || colour != p.dim { + colour + } else { + p.dim_lit.as_str() + }; + format!("{}{}", tint, colour) + }; rows.push(tc::seg( &[ ( @@ -784,6 +791,21 @@ struct Palette { warn: String, bad: String, dim: String, + /// A colour to draw over the selected-row tint. + /// + /// `dim` is 3.81 against `bg(38, 56, 76)`, under the 4.5 CLAUDE.md asks for + /// against the tint as well as the background. This is the same grey lifted + /// until it clears - 4.94 - and it is used *only* where the tint is on, so + /// an unselected row is exactly the colour it always was. + /// + /// The substitution happens inside the closure that composes the tint, not + /// at each call site. Seventeen sites were counted when this was found and + /// there were twenty-three by the time it was fixed; more than half of them + /// reach `dim` through a condition that has nothing to do with selection - + /// `if count > 0 { loud } else { dim }` - and a zero count is the normal + /// state, so those are the common case rather than the rare one. Anyone + /// fixing this a call site at a time would fix the obvious half. + dim_lit: String, grid: String, txt: String, lbl: String, @@ -797,6 +819,7 @@ fn palette() -> Palette { warn: tc::rgb(255, 200, 90), bad: tc::rgb(255, 100, 110), dim: tc::rgb(127, 147, 172), + dim_lit: tc::rgb(140, 170, 195), grid: tc::rgb(60, 78, 98), txt: tc::rgb(225, 235, 245), lbl: tc::rgb(130, 165, 200), @@ -1701,7 +1724,14 @@ fn main() { for (i, s) in stats.iter().enumerate().skip(first).take(room) { let here = i == selected; let tint = if here { tc::bg(38, 56, 76) } else { String::new() }; - let c = |colour: &str| format!("{}{}", tint, colour); + let c = |colour: &str| { + let colour = if tint.is_empty() || colour != p.dim { + colour + } else { + p.dim_lit.as_str() + }; + format!("{}{}", tint, colour) + }; // This row's own staleness: accounts land one at a time, so an // account already refetched for the new window shows real numbers // while the ones behind it still shimmer. diff --git a/widgets/src/bin/herdr-panes.rs b/widgets/src/bin/herdr-panes.rs index de3c658..2a403e7 100644 --- a/widgets/src/bin/herdr-panes.rs +++ b/widgets/src/bin/herdr-panes.rs @@ -459,6 +459,21 @@ struct Palette { idle: String, unknown: String, dim: String, + /// A colour to draw over the selected-row tint. + /// + /// `dim` is 3.81 against `bg(38, 56, 76)`, under the 4.5 CLAUDE.md asks for + /// against the tint as well as the background. This is the same grey lifted + /// until it clears - 4.94 - and it is used *only* where the tint is on, so + /// an unselected row is exactly the colour it always was. + /// + /// The substitution happens inside the closure that composes the tint, not + /// at each call site. Seventeen sites were counted when this was found and + /// there were twenty-three by the time it was fixed; more than half of them + /// reach `dim` through a condition that has nothing to do with selection - + /// `if count > 0 { loud } else { dim }` - and a zero count is the normal + /// state, so those are the common case rather than the rare one. Anyone + /// fixing this a call site at a time would fix the obvious half. + dim_lit: String, txt: String, lbl: String, accent: String, @@ -474,6 +489,7 @@ fn palette() -> Palette { idle: tc::rgb(128, 148, 172), unknown: tc::rgb(150, 150, 165), dim: tc::rgb(127, 147, 172), + dim_lit: tc::rgb(140, 170, 195), txt: tc::rgb(225, 235, 245), lbl: tc::rgb(130, 165, 200), accent: tc::rgb(150, 210, 255), @@ -822,7 +838,14 @@ fn main() { } else { String::new() }; - let c = |colour: &str| format!("{}{}", tint, colour); + let c = |colour: &str| { + let colour = if tint.is_empty() || colour != p.dim { + colour + } else { + p.dim_lit.as_str() + }; + format!("{}{}", tint, colour) + }; let name: String = a.name.chars().take(6).collect(); let state_cell = if loud { a.state.to_uppercase() @@ -919,7 +942,14 @@ fn main() { } let here = agents.len() + j == selected; let tint = if here { tc::bg(38, 56, 76) } else { String::new() }; - let c = |colour: &str| format!("{}{}", tint, colour); + let c = |colour: &str| { + let colour = if tint.is_empty() || colour != p.dim { + colour + } else { + p.dim_lit.as_str() + }; + format!("{}{}", tint, colour) + }; let heat = match n.cpu { Some(v) if v > 0.0 => tc::heat((v / 100.0).min(1.0)), _ => p.dim.clone(), @@ -984,7 +1014,14 @@ fn main() { } let here = agents.len() + running.len() + j == selected; let tint = if here { tc::bg(38, 56, 76) } else { String::new() }; - let c = |colour: &str| format!("{}{}", tint, colour); + let c = |colour: &str| { + let colour = if tint.is_empty() || colour != p.dim { + colour + } else { + p.dim_lit.as_str() + }; + format!("{}{}", tint, colour) + }; let place = if show_labels { let label = labels.get(&n.workspace_id).cloned().unwrap_or_default(); if label.is_empty() { n.workspace_id.clone() } else { label } diff --git a/widgets/src/bin/linear.rs b/widgets/src/bin/linear.rs index 812492b..b097fa9 100644 --- a/widgets/src/bin/linear.rs +++ b/widgets/src/bin/linear.rs @@ -796,6 +796,21 @@ struct Palette { warn: String, bad: String, dim: String, + /// A colour to draw over the selected-row tint. + /// + /// `dim` is 3.81 against `bg(38, 56, 76)`, under the 4.5 CLAUDE.md asks for + /// against the tint as well as the background. This is the same grey lifted + /// until it clears - 4.94 - and it is used *only* where the tint is on, so + /// an unselected row is exactly the colour it always was. + /// + /// The substitution happens inside the closure that composes the tint, not + /// at each call site. Seventeen sites were counted when this was found and + /// there were twenty-three by the time it was fixed; more than half of them + /// reach `dim` through a condition that has nothing to do with selection - + /// `if count > 0 { loud } else { dim }` - and a zero count is the normal + /// state, so those are the common case rather than the rare one. Anyone + /// fixing this a call site at a time would fix the obvious half. + dim_lit: String, grid: String, txt: String, lbl: String, @@ -813,6 +828,7 @@ fn palette() -> Palette { warn: tc::rgb(255, 200, 90), bad: tc::rgb(255, 100, 110), dim: tc::rgb(127, 147, 172), + dim_lit: tc::rgb(140, 170, 195), grid: tc::rgb(60, 78, 98), txt: tc::rgb(225, 235, 245), lbl: tc::rgb(130, 165, 200), @@ -2239,7 +2255,14 @@ fn main() { ); let on = focus == Some(cycles_pane) && ci == sel[cycles_pane]; let tint = if on { tc::bg(38, 56, 76) } else { String::new() }; - let c_of = |colour: &str| format!("{}{}", tint, colour); + let c_of = |colour: &str| { + let colour = if tint.is_empty() || colour != p.dim { + colour + } else { + p.dim_lit.as_str() + }; + format!("{}{}", tint, colour) + }; let hot = tc::heat(frac); let mut line = vec![ ( @@ -2488,7 +2511,14 @@ fn main() { let count = |k: &str| c.get(k).copied().unwrap_or(0); let here = on_teams && i == sel[teams_pane]; let tint = if here { tc::bg(38, 56, 76) } else { String::new() }; - let c_of = |colour: &str| format!("{}{}", tint, colour); + let c_of = |colour: &str| { + let colour = if tint.is_empty() || colour != p.dim { + colour + } else { + p.dim_lit.as_str() + }; + format!("{}{}", tint, colour) + }; let mut line = vec![ ( c_of(if here { &p.accent } else { &p.txt }), @@ -2597,7 +2627,14 @@ fn main() { cursor = Some(rows.len()); } let tint = if here { tc::bg(38, 56, 76) } else { String::new() }; - let c_of = |colour: &str| format!("{}{}", tint, colour); + let c_of = |colour: &str| { + let colour = if tint.is_empty() || colour != p.dim { + colour + } else { + p.dim_lit.as_str() + }; + format!("{}{}", tint, colour) + }; let colour = match q.kind.as_str() { "started" => p.warn.as_str(), _ => p.txt.as_str(), diff --git a/widgets/src/bin/pr.rs b/widgets/src/bin/pr.rs index 0d0c86e..a72a1ef 100644 --- a/widgets/src/bin/pr.rs +++ b/widgets/src/bin/pr.rs @@ -524,6 +524,21 @@ struct Palette { warn: String, bad: String, dim: String, + /// A colour to draw over the selected-row tint. + /// + /// `dim` is 3.81 against `bg(38, 56, 76)`, under the 4.5 CLAUDE.md asks for + /// against the tint as well as the background. This is the same grey lifted + /// until it clears - 4.94 - and it is used *only* where the tint is on, so + /// an unselected row is exactly the colour it always was. + /// + /// The substitution happens inside the closure that composes the tint, not + /// at each call site. Seventeen sites were counted when this was found and + /// there were twenty-three by the time it was fixed; more than half of them + /// reach `dim` through a condition that has nothing to do with selection - + /// `if count > 0 { loud } else { dim }` - and a zero count is the normal + /// state, so those are the common case rather than the rare one. Anyone + /// fixing this a call site at a time would fix the obvious half. + dim_lit: String, grid: String, txt: String, lbl: String, @@ -537,6 +552,7 @@ fn palette() -> Palette { warn: tc::rgb(255, 200, 90), bad: tc::rgb(255, 100, 110), dim: tc::rgb(127, 147, 172), + dim_lit: tc::rgb(140, 170, 195), grid: tc::rgb(60, 78, 98), txt: tc::rgb(225, 235, 245), lbl: tc::rgb(130, 165, 200), @@ -1492,7 +1508,14 @@ fn list_view( for (i, pr) in prs.iter().enumerate().skip(first).take(room) { let here = i == selected; let tint = if here { tc::bg(38, 56, 76) } else { String::new() }; - let c = |colour: &str| format!("{}{}", tint, colour); + let c = |colour: &str| { + let colour = if tint.is_empty() || colour != p.dim { + colour + } else { + p.dim_lit.as_str() + }; + format!("{}{}", tint, colour) + }; let (rlabel, rcol) = review_label(&text(pr, "reviewDecision"), p); let (clabel, ccol) = check_label(&rollup(pr), p); let stacked = !pr["stackEntry"].is_null(); @@ -1959,7 +1982,14 @@ fn detail_view( }; let on_cursor = idx == stack_sel; let tint = if on_cursor { tc::bg(38, 56, 76) } else { String::new() }; - let c = |colour: &str| format!("{}{}", tint, colour); + let c = |colour: &str| { + let colour = if tint.is_empty() || colour != p.dim { + colour + } else { + p.dim_lit.as_str() + }; + format!("{}{}", tint, colour) + }; let mut name = text(node, "title"); if let Some(pos) = position { name = format!("{}. {}", pos, name); diff --git a/widgets/tests/check.rs b/widgets/tests/check.rs index 8ae0b8d..2ad6b36 100644 --- a/widgets/tests/check.rs +++ b/widgets/tests/check.rs @@ -528,6 +528,120 @@ fn every_key_the_help_text_names_is_answered() { assert!(wrong.is_empty(), "\n{}", wrong.join("\n")); } +fn luminance(rgb: (f64, f64, f64)) -> f64 { + let ch = |c: f64| { + let c = c / 255.0; + if c <= 0.04045 { c / 12.92 } else { ((c + 0.055) / 1.055).powf(2.4) } + }; + 0.2126 * ch(rgb.0) + 0.7152 * ch(rgb.1) + 0.0722 * ch(rgb.2) +} + +fn contrast(a: (f64, f64, f64), b: (f64, f64, f64)) -> f64 { + let (x, y) = (luminance(a), luminance(b)); + (x.max(y) + 0.05) / (x.min(y) + 0.05) +} + +/// The three numbers in the first `call(r, g, b)` on a line. +fn triple(line: &str, call: &str) -> Option<(f64, f64, f64)> { + let at = line.find(call)?; + let open = line[at..].find('(')? + at; + let close = line[open..].find(')')? + open; + let n: Vec<f64> = line[open + 1..close] + .split(',') + .filter_map(|x| x.trim().parse().ok()) + .collect(); + (n.len() == 3).then(|| (n[0], n[1], n[2])) +} + +/// Text drawn over a selection tint has to clear AA against the tint, not +/// only against the terminal's own background. +/// +/// CLAUDE.md has asked for this in prose since before the port, and it went +/// unmet in four widgets for as long as there were four widgets: `dim` at +/// (127, 147, 172) measures 3.81 on `bg(38, 56, 76)`. The count of places it +/// reached a tinted row grew from seventeen to twenty-three while that sat +/// open, which is what prose costs. +/// +/// Only colours that actually meet are compared. The first version of this +/// paired every `bg()` in a file with every grey in it and reported two +/// widgets that were fine - one of them on a tint that exists in a test +/// fixture, the other on a tint only ever drawn with `accent`. A check that +/// cries wolf gets turned off. +#[test] +fn text_on_a_selection_tint_clears_aa() { + let mut wrong = Vec::new(); + for (name, whole) in widgets() { + // Fixtures are not the screen. + let src = whole.split("#[cfg(test)]").next().unwrap_or("").to_string(); + let mut greys: BTreeMap<String, (f64, f64, f64)> = BTreeMap::new(); + for line in src.lines() { + for field in ["dim", "dim_lit"] { + if line.trim_start().starts_with(&format!("{}: tc::rgb", field)) { + if let Some(c) = triple(line, "tc::rgb") { + greys.insert(field.to_string(), c); + } + } + } + } + // What each tint is composed with, one line at a time. + for line in src.lines() { + let Some(tint) = triple(line, "tc::bg") else { continue }; + // Composed inline with a named colour: that exact pair. + let named: Vec<&str> = ["dim_lit", "dim", "accent", "txt"] + .into_iter() + .filter(|f| line.contains(&format!("p.{}", f))) + .collect(); + // Or assigned to `tint` and composed later, where the greys are + // what reach it - the lighter one when the widget has it. + let reached: Vec<String> = if line.contains("tint") && named.is_empty() { + greys + .contains_key("dim_lit") + .then(|| vec!["dim_lit".to_string()]) + .unwrap_or_else(|| greys.keys().cloned().collect()) + } else { + named.into_iter().map(str::to_string).collect() + }; + for field in reached { + let Some(&c) = greys.get(&field) else { continue }; + let r = contrast(c, tint); + if r < 4.5 { + wrong.push(format!( + "{}: {} {:?} on tint {:?} measures {:.2}, under AA 4.5", + name, field, c, tint, r + )); + } + } + } + } + assert!(wrong.is_empty(), "on the selected-row tint:\n{}", wrong.join("\n")); +} + +/// A widget with a lighter grey has to actually reach for it. +/// +/// The check above measures the colour and cannot see the wiring: delete the +/// substitution inside the tint closure and `dim` goes back on the tint while +/// `dim_lit` sits in the palette measuring beautifully. So the substitution +/// is counted instead - once per closure that composes a tint. +#[test] +fn a_widget_with_a_lighter_grey_uses_it_on_every_tint() { + let mut wrong = Vec::new(); + for (name, whole) in widgets() { + let src = whole.split("#[cfg(test)]").next().unwrap_or("").to_string(); + if !src.contains("dim_lit: tc::rgb") { + continue; + } + let closures = src.matches("format!(\"{}{}\", tint, colour)").count(); + let swaps = src.matches("dim_lit.as_str()").count() + src.matches("&p.dim_lit").count(); + if swaps < closures { + wrong.push(format!( + "{}: {} tint closures but {} reach for dim_lit", + name, closures, swaps + )); + } + } + assert!(wrong.is_empty(), "a lighter grey nobody draws:\n{}", wrong.join("\n")); +} + #[test] fn a_poller_that_dies_records_why() { // CLAUDE.md's central gotcha: a thread that stops takes its From 8b3f87c3551174176c999393d396cc0b39308135 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Wed, 26 Aug 2026 04:28:59 +0800 Subject: [PATCH 118/147] docs: README and AGENTS.md against the tree as it is Both had drifted across a long session and a migration. Corrected against the sources rather than against memory; the notable ones: `braille_plot()` was in the README's list of what the shared core holds. It does not exist and never has in the Rust - latency and link each carry a private `braille_canvas`, and the two do not even share a signature. A reader reaching for it would have found nothing. The config paragraph still described where the Python looked. The Needs column named three external tools where there are five, and omitted `curl` from the four widgets that refuse to start without it - checked by finding `missing(&["curl"])` in each rather than by assuming. AGENTS.md's "Before you commit" listed five of the ten checks `check.rs` now runs. The five missing ones are there with the reasons the file's own comments give, including that the contrast check compares only colours that actually meet, because its first version cried wolf. Four widget rows in the README table describe features added since they were written: deployments' build log, github's per-account screen, linear's three drill-in screens, ports' traffic. Left alone deliberately: the Python-era gotchas in AGENTS.md, which read as paid-for history rather than as instructions. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- AGENTS.md | 60 +++++++++++++++++++++++++++++++++++++++++------------ README.md | 62 +++++++++++++++++++++++++++++++++---------------------- 2 files changed, 84 insertions(+), 38 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index da7b5ec..1940ca6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -30,9 +30,9 @@ than faked. `matrix` is the sole exception and computes nothing on purpose. shows only libc, libm and libgcc. Keep it that way: a crate that wants a system library at run time is the one kind that cannot come in. If a widget needs an external *tool* - (`ping`, `tailscale`, `herdr`) it degrades gracefully when that tool is - absent - that is a different thing from a library and the rule is - unchanged. + (`curl`, `ss`, `ping`, `tailscale`, `herdr`) it says so and stops, or goes + on without what that tool would have told it - that is a different thing + from a library and the rule is unchanged. - **Config, never hardcoded.** Hostnames, cities, tokens and account lists go in `config.json` (git-ignored) via `load_config()`. Add new keys to `config.example.json` in the same commit — and **use the section name the @@ -66,9 +66,30 @@ screen, exactly like "there is no data": - **a footer hint naming a key no match arm answers** — a hint bound to nothing says the feature is there; - **a footer hint missing from the widget's doc**; +- **a key the `--help` text names that nothing answers** — `--help` is where + someone looks when the footer was not enough, and until this check went in + nothing read those files at all; - **a config key a widget reads that is not in `config.example.json`** — an undiscoverable setting is not a setting; -- **a section in the example no widget reads**. +- **a section in the example no widget reads**, and separately **a key in the + example the widget never reads** — checking the section alone passes a + widget that reads three of its four keys and ignores the fourth; +- **a bare `cfg.get()` with no fallback in the same statement** — `cfg_f64` + and its siblings take a default by signature, so they cannot go wrong; a + raw `get()` can, and then a key deleted from `config.json` lands on zero or + on a panic instead of on the widget's own default; +- **text on the selected-row tint measuring under AA 4.5** — the convention + above, which was prose here from before the port and went unmet in four + widgets for as long as there were four widgets. The number of places + the failing grey reached a tinted row grew from seventeen to twenty-three + while it sat open, which is what prose costs. Only colours that actually + meet are compared: the first version paired every tint in a file with every + grey in it and flagged two widgets that were fine; +- **a widget that defines a lighter grey and never reaches for it** — the + contrast check measures the colour and cannot see the wiring. Delete the + substitution inside the tint closure and the light grey sits in the palette + measuring beautifully while the dark one goes back on the tint, so the + substitutions are counted instead, one per closure that composes a tint. The hint reader sees `[k]` wherever it falls, four rules keeping `[{}]`, `[::1]`, `[[bin]]` and `args[0]` out; the glyphs `↵ → ← ↑ ↓`; the names @@ -82,6 +103,13 @@ have been wrong before — three versions of this check cried wolf in one day, and a checker that cries wolf gets turned off — so when it fires, read the flag before believing it, and when it is quiet, that is not proof. +The help reader is cruder still and admits it. Only two shapes count, a +letter right after `press` and a letter right before a verb, because reading +every single letter took the `a` out of "with a longer" and reported a key +called `a`. So in `Enter, i or c opens`, only `c` touches the verb and a +stale `i` beside it goes unseen — catching one of the two still lands the +reader in the right sentence. + `check.py` covered the same ground for the Python, plus unbound names - which the compiler now makes impossible. It went with the Python. @@ -138,17 +166,23 @@ which the compiler now makes impossible. It went with the Python. ## Layout of the code `toys-core` holds everything shared: terminal sizing, full-frame `draw()`, -24-bit `rgb()`, `seg()` for clipping coloured segments to a cell budget, -`pack_hints()`, `follow()` for a window that keeps a cursor in view, bar -and chart helpers (`vbars`, `vbars_down`, `braille_plot`, -`stacked_bar`, `meter`, `skeleton`), `config_token_warning()` for -widgets holding a secret, non-blocking `Keyboard`, and OSC 52 -`clipboard()`. +24-bit `rgb()` and the green→amber→red `heat()` ramp, `seg()` for clipping +coloured segments to a cell budget, `pack_hints()`, `follow()` for a window +that keeps a cursor in view, bar and chart helpers (`vbars`, `vbars_down`, +`stacked_bar`, `meter`, `skeleton`), `get()` and `post_json()` over `curl`, +`config_token_warning()` for widgets holding a secret, non-blocking +`Keyboard`, and OSC 52 `clipboard()`. + +Braille line charts are not in there. `latency` and `link` each keep their +own `braille_canvas`, and the two are not the same function: latency's series +carries the gaps a ping can leave, link's is told how many slots the axis +holds. Copy from whichever is closer rather than expecting core to have one. `docs/port-decisions.md` records what the port changed from the Python and -why - the keys it consolidated, the two it renamed, the charts it draws -differently. It is history rather than a comparison now, and it is the answer -to most questions beginning *why does this key do that*. +why - the keys it consolidated, the three it renamed, the charts it draws +differently, and what was built afterwards on the Rust side alone. It is +history rather than a comparison now, and it is the answer to most questions +beginning *why does this key do that*. `docs/building-herdr-panels.md` records what was learned driving these from Herdr: resize semantics, focus, and the layout mistakes worth skipping. diff --git a/README.md b/README.md index 2d5d642..7a3fe16 100644 --- a/README.md +++ b/README.md @@ -35,23 +35,23 @@ nothing at all — it just looks good, and it knows it. |---|---|---|---| | **`start`** | The front door: every widget, what it does, and whether it will work on this machine — pick one and it runs, quit it and you are back. | — | [read →](docs/start.md) | | **`latency`** | Continuous latency to a list of hosts: median, jitter, loss and a log-scale graph, so a slow link and an *unsteady* one look different. | `ping` | [read →](docs/latency.md) | -| **`deployments`** | Vercel deployments over time — activity per hour, build-time drift, and a copy sheet for the dashboard, preview and PR URLs. | a Vercel token | [read →](docs/deployments.md) | +| **`deployments`** | Vercel deployments over time — activity per hour, build-time drift, and the build log of the one you open, so a failure explains itself instead of only naming a code. A copy page carries the dashboard, preview and PR URLs. | `curl`, a Vercel token | [read →](docs/deployments.md) | | **`tailnet`** | Tailscale peers, and whether each is reached directly or through a relay. Live throughput, full machine info, copyable addresses. | `tailscale` | [read →](docs/tailnet.md) | | **`herdr-panes`** | Every agent and process across all workspaces, ordered by which one needs a human. Enter jumps you there. | `herdr` | [read →](docs/herdr-panes.md) | -| **`github`** | Pull requests across every org: merge rate, opened-vs-merged per day, review backlog and the contribution calendar. | a GitHub token | [read →](docs/github.md) | -| **`pr`** | The pull requests you have to follow up on: checks, reviews, mergeability, and a stack map with the order a stack has to merge in. | a GitHub token | [read →](docs/pr.md) | -| **`linear`** | Linear across every team: what is outstanding, the running cycles and their scope creep, and issues created against completed. | a Linear API key | [read →](docs/linear.md) | +| **`github`** | Pull requests across every org: merge rate, opened-vs-merged per day, review backlog and the contribution calendar — and `↵` for one account on a screen of its own, because a queue growing in one of them is invisible in a total the others are also feeding. | `curl`, a GitHub token | [read →](docs/github.md) | +| **`pr`** | The pull requests you have to follow up on: checks, reviews, mergeability, and a stack map with the order a stack has to merge in. | `curl`, a GitHub token | [read →](docs/pr.md) | +| **`linear`** | Linear across every team: what is outstanding, the running cycles and their scope creep, issues created against completed, and every project still going. `↵` opens a cycle, a team or a project on a screen of its own. | `curl`, a Linear API key | [read →](docs/linear.md) | | **`usage`** | How much each coding agent on the machine has been used — tokens, sessions, AI-written code — and what is left of each one's rate limit, one tab per agent. | the agents' own logins | [read →](docs/usage.md) | -| **`ports`** | What is listening on this machine — the dev servers you have running, which project each was started from, how long it has been up, and whether anything outside the box can reach it. `k` stops the selected one; `↵` opens it to copy an address or publish it over Tailscale or Cloudflare. | — | [read →](docs/ports.md) | +| **`ports`** | What is listening on this machine — the dev servers you have running, which project each was started from, how long it has been up, how much traffic it is carrying, and whether anything outside the box can reach it. `k` stops the selected one; `↵` opens it for a traffic chart, an address to copy, or a publish over Tailscale or Cloudflare. | `ss` for the traffic | [read →](docs/ports.md) | | **`netwatch`** | Which processes are using the network — total since it started, current rate, up and down, per process — read from the kernel's own per-socket counters rather than by capturing packets. | `ss` | [read →](docs/netwatch.md) | | **`link`** | How good the connection is between this machine and whoever is connected to it — round-trip time, jitter, loss and achieved rate for every inbound session, read from the kernel rather than probed. | `ss` | [read →](docs/link.md) | | **`clocks`** | Server clock, countdowns to the next hour / end of office hours / end of day, a pomodoro, and a world clock. | — | [read →](docs/clocks.md) | | **`matrix`** | Nothing whatsoever. Digital rain, with truecolor fade trails. | — | — | -Each is a single self-contained binary — everything it needs is compiled in, -`ldd` shows only libc, libm and libgcc, and there is nothing to install -alongside. 24-bit colour, and a full redraw each frame so everything reflows -when you resize the pane. +Each is a single self-contained binary — every library it needs is compiled +in, `ldd` shows only libc, libm and libgcc, and there is nothing to install +alongside it. 24-bit colour, and a full redraw each frame so everything +reflows when you resize the pane. ```sh cargo build --release # fourteen binaries in ./target/release @@ -91,9 +91,11 @@ widget in a 30-column strip still says something useful. ## Configuration -Every widget reads optional settings from the first of -`$TERMINAL_TOYS_CONFIG`, `~/.config/terminal-toys/config.json`, or -`config.json` beside the scripts. Copy `config.example.json` to start. +Every widget reads optional settings from the first readable of +`$TERMINAL_TOYS_CONFIG`, `$XDG_CONFIG_HOME/terminal-toys/config.json` +(`~/.config/terminal-toys/config.json` where that is unset), `config.json` in +the working directory, and `config.json` beside the binary. Copy +`config.example.json` to start. This keeps hostnames, ping targets, city lists and tokens out of the source tree: the repo ships generic defaults, and `config.json` is git-ignored along @@ -108,11 +110,13 @@ configuration at all. ## Requirements -- A Rust toolchain to build; **nothing** to run. The binaries carry what - they need, SQLite included +- A Rust toolchain to build; **no library to install** to run — the binaries + carry what they link against, SQLite included - A terminal with 24-bit colour -- Per-widget: `ping`, `tailscale` or `herdr` as listed above. Each needs only - its own, and **none needs root** +- Per-widget, the external *tools* the table above names: `curl`, `ss`, + `ping`, `tailscale`, `herdr`. Each widget needs only its own; one that + cannot work without its tool says so rather than drawing an empty pane; and + **none needs root** ## Design @@ -168,15 +172,18 @@ skipping. These began as Python and were ported to Rust widget by widget; [`docs/port-decisions.md`](docs/port-decisions.md) records what the port -changed and why — the keys it consolidated, the two it renamed, the charts it -draws differently. It is history now rather than a comparison, but it is the -answer to most questions beginning *why does this key do that*. +changed and why — the keys it consolidated, the three it renamed, the charts +it draws differently, and what was built afterwards on the Rust side alone. It +is history now rather than a comparison, but it is the answer to most +questions beginning *why does this key do that*. `cargo test` from the root runs each widget's tests plus `widgets/tests/check.rs`, which reads the sources and fails on a poller that -dies without saying why, a footer hint naming a key nothing answers, a hint -missing from the widget's doc, and a config key read but never documented in -`config.example.json`. +dies without saying why, a footer or `--help` line naming a key nothing +answers, a hint missing from the widget's doc, a config key read but never +documented in `config.example.json` — or documented there and never read, or +read with no fallback behind it — and a colour that draws text on the +selected-row tint below WCAG AA. `toys-core` holds the shared pieces — terminal sizing, a full-frame `draw()`, 24-bit colour, a green→amber→red `heat()` ramp, `seg()` for clipping coloured @@ -186,9 +193,14 @@ arrow-key decoding, and `clipboard()` over OSC 52. The chart helpers are worth knowing before drawing anything new: `vbars()` and its mirror `vbars_down()` (pair them on a shared scale for a diverging chart), -`braille_plot()` for continuous lines at 2×4 sub-pixels a cell, `stacked_bar()` -for proportions, `meter()` for a gauge, and `skeleton()` for the shimmer that -stands in for a figure still being fetched. +`stacked_bar()` for proportions, `meter()` for a gauge, and `skeleton()` for +the shimmer that stands in for a figure still being fetched. + +Braille line charts are not among them. `latency` and `link` each keep their +own `braille_canvas`, and the two are not the same function: latency's series +carries the gaps a ping can leave, and link's is told how many slots the axis +holds, so that a session younger than the chart takes its own share of the +width rather than being stretched across all of it. ## License From 661b16552f30df7ba4d23cf2bfee12bf6969f0f9 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Wed, 26 Aug 2026 04:29:36 +0800 Subject: [PATCH 119/147] release: a tag builds it, names it, and says what changed TOY-39, Linux only. Apple Silicon is TOY-40 and needs a runner this does not. Every binary answers --version with the version, the commit it was built from, and that commit's date. The version alone identifies nothing useful: it changes at a release and almost every binary anybody runs is between two. netwatch used to answer this itself and said "netwatch 1.1" while the workspace was at 0.1.0 - a number nothing set and nobody maintained. It is answered in `maybe_help` now, beside --help, so fourteen binaries cannot disagree about how to say it. The commit and the date come from a build script, because neither is knowable from source. Any of the three may read "unknown": built from a tarball with no .git, that is the honest answer and not a build failure. The sha carries "-dirty" when the tree had uncommitted changes under it, because a sha alone says which commit was checked out rather than which source was compiled. The date prefers SOURCE_DATE_EPOCH, then the commit's own date, and never the wall clock - the first two make two builds of the same source agree, and the third makes every build differ for no reader's benefit. The workflow does not rewrite the source it is building. The tag and the manifest are checked against each other and the build stops if they disagree, rather than the manifest being edited to match: a build that edits its own source produces a binary no checkout can reproduce. Three gates, each for something that has gone wrong or would go unnoticed: `panic = "unwind"` is still set, and RUSTFLAGS is empty. Under "abort" the catch_unwind arms in three widgets are unreachable and the source reads as protected while the binary is not. It shipped that way once. `ldd` on every binary shows nothing beyond the C runtime. rusqlite is taken with `bundled` so SQLite is compiled in, and the promise is that nothing needs installing alongside. Checked rather than asserted, because a crate that started wanting a system library would otherwise ship quietly. Run locally against the real binaries: passes, and narrowing the allowlist makes it report, so it is not vacuous. The runner is pinned to 22.04 rather than -latest. The oldest glibc a binary runs on is the one it was built against, which is a decision rather than something to inherit from whatever the image became this month. The changelog groups by the part of a subject before the colon, because that is the only structure three hundred prose subjects have, and because "what changed in ports" is the question a changelog for fourteen separate binaries gets asked. A prefix only counts if it names a real widget or area: early history has subjects like "Add agents.py: every coding agent", where that part is the start of a sentence, and taken at face value they made forty-seven sections out of three hundred commits. The widget list is read from the tree, so a new widget is a scope the day it lands. A subject naming two widgets is listed under both. Run against the real history, which is also the first-release path since there are no tags: 314 commits, 19 sections, 320 entries. Not proven here, and cannot be: pushing a tag is what runs this, and doing that would cut a real release. The first tag is the live test. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- .github/changelog.sh | 69 +++++++++++++++++++++ .github/workflows/release.yml | 109 ++++++++++++++++++++++++++++++++++ .gitignore | 6 ++ core/build.rs | 72 ++++++++++++++++++++++ core/src/lib.rs | 36 +++++++++++ widgets/src/bin/netwatch.rs | 4 -- 6 files changed, 292 insertions(+), 4 deletions(-) create mode 100755 .github/changelog.sh create mode 100644 .github/workflows/release.yml create mode 100644 core/build.rs diff --git a/.github/changelog.sh b/.github/changelog.sh new file mode 100755 index 0000000..efc3df7 --- /dev/null +++ b/.github/changelog.sh @@ -0,0 +1,69 @@ +#!/usr/bin/env bash +# Build a changelog for one release, from the commit subjects between two +# tags. +# +# The subjects here are prose, not conventional commits - "netwatch: every +# rate read a quarter too high" rather than "fix(netwatch): ...". There is no +# type to group by and inventing one would mean rewriting three hundred +# subjects. What every subject does carry is the part before the first colon, +# which is the widget or the area it touched, so that is the grouping: a +# reader asking "what changed in ports" gets an answer, which is the question +# a changelog for fourteen separate binaries is actually asked. +# +# A prefix only counts as a scope if it names something real - a widget in +# widgets/src/bin, or one of the areas below. Early history has subjects like +# "Add agents.py: every coding agent", where the part before the colon is the +# start of a sentence rather than a scope; taken at face value those made +# forty-seven sections out of three hundred commits. The widget list is read +# from the tree rather than written down here, so a new widget is a scope the +# day it lands. +# +# Usage: changelog.sh <tag> [previous-tag] +# With no previous tag it takes the whole history, which is what the first +# release needs and what it will get, there being no tags yet. +set -euo pipefail + +here=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd) +tag="${1:?usage: changelog.sh <tag> [previous-tag]}" +prev="${2:-}" + +if [ -z "$prev" ]; then + prev=$(git describe --tags --abbrev=0 "${tag}^" 2>/dev/null || true) +fi +if [ -n "$prev" ]; then + range="${prev}..${tag}" + since="since ${prev}" +else + range="$tag" + since="everything so far" +fi + +# Every widget, plus the places that are not one. +scopes=$( + { ls "$here/widgets/src/bin" 2>/dev/null | sed -n 's/\.rs$//p' + printf '%s\n' core widgets docs tests ci rust release + } | sort -u +) + +printf '## %s\n\n' "$tag" +printf '%s commits, %s.\n\n' "$(git log --oneline "$range" | wc -l | tr -d ' ')" "$since" + +git log --format='%s' "$range" | awk -v known="$scopes" -F': ' ' + BEGIN { n = split(known, k, "\n"); for (i = 1; i <= n; i++) if (k[i] != "") is[k[i]] = 1 } + { + if (NF < 2) { print "everything else\t" $0; next } + scope = $1 + rest = substr($0, length(scope) + 3) + n = split(scope, parts, /, */) + # Every part has to be a real scope. "linear, netwatch" is two + # widgets; "Add agents.py" is a sentence that happens to contain a + # comma-free prefix and belongs whole, under everything else. + good = (n > 0) + for (i = 1; i <= n; i++) if (!(parts[i] in is)) good = 0 + if (!good) { print "everything else\t" $0; next } + for (i = 1; i <= n; i++) print parts[i] "\t" rest + } +' | sort -f -t"$(printf '\t')" -k1,1 | awk -F'\t' ' + $1 != seen { if (seen != "") printf "\n"; printf "### %s\n\n", $1; seen = $1 } + { printf "- %s\n", $2 } +' diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..7ec6a5d --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,109 @@ +# A tag produces a release: fourteen Linux binaries, their checksums, and a +# changelog built from the commit subjects since the last tag. +# +# Nothing here rewrites the source it is building. The version in Cargo.toml +# and the tag are checked against each other and the build stops if they +# disagree, rather than the workflow editing the manifest to make them match +# - a build that edits its own source produces a binary no checkout can +# reproduce, which is a strange thing to hand somebody. +name: release + +on: + push: + tags: ['v*'] + +permissions: + contents: write + +jobs: + linux: + # Pinned, not `-latest`. The oldest glibc a binary runs on is the one it + # was built against, so that is a decision rather than something to + # inherit from whatever the runner image became this month. 22.04 is + # glibc 2.35. + runs-on: ubuntu-22.04 + steps: + - uses: actions/checkout@v4 + with: + # The changelog reads the history between two tags, and the build + # stamps the commit into --version. A shallow clone has neither. + fetch-depth: 0 + + - uses: dtolnay/rust-toolchain@stable + + - name: The tag and the manifest must agree + run: | + tag="${GITHUB_REF_NAME#v}" + manifest=$(sed -n 's/^version = "\(.*\)"/\1/p' Cargo.toml | head -1) + if [ "$tag" != "$manifest" ]; then + echo "tag v$tag but Cargo.toml says $manifest" >&2 + echo "bump the manifest and tag that commit, rather than having" >&2 + echo "this workflow rewrite the source it is building" >&2 + exit 1 + fi + echo "v$tag" + + - name: The release profile still unwinds + run: | + # Three widgets wrap their poll thread in catch_unwind and record + # why it stopped. Under panic = "abort" those arms are unreachable + # and the source reads as protected while the binary is not - it + # was shipped that way once. Costs about 4.5% of the total size, + # measured. + grep -q '^panic = "unwind"$' Cargo.toml || { + echo "Cargo.toml no longer sets panic = unwind" >&2; exit 1; } + # And nothing here may quietly override it. + if [ -n "${RUSTFLAGS:-}" ]; then + echo "RUSTFLAGS is set ($RUSTFLAGS) and could undo the profile" >&2 + exit 1 + fi + + - run: cargo test --release + + - run: cargo build --release + + - name: Nothing dynamic beyond the C runtime + run: | + # rusqlite is taken with `bundled` so SQLite is compiled in, and + # the promise on the tin is that a binary needs nothing installed + # alongside it. Checked rather than asserted: a crate that starts + # wanting a system library would otherwise ship quietly. + allowed='linux-vdso|libc\.so|libm\.so|libgcc_s\.so|ld-linux' + bad=0 + for b in $(cargo metadata --no-deps --format-version 1 \ + | grep -o '"name":"[a-z-]*","src_path":"[^"]*bin/[a-z-]*\.rs"' \ + | sed 's/.*bin\///; s/\.rs"//'); do + [ -x "target/release/$b" ] || continue + leaked=$(ldd "target/release/$b" | grep -vE "$allowed" | grep -v '^\s*$' || true) + if [ -n "$leaked" ]; then + echo "$b links something it should carry:" >&2 + echo "$leaked" >&2 + bad=1 + fi + done + [ "$bad" = 0 ] + + - name: Changelog + run: ./.github/changelog.sh "$GITHUB_REF_NAME" > CHANGELOG-release.md + + - name: One tarball, and its checksum + run: | + name="terminal-toys-${GITHUB_REF_NAME}-x86_64-unknown-linux-gnu" + mkdir -p "dist/$name" + # The binaries, and the docs that explain them - `start` embeds + # them but a person reading the tarball has no other copy. + find target/release -maxdepth 1 -type f -executable ! -name '*.*' \ + -exec cp {} "dist/$name/" \; + cp -r docs README.md LICENSE config.example.json "dist/$name/" + tar -C dist -czf "$name.tar.gz" "$name" + sha256sum "$name.tar.gz" > "$name.tar.gz.sha256" + ls -la "$name.tar.gz" + + - name: Release + env: + GH_TOKEN: ${{ github.token }} + run: | + gh release create "$GITHUB_REF_NAME" \ + --title "$GITHUB_REF_NAME" \ + --notes-file CHANGELOG-release.md \ + terminal-toys-*.tar.gz terminal-toys-*.tar.gz.sha256 diff --git a/.gitignore b/.gitignore index a11bf6f..24ded0e 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,12 @@ target/ .DS_Store +# What a release build leaves behind, if one is run by hand. +dist/ +terminal-toys-*.tar.gz +terminal-toys-*.tar.gz.sha256 +CHANGELOG-release.md + # Personal settings, and now secrets: config.json holds the Vercel token. # Variants are covered too, so a config.local.json or a stray .env cannot be # committed by accident. diff --git a/core/build.rs b/core/build.rs new file mode 100644 index 0000000..c2a9872 --- /dev/null +++ b/core/build.rs @@ -0,0 +1,72 @@ +//! What the binary can say about itself. +//! +//! The version comes from `Cargo.toml`; the commit and the date come from +//! here, because neither is knowable from source alone. A `--version` that +//! cannot say which commit it is has answered nothing useful: the version +//! only changes at a release, and most builds anybody runs are between two. + +use std::process::Command; + +fn main() { + // The commit, short. `git` may not be here at all - a release tarball + // has no `.git` - and that is not a build failure, it is an honest + // "unknown". A build that refuses to happen off a checkout is worse + // than one that admits what it does not know. + let commit = Command::new("git") + .args(["rev-parse", "--short", "HEAD"]) + .output() + .ok() + .filter(|o| o.status.success()) + .and_then(|o| String::from_utf8(o.stdout).ok()) + .map(|s| s.trim().to_string()) + .filter(|s| !s.is_empty()) + .unwrap_or_else(|| "unknown".into()); + + // Whether that commit had anything uncommitted under it. A sha alone + // says which commit was checked out, not which source was compiled. + let dirty = Command::new("git") + .args(["status", "--porcelain", "--untracked-files=no"]) + .output() + .ok() + .filter(|o| o.status.success()) + .map(|o| !o.stdout.is_empty()) + .unwrap_or(false); + let commit = if dirty { format!("{}-dirty", commit) } else { commit }; + + // SOURCE_DATE_EPOCH first, which is the convention for making a build + // reproducible: with it set, two builds of the same source agree. Then + // the commit's own date, which has the same property and needs nothing + // set. Wall-clock never, because it makes every build differ from every + // other for no reader's benefit. + let date = std::env::var("SOURCE_DATE_EPOCH") + .ok() + .and_then(|s| s.parse::<i64>().ok()) + .map(|secs| { + Command::new("date") + .args(["-u", "-d", &format!("@{}", secs), "+%Y-%m-%d"]) + .output() + .ok() + .and_then(|o| String::from_utf8(o.stdout).ok()) + .map(|s| s.trim().to_string()) + .unwrap_or_else(|| "unknown".into()) + }) + .or_else(|| { + Command::new("git") + .args(["log", "-1", "--date=format:%Y-%m-%d", "--format=%cd"]) + .output() + .ok() + .filter(|o| o.status.success()) + .and_then(|o| String::from_utf8(o.stdout).ok()) + .map(|s| s.trim().to_string()) + .filter(|s| !s.is_empty()) + }) + .unwrap_or_else(|| "unknown".into()); + + println!("cargo:rustc-env=TOYS_COMMIT={}", commit); + println!("cargo:rustc-env=TOYS_BUILD_DATE={}", date); + // Rebuild when the checked-out commit changes. Without this the sha is + // whatever it was the first time core compiled, and a `--version` that + // names the wrong commit is worse than one that says "unknown". + println!("cargo:rerun-if-changed=../.git/HEAD"); + println!("cargo:rerun-if-env-changed=SOURCE_DATE_EPOCH"); +} diff --git a/core/src/lib.rs b/core/src/lib.rs index e8ad669..0afc21d 100644 --- a/core/src/lib.rs +++ b/core/src/lib.rs @@ -1173,6 +1173,42 @@ pub fn maybe_help(doc: &str) { println!("{}", doc.trim()); std::process::exit(0); } + // Answered here rather than by each widget, for the same reason `--help` + // is: fourteen binaries that disagree about how to say their own version + // are fourteen answers to one question. netwatch used to answer this + // itself and said "netwatch 1.1" while the workspace was at 0.1.0 - a + // number nothing set, kept up to date by nobody. + if args.iter().any(|a| a == "-V" || a == "--version") { + println!("{}", version()); + std::process::exit(0); + } +} + +/// What this binary is, in one line. +/// +/// The version, the commit it was built from, and the date of that commit. +/// The version alone is not enough to identify a build: it changes only at a +/// release, and almost every binary anybody runs is somewhere between two. +/// +/// Any of the three may read `unknown` - built from a tarball with no `.git`, +/// say. That is the honest answer and it is not a build failure; a +/// `--version` that had to guess would be worse than one that admits it. +pub fn version() -> String { + format!( + "{} {} ({}, {})", + binary_name(), + env!("CARGO_PKG_VERSION"), + env!("TOYS_COMMIT"), + env!("TOYS_BUILD_DATE"), + ) +} + +/// The name this binary was invoked as, for the first word of `--version`. +fn binary_name() -> String { + std::env::current_exe() + .ok() + .and_then(|p| p.file_name().map(|n| n.to_string_lossy().into_owned())) + .unwrap_or_else(|| "terminal-toys".into()) } #[cfg(test)] diff --git a/widgets/src/bin/netwatch.rs b/widgets/src/bin/netwatch.rs index 7f298f5..f854dc7 100644 --- a/widgets/src/bin/netwatch.rs +++ b/widgets/src/bin/netwatch.rs @@ -1655,10 +1655,6 @@ fn main() { plain = true; i += 1; } - "-V" | "--version" => { - println!("netwatch 1.1"); - return; - } // Refused rather than ignored: a typo that silently does // nothing is worse than one that says so, and the Python has // always said so. From ece2c66296decbc6d8a04f7009f0b9c3aae277a4 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Wed, 26 Aug 2026 05:03:35 +0800 Subject: [PATCH 120/147] review: what two reviewers found, and what the fix for them found A cross-review of the last three commits by two independent reviewers. They agreed on two things, disagreed on nothing, and between them found that the accessibility fix shipped one commit ago was incomplete. Both flagged the version stamp. `cargo:rerun-if-changed=../.git/HEAD` fails twice over: on a branch checkout that file holds `ref: refs/heads/<branch>` and does not move when a commit lands, and in a linked worktree there is no `.git` directory at all, so the path does not exist - which cargo reads as "always rerun". Correct output by accident, here, and stale in every clone and in CI. It now asks git where the files actually are, follows HEAD to the ref that moves, and watches packed-refs and HEAD itself for a detached checkout. Watched a real commit move the stamp before believing it. Both flagged the workflow's mutable action tags. Pinned to commit shas with the readable version alongside, and the toolchain to 1.98.0: two builds of one tag compiled by different compilers are two different binaries wearing one version number. Then the one that mattered. The contrast fix lightened `dim` and claimed the job was done; four other colours fail on the same tint through the same closures. `bad` at 4.17 in pr and linear, `unknown` at 4.11, `blocked` at 4.29, and `idle` at 3.85 - which is what most of herdr-panes' rows are, so the widget's commonest text was failing while the commit said it was fixed. Generalising the check to every palette colour rather than the one that was measured first found two more nobody had: herdr-panes' `idle_c` at 3.41, the worst in the tree, and tailnet's `offline` at 3.67. All six now have lighter twins, chosen by lifting toward white until they clear with the same margin `dim_lit` has. The check needed three corrections of its own, each found by breaking it: It skipped both a colour with a lighter twin and the twin itself, so it measured nothing at all - a failing value put back into a `_lit` field passed. The twin is the thing that reaches the tint and is what gets measured now. It blamed colours that never meet a tint - github's `bad` is only ever drawn on the plain background - so it now asks whether a colour is handed to a closure that composes one. And it verified wiring by counting, which cannot see a guard that has been neutered: the body still names the lighter colour, the count is unchanged, and the check stays green while the swap never fires. Guards and swaps are paired now. That immediately found github still using the older closure shape, which is normalised so one rule reads all five widgets. Two smaller ones. `changelog.sh` sorted without `-s`, so bullets inside a section came out in whatever order the whole-line comparison gave rather than the order they happened - reproduced, then fixed. And `check.rs` split a widget's source on the first `#[cfg(test)]` of the joined blob, so usage's eight submodules, seven thousand lines, were invisible to every check that did it; each file's tests are stripped before joining now. Rejected: nothing. Deferred: a multi-line `tint` expression is still invisible to the line-by-line scan, which needs a parser rather than a predicate and does not bite today. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- .github/changelog.sh | 2 +- .github/workflows/release.yml | 14 ++- core/build.rs | 47 +++++++- widgets/src/bin/github.rs | 24 +++-- widgets/src/bin/herdr-panes.rs | 68 ++++++++++-- widgets/src/bin/linear.rs | 44 ++++++-- widgets/src/bin/pr.rs | 32 ++++-- widgets/src/bin/tailnet.rs | 13 ++- widgets/tests/check.rs | 191 ++++++++++++++++++++++++++------- 9 files changed, 362 insertions(+), 73 deletions(-) diff --git a/.github/changelog.sh b/.github/changelog.sh index efc3df7..b510e0b 100755 --- a/.github/changelog.sh +++ b/.github/changelog.sh @@ -63,7 +63,7 @@ git log --format='%s' "$range" | awk -v known="$scopes" -F': ' ' if (!good) { print "everything else\t" $0; next } for (i = 1; i <= n; i++) print parts[i] "\t" rest } -' | sort -f -t"$(printf '\t')" -k1,1 | awk -F'\t' ' +' | sort -f -s -t"$(printf '\t')" -k1,1 | awk -F'\t' ' $1 != seen { if (seen != "") printf "\n"; printf "### %s\n\n", $1; seen = $1 } { printf "- %s\n", $2 } ' diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 7ec6a5d..64e4d1e 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -23,13 +23,23 @@ jobs: # glibc 2.35. runs-on: ubuntu-22.04 steps: - - uses: actions/checkout@v4 + # Pinned to a commit, not a tag. A tag is mutable: re-running this + # workflow on the same release tag could execute different action code + # than the release was built with, which makes "reproducible" a word + # rather than a property. Comments carry the human-readable version so + # a reader can tell what these are without resolving them. + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 with: # The changelog reads the history between two tags, and the build # stamps the commit into --version. A shallow clone has neither. fetch-depth: 0 - - uses: dtolnay/rust-toolchain@stable + - uses: dtolnay/rust-toolchain@6c977a6ca4077a0ceb28ffbe03f59d46e9ac8772 # master + with: + # An exact version, for the same reason. `stable` moves, and two + # builds of one tag compiled by different compilers are two + # different binaries wearing one version number. + toolchain: "1.98.0" - name: The tag and the manifest must agree run: | diff --git a/core/build.rs b/core/build.rs index c2a9872..f0f93ab 100644 --- a/core/build.rs +++ b/core/build.rs @@ -64,9 +64,48 @@ fn main() { println!("cargo:rustc-env=TOYS_COMMIT={}", commit); println!("cargo:rustc-env=TOYS_BUILD_DATE={}", date); - // Rebuild when the checked-out commit changes. Without this the sha is - // whatever it was the first time core compiled, and a `--version` that - // names the wrong commit is worse than one that says "unknown". - println!("cargo:rerun-if-changed=../.git/HEAD"); + + // Rebuild when the checked-out commit changes, or the sha is whatever it + // was the first time core compiled and `--version` names the wrong + // commit - worse than one that says "unknown", because it looks right. + // + // Watching `.git/HEAD` alone does not do it, and fails two ways at once. + // On a branch checkout that file holds `ref: refs/heads/<branch>` and + // does not change when a commit lands; what moves is the ref it names. + // And in a linked worktree there is no `.git` directory at all - `.git` + // is a file pointing elsewhere - so the path does not exist, which cargo + // reads as "always rerun". Correct output, by accident, and only here. + // + // So git is asked where these actually live. `--git-path` resolves a + // worktree's real git directory, and the ref is followed to the file + // that moves. packed-refs covers a ref with no loose file of its own, + // and HEAD itself covers a detached checkout, where it holds the sha. + let watch = |path: &str| { + let resolved = Command::new("git") + .args(["rev-parse", "--git-path", path]) + .output() + .ok() + .filter(|o| o.status.success()) + .and_then(|o| String::from_utf8(o.stdout).ok()) + .map(|s| s.trim().to_string()) + .filter(|s| !s.is_empty()); + if let Some(file) = resolved { + println!("cargo:rerun-if-changed={}", file); + } + }; + watch("HEAD"); + watch("packed-refs"); + if let Some(head_ref) = Command::new("git") + .args(["symbolic-ref", "-q", "HEAD"]) + .output() + .ok() + .filter(|o| o.status.success()) + .and_then(|o| String::from_utf8(o.stdout).ok()) + .map(|s| s.trim().to_string()) + .filter(|s| !s.is_empty()) + { + watch(&head_ref); + } + println!("cargo:rerun-if-env-changed=SOURCE_DATE_EPOCH"); } diff --git a/widgets/src/bin/github.rs b/widgets/src/bin/github.rs index 1594909..5fdc7ee 100644 --- a/widgets/src/bin/github.rs +++ b/widgets/src/bin/github.rs @@ -356,10 +356,15 @@ fn account_detail( }; let tint = if here { tc::bg(38, 56, 76) } else { String::new() }; let c = |colour: &str| { - let colour = if tint.is_empty() || colour != p.dim { + // Same shape as the other widgets that do this, so one rule + // reads them all: a guard per colour, each reaching its own + // lighter twin. + let colour = if tint.is_empty() { colour - } else { + } else if colour == p.dim { p.dim_lit.as_str() + } else { + colour }; format!("{}{}", tint, colour) }; @@ -795,8 +800,10 @@ struct Palette { /// /// `dim` is 3.81 against `bg(38, 56, 76)`, under the 4.5 CLAUDE.md asks for /// against the tint as well as the background. This is the same grey lifted - /// until it clears - 4.94 - and it is used *only* where the tint is on, so - /// an unselected row is exactly the colour it always was. + /// until it clears - 4.94 - and it is used *only* where a tint is on, so an + /// untinted row is exactly the colour it always was. Not quite the same as + /// "unselected": herdr-panes tints a blocked or done row whether or not it + /// is selected, and those get the lighter colours too. /// /// The substitution happens inside the closure that composes the tint, not /// at each call site. Seventeen sites were counted when this was found and @@ -1725,10 +1732,15 @@ fn main() { let here = i == selected; let tint = if here { tc::bg(38, 56, 76) } else { String::new() }; let c = |colour: &str| { - let colour = if tint.is_empty() || colour != p.dim { + // Same shape as the other widgets that do this, so one rule + // reads them all: a guard per colour, each reaching its own + // lighter twin. + let colour = if tint.is_empty() { colour - } else { + } else if colour == p.dim { p.dim_lit.as_str() + } else { + colour }; format!("{}{}", tint, colour) }; diff --git a/widgets/src/bin/herdr-panes.rs b/widgets/src/bin/herdr-panes.rs index 2a403e7..1708cd4 100644 --- a/widgets/src/bin/herdr-panes.rs +++ b/widgets/src/bin/herdr-panes.rs @@ -454,17 +454,22 @@ enum Row { struct Palette { blocked: String, + blocked_lit: String, done: String, working: String, idle: String, + idle_lit: String, unknown: String, + unknown_lit: String, dim: String, /// A colour to draw over the selected-row tint. /// /// `dim` is 3.81 against `bg(38, 56, 76)`, under the 4.5 CLAUDE.md asks for /// against the tint as well as the background. This is the same grey lifted - /// until it clears - 4.94 - and it is used *only* where the tint is on, so - /// an unselected row is exactly the colour it always was. + /// until it clears - 4.94 - and it is used *only* where a tint is on, so an + /// untinted row is exactly the colour it always was. Not quite the same as + /// "unselected": herdr-panes tints a blocked or done row whether or not it + /// is selected, and those get the lighter colours too. /// /// The substitution happens inside the closure that composes the tint, not /// at each call site. Seventeen sites were counted when this was found and @@ -479,15 +484,19 @@ struct Palette { accent: String, proc: String, idle_c: String, + idle_c_lit: String, } fn palette() -> Palette { Palette { blocked: tc::rgb(255, 105, 115), + blocked_lit: tc::rgb(255, 128, 136), done: tc::rgb(90, 240, 160), working: tc::rgb(255, 200, 90), idle: tc::rgb(128, 148, 172), + idle_lit: tc::rgb(152, 168, 188), unknown: tc::rgb(150, 150, 165), + unknown_lit: tc::rgb(165, 165, 178), dim: tc::rgb(127, 147, 172), dim_lit: tc::rgb(140, 170, 195), txt: tc::rgb(225, 235, 245), @@ -495,6 +504,7 @@ fn palette() -> Palette { accent: tc::rgb(150, 210, 255), proc: tc::rgb(170, 190, 215), idle_c: tc::rgb(122, 138, 160), + idle_c_lit: tc::rgb(155, 167, 184), } } @@ -839,10 +849,24 @@ fn main() { String::new() }; let c = |colour: &str| { - let colour = if tint.is_empty() || colour != p.dim { + // Any colour that would not clear AA on this tint is swapped + // for its lighter twin. `dim` was measured first; a review + // found the others after the first fix shipped saying it was + // done, so they are here by measurement rather than by guess. + let colour = if tint.is_empty() { colour - } else { + } else if colour == p.dim { p.dim_lit.as_str() + } else if colour == p.idle { + p.idle_lit.as_str() + } else if colour == p.unknown { + p.unknown_lit.as_str() + } else if colour == p.blocked { + p.blocked_lit.as_str() + } else if colour == p.idle_c { + p.idle_c_lit.as_str() + } else { + colour }; format!("{}{}", tint, colour) }; @@ -943,10 +967,24 @@ fn main() { let here = agents.len() + j == selected; let tint = if here { tc::bg(38, 56, 76) } else { String::new() }; let c = |colour: &str| { - let colour = if tint.is_empty() || colour != p.dim { + // Any colour that would not clear AA on this tint is swapped + // for its lighter twin. `dim` was measured first; a review + // found the others after the first fix shipped saying it was + // done, so they are here by measurement rather than by guess. + let colour = if tint.is_empty() { colour - } else { + } else if colour == p.dim { p.dim_lit.as_str() + } else if colour == p.idle { + p.idle_lit.as_str() + } else if colour == p.unknown { + p.unknown_lit.as_str() + } else if colour == p.blocked { + p.blocked_lit.as_str() + } else if colour == p.idle_c { + p.idle_c_lit.as_str() + } else { + colour }; format!("{}{}", tint, colour) }; @@ -1015,10 +1053,24 @@ fn main() { let here = agents.len() + running.len() + j == selected; let tint = if here { tc::bg(38, 56, 76) } else { String::new() }; let c = |colour: &str| { - let colour = if tint.is_empty() || colour != p.dim { + // Any colour that would not clear AA on this tint is swapped + // for its lighter twin. `dim` was measured first; a review + // found the others after the first fix shipped saying it was + // done, so they are here by measurement rather than by guess. + let colour = if tint.is_empty() { colour - } else { + } else if colour == p.dim { p.dim_lit.as_str() + } else if colour == p.idle { + p.idle_lit.as_str() + } else if colour == p.unknown { + p.unknown_lit.as_str() + } else if colour == p.blocked { + p.blocked_lit.as_str() + } else if colour == p.idle_c { + p.idle_c_lit.as_str() + } else { + colour }; format!("{}{}", tint, colour) }; diff --git a/widgets/src/bin/linear.rs b/widgets/src/bin/linear.rs index b097fa9..712c050 100644 --- a/widgets/src/bin/linear.rs +++ b/widgets/src/bin/linear.rs @@ -795,13 +795,16 @@ struct Palette { ok: String, warn: String, bad: String, + bad_lit: String, dim: String, /// A colour to draw over the selected-row tint. /// /// `dim` is 3.81 against `bg(38, 56, 76)`, under the 4.5 CLAUDE.md asks for /// against the tint as well as the background. This is the same grey lifted - /// until it clears - 4.94 - and it is used *only* where the tint is on, so - /// an unselected row is exactly the colour it always was. + /// until it clears - 4.94 - and it is used *only* where a tint is on, so an + /// untinted row is exactly the colour it always was. Not quite the same as + /// "unselected": herdr-panes tints a blocked or done row whether or not it + /// is selected, and those get the lighter colours too. /// /// The substitution happens inside the closure that composes the tint, not /// at each call site. Seventeen sites were counted when this was found and @@ -827,6 +830,7 @@ fn palette() -> Palette { ok: tc::rgb(90, 240, 160), warn: tc::rgb(255, 200, 90), bad: tc::rgb(255, 100, 110), + bad_lit: tc::rgb(255, 128, 136), dim: tc::rgb(127, 147, 172), dim_lit: tc::rgb(140, 170, 195), grid: tc::rgb(60, 78, 98), @@ -2256,10 +2260,18 @@ fn main() { let on = focus == Some(cycles_pane) && ci == sel[cycles_pane]; let tint = if on { tc::bg(38, 56, 76) } else { String::new() }; let c_of = |colour: &str| { - let colour = if tint.is_empty() || colour != p.dim { + // Any colour that would not clear AA on this tint is swapped + // for its lighter twin. `dim` was measured first; a review + // found the others after the first fix shipped saying it was + // done, so they are here by measurement rather than by guess. + let colour = if tint.is_empty() { colour - } else { + } else if colour == p.dim { p.dim_lit.as_str() + } else if colour == p.bad { + p.bad_lit.as_str() + } else { + colour }; format!("{}{}", tint, colour) }; @@ -2512,10 +2524,18 @@ fn main() { let here = on_teams && i == sel[teams_pane]; let tint = if here { tc::bg(38, 56, 76) } else { String::new() }; let c_of = |colour: &str| { - let colour = if tint.is_empty() || colour != p.dim { + // Any colour that would not clear AA on this tint is swapped + // for its lighter twin. `dim` was measured first; a review + // found the others after the first fix shipped saying it was + // done, so they are here by measurement rather than by guess. + let colour = if tint.is_empty() { colour - } else { + } else if colour == p.dim { p.dim_lit.as_str() + } else if colour == p.bad { + p.bad_lit.as_str() + } else { + colour }; format!("{}{}", tint, colour) }; @@ -2628,10 +2648,18 @@ fn main() { } let tint = if here { tc::bg(38, 56, 76) } else { String::new() }; let c_of = |colour: &str| { - let colour = if tint.is_empty() || colour != p.dim { + // Any colour that would not clear AA on this tint is swapped + // for its lighter twin. `dim` was measured first; a review + // found the others after the first fix shipped saying it was + // done, so they are here by measurement rather than by guess. + let colour = if tint.is_empty() { colour - } else { + } else if colour == p.dim { p.dim_lit.as_str() + } else if colour == p.bad { + p.bad_lit.as_str() + } else { + colour }; format!("{}{}", tint, colour) }; diff --git a/widgets/src/bin/pr.rs b/widgets/src/bin/pr.rs index a72a1ef..fc574fe 100644 --- a/widgets/src/bin/pr.rs +++ b/widgets/src/bin/pr.rs @@ -523,13 +523,16 @@ struct Palette { ok: String, warn: String, bad: String, + bad_lit: String, dim: String, /// A colour to draw over the selected-row tint. /// /// `dim` is 3.81 against `bg(38, 56, 76)`, under the 4.5 CLAUDE.md asks for /// against the tint as well as the background. This is the same grey lifted - /// until it clears - 4.94 - and it is used *only* where the tint is on, so - /// an unselected row is exactly the colour it always was. + /// until it clears - 4.94 - and it is used *only* where a tint is on, so an + /// untinted row is exactly the colour it always was. Not quite the same as + /// "unselected": herdr-panes tints a blocked or done row whether or not it + /// is selected, and those get the lighter colours too. /// /// The substitution happens inside the closure that composes the tint, not /// at each call site. Seventeen sites were counted when this was found and @@ -551,6 +554,7 @@ fn palette() -> Palette { ok: tc::rgb(90, 240, 160), warn: tc::rgb(255, 200, 90), bad: tc::rgb(255, 100, 110), + bad_lit: tc::rgb(255, 128, 136), dim: tc::rgb(127, 147, 172), dim_lit: tc::rgb(140, 170, 195), grid: tc::rgb(60, 78, 98), @@ -1509,10 +1513,18 @@ fn list_view( let here = i == selected; let tint = if here { tc::bg(38, 56, 76) } else { String::new() }; let c = |colour: &str| { - let colour = if tint.is_empty() || colour != p.dim { + // Any colour that would not clear AA on this tint is swapped + // for its lighter twin. `dim` was measured first; a review + // found the others after the first fix shipped saying it was + // done, so they are here by measurement rather than by guess. + let colour = if tint.is_empty() { colour - } else { + } else if colour == p.dim { p.dim_lit.as_str() + } else if colour == p.bad { + p.bad_lit.as_str() + } else { + colour }; format!("{}{}", tint, colour) }; @@ -1983,10 +1995,18 @@ fn detail_view( let on_cursor = idx == stack_sel; let tint = if on_cursor { tc::bg(38, 56, 76) } else { String::new() }; let c = |colour: &str| { - let colour = if tint.is_empty() || colour != p.dim { + // Any colour that would not clear AA on this tint is swapped + // for its lighter twin. `dim` was measured first; a review + // found the others after the first fix shipped saying it was + // done, so they are here by measurement rather than by guess. + let colour = if tint.is_empty() { colour - } else { + } else if colour == p.dim { p.dim_lit.as_str() + } else if colour == p.bad { + p.bad_lit.as_str() + } else { + colour }; format!("{}{}", tint, colour) }; diff --git a/widgets/src/bin/tailnet.rs b/widgets/src/bin/tailnet.rs index 502ac3b..927ea0d 100644 --- a/widgets/src/bin/tailnet.rs +++ b/widgets/src/bin/tailnet.rs @@ -512,6 +512,7 @@ fn sample_rates(state: &mut State, data: &serde_json::Value, history: usize) { struct Palette { online: String, offline: String, + offline_lit: String, direct: String, relay: String, dim: String, @@ -526,6 +527,7 @@ fn palette() -> Palette { Palette { online: tc::rgb(90, 240, 160), offline: tc::rgb(120, 130, 150), + offline_lit: tc::rgb(144, 152, 169), direct: tc::rgb(90, 240, 160), relay: tc::rgb(255, 190, 90), dim: tc::rgb(127, 147, 172), @@ -1023,7 +1025,16 @@ fn main() { let up = mine || peer["Online"].as_bool().unwrap_or(false); let here = idx == selected; let tint = if here { tc::bg(28, 44, 62) } else { String::new() }; - let c = |colour: &str| format!("{}{}", tint, colour); + let c = |colour: &str| { + // offline is what a peer that is not up is drawn in, and it + // measured 3.67 on this tint - the worst in the widget. + let colour = if !tint.is_empty() && colour == p.offline { + p.offline_lit.as_str() + } else { + colour + }; + format!("{}{}", tint, colour) + }; let path_direct = !text(peer, "CurAddr").is_empty(); // "this" rather than DIRECT or a relay name: the path column // answers how the traffic gets there, and for this machine it diff --git a/widgets/tests/check.rs b/widgets/tests/check.rs index 2ad6b36..5904017 100644 --- a/widgets/tests/check.rs +++ b/widgets/tests/check.rs @@ -47,6 +47,53 @@ fn root() -> PathBuf { .expect("the repo root") } +/// Every `<name>_lit` the palette defines. +fn colours_ending_in_lit(src: &str) -> Vec<String> { + let mut found = Vec::new(); + for line in src.lines() { + let t = line.trim_start(); + if !t.contains(": tc::rgb(") { + continue; + } + if let Some(field) = t.split(':').next() { + if field.ends_with("_lit") && !field.contains(' ') { + found.push(field.to_string()); + } + } + } + found.sort(); + found.dedup(); + found +} + +/// Whether a palette colour is ever handed to the closure that composes a +/// selection tint. +/// +/// Most colours are drawn straight - `p.bad.as_str()` - and never meet a +/// tint; blaming those is how a contrast check starts crying wolf, which +/// this file has already had to fix twice. A colour counts if it is named on +/// a line that calls the tint helper, or if it is returned by one of the +/// small colour pickers whose result is then handed to it. +fn handed_to_a_tint(src: &str, field: &str) -> bool { + let named = format!("p.{}", field); + let mentions = |line: &str| match line.find(&named) { + // `p.dim` is a prefix of `p.dim_lit`. + Some(at) => !line[at + named.len()..].starts_with('_'), + None => false, + }; + src.lines().any(|line| { + let composes = line.contains("c(") || line.contains("c_of(") || line.contains("tinted("); + let picker = line.trim_start().starts_with("\"") && line.contains("=> &p."); + (composes && mentions(line)) || (picker && mentions(line)) + }) +} + +/// A source with its own test module removed. Fixtures are not the screen, +/// and a colour or a key that only appears in one is not shipped. +fn without_tests(src: &str) -> String { + src.split("#[cfg(test)]").next().unwrap_or("").to_string() +} + /// Every widget binary, by stem, with its source. fn widgets() -> BTreeMap<String, String> { let dir = root().join("widgets/src/bin"); @@ -57,14 +104,21 @@ fn widgets() -> BTreeMap<String, String> { continue; } let stem = path.file_stem().and_then(|s| s.to_str()).unwrap_or("").to_string(); - let mut src = std::fs::read_to_string(&path).unwrap_or_default(); + // Each file's own tests are dropped before joining, not after. Split + // on the first `#[cfg(test)]` of the joined blob and a widget with + // submodules is read only as far as its main file's tests - usage's + // are two thirds of the way down, so its eight submodules, seven + // thousand lines, were invisible to every check that did it that way. + let mut src = without_tests(&std::fs::read_to_string(&path).unwrap_or_default()); // A widget split across a directory - usage - reads as one widget. let sub = dir.join(&stem); if sub.is_dir() { for part in std::fs::read_dir(&sub).expect("a widget directory").flatten() { if part.path().extension().and_then(|e| e.to_str()) == Some("rs") { src.push('\n'); - src.push_str(&std::fs::read_to_string(part.path()).unwrap_or_default()); + src.push_str(&without_tests( + &std::fs::read_to_string(part.path()).unwrap_or_default(), + )); } } } @@ -562,47 +616,85 @@ fn triple(line: &str, call: &str) -> Option<(f64, f64, f64)> { /// reached a tinted row grew from seventeen to twenty-three while that sat /// open, which is what prose costs. /// -/// Only colours that actually meet are compared. The first version of this -/// paired every `bg()` in a file with every grey in it and reported two -/// widgets that were fine - one of them on a tint that exists in a test -/// fixture, the other on a tint only ever drawn with `accent`. A check that -/// cries wolf gets turned off. +/// It checks **every** palette colour a widget defines, not the one that was +/// measured first. The version before this one looked only at `dim` and +/// `dim_lit`, and a review found three more failing on the same tint through +/// the same closures - `bad` at 4.17, `unknown` at 4.11, and `idle` at 3.85, +/// which is what most of herdr-panes' rows are. A check that only knows +/// about the bug it was written for finds that bug and stops. +/// +/// A colour with a `_lit` twin is exempt: the twin is what reaches the tint, +/// and it is measured instead. Only colours that meet a tint are compared - +/// an earlier version paired every `bg()` in a file with every colour in it +/// and reported two widgets that were fine, one on a tint that exists only +/// in a test fixture. A check that cries wolf gets turned off. #[test] fn text_on_a_selection_tint_clears_aa() { let mut wrong = Vec::new(); - for (name, whole) in widgets() { - // Fixtures are not the screen. - let src = whole.split("#[cfg(test)]").next().unwrap_or("").to_string(); - let mut greys: BTreeMap<String, (f64, f64, f64)> = BTreeMap::new(); + for (name, src) in widgets() { + // Every colour the palette defines, by field. + let mut colours: BTreeMap<String, (f64, f64, f64)> = BTreeMap::new(); for line in src.lines() { - for field in ["dim", "dim_lit"] { - if line.trim_start().starts_with(&format!("{}: tc::rgb", field)) { - if let Some(c) = triple(line, "tc::rgb") { - greys.insert(field.to_string(), c); - } - } + let t = line.trim_start(); + let Some(field) = t.split(':').next() else { continue }; + if !t.contains(": tc::rgb(") || field.contains(' ') || field.is_empty() { + continue; + } + if let Some(c) = triple(line, "tc::rgb") { + colours.insert(field.to_string(), c); } } - // What each tint is composed with, one line at a time. for line in src.lines() { let Some(tint) = triple(line, "tc::bg") else { continue }; - // Composed inline with a named colour: that exact pair. - let named: Vec<&str> = ["dim_lit", "dim", "accent", "txt"] - .into_iter() - .filter(|f| line.contains(&format!("p.{}", f))) + // Composed inline with one named colour: that exact pair. Or + // assigned to `tint` and composed later by a closure, in which + // case every colour in the palette can reach it. + let inline: Vec<String> = colours + .keys() + .filter(|f| { + // `p.dim` is a prefix of `p.dim_lit`; without the guard a + // line drawing only the lighter one would be blamed for + // the darker one it never draws. + let needle = format!("p.{}", f); + match line.find(&needle) { + None => false, + Some(at) => !line[at + needle.len()..].starts_with('_'), + } + }) + .cloned() .collect(); - // Or assigned to `tint` and composed later, where the greys are - // what reach it - the lighter one when the widget has it. - let reached: Vec<String> = if line.contains("tint") && named.is_empty() { - greys - .contains_key("dim_lit") - .then(|| vec!["dim_lit".to_string()]) - .unwrap_or_else(|| greys.keys().cloned().collect()) + let reached: Vec<String> = if !inline.is_empty() { + inline + } else if line.contains("tint") { + // Not every colour in the palette reaches the tint - most are + // drawn straight, as `p.bad.as_str()`. Only the ones handed to + // the closure count, either directly or through a colour + // picker whose arms return them. Without this the check + // reported github's `bad`, which is only ever drawn on the + // plain background, and a check that cries wolf gets turned + // off - which is the note this file already carries twice. + colours + .keys() + .filter(|f| handed_to_a_tint(&src, f)) + .cloned() + .collect() } else { - named.into_iter().map(str::to_string).collect() + continue; }; for field in reached { - let Some(&c) = greys.get(&field) else { continue }; + // Gridlines are not text, and say so where they are defined. + if field.contains("grid") { + continue; + } + // The lighter twin is what reaches the tint, so the twin is + // what gets measured. Skipping both - which this did briefly, + // and which passed a mutation that put a failing value back + // into a `_lit` field - measures nothing at all. + let field = match colours.contains_key(&format!("{}_lit", field)) { + true => format!("{}_lit", field), + false => field, + }; + let Some(&c) = colours.get(&field) else { continue }; let r = contrast(c, tint); if r < 4.5 { wrong.push(format!( @@ -613,6 +705,8 @@ fn text_on_a_selection_tint_clears_aa() { } } } + wrong.sort(); + wrong.dedup(); assert!(wrong.is_empty(), "on the selected-row tint:\n{}", wrong.join("\n")); } @@ -631,12 +725,35 @@ fn a_widget_with_a_lighter_grey_uses_it_on_every_tint() { continue; } let closures = src.matches("format!(\"{}{}\", tint, colour)").count(); - let swaps = src.matches("dim_lit.as_str()").count() + src.matches("&p.dim_lit").count(); - if swaps < closures { - wrong.push(format!( - "{}: {} tint closures but {} reach for dim_lit", - name, closures, swaps - )); + // Every lighter colour the palette defines has to be reached for by + // every closure that composes a tint. Counting only `dim_lit` let a + // mutation through: unwiring the `idle_c` arm left the dim_lit count + // untouched and the check green, which is the shape of hole this + // test exists to close. + // A swap and the guard that reaches it come in pairs. Counting + // occurrences alone cannot see a guard that has been neutered - the + // body still mentions the lighter colour, so the count is unchanged + // and the check stays green while the swap never fires. + for lit in colours_ending_in_lit(&src) { + let base = lit.trim_end_matches("_lit"); + let swaps = src.matches(&format!("p.{}.as_str()", lit)).count(); + let guards = src.matches(&format!("colour == p.{} {{", base)).count(); + if swaps != guards { + wrong.push(format!( + "{}: {} reached {} times but guarded on `colour == p.{}` {} times", + name, lit, swaps, base, guards + )); + } + } + for lit in colours_ending_in_lit(&src) { + let swaps = src.matches(&format!("p.{}.as_str()", lit)).count() + + src.matches(&format!("&p.{}", lit)).count(); + if swaps < closures { + wrong.push(format!( + "{}: {} tint closures but {} reach for {}", + name, closures, swaps, lit + )); + } } } assert!(wrong.is_empty(), "a lighter grey nobody draws:\n{}", wrong.join("\n")); From 7a65f8477b742c6645defcf8dd9c8f5274af14af Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Wed, 26 Aug 2026 10:43:44 +0800 Subject: [PATCH 121/147] check: read a whole tint statement, not a line of one The deferred finding from the cross-review, and the last of them. The contrast check scanned line by line, so it only saw a tint composed on one line. herdr-panes binds its across nine: let tint = if here { tc::bg(38, 56, 76) } else if a.state == "blocked" { The line carrying that first bg() names no colour and does not contain the word "tint", so neither branch of the scan fired and nothing at all was checked against it. It happened not to matter only because the same value appears on its own line twice more in the same file - alone, or changed on its own, an AA failure there would have gone unseen. It now reads a `tint` binding as one statement, however long, and takes every bg() inside it. Proven both ways rather than assumed: changing only that multi-line tint is reported four times over by the new check, and the version committed an hour ago passes the identical mutation without a word. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- widgets/tests/check.rs | 113 +++++++++++++++++++++++++++++++---------- 1 file changed, 87 insertions(+), 26 deletions(-) diff --git a/widgets/tests/check.rs b/widgets/tests/check.rs index 5904017..1da5e34 100644 --- a/widgets/tests/check.rs +++ b/widgets/tests/check.rs @@ -47,6 +47,66 @@ fn root() -> PathBuf { .expect("the repo root") } +/// Every selection tint a widget composes, and how it was reached. +/// +/// Returns `(tint, inline_colour)` - the colour named on the same line when +/// the tint is composed inline, and `None` when it is bound to a `tint` +/// variable and handed to a closure later. +/// +/// A whole statement at a time, not a line at a time. herdr-panes binds its +/// tint across nine lines: +/// +/// ```ignore +/// let tint = if here { +/// tc::bg(38, 56, 76) +/// } else if a.state == "blocked" { +/// ``` +/// +/// The line carrying that first `bg()` names no colour and does not contain +/// the word "tint", so a line-by-line scan saw neither and checked nothing +/// for it. It happened not to matter only because the same tint appears on +/// its own line twice more in the same file; alone, or changed on its own, an +/// AA failure there would have gone unseen. +fn tints_of(src: &str) -> Vec<((f64, f64, f64), Option<String>)> { + let mut found = Vec::new(); + let lines: Vec<&str> = src.lines().collect(); + let mut i = 0; + while i < lines.len() { + let line = lines[i]; + // A binding whose name is `tint`: take the statement to its end. + let binds_tint = line.contains("let tint") + || line.trim_start().starts_with("tint =") + || line.contains("let tint:"); + if binds_tint { + let mut depth: i32 = 0; + let mut j = i; + loop { + let l = lines[j]; + depth += l.matches('{').count() as i32 - l.matches('}').count() as i32; + if let Some(t) = triple(l, "tc::bg") { + found.push((t, None)); + } + // The statement ends at a `;` once every brace has closed. + if depth <= 0 && l.trim_end().ends_with(';') { + break; + } + j += 1; + if j >= lines.len() || j > i + 40 { + break; + } + } + i = j + 1; + continue; + } + // Otherwise a bg() composed inline, with the colour on the same line. + if let Some(t) = triple(line, "tc::bg") { + found.push((t, Some(line.to_string()))); + } + i += 1; + } + found +} + /// Every `<name>_lit` the palette defines. fn colours_ending_in_lit(src: &str) -> Vec<String> { let mut found = Vec::new(); @@ -644,35 +704,36 @@ fn text_on_a_selection_tint_clears_aa() { colours.insert(field.to_string(), c); } } - for line in src.lines() { - let Some(tint) = triple(line, "tc::bg") else { continue }; - // Composed inline with one named colour: that exact pair. Or - // assigned to `tint` and composed later by a closure, in which - // case every colour in the palette can reach it. - let inline: Vec<String> = colours - .keys() - .filter(|f| { - // `p.dim` is a prefix of `p.dim_lit`; without the guard a - // line drawing only the lighter one would be blamed for - // the darker one it never draws. - let needle = format!("p.{}", f); - match line.find(&needle) { - None => false, - Some(at) => !line[at + needle.len()..].starts_with('_'), - } - }) - .cloned() - .collect(); + for (tint, inline_line) in tints_of(&src) { + // Composed inline with a named colour: that exact pair. Bound to + // `tint` and handed to a closure: every colour the closure is + // given can land on it. + let inline: Vec<String> = match inline_line.as_ref() { + None => Vec::new(), + Some(line) => colours + .keys() + .filter(|f| { + // `p.dim` is a prefix of `p.dim_lit`; without the + // guard a line drawing only the lighter one would be + // blamed for the darker one it never draws. + let needle = format!("p.{}", f); + match line.find(&needle) { + None => false, + Some(at) => !line[at + needle.len()..].starts_with('_'), + } + }) + .cloned() + .collect(), + }; let reached: Vec<String> = if !inline.is_empty() { inline - } else if line.contains("tint") { + } else if inline_line.is_none() { // Not every colour in the palette reaches the tint - most are - // drawn straight, as `p.bad.as_str()`. Only the ones handed to - // the closure count, either directly or through a colour - // picker whose arms return them. Without this the check - // reported github's `bad`, which is only ever drawn on the - // plain background, and a check that cries wolf gets turned - // off - which is the note this file already carries twice. + // drawn straight, as `p.bad.as_str()`. Only the ones handed + // to a closure count, directly or through a colour picker + // whose arms return them. Without this the check reported + // github's `bad`, which is only ever drawn on the plain + // background, and a check that cries wolf gets turned off. colours .keys() .filter(|f| handed_to_a_tint(&src, f)) From ce05790d01adfd1462aef2e0915411256c6b19fa Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Wed, 26 Aug 2026 11:34:12 +0800 Subject: [PATCH 122/147] github, clocks: four the PR's reviewers were right about PR #31 has thirty-odd open review threads from three bots. Most are outdated - they cite paths under `rust/` that the migration moved - and several are opinion. These four are neither. github's `graphql()` did not refuse an errors payload. GraphQL answers 200 with an `errors` array, so a successful request is not a successful query; reading past it leaves every alias the query asked for missing, `count_at` turns those into zeros, and the zeros go into the day cache as historical fact. The affected days are then never retried and the contribution chart shows a quiet week that never happened. linear and pr both refuse this in exactly the same place - github was the one that did not, and it checked for errors at two call sites instead, which covered the two paths somebody had thought about and not the one that cached. github sliced a server-supplied message by bytes: `&why[..why.len().min(50)]` panics on any multibyte character crossing byte fifty, inside a poll thread. Two other places in the same file already take characters, and linear carries a test for this exact defect class after it panicked there. clocks substituted four hardcoded cities whenever its list came to nothing - including when the list was set and every zone in it was a typo. A person who misspells their timezones was shown San Francisco, London, Singapore and Tokyo, which are plausible, wrong, and say nothing about the mistake. Absent and empty are told apart now: nobody having said what they want still gets the four, and having said it and got nothing keeps nothing. And the test that swaps PATH now holds a lock while it does. PATH is process-wide, cargo runs a binary's tests in parallel, and `missing()` reads it - so a second test calling it mid-swap would fail for a reason unrelated to what it tests, occasionally. One check moved with them. Asking whether a config key is *present* has no value to fall back to, and the fallback that rule asks for is precisely what would collapse absent and empty back together. Presence reads are allowed; a genuinely bare read is still caught, checked by writing one. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- core/src/lib.rs | 7 +++++++ widgets/src/bin/clocks.rs | 12 +++++++++++- widgets/src/bin/github.rs | 33 ++++++++++++++++++++++----------- widgets/tests/check.rs | 9 ++++++++- 4 files changed, 48 insertions(+), 13 deletions(-) diff --git a/core/src/lib.rs b/core/src/lib.rs index 0afc21d..82c40c0 100644 --- a/core/src/lib.rs +++ b/core/src/lib.rs @@ -1404,6 +1404,13 @@ mod tests { let tool = dir.join("definitely-not-a-real-tool"); std::fs::write(&tool, "#!/bin/sh\n").unwrap(); + // PATH is process-wide and cargo runs a binary's tests in parallel, + // so this is held for as long as the value is borrowed. `missing()` + // reads PATH, and a second test calling it mid-swap would see a + // directory holding one fake tool - failing for a reason that has + // nothing to do with what it was testing, and only sometimes. + static ENV: std::sync::Mutex<()> = std::sync::Mutex::new(()); + let _guard = ENV.lock().unwrap_or_else(|e| e.into_inner()); let held = std::env::var("PATH").unwrap_or_default(); std::env::set_var("PATH", dir.to_string_lossy().to_string()); diff --git a/widgets/src/bin/clocks.rs b/widgets/src/bin/clocks.rs index 2595c58..a7b4e10 100644 --- a/widgets/src/bin/clocks.rs +++ b/widgets/src/bin/clocks.rs @@ -1037,6 +1037,12 @@ fn phase_of(there: &chrono::DateTime<Tz>, p: &Palette) -> (String, &'static str) /// UTC: a clock quietly showing the wrong city is worse than one absent. fn load_cities(cfg: &serde_json::Value) -> Vec<City> { let mut out = Vec::new(); + // Whether the key is there at all, which is a different thing from it + // being empty. Absent means nobody has said what they want and a default + // is a kindness; present means they have, and substituting four cities + // of our own for the answer they gave is the widget telling them about + // somewhere they did not ask about. + let asked = cfg.get("cities").and_then(|v| v.as_array()).is_some(); if let Some(items) = cfg.get("cities").and_then(|v| v.as_array()) { for pair in items { let name = pair.get(0).and_then(|v| v.as_str()).unwrap_or(""); @@ -1060,7 +1066,11 @@ fn load_cities(cfg: &serde_json::Value) -> Vec<City> { }); return out; } - if out.is_empty() { + // Only when nothing was configured. A list that was set and parsed to + // nothing - empty, or every zone a typo - is left empty, so the row that + // is missing is the question rather than a plausible answer to a + // different one. + if out.is_empty() && !asked { for (name, zone) in [ ("San Francisco", "America/Los_Angeles"), ("London", "Europe/London"), diff --git a/widgets/src/bin/github.rs b/widgets/src/bin/github.rs index 5fdc7ee..31c8796 100644 --- a/widgets/src/bin/github.rs +++ b/widgets/src/bin/github.rs @@ -519,7 +519,17 @@ fn graphql( } } } - serde_json::from_str(&text).map_err(|e| e.to_string()) + let data: serde_json::Value = serde_json::from_str(&text).map_err(|e| e.to_string())?; + // GraphQL answers 200 with an `errors` array, so a successful request is + // not a successful query. Read past it and every alias the query asked + // for is missing, which `count_at` turns into zeros - and those zeros go + // into the day cache as historical fact, so the affected days are never + // retried and the chart shows a quiet week that never happened. linear + // and pr both refuse this in the same place; github did not. + if let Some(first) = data["errors"].as_array().and_then(|a| a.first()) { + return Err(first["message"].as_str().unwrap_or("").chars().take(80).collect()); + } + Ok(data) } /// Flag a token that will undercount rather than fail. @@ -857,7 +867,13 @@ fn one_pass( let why = who["errors"][0]["message"] .as_str() .unwrap_or("no viewer login in the response"); - return Err(format!("who am I: {}", &why[..why.len().min(50)])); + // By characters, not bytes: a message with any multibyte + // character crossing byte fifty would panic the slice, and + // this one comes from a server. + return Err(format!( + "who am I: {}", + why.chars().take(50).collect::<String>() + )); } }; } @@ -927,18 +943,13 @@ fn one_pass( let data = match graphql(&build_query(acc, days_now, viewer), tok, scopes) { Ok(d) => d, Err(e) => { - failed.push(format!("{} ({})", acc, e.chars().take(20).collect::<String>())); + // Fifty characters, which is what the branch below used to + // take before `graphql` started refusing an errors payload + // itself and made that branch unreachable. + failed.push(format!("{} ({})", acc, e.chars().take(50).collect::<String>())); continue; } }; - if let Some(first) = data["errors"].as_array().and_then(|a| a.first()) { - failed.push(format!( - "{} ({})", - acc, - first["message"].as_str().unwrap_or("").chars().take(50).collect::<String>() - )); - continue; - } let d = &data["data"]; if let Some(limit) = d["rateLimit"]["limit"].as_i64() { rate = Some((d["rateLimit"]["remaining"].as_i64().unwrap_or(0), limit)); diff --git a/widgets/tests/check.rs b/widgets/tests/check.rs index 1da5e34..d9af259 100644 --- a/widgets/tests/check.rs +++ b/widgets/tests/check.rs @@ -546,7 +546,14 @@ fn every_config_read_falls_back_to_a_code_default() { let statement = &rest[..stop]; let guarded = statement.contains("unwrap_or") || statement.contains("unwrap_or_else") - || statement.contains("unwrap_or_default"); + || statement.contains("unwrap_or_default") + // Asking whether a key is *there* has no value to default. + // clocks needs it: a `cities` list that was set and came to + // nothing must stay nothing, where an absent one gets the + // code's four. Collapsing those two is the bug, and the + // fallback this rule asks for is what would collapse them. + || statement.contains(".is_some()") + || statement.contains(".is_none()"); if !guarded { wrong.push(format!( "{}: reads {:?} from config with no fallback in the statement", From 1998e9ac3f425ae27c24ba60b9fb60af99b7f246 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Wed, 26 Aug 2026 12:02:27 +0800 Subject: [PATCH 123/147] core: three ways a helper turned a real answer into silence `cfg_strings` could not tell an empty list from an absent key, so a widget configured with `[]` was handed the fallback - the one shape a reader chooses precisely to mean "nothing". Absent still falls back; empty is now honoured as the answer it is. `refused` dropped the response body on a failed POST. GitHub and Vercel both explain a 4xx in the body and say nothing useful in the status, so the widget showed "422" where the server had written the reason. `run_full` left stderr on the inherited terminal, where a tool's complaint scribbled over the frame instead of reaching the caller that could display it. It is piped now, and the caller decides. build.rs drops its `rerun-if-changed` watches entirely. Watching the git ref fixed the commit half of the stamp, but nothing under `.git` moves when a source file is edited, so `-dirty` stayed absent over a modified tree - a marker claiming "clean" that was false. Always running the script is what makes the stamp true, and the cost was measured, not feared: a no-op rebuild is 0.03s. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- core/build.rs | 54 ++++++--------------- core/src/lib.rs | 121 ++++++++++++++++++++++++++++++++++++++++++++---- 2 files changed, 127 insertions(+), 48 deletions(-) diff --git a/core/build.rs b/core/build.rs index f0f93ab..13deaec 100644 --- a/core/build.rs +++ b/core/build.rs @@ -65,47 +65,21 @@ fn main() { println!("cargo:rustc-env=TOYS_COMMIT={}", commit); println!("cargo:rustc-env=TOYS_BUILD_DATE={}", date); - // Rebuild when the checked-out commit changes, or the sha is whatever it - // was the first time core compiled and `--version` names the wrong - // commit - worse than one that says "unknown", because it looks right. + // No `rerun-if-changed` at all, which makes cargo run this on every + // build. That is deliberate and it is the only thing that makes the + // stamp true. // - // Watching `.git/HEAD` alone does not do it, and fails two ways at once. - // On a branch checkout that file holds `ref: refs/heads/<branch>` and - // does not change when a commit lands; what moves is the ref it names. - // And in a linked worktree there is no `.git` directory at all - `.git` - // is a file pointing elsewhere - so the path does not exist, which cargo - // reads as "always rerun". Correct output, by accident, and only here. + // Watching `.git/HEAD` does not work: on a branch checkout that file + // holds `ref: refs/heads/<branch>` and does not move when a commit + // lands. Watching the ref it names fixes the commit half - but nothing + // in `.git` moves when a source file is edited, so `-dirty` stayed + // absent while the tree was dirty. A marker that says "clean" over a + // modified tree is worse than no marker: it is a claim, and it is false. // - // So git is asked where these actually live. `--git-path` resolves a - // worktree's real git directory, and the ref is followed to the file - // that moves. packed-refs covers a ref with no loose file of its own, - // and HEAD itself covers a detached checkout, where it holds the sha. - let watch = |path: &str| { - let resolved = Command::new("git") - .args(["rev-parse", "--git-path", path]) - .output() - .ok() - .filter(|o| o.status.success()) - .and_then(|o| String::from_utf8(o.stdout).ok()) - .map(|s| s.trim().to_string()) - .filter(|s| !s.is_empty()); - if let Some(file) = resolved { - println!("cargo:rerun-if-changed={}", file); - } - }; - watch("HEAD"); - watch("packed-refs"); - if let Some(head_ref) = Command::new("git") - .args(["symbolic-ref", "-q", "HEAD"]) - .output() - .ok() - .filter(|o| o.status.success()) - .and_then(|o| String::from_utf8(o.stdout).ok()) - .map(|s| s.trim().to_string()) - .filter(|s| !s.is_empty()) - { - watch(&head_ref); - } - + // The cost was measured rather than feared. The script is three git + // calls; cargo compares the environment it emits and only rebuilds + // dependents when it changes, so a no-op rebuild is 0.03s. The first + // build after the tree goes from clean to dirty relinks the fourteen + // binaries, which is exactly when their stamp has genuinely changed. println!("cargo:rerun-if-env-changed=SOURCE_DATE_EPOCH"); } diff --git a/core/src/lib.rs b/core/src/lib.rs index 82c40c0..268696a 100644 --- a/core/src/lib.rs +++ b/core/src/lib.rs @@ -279,13 +279,25 @@ pub fn cfg_str(cfg: &serde_json::Value, key: &str, fallback: &str) -> String { .to_string() } +/// A list of settings, or the default when nobody has given one. +/// +/// A list that is there and empty is an answer, not the absence of one, and +/// it is the one case the earlier version got wrong: it read `[]` as "unset" +/// and handed back the fallback, so `"hosts": []` had latency pinging two +/// addresses the config had just said it did not want. Absent means nobody +/// has said what they want and a default is a kindness; present means they +/// have, and substituting a list of our own is the widget talking about +/// something it was not asked about. +/// +/// Anything that is not an array at all - a string where a list belongs - +/// is not an answer either, so it falls back with the absent case. pub fn cfg_strings(cfg: &serde_json::Value, key: &str, fallback: &[&str]) -> Vec<String> { match cfg.get(key).and_then(|v| v.as_array()) { - Some(items) if !items.is_empty() => items + Some(items) => items .iter() .filter_map(|v| v.as_str().map(|s| s.to_string())) .collect(), - _ => fallback.iter().map(|s| s.to_string()).collect(), + None => fallback.iter().map(|s| s.to_string()).collect(), } } @@ -527,11 +539,32 @@ pub fn post_json( .map(|(k, v)| (k.trim().to_lowercase(), v.trim().to_string())) .collect(); if !(200..300).contains(&status) { - return Err(format!("HTTP {}", status)); + return Err(refused(status, &body)); } Ok((body, found)) } +/// What a refused POST says: the status, and the body that explains it. +/// +/// The status on its own is the half of a refusal that never says what to +/// do about it. Linear and GitHub put the missing scope, the malformed +/// field and the expired token in the body - which is the case the comment +/// on `post_json` keeps the body for - and returning `HTTP 400` alone sent +/// a reader to the API documentation for something the API had already +/// explained. +/// +/// Squeezed onto one line and capped the way every other subprocess +/// complaint here is, so an HTML error page cannot take the whole pane. +fn refused(status: u16, body: &str) -> String { + let said: String = body.split_whitespace().collect::<Vec<_>>().join(" "); + let said: String = said.chars().take(200).collect(); + if said.is_empty() { + format!("HTTP {}", status) + } else { + format!("HTTP {}: {}", status, said) + } +} + /// Split curl's `--dump-header -` output into its last header block and /// the body under it. /// @@ -1113,7 +1146,12 @@ fn decode(buf: &mut String, lone_esc: &mut bool) -> Vec<String> { /// the pane kept drawing its last frame as though it were current. /// /// Returns everything the child produced, so a caller that needs the exit -/// status or stderr - to say why a command refused - still has them. +/// status or stderr - to say why a command refused - still has them. Both +/// pipes are captured for that reason: `run` below and `ports`'s `refusal` +/// each read `stderr` to name a refusal, and while it was sent to /dev/null +/// they had nothing to read, so "tailscale serve needs an operator" and +/// every other permission, login and bad-argument message arrived as an +/// exit status or as the word "refused". pub fn run_full(args: &[&str], seconds: u64) -> Result<std::process::Output, String> { use std::process::{Command, Stdio}; use std::sync::mpsc; @@ -1124,14 +1162,14 @@ pub fn run_full(args: &[&str], seconds: u64) -> Result<std::process::Output, Str .args(rest) .stdin(Stdio::null()) .stdout(Stdio::piped()) - .stderr(Stdio::null()) + .stderr(Stdio::piped()) .spawn() .map_err(|e| format!("{}: {}", program, e))?; let pid = child.id() as i32; let (tx, rx) = mpsc::channel(); - // wait_with_output drains the pipe while it waits; doing the wait on - // this side and the read afterwards would deadlock on a child that - // fills its stdout buffer. + // wait_with_output drains both pipes while it waits; doing the wait on + // this side and the reads afterwards would deadlock on a child that + // fills its stdout or stderr buffer. std::thread::spawn(move || { let _ = tx.send(child.wait_with_output()); }); @@ -1757,4 +1795,71 @@ mod tests { } out } + + /// A list that is there and empty said something; a list that is not + /// there did not. The first version read both as "unset", so + /// `"hosts": []` had latency pinging the two resolvers its config had + /// just declined. + #[test] + fn an_empty_list_is_an_answer_and_a_missing_one_is_not() { + let fallback = ["1.1.1.1", "8.8.8.8"]; + let said_none = serde_json::json!({ "hosts": [] }); + assert!( + cfg_strings(&said_none, "hosts", &fallback).is_empty(), + "an empty list is the answer, not the absence of one" + ); + let silent = serde_json::json!({ "window": 600 }); + assert_eq!( + cfg_strings(&silent, "hosts", &fallback), + vec!["1.1.1.1".to_string(), "8.8.8.8".to_string()], + "nobody said, so the default is a kindness" + ); + // Not a list at all is not an answer either. + let wrong = serde_json::json!({ "hosts": "1.1.1.1" }); + assert_eq!(cfg_strings(&wrong, "hosts", &fallback).len(), 2); + let given = serde_json::json!({ "hosts": ["a.example", "b.example"] }); + assert_eq!( + cfg_strings(&given, "hosts", &fallback), + vec!["a.example".to_string(), "b.example".to_string()] + ); + } + + /// The status names that a request was refused; only the body names + /// what to do about it. + #[test] + fn a_refused_post_carries_what_the_api_said() { + let said = refused(401, "{\"message\":\"Bad credentials\"}"); + assert!(said.contains("401"), "{:?}", said); + assert!(said.contains("Bad credentials"), "{:?}", said); + // A body over several lines still arrives as one row. + let wrapped = refused(403, "{\n \"message\": \"Resource not accessible\"\n}"); + assert!(!wrapped.contains('\n'), "{:?}", wrapped); + assert!(wrapped.contains("Resource not accessible"), "{:?}", wrapped); + // An error page cannot spend the whole pane. + let long = refused(502, &"x".repeat(4000)); + assert!(long.chars().count() < 240, "{} characters", long.chars().count()); + // And a server that says nothing still says which refusal it was. + assert_eq!(refused(500, " \n"), "HTTP 500"); + } + + /// stderr is where a command says why it refused. It was sent to + /// /dev/null, so `run` and `ports`'s `refusal` - both of which read it - + /// had nothing to read, and a permission or login failure arrived as an + /// exit status. + #[test] + fn a_command_that_failed_hands_back_what_it_complained() { + let out = run_full(&["sh", "-c", "echo 'needs an operator' >&2; exit 3"], 5) + .expect("sh ran"); + assert!(!out.status.success()); + assert!( + String::from_utf8_lossy(&out.stderr).contains("needs an operator"), + "stderr was {:?}", + String::from_utf8_lossy(&out.stderr) + ); + let why = run(&["sh", "-c", "echo 'needs an operator' >&2; exit 3"], 5) + .expect_err("exit 3 is an error"); + assert!(why.contains("needs an operator"), "{:?}", why); + // Capturing stderr must not cost stdout on the way past. + assert_eq!(run(&["sh", "-c", "echo fine"], 5).unwrap().trim(), "fine"); + } } From 71c51d704468ab567b7e43dc55e5603588ada080 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Wed, 26 Aug 2026 12:02:43 +0800 Subject: [PATCH 124/147] linear, pr, github, deployments: walk the pages, or say the number is a floor One defect in four widgets: a GraphQL or REST connection was read one page deep and the result printed as a total. Every count below was then a count of the first page, and nothing on screen said so. Where the truncated list drives later work, the fix is to paginate, because a floor marker cannot help - the missing rows are not merely unshown, they are unqueried: - `github` org discovery stopped at 20, and the account list is what every headline is computed from, so a missed org made the numbers wrong rather than short. `pr` had the identical bug feeding `@mine`; orgs past the first page were scopes the board never searched. - `linear` cycles and teams. `TEAMS_QUERY` never asked for `endCursor`, so it could not have been walked whatever the caller did. - `deployments` read one `/v2/teams` response, so later teams' deployments were never requested at all. The walk follows `pagination.next`, dedupes ids because a timestamp cursor repeats the boundary row, and stops on a cursor that does not move. Where the list is only displayed, and the pane has no room for more than it already fetched, the honest fix is cheaper - mark it partial: - `pr` check contexts are capped at 25 and the pane draws 8 rows, so fetching 200 names buys nothing. `totalCount` is one field and exact: the header now reads `25 of 208 fetched`, and `12 total` unchanged when the page was not full. - `pr` pooled searches were already promised as marked in docs/pr.md - per-source `issueCount` was requested and thrown away. The sources overlap so the counts cannot be summed, but the union is no smaller than the largest of them: ` 51 of at least 664 open`. - `linear` members and milestones read `21+` and `25+`. Two new checks refuse the shape that made this invisible: a walked connection must ask for a cursor and hand one back, and a page of milestones must not be reported as every milestone. Uncapped output is byte-identical to before in every case. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- docs/linear.md | 11 +- widgets/src/bin/deployments.rs | 224 +++++++++++++++++++++++++++++++-- widgets/src/bin/github.rs | 79 ++++++++++-- widgets/src/bin/linear.rs | 204 ++++++++++++++++++++++++++---- widgets/src/bin/pr.rs | 166 +++++++++++++++++++++--- 5 files changed, 617 insertions(+), 67 deletions(-) diff --git a/docs/linear.md b/docs/linear.md index e25d082..0a12b4f 100644 --- a/docs/linear.md +++ b/docs/linear.md @@ -91,7 +91,7 @@ decision. backlog / todo / in progress. Not windowed: it answers "how much is there right now", and does not move when you change the window. -**Active cycles** — every team's running cycle, from a single query. Progress +**Active cycles** — every team's running cycle, walked like everything else; one request while they fit a page. Progress bar, points completed against scope, and days remaining. `+175 added` is the number to watch: scope added *after* the cycle opened. A @@ -284,6 +284,15 @@ paged through at 250 records a time. Pagination is capped at 12 pages per query and the header says `truncated` when the cap is reached, rather than quietly reporting a smaller number. +The teams and the active cycles are walked the same way. A cycle walk that +hits the cap makes the heading read `at least 600 running` rather than `600 +running`. Two nested connections are marked rather than walked, because +walking them would re-fetch a whole project record per page to settle a +question that is almost always already settled: a project's `members` row +reads `21+` with a trailing `…`, and its MILESTONES heading `25+`, when +Linear says the page it returned was not the last. Those rows show a page, +not necessarily everything. + ## Keys The board is longer than most panes are tall, and **every section is drawn diff --git a/widgets/src/bin/deployments.rs b/widgets/src/bin/deployments.rs index 77dcfa5..2b5f7f1 100644 --- a/widgets/src/bin/deployments.rs +++ b/widgets/src/bin/deployments.rs @@ -71,21 +71,107 @@ fn api(path: &str, tok: &str) -> Result<serde_json::Value, String> { serde_json::from_str(&body).map_err(|e| e.to_string()) } -/// Every team the token can see, so deployments are not just personal. +/// The team ids in one page of `/v2/teams`, and the cursor for the next. /// -/// An empty list on failure is deliberate: the personal scope still works, -/// and a widget that refused to start because one endpoint was down would -/// be worse than one showing fewer rows. -fn discover_teams(tok: &str) -> Vec<String> { - let Ok(res) = api("/v2/teams", tok) else { - return Vec::new(); - }; - res["teams"] +/// Vercel pages every list endpoint the same way: `pagination.next` is the +/// timestamp to hand back as `until`, and it is null on the last page. +/// Split out so the paging can be tested without a token. +fn teams_page(res: &serde_json::Value) -> (Vec<String>, Option<i64>) { + let ids = res["teams"] .as_array() .into_iter() .flatten() .filter_map(|t| t["id"].as_str().map(String::from)) - .collect() + .collect(); + let next = &res["pagination"]["next"]; + // Documented as a number; read as a string too, because a cursor that + // arrives quoted would otherwise stop the walk one page in and look + // exactly like an account with fewer teams in it. + let next = next + .as_i64() + .or_else(|| next.as_str().and_then(|s| s.parse().ok())); + (ids, next) +} + +/// How many pages of teams to walk before giving up on the cursor. +const TEAM_PAGES: usize = 20; + +/// Every team the token can see, so deployments are not just personal. +/// +/// All of them, which took a second version: the endpoint answers one page +/// at a time and the first version asked once. Deployments are then never +/// requested for the teams that were on the pages nobody asked for, while +/// the widget goes on describing itself as covering every team the token +/// can see - a partial board presented as a whole one. +/// +/// An empty list on failure is deliberate and stays: the personal scope +/// still works, and a widget that refused to start because one endpoint was +/// down would be worse than one showing fewer rows. The *silence* was not +/// deliberate, so what comes back beside the ids is why the walk stopped, +/// for the screen to say out loud. +fn discover_teams(tok: &str) -> (Vec<String>, Option<String>) { + walk_teams(|until| { + let mut path = "/v2/teams?limit=100".to_string(); + if let Some(mark) = until { + path += &format!("&until={}", mark); + } + api(&path, tok) + }) +} + +/// The walk itself, over whatever is answering. +/// +/// The fetch is a parameter so the paging can be tested without a token, +/// and paging is exactly what was wrong: one page was read and the rest of +/// the teams were never asked about. On this machine that is the only half +/// of this function anything can check. +fn walk_teams( + mut fetch: impl FnMut(Option<i64>) -> Result<serde_json::Value, String>, +) -> (Vec<String>, Option<String>) { + let mut ids: Vec<String> = Vec::new(); + let mut until: Option<i64> = None; + for _ in 0..TEAM_PAGES { + let res = match fetch(until) { + Ok(res) => res, + Err(said) => { + let stopped = if ids.is_empty() { + format!("could not list teams ({}) - personal scope only", said) + } else { + format!("team list stopped early ({}) - teams may be missing", said) + }; + return (ids, Some(stopped)); + } + }; + let (page, next) = teams_page(&res); + for id in page { + // The cursor is a creation timestamp and the boundary team can + // come back on both sides of it. A repeated id would be a + // repeated scope: the same deployments fetched twice and listed + // twice. + if !ids.contains(&id) { + ids.push(id); + } + } + match next { + None => return (ids, None), + // A cursor that has not moved would ask for the same page for + // ever. Stopping is right; stopping quietly is not. + Some(mark) if Some(mark) == until => { + return ( + ids, + Some("team list stopped early (the cursor stopped moving)".into()), + ) + } + Some(mark) => until = Some(mark), + } + } + ( + ids, + Some(format!( + "team list stopped early (more than {} pages) - teams may be missing", + TEAM_PAGES + )), + ) } /// Per-deployment detail: why it failed, timings, regions, aliases. @@ -774,8 +860,14 @@ fn main() { let name = tc::cfg_str(&cfg, "token_env", "VERCEL_TOKEN"); if name.is_empty() { "VERCEL_TOKEN".to_string() } else { name } }; + // Why the discovered scope is not everything, when it is not. Kept for + // the poller rather than said once: `err` is rebuilt every round, and a + // board that is missing a team goes on missing it every round too. + let mut scope_note: Option<String> = None; if !tok.is_empty() && teams.is_empty() { - teams = discover_teams(&tok); + let (found, stopped) = discover_teams(&tok); + teams = found; + scope_note = stopped; } let state = Arc::new(Mutex::new(State::default())); @@ -786,6 +878,7 @@ fn main() { let poll_projects = projects.clone(); let poll_token = tok.clone(); let poll_env = env_name.clone(); + let poll_scope = scope_note.clone(); std::thread::spawn(move || loop { if poll_token.is_empty() { if let Ok(mut guard) = poller.lock() { @@ -842,12 +935,21 @@ fn main() { if let Ok(mut guard) = poller.lock() { // A failed round keeps the last good list rather than // blanking the board: stale rows with a message beside them - // say more than an empty screen does. + // say more than an empty screen does. Judged on this round's + // own error, before the standing one is added to it: a scope + // that was never complete is not a round that failed. if !out.is_empty() || err.is_empty() { guard.deployments = out; guard.fetched = now(); } - guard.err = err; + // A scope that was never complete is a caveat about which + // teams are being asked at all, so it goes in front of + // whatever this round has to say rather than under it. + guard.err = match (&poll_scope, err.is_empty()) { + (None, _) => err, + (Some(said), true) => said.clone(), + (Some(said), false) => format!("{} · {}", said, err), + }; } } let (lock, cond) = &*poller_wake; @@ -1501,4 +1603,100 @@ mod tests { assert_eq!(titled("INITIALIZING"), "Initializing"); assert_eq!(titled(""), ""); } + + #[test] + fn a_page_of_teams_hands_back_the_cursor_for_the_next_one() { + // The shape Vercel answers with. Reading only `teams` and stopping + // is how a token that can see thirty teams got deployments for the + // first twenty, on a board describing itself as covering them all. + let page = serde_json::json!({ + "teams": [{"id": "team_one"}, {"id": "team_two"}], + "pagination": {"count": 2, "next": 1588720733602i64, "prev": 0} + }); + let (ids, next) = teams_page(&page); + assert_eq!(ids, vec!["team_one".to_string(), "team_two".to_string()]); + assert_eq!(next, Some(1588720733602)); + + // The last page says so with a null cursor, and that is the only + // thing that means the walk is done. + let last = serde_json::json!({ + "teams": [{"id": "team_three"}], + "pagination": {"count": 1, "next": serde_json::Value::Null} + }); + assert_eq!(teams_page(&last).1, None); + + // A quoted cursor is still a cursor: read as absent it would stop + // the walk one page in and look like a smaller account. + let quoted = serde_json::json!({ + "teams": [], "pagination": {"next": "1588720733602"} + }); + assert_eq!(teams_page("ed).1, Some(1588720733602)); + + // An answer with neither in it is an empty page and a finished walk, + // not a panic. + assert_eq!(teams_page(&serde_json::json!({})), (Vec::new(), None)); + } + + #[test] + fn every_page_of_teams_is_asked_for() { + // Three pages, and the second and third are only reached by handing + // the cursor back. The first version of this stopped after page one + // and never requested a deployment for the teams below the fold. + let mut asked: Vec<Option<i64>> = Vec::new(); + let (ids, stopped) = walk_teams(|until| { + asked.push(until); + Ok(match until { + None => serde_json::json!({ + "teams": [{"id": "team_a"}, {"id": "team_b"}], + "pagination": {"next": 300} + }), + // The boundary team comes back on both sides of a timestamp + // cursor; a second copy would be a second scope, fetched and + // listed twice. + Some(300) => serde_json::json!({ + "teams": [{"id": "team_b"}, {"id": "team_c"}], + "pagination": {"next": 200} + }), + _ => serde_json::json!({ + "teams": [{"id": "team_d"}], + "pagination": {"next": serde_json::Value::Null} + }), + }) + }); + assert_eq!(asked, vec![None, Some(300), Some(200)]); + assert_eq!(ids, ["team_a", "team_b", "team_c", "team_d"]); + assert_eq!(stopped, None, "a complete walk has nothing to explain"); + + // A page that fails halfway leaves a list that is not the whole + // list, and says so - the board is missing a team either way, and + // the difference is whether the screen admits it. + let (some, stopped) = walk_teams(|until| match until { + None => Ok(serde_json::json!({ + "teams": [{"id": "team_a"}], "pagination": {"next": 300} + })), + _ => Err("curl exited 28".into()), + }); + assert_eq!(some, ["team_a"]); + let said = stopped.expect("a half-read list has to say so"); + assert!(said.contains("curl exited 28"), "{}", said); + + // Nothing at all still starts the widget on the personal scope, and + // still explains why that is all there is. + let (none, stopped) = walk_teams(|_| Err("HTTP 403".into())); + assert!(none.is_empty()); + assert!(stopped.unwrap_or_default().contains("HTTP 403")); + + // A cursor that never moves is a walk that would never end. It stops, + // and it does not pretend the list is complete. + let mut rounds = 0; + let (ids, stopped) = walk_teams(|_| { + rounds += 1; + Ok(serde_json::json!({ + "teams": [{"id": "team_a"}], "pagination": {"next": 300} + })) + }); + assert_eq!(ids, ["team_a"]); + assert!(rounds <= TEAM_PAGES, "the walk ran {} times", rounds); + assert!(stopped.is_some(), "a walk that gave up has to say so"); + } } diff --git a/widgets/src/bin/github.rs b/widgets/src/bin/github.rs index 31c8796..14288fe 100644 --- a/widgets/src/bin/github.rs +++ b/widgets/src/bin/github.rs @@ -845,6 +845,21 @@ fn palette() -> Palette { } } +/// One page of the orgs the viewer belongs to, from `after` onwards. +/// +/// A hundred at a time, and the caller follows `endCursor` until GitHub +/// says there is no next page. +fn orgs_query(after: Option<&str>) -> String { + let at = match after { + Some(c) => format!(", after: {}", serde_json::Value::String(c.to_string())), + None => String::new(), + }; + format!( + "{{ viewer {{ login organizations(first: 100{}) {{ pageInfo {{ hasNextPage endCursor }} nodes {{ login }} }} }} }}", + at + ) +} + #[allow(clippy::too_many_arguments)] fn one_pass( tok: &str, @@ -879,19 +894,39 @@ fn one_pass( } let mut accounts = state.lock().map(|g| g.accounts.clone()).unwrap_or_default(); if accounts.is_empty() { - // Every org you belong to, plus your own account. - let d = graphql( - "{ viewer { login organizations(first:20) { nodes { login } } } }", - tok, - scopes, - )?; - accounts = d["data"]["viewer"]["organizations"]["nodes"] - .as_array() - .into_iter() - .flatten() - .map(|o| o["login"].as_str().unwrap_or("").to_string()) - .filter(|s| !s.is_empty()) - .collect(); + // Every org you belong to, plus your own account - and *every* is + // what docs/github.md promises for an empty `accounts`. One page of + // twenty kept that promise only for people who belong to fewer than + // twenty; past that the extra orgs were not undercounted, they were + // never asked about, and every headline on the board was a total + // over an account list that nothing on screen said was short. So + // the cursor is followed to the end. + let mut cursor: Option<String> = None; + loop { + let d = graphql(&orgs_query(cursor.as_deref()), tok, scopes)?; + let conn = &d["data"]["viewer"]["organizations"]; + accounts.extend( + conn["nodes"] + .as_array() + .into_iter() + .flatten() + .map(|o| o["login"].as_str().unwrap_or("").to_string()) + .filter(|s| !s.is_empty()), + ); + let next = conn["pageInfo"]["endCursor"] + .as_str() + .unwrap_or("") + .to_string(); + // This runs on the poller thread: a cursor that stops advancing + // has to end the loop rather than spin it. + if !conn["pageInfo"]["hasNextPage"].as_bool().unwrap_or(false) + || next.is_empty() + || Some(&next) == cursor.as_ref() + { + break; + } + cursor = Some(next); + } accounts.push("@me".into()); if let Ok(mut g) = state.lock() { g.accounts = accounts.clone(); @@ -1963,6 +1998,24 @@ mod tests { assert_eq!(scope_warning(&Scopes::default()), ""); } + #[test] + fn org_discovery_follows_the_cursor() { + // The first page asks for no cursor at all, and for the page + // information that says whether there is another. + let first = orgs_query(None); + assert!(first.contains("organizations(first: 100)"), "{}", first); + assert!(first.contains("hasNextPage") && first.contains("endCursor")); + // A cursor is a string GitHub chose, so it goes in quoted rather + // than pasted: it has carried `=` and `==` for as long as it has + // been base64. + let next = orgs_query(Some("Y3Vyc29yOnYyOpHOAAQ=")); + assert!( + next.contains(r#"organizations(first: 100, after: "Y3Vyc29yOnYyOpHOAAQ=")"#), + "{}", + next + ); + } + #[test] fn an_account_scopes_its_own_search() { assert_eq!(scope_of("acme", "wiiiimm"), "org:acme"); diff --git a/widgets/src/bin/linear.rs b/widgets/src/bin/linear.rs index 712c050..6d1ca38 100644 --- a/widgets/src/bin/linear.rs +++ b/widgets/src/bin/linear.rs @@ -177,9 +177,16 @@ query($after: String, $since: DateTimeOrDuration!) {{ ) } +/// The running cycles, walked to the end. +/// +/// Fifty is more than most workspaces have running at once - which is +/// exactly why the fifty-first used to go missing without a word. Walking +/// costs nothing while they fit one page: `pages` stops the moment Linear +/// says there is no next one, so the common case is the one request it +/// always was. const CYCLES_QUERY: &str = r#" -{ - cycles(first: 50, filter: { isActive: { eq: true } }) { +query($after: String) { + cycles(first: 50, after: $after, filter: { isActive: { eq: true } }) { nodes { id name number startsAt endsAt progress issueCountHistory completedIssueCountHistory @@ -221,14 +228,28 @@ query($id: String!) { id name url description startedAt completedAt scopeHistory completedScopeHistory issueCountHistory completedIssueCountHistory - members(first: 20) { nodes { name } } - projectMilestones(first: 25) { nodes { name targetDate progress } } - initiatives(first: 5) { nodes { name } } + members(first: 20) { nodes { name } pageInfo { hasNextPage } } + projectMilestones(first: 25) { + nodes { name targetDate progress } + pageInfo { hasNextPage } + } + initiatives(first: 5) { nodes { name } pageInfo { hasNextPage } } } }"#; +/// Every team, walked to the end. +/// +/// This is the list every other figure on the board is filtered through, so +/// a team missing from it takes its issues, its cycles and its projects with +/// it - and the board would have said nothing. It asked for `hasNextPage` +/// and never read it. const TEAMS_QUERY: &str = r#" -{ teams(first: 100) { nodes { key name } pageInfo { hasNextPage } } }"#; +query($after: String) { + teams(first: 100, after: $after) { + nodes { key name } + pageInfo { hasNextPage endCursor } + } +}"#; fn text(value: &serde_json::Value, key: &str) -> String { value[key].as_str().unwrap_or("").to_string() @@ -523,6 +544,10 @@ struct State { /// the keys have asked for. window: i64, truncated: bool, + /// The cycle walk stopped at the page cap, so `cycles` is a floor. Kept + /// apart from `truncated`, which is drawn against the open-issue count + /// and would be pointing at the wrong number. + cycles_capped: bool, err: String, fetched: f64, } @@ -556,11 +581,13 @@ fn one_pass( .format("%Y-%m-%dT00:00:00.000Z") .to_string(); - let teams_res = graphql(TEAMS_QUERY, tok, serde_json::json!({}), quota)?; - let teams: Vec<(String, String)> = teams_res["teams"]["nodes"] - .as_array() - .into_iter() - .flatten() + // Every counter below is filtered through these keys, so a team left + // off the end of the first page understates all of them at once. The + // cap joins the board's own truncation marker for that reason. + let (team_nodes, cap_teams) = + pages(tok, TEAMS_QUERY, &["teams"], &serde_json::json!({}), quota)?; + let teams: Vec<(String, String)> = team_nodes + .iter() .map(|t| (text(t, "key"), text(t, "name"))) .filter(|(key, _)| wanted(key)) .collect(); @@ -650,13 +677,11 @@ fn one_pass( } // The running cycles, each already carrying its own burndown. - let cycles_res = graphql(CYCLES_QUERY, tok, serde_json::json!({}), quota)?; - let cycles: Vec<serde_json::Value> = cycles_res["cycles"]["nodes"] - .as_array() + let (cycle_nodes, cycles_capped) = + pages(tok, CYCLES_QUERY, &["cycles"], &serde_json::json!({}), quota)?; + let cycles: Vec<serde_json::Value> = cycle_nodes .into_iter() - .flatten() .filter(|c| keys.contains(&text(&c["team"], "key"))) - .cloned() .collect(); // Every project, filed under each team that owns it. A project can be @@ -780,7 +805,8 @@ fn one_pass( guard.oldest_open = oldest_open; guard.oldest_wip = oldest_wip; guard.window = days; - guard.truncated = capped || cap2 || cap3 || cap4; + guard.truncated = capped || cap2 || cap3 || cap4 || cap_teams; + guard.cycles_capped = cycles_capped; guard.fetched = now(); guard.err = if source == "config" { tc::config_token_warning().unwrap_or_default() @@ -850,6 +876,19 @@ fn state_colour<'a>(state: &str, p: &'a Palette) -> &'a str { } } +/// How many cycles are running - or, when the walk stopped at the page cap, +/// how many are known to be running. +/// +/// A count that stopped counting is a floor, and saying "at least" is the +/// difference between a board that is quiet and a board that gave up. +fn running_label(n: usize, capped: bool) -> String { + if capped { + format!("at least {} running", n) + } else { + format!("{} running", n) + } +} + fn state_label(state: &str) -> &'static str { match state { "triage" => "triage", @@ -1499,11 +1538,18 @@ fn project_detail( .map(|m| text(m, "name")) .filter(|n| !n.is_empty()) .collect(); + // A page of members, not necessarily every member. Paginating it + // would mean asking for the whole project record again - burn-up, + // milestones and all - per page, every time this screen opens, to + // settle a question that is almost always already settled. So the + // connection says whether there are more and the row carries it: + // "21+" is honest where "21" would be wrong. + let more = v["members"]["pageInfo"]["hasNextPage"].as_bool().unwrap_or(false); if !names.is_empty() { field( "members", - names.len().to_string(), - names.join(", "), + if more { format!("{}+", names.len()) } else { names.len().to_string() }, + if more { format!("{}, …", names.join(", ")) } else { names.join(", ") }, p.dim.as_str(), ); } @@ -1588,6 +1634,9 @@ fn project_detail( // Milestones, in the order they fall due. Linear returns them in no // order at all, and a list of dates out of order reads as noise. + let more_stones = v["projectMilestones"]["pageInfo"]["hasNextPage"] + .as_bool() + .unwrap_or(false); let mut stones: Vec<(String, String, f64)> = v["projectMilestones"]["nodes"] .as_array() .into_iter() @@ -1612,7 +1661,16 @@ fn project_detail( rows.push(tc::seg( &[ (p.lbl.as_str(), " ── MILESTONES ── ".into()), - (p.dim.as_str(), format!("{}", stones.len())), + // Same rule as the members row: a page of milestones is not + // necessarily every milestone, and "25" would say it was. + ( + p.dim.as_str(), + if more_stones { + format!("{}+", stones.len()) + } else { + stones.len().to_string() + }, + ), ], w - 1, )); @@ -2222,7 +2280,7 @@ fn main() { if here_now { p.accent.as_str() } else { p.lbl.as_str() }, " ── ACTIVE CYCLES ── ".into(), ), - (p.dim.as_str(), format!("{} running", s.cycles.len())), + (p.dim.as_str(), running_label(s.cycles.len(), s.cycles_capped)), ( if here_now { p.accent.as_str() } else { p.dim.as_str() }, heading_keys(cycles_pane, focus, &pane_len).to_string(), @@ -3288,6 +3346,110 @@ mod tests { assert!(!out.contains("asking Linear"), "{}", out); } + #[test] + fn a_page_of_milestones_is_not_reported_as_every_milestone() { + // The same rule one heading down. MILESTONES printed the length of + // the page it was given, so a project with more than the twenty-five + // asked for read as a project with exactly twenty-five. + let q = a_project("p1", "hallway-lights", "In Progress", "started", 0.5); + let stones = |more: bool| { + serde_json::json!({ + "projectMilestones": { + "nodes": [ + { "name": "kick-off", "targetDate": "2026-09-03", "progress": 100.0 }, + { "name": "cutover", "targetDate": "2026-09-05", "progress": 0.0 }, + ], + "pageInfo": { "hasNextPage": more }, + }, + }) + }; + let shown = |v: &serde_json::Value| { + plain(&project_detail(&q, "ABC", Some(v), &HashMap::new(), None, 100, &palette())) + }; + let out = shown(&stones(true)); + assert!(out.contains("MILESTONES ── 2+"), "a page that did not end is a floor:\n{}", out); + let out = shown(&stones(false)); + assert!(out.contains("MILESTONES ── 2"), "{}", out); + assert!(!out.contains("2+"), "nothing is missing, so nothing is marked:\n{}", out); + + // A record from before the flag was asked for reads as a plain total + // rather than as suspect - the same allowance the members row makes. + let old = serde_json::json!({ + "projectMilestones": { "nodes": [ + { "name": "kick-off", "targetDate": "2026-09-03", "progress": 100.0 }, + ]}, + }); + assert!(!shown(&old).contains("1+"), "no flag is not the same as a flag saying more"); + } + + #[test] + fn a_page_of_members_is_not_reported_as_every_member() { + let q = a_project("p1", "hallway-lights", "In Progress", "started", 0.5); + // Linear hands back a page and says whether there are more. The row + // used to count the page and print the figure as the project's + // membership, which for a project with more members than a page + // holds is a wrong number, not a rounded one. + let record = serde_json::json!({ + "members": { + "nodes": [ { "name": "ada" }, { "name": "grace" } ], + "pageInfo": { "hasNextPage": true }, + }, + }); + let out = + plain(&project_detail(&q, "ABC", Some(&record), &HashMap::new(), None, 100, &palette())); + assert!(out.contains("2+"), "a page that did not end is a floor:\n{}", out); + assert!(out.contains("ada, grace, …"), "and the list says so too:\n{}", out); + + // The connection ended, so the count is the count. + let record = serde_json::json!({ + "members": { + "nodes": [ { "name": "ada" }, { "name": "grace" } ], + "pageInfo": { "hasNextPage": false }, + }, + }); + let out = + plain(&project_detail(&q, "ABC", Some(&record), &HashMap::new(), None, 100, &palette())); + assert!(!out.contains("2+"), "nothing is missing, so nothing is marked:\n{}", out); + assert!(out.contains("ada, grace"), "{}", out); + assert!(!out.contains('…'), "{}", out); + + // A record with no pageInfo at all - an older shape, or a fixture - + // reads as complete rather than as suspect. + let record = serde_json::json!({ "members": { "nodes": [ { "name": "ada" } ] } }); + let out = + plain(&project_detail(&q, "ABC", Some(&record), &HashMap::new(), None, 100, &palette())); + assert!(!out.contains("1+"), "{}", out); + } + + #[test] + fn a_cycle_count_that_stopped_counting_does_not_call_itself_a_total() { + assert_eq!(running_label(4, false), "4 running"); + assert_eq!(running_label(600, true), "at least 600 running"); + } + + #[test] + fn every_walked_connection_asks_for_a_cursor_and_hands_one_back() { + // pages() sends $after and moves on pageInfo.endCursor. A query + // missing either is walked in place: the same first page fetched + // PAGE_CAP times, or one page returned as the whole connection. + // TEAMS_QUERY asked for hasNextPage, offered no endCursor, and was + // not walked at all - which is how a hundred teams became all of + // them. + let walked: [(&str, String); 6] = [ + ("teams", TEAMS_QUERY.into()), + ("cycles", CYCLES_QUERY.into()), + ("projects", PROJECTS_QUERY.into()), + ("open", open_query()), + ("created", created_query()), + ("done", done_query()), + ]; + for (name, q) in &walked { + assert!(q.contains("$after: String"), "{} declares no cursor:\n{}", name, q); + assert!(q.contains("after: $after"), "{} never passes its cursor:\n{}", name, q); + assert!(q.contains("endCursor"), "{} asks for no endCursor:\n{}", name, q); + } + } + #[test] fn milestones_fall_in_date_order_and_their_bars_are_out_of_a_hundred() { let q = a_project("p1", "hallway-lights", "In Progress", "started", 0.5); diff --git a/widgets/src/bin/pr.rs b/widgets/src/bin/pr.rs index fc574fe..29d00cf 100644 --- a/widgets/src/bin/pr.rs +++ b/widgets/src/bin/pr.rs @@ -136,7 +136,7 @@ query($owner: String!, $name: String!, $number: Int!) { reviewRequests(first: 12) { nodes { requestedReviewer { ... on User { login } ... on Team { name } } } } commits(last: 1) { nodes { commit { statusCheckRollup { - state contexts(first: 25) { nodes { + state contexts(first: 25) { totalCount nodes { ... on CheckRun { name conclusion status startedAt completedAt } ... on StatusContext { context state } } } } } } } } @@ -284,6 +284,10 @@ struct State { orgs: Vec<String>, prs: Vec<serde_json::Value>, total: usize, + /// Set when a source filled its page, so `total` is a floor and every + /// count drawn from `prs` describes what was fetched rather than what + /// is open. + capped: bool, query: String, detail: Option<serde_json::Value>, stack_rows: Vec<StackRow>, @@ -434,6 +438,28 @@ fn fetch_detail( Ok(()) } +/// How many open pull requests the pooled sources really cover, and whether +/// that number is a floor rather than a count. +/// +/// A source that filled its page has more behind it, and the sources +/// overlap - `orgs` and `authored` find the same PR all day - so the +/// `issueCount`s cannot be added up. Two things are known exactly: the union +/// holds every distinct PR already in hand, and it holds the whole of any +/// single source, so it is no smaller than the largest `issueCount`. The +/// larger of those is the floor the header reports. When nothing filled its +/// page the pool *is* the union and the number is a plain total. +fn union_total(sources: &[(i64, usize)], pooled: usize) -> (usize, bool) { + let capped = sources.iter().any(|(counted, got)| *counted > *got as i64); + if !capped { + return (pooled, false); + } + let floor = sources + .iter() + .map(|(counted, _)| (*counted).max(0) as usize) + .fold(pooled, usize::max); + (floor, true) +} + fn fetch_list( tok: &str, source: &str, @@ -445,19 +471,50 @@ fn fetch_list( ) -> Result<(), String> { let need_viewer = state.lock().map(|g| g.viewer.is_empty()).unwrap_or(true); if need_viewer { - let who = graphql( - "{ viewer { login organizations(first:20) { nodes { login } } } }", - tok, - serde_json::json!({}), - )?; + // Every org, not the first page of them. `@mine` is built out of + // this list as owner qualifiers, so an org missing here is not an + // undercount - it is a scope the board never searched, and nothing + // downstream can tell that from an org with no open PRs. + let mut login = String::new(); + let mut orgs: Vec<String> = Vec::new(); + let mut cursor: Option<String> = None; + loop { + let who = graphql( + "query($after: String) { viewer { login \ + organizations(first: 100, after: $after) { \ + pageInfo { hasNextPage endCursor } nodes { login } } } }", + tok, + serde_json::json!({ "after": cursor }), + )?; + if login.is_empty() { + login = text(&who["viewer"], "login"); + } + let conn = &who["viewer"]["organizations"]; + orgs.extend( + conn["nodes"] + .as_array() + .into_iter() + .flatten() + .map(|o| text(o, "login")) + .filter(|o| !o.is_empty()), + ); + let next = conn["pageInfo"]["endCursor"] + .as_str() + .unwrap_or("") + .to_string(); + // This runs on the poller thread: a cursor that stops advancing + // has to end the loop rather than spin it. + if !conn["pageInfo"]["hasNextPage"].as_bool().unwrap_or(false) + || next.is_empty() + || Some(&next) == cursor.as_ref() + { + break; + } + cursor = Some(next); + } if let Ok(mut g) = state.lock() { - g.viewer = text(&who["viewer"], "login"); - g.orgs = who["viewer"]["organizations"]["nodes"] - .as_array() - .into_iter() - .flatten() - .map(|o| text(o, "login")) - .collect(); + g.viewer = login; + g.orgs = orgs; } } let (viewer, orgs) = state @@ -476,6 +533,7 @@ fn fetch_list( // source filled its page, so a truncated union is not read as a total. let mut pool: HashMap<String, serde_json::Value> = HashMap::new(); let mut order: Vec<String> = Vec::new(); + let mut counted: Vec<(i64, usize)> = Vec::new(); for (i, (name, _)) in pairs.iter().enumerate() { let block = &d[format!("s{}", i)]; let got: Vec<&serde_json::Value> = block["nodes"] @@ -484,6 +542,8 @@ fn fetch_list( .flatten() .filter(|n| !n.is_null()) .collect(); + // What the search says it matched, beside what it handed over. + counted.push((block["issueCount"].as_i64().unwrap_or(0), got.len())); for n in got { let url = text(n, "url"); let entry = pool.entry(url.clone()).or_insert_with(|| { @@ -507,7 +567,9 @@ fn fetch_list( .map(|(n, _)| n.clone()) .collect::<Vec<_>>() .join(", "); - g.total = nodes.len(); + let (total, capped) = union_total(&counted, nodes.len()); + g.total = total; + g.capped = capped; g.prs = nodes; g.fetched = now(); g.err = if source == "config" { @@ -775,11 +837,12 @@ fn main() { loop { tick += 1; - let (prs, total, detail, stack_rows, loading, err, fetched, stages, target) = + let (prs, total, capped, detail, stack_rows, loading, err, fetched, stages, target) = match state.lock() { Ok(g) => ( g.prs.clone(), g.total, + g.capped, g.detail.clone(), g.stack_rows.clone(), g.loading, @@ -957,7 +1020,19 @@ fn main() { let (w, h) = tc::size(); let mut rows = vec![tc::title("pr watch", w, &p.pr)]; let mut head = vec![ - (p.dim.as_str(), format!(" {} of {}", shown.len(), total)), + // "at least", because a source that filled its page has more + // behind it and the sources overlap, so the union cannot be + // added up - only bounded from below. docs/pr.md has promised + // the header would say so since before the port. + ( + p.dim.as_str(), + format!( + " {} of {}{}", + shown.len(), + if capped { "at least " } else { "" }, + total + ), + ), ( p.dim.as_str(), if !needle.is_empty() || source_filter != "all" { @@ -1045,6 +1120,8 @@ fn main() { // board, not a redefinition of it. rows.extend(stats_view( &sort_prs(&prs, SORTS[sort_at], newest_first), + total, + capped, w, &p, )); @@ -1112,7 +1189,13 @@ fn main() { /// median and the state bar lurch on every keystroke made them unreadable /// and, worse, made them look like statements about the whole board when /// they described three matching rows. -fn stats_view(prs: &[serde_json::Value], w: usize, p: &Palette) -> Vec<String> { +fn stats_view( + prs: &[serde_json::Value], + total: usize, + capped: bool, + w: usize, + p: &Palette, +) -> Vec<String> { let mut rows = vec![String::new()]; if prs.is_empty() { return rows; @@ -1153,7 +1236,17 @@ fn stats_view(prs: &[serde_json::Value], w: usize, p: &Palette) -> Vec<String> { &[ (p.lbl.as_str(), " ── STATE ── ".into()), (p.txt.as_str(), format!("{}", n)), - (p.dim.as_str(), " open · ".into()), + // Everything after this counts the PRs in hand. When a source + // filled its page they are a sample of the board rather than + // the board, and the line has to say which it is describing. + ( + p.dim.as_str(), + if capped { + format!(" fetched of at least {} open · ", total) + } else { + " open · ".to_string() + }, + ), (p.dim.as_str(), format!("{} draft", drafts)), (p.dim.as_str(), " · ".into()), ( @@ -1860,11 +1953,28 @@ fn detail_view( .flatten() .filter(|c| !c.is_null()) .collect(); + // The query asks for one page of contexts, and a repository with + // more of them than that fits sent back a page rather than all of + // them - so `ctx.len()` is how many arrived, not how many ran. The + // rollup reports the true count for a point of field complexity, and + // a run that is missing here is exactly the one worth knowing about: + // a failure outside the page cannot be named, only counted. + let counted = roll["contexts"]["totalCount"].as_i64().unwrap_or(0).max(0) as usize; + // Never below what is in hand: a missing field must not turn eleven + // checks into "11 of 0". + let counted = counted.max(ctx.len()); rows.push(tc::seg( &[ (p.lbl.as_str(), " ── CHECKS ── ".into()), (scol, state.into()), - (p.dim.as_str(), format!(" {} total", ctx.len())), + ( + p.dim.as_str(), + if ctx.len() < counted { + format!(" {} of {} fetched", ctx.len(), counted) + } else { + format!(" {} total", counted) + }, + ), ], w - 1, )); @@ -2118,6 +2228,24 @@ mod tests { assert!(root.is_some()); } + #[test] + fn a_page_that_filled_up_turns_the_total_into_a_floor() { + // Nothing filled its page: the pool is the union, exactly. + assert_eq!(union_total(&[(30, 30), (12, 12)], 35), (35, false)); + // `orgs` filled its page of 50 with 212 behind it. The sources + // overlap, so 212 + 12 would be nonsense - but the union contains + // the whole of `orgs`, so it holds at least 212. + assert_eq!(union_total(&[(212, 50), (12, 12)], 58), (212, true)); + // A capped source can still be smaller than what is already pooled, + // and then the pool is the better floor of the two. + assert_eq!(union_total(&[(51, 50), (3, 3)], 53), (53, true)); + // One source, capped, with nothing else to add to it. + assert_eq!(union_total(&[(60, 50)], 50), (60, true)); + // No sources is no floor, and above all not a claim of zero open + // PRs dressed up as one. + assert_eq!(union_total(&[], 0), (0, false)); + } + #[test] fn mine_expands_to_every_org_plus_the_account() { let sources = vec![ From ad6ce04d714c53ef5bbf23a051977ee1f62b1f96 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Wed, 26 Aug 2026 12:02:57 +0800 Subject: [PATCH 125/147] herdr-panes, tailnet, latency: a probe that failed is not a quiet source MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The founding rule cuts both ways: every number on screen is real, and so every *absence* on screen has to be real too. In three widgets a failed probe rendered as the same blank the truth would have rendered as. `herdr-panes` was the worst of the three, and worse than reported. A failed `pane process-info` exits 0 and prints `{"error":{...}}` with no `result`, so the run succeeded, the JSON parsed, and the reader returned the same `None` it returns for a pane sitting at its prompt. Failure was undetectable by status - only by shape. `result_of` now tells the three apart, `foreground` answers Running / Prompt / Unknown(why) rather than a bool, and an unread pane sorts to the top of PROCESSES with its reason on its own row, because at 80 columns the heading clips exactly where the reason would start. `[i]` hides only panes known to be at a prompt, so an unreadable one cannot be filtered out of sight. `tailnet` showed a cached peer list with no hint the refresh behind it had failed; the banner now carries `data_at`. Its prober grew the error field latency already had, a backoff so a failing probe stops spinning, and `probing…` on self rather than nothing. `latency` said `collecting…` forever when no hosts were configured - indistinguishable from hosts that had not answered yet. With an empty target list it now says so and names the key to set. `deployments`' team walk seeds the widget's error line on every poll round rather than being overwritten by that round's own error, so an early stop cannot pass for a short list. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- widgets/src/bin/herdr-panes.rs | 366 +++++++++++++++++++++++++++------ widgets/src/bin/latency.rs | 68 +++++- widgets/src/bin/tailnet.rs | 143 +++++++++++-- 3 files changed, 486 insertions(+), 91 deletions(-) diff --git a/widgets/src/bin/herdr-panes.rs b/widgets/src/bin/herdr-panes.rs index 1708cd4..0a7eeb3 100644 --- a/widgets/src/bin/herdr-panes.rs +++ b/widgets/src/bin/herdr-panes.rs @@ -55,18 +55,42 @@ fn herdr_action(args: &[&str]) -> bool { tc::run(&argv, RUN_TIMEOUT).is_ok() } -/// Run a herdr command and hand back the `result` object it printed. -fn herdr(args: &[&str]) -> Option<serde_json::Value> { - let mut argv = vec!["herdr"]; - argv.extend_from_slice(args); - let text = tc::run(&argv, RUN_TIMEOUT).ok()?; - let parsed: serde_json::Value = serde_json::from_str(&text).ok()?; +/// The `result` object out of one herdr answer, or why there is none. +/// +/// Split from the running of the command, because the running is not where +/// the failure shows: herdr answers a request it cannot serve with an +/// `error` object and exit status 0, so a pane that does not exist and a +/// pane with nothing to say arrive as two commands that both succeeded. +/// They are told apart by shape here or they are not told apart at all. +fn result_of(text: &str) -> Result<serde_json::Value, String> { + let parsed: serde_json::Value = + serde_json::from_str(text).map_err(|e| format!("unreadable answer: {}", e))?; + if let Some(said) = parsed.get("error") { + let message = said["message"].as_str().unwrap_or("").trim(); + return Err(if message.is_empty() { + format!("herdr said {}", said) + } else { + message.to_string() + }); + } match parsed.get("result") { - Some(serde_json::Value::Null) | None => None, - Some(value) => Some(value.clone()), + Some(serde_json::Value::Null) | None => Err("herdr answered with no result".into()), + Some(value) => Ok(value.clone()), } } +/// Run a herdr command and hand back its `result`, or why there is none. +fn herdr_result(args: &[&str]) -> Result<serde_json::Value, String> { + let mut argv = vec!["herdr"]; + argv.extend_from_slice(args); + result_of(&tc::run(&argv, RUN_TIMEOUT)?) +} + +/// The same, for the callers that have nothing to do with the reason. +fn herdr(args: &[&str]) -> Option<serde_json::Value> { + herdr_result(args).ok() +} + /// Keep the end of a path, marking the cut so it does not read as a name. fn tail_path(path: &str, n: usize) -> String { let chars: Vec<char> = path.chars().collect(); @@ -218,7 +242,32 @@ fn showing(window: &std::ops::Range<usize>, first: usize, len: usize) -> String } } -/// A pane with no agent in it: either running something, or at a prompt. +/// What a pane with no agent in it is doing. +/// +/// Three states rather than a bool, because the third one is real: a pane +/// whose probe failed is neither running nor resting, and filing it as +/// either says something true has been established when nothing has. +#[derive(Clone, Copy, Debug, Default, PartialEq)] +enum Doing { + Running, + Prompt, + /// `pane process-info` did not answer. The default, because a pane + /// nobody has managed to look at has told us nothing. + #[default] + Unknown, +} + +/// Unreadable first, then what is running, then the prompts: the row that +/// wants looking at is the one where the widget cannot say. +fn doing_rank(doing: Doing) -> usize { + match doing { + Doing::Unknown => 0, + Doing::Running => 1, + Doing::Prompt => 2, + } +} + +/// A pane with no agent in it: running something, at a prompt, or unread. #[derive(Clone, Default)] struct Panel { pane_id: String, @@ -226,7 +275,11 @@ struct Panel { workspace_id: String, command: String, cwd: String, - idle: bool, + doing: Doing, + /// Why the probe failed, when it did. Carried rather than counted: a + /// number of panes nobody could read is a smaller answer than "pane + /// not found" or "herdr did not answer in 15s". + why: String, cpu: Option<f64>, rss: Option<u64>, } @@ -268,18 +321,43 @@ fn text_at(value: &serde_json::Value, key: &str) -> String { value[key].as_str().unwrap_or("").to_string() } -/// The foreground process of a pane, if it is running one. +/// What a pane's foreground process is, or why we could not tell. /// -/// A pane sitting at its shell prompt has nothing to report, and the test -/// for that is that the foreground pid is the shell's own. -fn foreground(pane_id: &str) -> Option<(i32, Vec<String>, String, String)> { - let info = herdr(&["pane", "process-info", "--pane", pane_id])?; +/// Three answers rather than two, and that is the whole point of the type. +/// A pane at its shell prompt and a probe that failed used to arrive here +/// as the same `None`, and the caller wrote that down as idle - so a herdr +/// that had stopped answering turned a board full of working panes into a +/// board full of resting ones, with nothing on screen saying otherwise. +enum Front { + /// Running something: its pid, argv, name and directory. + Running(i32, Vec<String>, String, String), + /// At its shell prompt - the foreground pid is the shell's own. + Prompt, + /// The probe did not answer, so which of the two this is nobody knows. + Unknown(String), +} + +/// What one `pane process-info` answer says the pane is doing. +/// +/// Split from the request so all three answers can be tested on a value +/// rather than on a live Herdr, the way `parse_proc_stat` is. +fn classify(info: &serde_json::Value) -> Front { let process = &info["process_info"]; - let front = process["foreground_processes"].as_array()?.first()?.clone(); - let pid = front["pid"].as_i64()? as i32; - let busy = process["shell_pid"].as_i64() != Some(pid as i64); - if !busy { - return None; + let Some(front) = process["foreground_processes"] + .as_array() + .and_then(|a| a.first()) + else { + return Front::Unknown("no foreground process reported".into()); + }; + let Some(pid) = front["pid"].as_i64() else { + return Front::Unknown("foreground process has no pid".into()); + }; + // The shell's own pid in the foreground is the prompt being what is in + // the foreground. An absent `shell_pid` is not that - it says nothing - + // so it goes on as running rather than resting, which is the direction + // that cannot repeat the bug this type exists for. + if process["shell_pid"].as_i64() == Some(pid) { + return Front::Prompt; } let argv = front["argv"] .as_array() @@ -289,7 +367,20 @@ fn foreground(pane_id: &str) -> Option<(i32, Vec<String>, String, String)> { .collect() }) .unwrap_or_default(); - Some((pid, argv, text_at(&front, "name"), text_at(&front, "cwd"))) + Front::Running( + pid as i32, + argv, + text_at(front, "name"), + text_at(front, "cwd"), + ) +} + +/// The foreground process of a pane, the prompt, or the failed probe. +fn foreground(pane_id: &str) -> Front { + match herdr_result(&["pane", "process-info", "--pane", pane_id]) { + Ok(info) => classify(&info), + Err(why) => Front::Unknown(why), + } } fn poll(state: &Arc<Mutex<State>>, seen: &mut Seen, hz: f64) { @@ -326,8 +417,12 @@ fn poll(state: &Arc<Mutex<State>>, seen: &mut Seen, hz: f64) { } let (_, began, exact) = seen.since[&pane_id].clone(); let (cpu, rss) = match foreground(&pane_id) { - Some((pid, _, _, _)) => cpu_of(seen, pid, at, hz), - None => (None, None), + Front::Running(pid, _, _, _) => cpu_of(seen, pid, at, hz), + // An agent's state comes from `agent list`, not from the probe, + // so a failed probe costs the row its CPU and memory and + // nothing else - and those already draw as `-` and `--` when + // there is no reading, which there is not. + Front::Prompt | Front::Unknown(_) => (None, None), }; agents.push(Agent { name: text_at(entry, "agent"), @@ -357,20 +452,37 @@ fn poll(state: &Arc<Mutex<State>>, seen: &mut Seen, hz: f64) { let pane_id = text_at(pane, "pane_id"); let front = foreground(&pane_id); let (cpu, rss) = match &front { - Some((pid, _, _, _)) => cpu_of(seen, *pid, at, hz), - None => (None, None), + Front::Running(pid, _, _, _) => cpu_of(seen, *pid, at, hz), + Front::Prompt | Front::Unknown(_) => (None, None), }; - let (command, cwd) = match &front { - Some((_, argv, name, cwd)) => ( - command_label(argv, name), - if cwd.is_empty() { text_at(pane, "cwd") } else { cwd.clone() }, + let (doing, command, cwd, why) = match front { + Front::Running(_, argv, name, cwd) => ( + Doing::Running, + command_label(&argv, &name), + if cwd.is_empty() { text_at(pane, "cwd") } else { cwd }, + String::new(), + ), + Front::Prompt => ( + Doing::Prompt, + String::new(), + text_at(pane, "cwd"), + String::new(), + ), + // The pane's own directory still comes from `pane list`, so + // an unread pane is not a blank row - it is a row that says + // where it is and that nobody could see into it. + Front::Unknown(why) => ( + Doing::Unknown, + String::new(), + text_at(pane, "cwd"), + why, ), - None => (String::new(), text_at(pane, "cwd")), }; panels.push(Panel { tab_id: text_at(pane, "tab_id"), workspace_id: text_at(pane, "workspace_id"), - idle: front.is_none(), + doing, + why, pane_id, command, cwd, @@ -379,16 +491,17 @@ fn poll(state: &Arc<Mutex<State>>, seen: &mut Seen, hz: f64) { }); } } - // Busy first, and the busiest of those first: the point of the section - // is what is costing something. + // Unread first, then busy, and the busiest of those first: the point of + // the section is what is costing something, and above that, what the + // widget could not find out at all. // Idle last, and that ordering is load-bearing twice over. The screen - // draws `running` then `resting`, and both the cursor and the window are + // draws `busy` then `resting`, and both the cursor and the window are // indices into `agents ++ panels` - so the two agree only because - // `panels` is already running-then-resting. Reorder this and the cursor - // silently marks one pane while enter switches to another. + // `panels` is already unread-then-running-then-resting. Reorder this and + // the cursor silently marks one pane while enter switches to another. panels.sort_by(|a, b| { - a.idle - .cmp(&b.idle) + doing_rank(a.doing) + .cmp(&doing_rank(b.doing)) .then(b.cpu.unwrap_or(0.0).total_cmp(&a.cpu.unwrap_or(0.0))) }); @@ -690,8 +803,16 @@ fn main() { ), Err(_) => return, }; - let running: Vec<&Panel> = panels.iter().filter(|n| !n.idle).collect(); - let resting: Vec<&Panel> = panels.iter().filter(|n| n.idle).collect(); + // Everything that is not known to be at a prompt shares the + // PROCESSES section, unread panes at the top of it. They are counted + // apart in the heading, because "running something" is a claim and + // the whole point of the unread ones is that the claim cannot be + // made. [i] hides only the panes we know are resting: hiding one we + // could not read would be the old bug wearing the new type. + let busy: Vec<&Panel> = panels.iter().filter(|n| n.doing != Doing::Prompt).collect(); + let resting: Vec<&Panel> = panels.iter().filter(|n| n.doing == Doing::Prompt).collect(); + let unread: Vec<&&Panel> = busy.iter().filter(|n| n.doing == Doing::Unknown).collect(); + let running = busy.len() - unread.len(); rows_now = agents .iter() .cloned() @@ -699,7 +820,7 @@ fn main() { .chain( panels .iter() - .filter(|n| show_idle || !n.idle) + .filter(|n| show_idle || n.doing != Doing::Prompt) .cloned() .map(Row::Process), ) @@ -801,8 +922,9 @@ fn main() { let chrome = rows.len() + 2 // AGENTS, and its column head + 2 + usize::from(wide) // blank, PROCESSES, its column head + + usize::from(!unread.is_empty()) // why they could not be read + usize::from(agents.is_empty()) // the line that stands in for a list - + usize::from(running.is_empty()) + + usize::from(busy.is_empty()) + if idle_listed { 2 } else { 0 } // blank, IDLE + footer.len() + 1; // the note line @@ -933,21 +1055,21 @@ fn main() { } rows.push(String::new()); - rows.push(tc::seg( - &[ - (p.lbl.as_str(), " ── PROCESSES ── ".into()), - ( - p.dim.as_str(), - format!( - "{} pane{} running something", - running.len(), - plural(running.len()) - ), - ), - (p.dim.as_str(), showing(&window, agents.len(), running.len())), - ], - w - 1, - )); + let mut heading = vec![ + (p.lbl.as_str(), " ── PROCESSES ── ".into()), + ( + p.dim.as_str(), + format!("{} pane{} running something", running, plural(running)), + ), + ]; + if !unread.is_empty() { + heading.push(( + p.unknown.as_str(), + format!(" · {} could not be read", unread.len()), + )); + } + heading.push((p.dim.as_str(), showing(&window, agents.len(), busy.len()))); + rows.push(tc::seg(&heading, w - 1)); if wide { rows.push(tc::seg( &[( @@ -960,7 +1082,20 @@ fn main() { w - 1, )); } - for (j, n) in running.iter().enumerate() { + // The reason, on a line of its own rather than after the count in + // the heading: on an eighty-column pane the heading runs out of room + // exactly where the reason starts, and the reason is the half worth + // keeping. They fail one reason at a time - the socket, or a pane + // going away between the listing and the probe - so the first one + // speaks for all of them. + if let Some(n) = unread.first() { + let why = if n.why.is_empty() { "no reason given" } else { &n.why }; + rows.push(tc::seg( + &[(p.unknown.as_str(), format!(" ⚠ {}", why))], + w - 1, + )); + } + for (j, n) in busy.iter().enumerate() { if !window.contains(&(agents.len() + j)) { continue; } @@ -992,11 +1127,31 @@ fn main() { Some(v) if v > 0.0 => tc::heat((v / 100.0).min(1.0)), _ => p.dim.clone(), }; + // An unread pane says so in words where a command would go. A + // bare "?" is what a running pane with unparseable argv shows, + // and the two are not the same thing at all. + let unreadable = n.doing == Doing::Unknown; let mut line = vec![ - (c(&p.proc), format!("{}▪ ", if here { "▸" } else { " " })), ( - c(&p.txt), - tc::pad(if n.command.is_empty() { "?" } else { &n.command }, 20), + c(if unreadable { &p.unknown } else { &p.proc }), + format!( + "{}{} ", + if here { "▸" } else { " " }, + if unreadable { '⚠' } else { '▪' } + ), + ), + ( + c(if unreadable { &p.unknown } else { &p.txt }), + tc::pad( + if unreadable { + "could not be read" + } else if n.command.is_empty() { + "?" + } else { + &n.command + }, + 20, + ), ), (c(&heat), percent(n.cpu)), ]; @@ -1017,7 +1172,9 @@ fn main() { line.iter().map(|(c, t)| (c.as_str(), t.clone())).collect(); rows.push(tc::seg(&refs, w - 1)); } - if running.is_empty() { + // True only when nothing was unread either: an empty section with a + // pane the probe failed on is not a Herdr where everything rests. + if busy.is_empty() { rows.push(tc::seg( &[(p.dim.as_str(), " every other pane is idle at a prompt".into())], w - 1, @@ -1041,16 +1198,16 @@ fn main() { ), ( p.dim.as_str(), - showing(&window, agents.len() + running.len(), resting.len()), + showing(&window, agents.len() + busy.len(), resting.len()), ), ], w - 1, )); for (j, n) in resting.iter().enumerate() { - if !window.contains(&(agents.len() + running.len() + j)) { + if !window.contains(&(agents.len() + busy.len() + j)) { continue; } - let here = agents.len() + running.len() + j == selected; + let here = agents.len() + busy.len() + j == selected; let tint = if here { tc::bg(38, 56, 76) } else { String::new() }; let c = |colour: &str| { // Any colour that would not clear AA on this tint is swapped @@ -1306,4 +1463,83 @@ mod tests { // A truncated line has no fields to find and must not be guessed at. assert_eq!(parse_proc_stat("42 (short) S 1 2 3"), None); } + + #[test] + fn a_failed_command_is_told_from_a_quiet_one() { + // What herdr answers a request it cannot serve, verbatim in shape: + // an `error` object, no `result`, and exit status 0. Nothing about + // having run the command says it did not work, so a reader looking + // only for `result` cannot tell this from a pane with nothing to + // report - which is how a failed probe used to become "idle". + let failed = r#"{"error":{"code":"pane_not_found","message":"pane not found"},"id":"p"}"#; + assert_eq!(result_of(failed).unwrap_err(), "pane not found"); + // An error with no message still has to say something. + assert!(!result_of(r#"{"error":{"code":"busy"}}"#) + .unwrap_err() + .is_empty()); + // Output that is not JSON at all is a failure, not a silence. + assert!(result_of("herdr: no server on this socket").is_err()); + // A null result is nothing, and says so rather than handing it on. + assert!(result_of(r#"{"id":"p","result":null}"#).is_err()); + // And a result that is there arrives whole. + let answered = r#"{"id":"p","result":{"process_info":{"pane_id":"w1:p1"}}}"#; + assert_eq!( + result_of(answered).unwrap()["process_info"]["pane_id"], + "w1:p1" + ); + } + + #[test] + fn a_pane_at_its_prompt_and_a_pane_nobody_could_read_are_not_one_answer() { + let info = |front: serde_json::Value, shell: i64| { + serde_json::json!({ + "process_info": {"foreground_processes": [front], "shell_pid": shell} + }) + }; + let shell = serde_json::json!({ + "pid": 200, "argv": ["/bin/bash"], "name": "bash", "cwd": "/w" + }); + // The foreground pid is the shell's own: the prompt is what is in + // front. This is the only thing that means idle. + assert!(matches!(classify(&info(shell, 200)), Front::Prompt)); + + let build = serde_json::json!({ + "pid": 311, "argv": ["/usr/bin/python3", "/w/build.py"], + "name": "python3", "cwd": "/w" + }); + match classify(&info(build, 200)) { + Front::Running(pid, argv, name, cwd) => { + assert_eq!(pid, 311); + assert_eq!(command_label(&argv, &name), "build.py"); + assert_eq!(cwd, "/w"); + } + _ => panic!("a pane running something is running something"), + } + + // An answer with nothing readable in it is neither of those. It used + // to fall through to the same `None` as the prompt, and the pane + // joined IDLE with no sign that anything had gone wrong. + assert!(matches!(classify(&serde_json::json!({})), Front::Unknown(_))); + assert!(matches!( + classify(&info(serde_json::json!({"argv": ["sh"]}), 200)), + Front::Unknown(_) + )); + + // An absent shell_pid says nothing, so it cannot say "prompt". + let alone = serde_json::json!({ + "process_info": {"foreground_processes": [{"pid": 7, "name": "vi"}]} + }); + assert!(matches!(classify(&alone), Front::Running(7, _, _, _))); + } + + #[test] + fn the_unread_panes_sort_above_the_busy_ones() { + // The section draws in this order and the cursor indexes it, so the + // rank is what keeps the two agreeing - and it puts the row the + // widget could not answer for at the top, where a failure belongs. + assert!(doing_rank(Doing::Unknown) < doing_rank(Doing::Running)); + assert!(doing_rank(Doing::Running) < doing_rank(Doing::Prompt)); + // A pane nobody has looked at yet is unread, not resting. + assert_eq!(Doing::default(), Doing::Unknown); + } } diff --git a/widgets/src/bin/latency.rs b/widgets/src/bin/latency.rs index b58e273..86047d1 100644 --- a/widgets/src/bin/latency.rs +++ b/widgets/src/bin/latency.rs @@ -101,6 +101,23 @@ struct Stats { } impl Target { + /// Record one reading and keep only the last `window` of them. + /// + /// Retention lives here rather than beside a push because it used to + /// live beside one push and not the other: the trim sat inside the loop + /// that reads `ping`'s output, so a target whose `ping` exits at once - + /// an unresolvable name, a host with no route to it - appended a loss + /// from the retry path every two seconds and never trimmed. The vector + /// grew for as long as the pane was up and `stats()` reread the whole + /// of it every frame. One door in, one rule. + fn record(&mut self, at: f64, rtt: Option<f64>, window: usize) { + self.samples.push((at, rtt)); + if self.samples.len() > window { + let drop = self.samples.len() - window; + self.samples.drain(..drop); + } + } + /// Round trips that arrived, newest last. fn rtts(&self) -> Vec<f64> { self.samples.iter().filter_map(|(_, r)| *r).collect() @@ -364,18 +381,14 @@ fn watch( format!("recovered after {:.0}s", stamp - since)); } target.alive = true; - target.samples.push((stamp, Some(rtt))); + target.record(stamp, Some(rtt), window); } else if is_loss(&line) { if target.down_since.is_none() { target.down_since = Some(stamp); log(&events, &hue, &label, "LOSS", "no reply".into()); } target.alive = false; - target.samples.push((stamp, None)); - } - if target.samples.len() > window { - let drop = target.samples.len() - window; - target.samples.drain(..drop); + target.record(stamp, None, window); } } let _ = child.wait(); @@ -405,7 +418,7 @@ fn watch( } if let Ok(mut guard) = shared.lock() { guard[index].alive = false; - guard[index].samples.push((now(), None)); + guard[index].record(now(), None, window); } std::thread::sleep(Duration::from_secs(2)); } @@ -632,10 +645,17 @@ fn graph( .copied() .collect(); if seen.is_empty() { - return ( - vec![tc::seg(&[(p.dim.as_str(), " collecting…".into())], w - 1)], - span, - ); + // Nothing to plot has two causes and they are not the same. With no + // targets there is nothing to collect and never will be, so + // "collecting…" is a promise the widget cannot keep - it is the + // pane looking busy over an empty list, which is the shape this + // repo's checks exist to catch. + let why = if targets.is_empty() { + " no hosts configured - set latency.hosts in config.json" + } else { + " collecting…" + }; + return (vec![tc::seg(&[(p.dim.as_str(), why.into())], w - 1)], span); } let lo = seen.iter().cloned().fold(f64::INFINITY, f64::min).max(0.05) * 0.8; let hi = (seen.iter().cloned().fold(0.0f64, f64::max) * 1.25).max(lo * 1.6); @@ -1249,6 +1269,32 @@ fn palette() -> Palette { mod tests { use super::*; + #[test] + fn a_target_that_never_answers_does_not_grow_for_ever() { + // The retry path - `ping` exited, sleep two seconds, try again - + // records a loss each time round. Its retention used to sit in the + // loop over `ping`'s output, which a target that exits immediately + // never enters, so an unreachable host grew the vector by a sample + // every two seconds for as long as the pane was up and made + // `stats()` reread all of it every frame. + let window = 8; + let mut t = Target::default(); + for i in 0..500 { + t.record(i as f64, None, window); + assert!(t.samples.len() <= window, "grew to {} at {}", t.samples.len(), i); + } + assert_eq!(t.samples.len(), window); + // What is kept is the newest, not the oldest. + assert_eq!(t.samples.first().map(|(at, _)| *at), Some(492.0)); + assert_eq!(t.samples.last().map(|(at, _)| *at), Some(499.0)); + // Answers are held to the same rule. + let mut t = Target::default(); + for i in 0..500 { + t.record(i as f64, Some(i as f64), window); + } + assert_eq!(t.samples.len(), window); + } + #[test] fn a_reply_gives_up_its_round_trip() { let line = "64 bytes from 1.1.1.1: icmp_seq=1 ttl=57 time=12.3 ms"; diff --git a/widgets/src/bin/tailnet.rs b/widgets/src/bin/tailnet.rs index 927ea0d..e92e143 100644 --- a/widgets/src/bin/tailnet.rs +++ b/widgets/src/bin/tailnet.rs @@ -291,14 +291,11 @@ fn parse_iso(iso: &str) -> Option<NaiveDateTime> { NaiveDateTime::parse_from_str(&iso[..19], "%Y-%m-%dT%H:%M:%S").ok() } -/// The age of an ISO-8601 timestamp, coarsely. -fn seen(iso: &str) -> String { - let Some(at) = parse_iso(iso) else { - return " -".into(); - }; - let s = (chrono::Utc::now().naive_utc() - at).num_seconds().max(0); +/// A span of seconds in three or four cells: 45s, 12m, 6h, 3d. +fn brief(s: f64) -> String { + let s = s.max(0.0) as i64; if s < 90 { - "now".into() + format!("{}s", s) } else if s < 5400 { format!("{}m", s / 60) } else if s < 172_800 { @@ -308,6 +305,15 @@ fn seen(iso: &str) -> String { } } +/// The age of an ISO-8601 timestamp, coarsely. +fn seen(iso: &str) -> String { + let Some(at) = parse_iso(iso) else { + return " -".into(); + }; + let s = (chrono::Utc::now().naive_utc() - at).num_seconds().max(0); + if s < 90 { "now".into() } else { brief(s as f64) } +} + /// ISO-8601 to a readable local time, or nothing when unset. fn stamp(iso: &str) -> String { let Some(at) = parse_iso(iso) else { @@ -391,6 +397,14 @@ struct Prober { samples: HashMap<String, Vec<Option<f64>>>, want: Option<(String, String)>, pid: Option<i32>, + /// Why the selected peer has no latency, when the reason is this + /// widget's own rather than the network's. `tailscale` is checked at + /// startup and `ping` is not, so on a host with one and not the other + /// the spawn failed, was thrown away, and was retried every two seconds + /// for as long as the widget was up - while an empty history suppressed + /// the whole latency section, which is what a peer nobody had pinged + /// yet looks like too. + err: String, } fn rtt_of(line: &str) -> Option<f64> { @@ -406,6 +420,12 @@ fn prober_loop(shared: Arc<Mutex<Prober>>) { loop { let target = shared.lock().ok().and_then(|g| g.want.clone()); let Some((machine, ip)) = target else { + // Nothing selected to probe - this machine, or a peer that is + // offline. Nothing has failed, and a reason left over from the + // last peer would be read as belonging to this one. + if let Ok(mut g) = shared.lock() { + g.err.clear(); + } std::thread::sleep(Duration::from_millis(400)); continue; }; @@ -416,12 +436,18 @@ fn prober_loop(shared: Arc<Mutex<Prober>>) { .spawn(); let mut child = match child { Ok(c) => c, - Err(_) => { + Err(e) => { + let why = format!("ping will not start: {}", e); + if let Ok(mut g) = shared.lock() { + g.err = why; + } std::thread::sleep(Duration::from_secs(2)); continue; } }; + // It started, so whatever stopped it last time is over. if let Ok(mut g) = shared.lock() { + g.err.clear(); g.pid = Some(child.id() as i32); } if let Some(stdout) = child.stdout.take() { @@ -447,10 +473,28 @@ fn prober_loop(shared: Arc<Mutex<Prober>>) { } } } + // Whether the selection moved on while that ping was running. If it + // did, the stream ended because we stopped it and there is nothing + // to report; if it did not, ping died on its own - which used to + // restart it immediately, in silence, as fast as the kernel would + // spawn it, for a peer whose latency section stayed empty. + let moved_on = shared + .lock() + .map(|g| g.want.as_ref().map(|w| w.0.as_str()) != Some(machine.as_str())) + .unwrap_or(true); let _ = child.kill(); - let _ = child.wait(); + let status = child.wait(); if let Ok(mut g) = shared.lock() { g.pid = None; + if !moved_on { + g.err = match &status { + Ok(s) => format!("ping stopped ({})", s), + Err(e) => format!("ping stopped: {}", e), + }; + } + } + if !moved_on { + std::thread::sleep(Duration::from_secs(2)); } } } @@ -480,6 +524,9 @@ struct State { rates: HashMap<String, Vec<(f64, f64)>>, counters: HashMap<String, (u64, u64, f64)>, endpoints_at: f64, + /// When `data` last came back parseable. A failed poll keeps the rows it + /// cannot replace, so this is what says how old they are. + data_at: f64, } /// Turn cumulative byte counters into per-second rates. @@ -657,6 +704,7 @@ fn main() { g.err.clear(); sample_rates(&mut g, d, history); g.data = Some(d.clone()); + g.data_at = now(); } } if let Some(eps) = eps { @@ -707,8 +755,14 @@ fn main() { }; loop { - let (data, eps_now, err, rates) = match state.lock() { - Ok(g) => (g.data.clone(), g.endpoints.clone(), g.err.clone(), g.rates.clone()), + let (data, eps_now, err, rates, data_at) = match state.lock() { + Ok(g) => ( + g.data.clone(), + g.endpoints.clone(), + g.err.clone(), + g.rates.clone(), + g.data_at, + ), Err(_) => return, }; @@ -828,6 +882,25 @@ fn main() { continue; }; + // A poll that fails after a good one keeps the rows it cannot + // replace, which is the right thing to do and used to be done in + // silence: `err` was only ever drawn in place of the peer list, so + // once there was a list to draw instead, a tailnet that had stopped + // answering went on looking exactly like one where nothing had + // changed. The rows stay, and say what they are. + let stale = if err.is_empty() { + String::new() + } else { + format!( + "polling is failing, these rows are cached, {} old ({})", + brief(now() - data_at), + err + ) + }; + if !stale.is_empty() { + rows.push(tc::seg(&[(p.relay.as_str(), format!(" ! {}", stale))], w - 1)); + } + let me = data["Self"].clone(); let peers: Vec<serde_json::Value> = data["Peer"] .as_object() @@ -910,12 +983,20 @@ fn main() { .flatten() .map(|(k, v)| (k.clone(), v.clone())) .collect(); - let latency = prober + let (latency, probe_err) = prober .lock() .ok() - .and_then(|g| g.samples.get(&peer_name(&chosen)).cloned()) + .map(|g| { + ( + g.samples.get(&peer_name(&chosen)).cloned().unwrap_or_default(), + g.err.clone(), + ) + }) .unwrap_or_default(); - info_overlay(&chosen, &eps_now, &users, w, h, &rates, &latency, &derp, &p) + info_overlay( + &chosen, &eps_now, &users, w, h, &rates, &latency, &probe_err, &stale, &derp, + &p, + ) } else { copy_overlay(&chosen, &eps_now, w, h, ¬e.0, &p) }; @@ -1168,10 +1249,17 @@ fn info_overlay( h: usize, rates: &HashMap<String, Vec<(f64, f64)>>, latency: &[Option<f64>], + probe_err: &str, + stale: &str, derp: &HashMap<String, String>, p: &Palette, ) -> Vec<String> { let mut rows = vec![tc::title("machine info", w, &p.accent)]; + // Every field below is out of the same cached status as the list behind + // this view, so it carries the same warning. + if !stale.is_empty() { + rows.push(tc::seg(&[(p.relay.as_str(), format!(" ! {}", stale))], w - 1)); + } let dns = text(peer, "DNSName").trim_end_matches('.').to_string(); let owner = users .get(&peer["UserID"].as_i64().unwrap_or(0).to_string()) @@ -1340,6 +1428,10 @@ fn info_overlay( } } + // Exactly the peers the main loop hands to the prober: not this machine, + // and not one that is offline. "probing…" sat on this machine's own row + // for as long as you left it open, for a ping that is never sent. + let probed = up && !peer["_self"].as_bool().unwrap_or(false); let pings: Vec<f64> = latency.iter().filter_map(|x| *x).collect(); if !latency.is_empty() { rows.push(String::new()); @@ -1421,7 +1513,7 @@ fn info_overlay( w - 1, )); } - } else if up { + } else if probed && probe_err.is_empty() { rows.push(String::new()); rows.push(tc::seg( &[ @@ -1431,6 +1523,27 @@ fn info_overlay( w - 1, )); } + // Why there is nothing to report, when the reason is this widget's own. + // It follows the figures rather than replacing them, the way latency's + // rows do: the samples taken before the probe broke are still true, and + // still the last thing this peer was known to be doing. + if probed && !probe_err.is_empty() { + if latency.is_empty() { + rows.push(String::new()); + rows.push(tc::seg( + &[ + (p.lbl.as_str(), " latency ".into()), + (p.relay.as_str(), probe_err.to_string()), + ], + w - 1, + )); + } else { + rows.push(tc::seg( + &[(p.relay.as_str(), format!(" ! {}", probe_err))], + w - 1, + )); + } + } if let Some(hist) = rates.get(&peer_name(peer)).filter(|h| !h.is_empty()) { rows.push(String::new()); From 5e2b5c7bd2bfdc461a7661fef81ac9b76d2024a1 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Wed, 26 Aug 2026 12:03:12 +0800 Subject: [PATCH 126/147] clocks: six that the day, the config and the shell each got wrong `day_bounds` computed the working day by adding hours to midnight, which is an hour out on both DST changeover days - the two days a year a clock widget is most worth looking at. It is generic over the timezone now and asks the zone where the boundary falls. Toast processes were spawned and never waited on, so a day of break notifications left a day of zombies. `reap` clears the finished ones before each spawn. `shown` was read from the wrong key: the pomodoro's visibility came from `show_hints`, so turning the hints off took the whole panel with it. The comment justifying it described what clocks.py did and was simply wrong about it - `pomodoro_enabled` is the key, and `show_hints` now only moves the hints. `show_hints` and `work_days` are in config.example.json for the first time, which is what makes them settings rather than rumours. Both are read through a wrapped `cfg\n.get(...)` chain, which is exactly the form the config check could not see - so neither was undocumented by oversight, they were undocumented by a blind spot. The check is widened in the commit that follows; these two are the bug it was blind to. docs/clocks.md said `+`/`-` changed focus length snapped to multiples of five. The code moves whichever block is running - focus, short or long - by one minute, clamped to 1-180. The code is right and the table now says what it does. A toast was emitted twice on the same transition. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- config.example.json | 4 + docs/clocks.md | 2 +- widgets/src/bin/clocks.rs | 342 +++++++++++++++++++++++++++++++------- 3 files changed, 286 insertions(+), 62 deletions(-) diff --git a/config.example.json b/config.example.json index 47a3cdf..24161a8 100644 --- a/config.example.json +++ b/config.example.json @@ -36,6 +36,10 @@ ], "work_start_hour": 9, "work_end_hour": 18, + "_show_hints_comment": "Whether the pomodoro key hints sit under the panel. Visible by default: the hints are how the keys are found in the first place, and starting hidden means a reader has to already know the key that reveals them. [?] toggles it live.", + "show_hints": true, + "_work_days_comment": "Which days count as working days, as names (sun, mon, ...) or numbers. Drives the working-day shading.", + "work_days": ["mon", "tue", "wed", "thu", "fri"], "pomodoro_enabled": false, "pomodoro_focus_minutes": 25, "pomodoro_short_break_minutes": 5, diff --git a/docs/clocks.md b/docs/clocks.md index b51cd6d..15fd0fc 100644 --- a/docs/clocks.md +++ b/docs/clocks.md @@ -96,7 +96,7 @@ shown — are not tied to the day and survive. | `space` | pause / resume | | `s` `b` `e` | start a break during focus, end one during a break — the footer names whichever applies | | `r` | restart the current phase | -| `+` `-` | focus length, snapped to multiples of five. `=` works as `+`, so it needs no shift, and the footer writes the pair as `[±]` | +| `+` `-` | one minute on or off **whichever block is running** — focus, short break or long break — clamped to 1–180. The finish line moves by however much the block actually changed, so a minute added twenty minutes into a twenty-five minute block leaves six, not twenty-six. `=` works as `+`, so it needs no shift, and the footer writes the pair as `[±]` | | `0` `c` | zero today's completed tally | | `?` `h` | hide/show the pomodoro controls | | `q` | quit | diff --git a/widgets/src/bin/clocks.rs b/widgets/src/bin/clocks.rs index a7b4e10..ca06201 100644 --- a/widgets/src/bin/clocks.rs +++ b/widgets/src/bin/clocks.rs @@ -221,16 +221,50 @@ fn countdowns(now: chrono::DateTime<Local>, office: &Office) -> Vec<Countdown> { ink: tc::rgb(255, 200, 90), }); - let into_day = now.num_seconds_from_midnight() as i64; + let (into_day, day_len) = day_bounds(&now); out.push(Countdown { label: "End of Day".into(), - left: 86400 - into_day, - frac: into_day as f64 / 86400.0, + left: day_len - into_day, + frac: into_day as f64 / day_len as f64, ink: tc::rgb(175, 130, 255), }); out } +/// How far into the local day `now` is, and how long that day runs. +/// +/// Measured between two midnights rather than assumed to be 86,400 +/// seconds: the day the clocks go forward is 23 hours long and the day +/// they go back is 25, and a fixed span puts both the time remaining and +/// the bar an hour out for the whole of a transition day. Generic over the +/// zone so the transition can be tested against a real one rather than +/// whichever zone this machine happens to be in. +fn day_bounds<T: TimeZone>(now: &chrono::DateTime<T>) -> (i64, i64) { + let zone = now.timezone(); + // Midnight itself is sometimes the hour that does not exist - Chile and + // Lebanon have moved their clocks at exactly that moment - so take the + // first minute of the day that does. + let midnight = |day: chrono::NaiveDate| { + (0..180).find_map(|m| { + zone.from_local_datetime( + &(day.and_time(NaiveTime::from_hms_opt(0, 0, 0).unwrap()) + + chrono::Duration::minutes(m)), + ) + .earliest() + }) + }; + let today = now.date_naive(); + match (midnight(today), midnight(today + chrono::Duration::days(1))) { + (Some(start), Some(end)) if end.timestamp() > start.timestamp() => ( + (now.timestamp() - start.timestamp()).max(0), + end.timestamp() - start.timestamp(), + ), + // A day the zone cannot place at all: fall back to the wall clock, + // which is what the day looks like on every day but the two it moves. + _ => (now.num_seconds_from_midnight() as i64, 86_400), + } +} + /// Seconds each flash stays lit. const FLASH_ON: f64 = 0.35; @@ -301,7 +335,9 @@ fn herdr_toast(title: &str, body: &str) { if std::env::var("HERDR_ENV").unwrap_or_default() != "1" { return; } - let _ = std::process::Command::new("herdr") + let mut sent = SENT.lock().unwrap_or_else(|e| e.into_inner()); + reap(&mut sent); + if let Ok(child) = std::process::Command::new("herdr") // --body, not a second positional: `herdr notification show` takes // one <TITLE> and the body is an option. Passing it positionally // fails with "unknown option" - silently, since stderr is nulled - @@ -310,7 +346,27 @@ fn herdr_toast(title: &str, body: &str) { .stdin(std::process::Stdio::null()) .stdout(std::process::Stdio::null()) .stderr(std::process::Stdio::null()) - .spawn(); + .spawn() + { + sent.push(child); + } +} + +/// Toasts already sent, still holding an exit status nobody has read. +/// +/// A `Child` that is never waited on stays a zombie for as long as the +/// widget runs, and an ignored pomodoro toasts once a minute - a panel +/// left alone for a day would leave hundreds of them behind. Each toast +/// clears the ones before it, which needs no thread of its own. +static SENT: std::sync::Mutex<Vec<std::process::Child>> = std::sync::Mutex::new(Vec::new()); + +/// Drop the handle of every toast that has finished. +/// +/// `try_wait` does not block, so a `herdr` that hangs keeps its slot in +/// the list rather than holding up the render loop. A handle that cannot +/// be waited on at all is dropped too: keeping it reaps nothing. +fn reap(sent: &mut Vec<std::process::Child>) { + sent.retain_mut(|child| matches!(child.try_wait(), Ok(None))); } /// The pomodoro, and the state it keeps between runs. @@ -322,6 +378,10 @@ fn herdr_toast(title: &str, body: &str) { struct Pomodoro { phase: Phase, running: bool, + /// pomodoro_enabled, then whatever the state file remembers: whether + /// the timer is on screen at all. It is the visibility flag in + /// clocks.py - and stored under the same "enabled" key - not a flag + /// for whether it runs, which no setting starts. shown: bool, /// When the current phase ends, while running. deadline: f64, @@ -337,11 +397,14 @@ struct Pomodoro { /// The day the tally belongs to, as %Y-%m-%d. Kept so a panel left /// running over midnight zeroes rather than adding to yesterday. day: String, - /// pomodoro_enabled: whether it starts running. clocks.py reads this - /// and the port did not, so setting it did nothing here. - enabled: bool, - /// pomodoro_notify: ring the terminal bell on a phase change. Read for - /// the same reason. + /// show_hints: whether the pomodoro's key hints are under the panel. + /// A display preference rather than timer state, but it rides in the + /// same file - under "hints" - so the panel comes back looking how it + /// was left. + hints: bool, + /// pomodoro_notify: announce a phase change to the terminal and to + /// Herdr. clocks.py reads this and the port did not, so setting it did + /// nothing here. notify: bool, } @@ -388,10 +451,14 @@ impl Pomodoro { let mut it = Pomodoro { phase: Phase::Focus, running: false, - // On screen from the start, paused. Hidden and paused are - // different things, and the Python shows it from the first - // frame with "paused" against it. - shown: true, + // Off until [p], which is what clocks.py does and what the doc + // promises: pomodoro_enabled is its visibility flag and it + // defaults to false. Hardcoding this true put an optional + // panel on screen for everyone who had turned it off. + shown: cfg + .get("pomodoro_enabled") + .and_then(|v| v.as_bool()) + .unwrap_or(false), deadline: 0.0, left: focus * 60.0, done: 0, @@ -405,10 +472,13 @@ impl Pomodoro { .unwrap_or(true), rang_at: -1, day: today(), - enabled: cfg - .get("pomodoro_enabled") + // Visible by default, as clocks.py has it: the hints are how + // the keys are found in the first place, and starting hidden + // means a reader has to already know the key that reveals them. + hints: cfg + .get("show_hints") .and_then(|v| v.as_bool()) - .unwrap_or(false), + .unwrap_or(true), // True, as clocks.py has it: a break ending is worth saying // out loud, and a machine with no config should behave the // same under either implementation. @@ -418,7 +488,10 @@ impl Pomodoro { .unwrap_or(true), }; it.left = it.duration(); - it.running = it.enabled; + // Never running from config alone. Setting it running here left the + // deadline at zero, and a deadline of zero falls back to a `left` + // that nothing decrements: a timer frozen at 25:00 with no "paused" + // beside it. Only a saved deadline resumes a block, in load(). it.load(); it } @@ -438,11 +511,15 @@ impl Pomodoro { if let Some(v) = d.get("focus").and_then(|v| v.as_f64()) { self.focus = v; } + // "enabled" is visibility and "hints" is the hint preference - the + // port had the second one holding the first, so hiding the panel + // rewrote whether the keys are listed and hiding the keys moved + // the panel. if let Some(v) = d.get("enabled").and_then(|v| v.as_bool()) { - self.enabled = v; + self.shown = v; } if let Some(v) = d.get("hints").and_then(|v| v.as_bool()) { - self.shown = v; + self.hints = v; } if d.get("day").and_then(|v| v.as_str()) != Some(self.day.as_str()) { return; // a new day starts a fresh count @@ -485,10 +562,10 @@ impl Pomodoro { }, "completed": self.done, "focus": self.focus, - "enabled": self.enabled, + "enabled": self.shown, "running": self.running, "was_running": self.running, - "hints": self.shown, + "hints": self.hints, "left": self.left, "deadline": self.deadline, }); @@ -602,8 +679,7 @@ impl Pomodoro { self.save(); } - /// Lengthen or shorten the focus block, in minutes. - /// Lengthen or shorten the block you are actually in. + /// Lengthen or shorten the block you are actually in, in minutes. /// /// Whichever phase is running: focus during focus, and that break during /// a break. It used to write to `focus` whatever the phase, so pressing @@ -611,16 +687,27 @@ impl Pomodoro { /// countdown alone - and the hint beside it read "focus" while the line /// above it read BREAK. Both breaks keep their own length, so shortening /// a short break does not shorten the long one. - fn adjust(&mut self, delta: f64, now: f64) { + /// + /// It takes no clock: moving the finish line needs the size of the + /// change, not the time of it. + fn adjust(&mut self, delta: f64) { + let before = self.duration(); let slot = match self.phase { Phase::Focus => &mut self.focus, Phase::Short => &mut self.short, Phase::Long => &mut self.long, }; *slot = (*slot + delta).clamp(1.0, 180.0); - self.left = self.duration(); + // Move the finish line by however much the block actually changed - + // the clamp can make that less than was asked for - rather than + // starting the block again. A minute added twenty minutes into a + // twenty-five minute block leaves six, not twenty-six. Shortening + // below what has already gone leaves the block over, which is + // true, and the counter says so by climbing. + let moved = self.duration() - before; + self.left += moved; if self.running { - self.deadline = now + self.left; + self.deadline += moved; } self.save(); } @@ -655,7 +742,19 @@ impl Pomodoro { return false; } self.rang_at = minute; - self.alert(&format!("{} over", self.phase.label())); + // Every channel gets the same sentence, and how far over is part of + // it: the render loop used to send a second, richer toast of its + // own, which meant two notifications under Herdr and one even with + // pomodoro_notify off. + self.alert(&format!( + "{} elapsed{}", + self.phase.label(), + if over >= 60.0 { + format!(", {} over", hms(over as i64)) + } else { + String::new() + } + )); true } @@ -712,14 +811,6 @@ fn main() { .and_then(|v| v.as_bool()) .unwrap_or(true); let mut flash_started: Option<f64> = None; - // Visible by default, as clocks.py has it: the hints are how the keys - // are found in the first place, and starting hidden means a reader has - // to already know the key that reveals them. [?] toggles, and - // show_hints in the config still decides either way. - let mut tips = cfg - .get("show_hints") - .and_then(|v| v.as_bool()) - .unwrap_or(true); tc::setup(); let mut keyboard = tc::Keyboard::new(); let mut scroll = 0usize; @@ -741,7 +832,15 @@ fn main() { // place that knows how many there are. "end" => scroll = usize::MAX / 2, "p" | "P" => pomo.toggle(seconds()), - "?" | "h" => tips = !tips, + // show_hints decides where this starts and [?] moves it, + // but the answer outlives the session: it rides in the + // pomodoro's state file, so hiding the hints once hides + // them tomorrow too. It used to live in a local nothing + // wrote down. + "?" | "h" => { + pomo.hints = !pomo.hints; + pomo.save(); + } // Everything below moves a timer that is not running, so // it is ignored rather than silently acted on. _ if !pomo.shown => {} @@ -750,8 +849,8 @@ fn main() { "s" | "S" | "b" | "B" | "e" | "E" => pomo.advance(seconds()), "r" | "R" => pomo.restart(seconds()), "0" | "c" => pomo.reset_count(), - "+" | "=" => pomo.adjust(1.0, seconds()), - "-" | "_" => pomo.adjust(-1.0, seconds()), + "+" | "=" => pomo.adjust(1.0), + "-" | "_" => pomo.adjust(-1.0), _ => {} } } @@ -792,20 +891,9 @@ fn main() { // midnight must zero rather than keep adding to yesterday. pomo.roll_day(); if pomo.tick(stamp) { + // The flash only. tick() has already alerted on every channel + // the settings allow, the toast among them. flash_started = Some(stamp); - let over = pomo.overtime(stamp); - herdr_toast( - "Pomodoro", - &format!( - "{} elapsed{}", - pomo.phase.label(), - if over >= 60.0 { - format!(", {} over", hms(over as i64)) - } else { - String::new() - } - ), - ); } if pomo.shown { let over = pomo.overtime(stamp); @@ -936,7 +1024,7 @@ fn main() { (p.accent.as_str(), "↑↓".into()), (p.dim.as_str(), " cities".into()), ]]; - if pomo.shown && tips { + if pomo.shown && pomo.hints { hints.push(vec![ (p.dim.as_str(), "[space] ".into()), ( @@ -979,7 +1067,10 @@ fn main() { // way back. Names the action rather than the state. hints.push(vec![( p.dim.as_str(), - format!("[?]{} pomodoro tips", if tips { "hide" } else { "show" }), + format!( + "[?]{} pomodoro tips", + if pomo.hints { "hide" } else { "show" } + ), )]); } hints.push(vec![(p.dim.as_str(), "[q]uit".into())]); @@ -1247,20 +1338,20 @@ mod tests { bell: false, rang_at: 0, day: today(), - enabled: false, + hints: true, notify: false, }; pomo.phase = Phase::Focus; - pomo.adjust(5.0, 0.0); + pomo.adjust(5.0); assert_eq!((pomo.focus, pomo.short, pomo.long), (30.0, 5.0, 15.0)); pomo.phase = Phase::Short; - pomo.adjust(-2.0, 0.0); + pomo.adjust(-2.0); assert_eq!((pomo.focus, pomo.short, pomo.long), (30.0, 3.0, 15.0)); pomo.phase = Phase::Long; - pomo.adjust(1.0, 0.0); + pomo.adjust(1.0); assert_eq!((pomo.focus, pomo.short, pomo.long), (30.0, 3.0, 16.0)); // And the hint reports the block in progress, not one named block. @@ -1271,7 +1362,7 @@ mod tests { // A block cannot be argued below a minute or above three hours. pomo.phase = Phase::Short; for _ in 0..10 { - pomo.adjust(-1.0, 0.0); + pomo.adjust(-1.0); } assert_eq!(pomo.short, 1.0); assert_eq!((pomo.focus, pomo.long), (30.0, 16.0), "the others are untouched"); @@ -1295,12 +1386,12 @@ mod tests { // new() loads and adjust() saves, so this needs its own state. let _held = sandbox("nudge"); let mut pomo = Pomodoro::new(&serde_json::json!({})); - pomo.adjust(5.0, 0.0); + pomo.adjust(5.0); assert_eq!(pomo.focus, 30.0); assert_eq!(pomo.duration(), 30.0 * 60.0); // It cannot be driven to zero or beyond a working day. for _ in 0..100 { - pomo.adjust(-10.0, 0.0); + pomo.adjust(-10.0); } assert!(pomo.focus >= 1.0, "focus fell to {}", pomo.focus); } @@ -1620,4 +1711,133 @@ mod tests { assert_eq!(items[1].label, "Start of Office Hour"); assert_eq!(items[1].left, 12 * 3600); } + + #[test] + fn a_day_the_clocks_move_is_not_twenty_four_hours() { + // Britain moves at one in the morning on the last Sunday of March + // and back on the last Sunday of October - in 2026, the 29th and + // the 25th. Held against a fixed 86,400 seconds, both days put the + // time remaining and the bar an hour out. + let london: Tz = "Europe/London".parse().unwrap(); + + let spring = london.with_ymd_and_hms(2026, 3, 29, 0, 30, 0).unwrap(); + let (into, len) = day_bounds(&spring); + assert_eq!(len, 23 * 3600, "the day the clocks go forward is 23 hours"); + // Half past midnight, with the jump still ahead: twenty-two and a + // half hours of the day left, not the twenty-three and a half a + // fixed day gives. + assert_eq!(len - into, 22 * 3600 + 1800); + + let autumn = london.with_ymd_and_hms(2026, 10, 25, 0, 30, 0).unwrap(); + let (into, len) = day_bounds(&autumn); + assert_eq!(len, 25 * 3600, "the day they go back is 25 hours"); + assert_eq!(len - into, 24 * 3600 + 1800); + + // And a day nothing happens on is still a plain day. + let plain = london.with_ymd_and_hms(2026, 8, 22, 6, 0, 0).unwrap(); + assert_eq!(day_bounds(&plain), (6 * 3600, 86_400)); + } + + #[test] + fn a_finished_toast_is_reaped_rather_than_left_a_zombie() { + // Every notification spawns a process, and one nobody waits on is a + // zombie for the life of the widget - an ignored pomodoro sends one + // a minute, so a panel left alone all day would leave hundreds. + let mut sent = Vec::new(); + for _ in 0..3 { + match std::process::Command::new("true") + .stdout(std::process::Stdio::null()) + .spawn() + { + Ok(child) => sent.push(child), + Err(_) => return, // nothing to spawn on this machine + } + } + // They exit in milliseconds, but "immediately" is not a promise the + // scheduler makes: allow a second before believing otherwise. + for _ in 0..100 { + reap(&mut sent); + if sent.is_empty() { + break; + } + std::thread::sleep(Duration::from_millis(10)); + } + assert!(sent.is_empty(), "{} toasts left unreaped", sent.len()); + } + + #[test] + fn the_timer_is_off_until_asked_for_and_never_starts_itself() { + let _held = sandbox("enabled"); + // With nothing configured there is nothing on screen, which is what + // the help text and the doc both promise. It was hardcoded shown. + let off = Pomodoro::new(&serde_json::json!({})); + assert!(!off.shown, "an optional panel was on screen unasked"); + assert!(!off.running); + + // pomodoro_enabled puts it there - paused. Setting `running` from + // it left the deadline at zero, and with no deadline the countdown + // reads a `left` that nothing decrements: a timer frozen at the + // full block with nothing on the row saying it was not moving. + let on = Pomodoro::new(&serde_json::json!({"pomodoro_enabled": true})); + assert!(on.shown); + assert!(!on.running, "a block nobody sat down for was being counted"); + let now = 1_000.0; + assert_eq!(on.remaining(now), on.duration()); + assert_eq!(on.remaining(now + 600.0), on.duration(), "a paused timer moved"); + } + + #[test] + fn the_hint_preference_is_not_the_pomodoros_visibility() { + // One field held both: "hints" in the state file was written from + // whether the panel was shown, so hiding the panel rewrote the [?] + // preference - which was itself never saved, and came back every + // restart. + let _held = sandbox("hints"); + let shown = serde_json::json!({"pomodoro_enabled": true}); + + let mut p = Pomodoro::new(&shown); + assert!(p.hints, "show_hints defaults to on"); + p.hints = false; // what [?] does + p.save(); + let back = Pomodoro::new(&shown); + assert!(!back.hints, "the hint preference did not survive a restart"); + assert!(back.shown, "hiding the hints hid the panel with them"); + + // And the other way about: hiding the panel leaves the hints alone. + let mut p = Pomodoro::new(&shown); + p.hints = true; + p.save(); + p.toggle(0.0); // what [p] does + assert!(!p.shown); + let back = Pomodoro::new(&shown); + assert!(!back.shown, "the panel came back after being hidden"); + assert!(back.hints, "hiding the panel rewrote the hint preference"); + } + + #[test] + fn a_nudge_moves_the_finish_line_rather_than_starting_the_block_over() { + // Twenty minutes into a twenty-five minute block, one more minute + // means six left. It used to mean twenty-six: the new length was + // assigned whole and the deadline rebuilt from now, so every nudge + // threw away however far in you were. + let _held = sandbox("nudge-keeps-progress"); + let mut pomo = Pomodoro::new(&serde_json::json!({})); + pomo.shown = true; + pomo.start_stop(0.0); + let twenty = 20.0 * 60.0; + pomo.adjust(1.0); + assert_eq!(pomo.remaining(twenty), 6.0 * 60.0); + + // Paused, where `left` is the number that counts. + pomo.start_stop(twenty); + assert_eq!(pomo.left, 6.0 * 60.0); + pomo.adjust(-2.0); + assert_eq!(pomo.left, 4.0 * 60.0); + + // Cut shorter than the time already spent and the block is over, + // which is true - the counter climbs rather than claiming minutes + // that have gone. + pomo.adjust(-20.0); + assert!(pomo.signed(twenty) < 0.0, "{} left", pomo.left); + } } From dec9fa10013d27369011a66083f1c93cb360577e Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Wed, 26 Aug 2026 12:13:03 +0800 Subject: [PATCH 127/147] check: the config scanner could not see a read that wrapped `config_use` worked a line at a time, so it matched `cfg.get("key")` and was blind to the same call split across two lines. rustfmt chooses between those forms on line width alone, which makes the blind spot arbitrary: a key stayed documented or went missing depending on how long its name was. Two real settings were hiding there - clocks' `show_hints` and `work_days`, both read through a wrapped `cfg\n.get(...)` chain, both absent from config.example.json, and this check reporting all clear the whole time. CLAUDE.md already lists the same shape as a paid-for mistake: a config audit that "read line by line and silently skipped every multi-line `cfg\n.get(...)` chain, which is most of them". `join_chains` rejoins a continuation onto the line before it, and only when the next non-space character is `.`, so nothing else changes meaning. Verified both directions rather than assumed: with the join in place and `show_hints` taken back out of the example the check fails naming that key, and with the join disabled the identical tree passes. That second half is the point - it is the bug, reproduced. Widening the receiver was tried instead and reverted. Accepting `raw.get(` and `gh.get(` alongside `cfg.get(` picks up `cwnd` and `reord_seen`, which link reads out of `ss` output and are not config; that is the false-positive direction CLAUDE.md warns turns a check off. Two candidates this surfaced were mine, not the code's: herdr-panes `refresh` and pr `token`/`token_env` looked missing only because the scan I compared against keyed sections by filename. pr declares both `pr` and `github` and its token keys live in the latter; herdr-panes declares `herdr_panes`, which documents `refresh` already. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- widgets/tests/check.rs | 34 +++++++++++++++++++++++++++++++++- 1 file changed, 33 insertions(+), 1 deletion(-) diff --git a/widgets/tests/check.rs b/widgets/tests/check.rs index d9af259..846995b 100644 --- a/widgets/tests/check.rs +++ b/widgets/tests/check.rs @@ -359,10 +359,42 @@ fn handled_keys(src: &str) -> BTreeSet<String> { } /// The config section a widget declares, and the keys it reads from it. +/// Rejoin a wrapped method chain onto the line it belongs to. +/// +/// `cfg.get("show_hints")` and the same call split over two lines are one +/// read, and rustfmt picks between them on line width alone - so a scanner +/// working a line at a time sees the first and is blind to the second. +/// Two real settings, clocks' `show_hints` and `work_days`, sat +/// undocumented behind exactly that shape while this check reported all +/// clear. A blind spot in a check that exists to find undocumented +/// settings is worse than no check, because it is read as proof. +/// +/// Only a newline whose next non-space character is `.` is removed, which +/// is narrow enough that nothing else on either line changes meaning. +/// Widening the receiver instead - accepting `raw.get(` and `gh.get(` as +/// well as `cfg.get(` - was tried and reverted: it picks up `cwnd` and +/// `reord_seen`, which are fields link reads out of `ss` output and not +/// config at all. +fn join_chains(src: &str) -> String { + let mut out = String::with_capacity(src.len()); + for line in src.lines() { + if line.trim_start().starts_with('.') && !out.is_empty() { + out.push_str(line.trim_start()); + } else { + if !out.is_empty() { + out.push('\n'); + } + out.push_str(line); + } + } + out +} + fn config_use(src: &str) -> (BTreeSet<String>, BTreeSet<String>) { let mut sections = BTreeSet::new(); let mut keys = BTreeSet::new(); - for line in src.lines() { + let joined = join_chains(src); + for line in joined.lines() { if let Some(at) = line.find("load_config(\"") { let after = &line[at + 13..]; if let Some(end) = after.find('"') { From 8606b230f44b4268e4c7994cd62ffca38a11fa02 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Wed, 26 Aug 2026 12:13:28 +0800 Subject: [PATCH 128/147] link, netwatch: a wrapped port, a hung command, and a baseline half-kept `link` cast configured ports with `as u16`, which wraps rather than refuses: `70000` became `4464`, a real port belonging to somebody else, so a typo in config.json silently watched the wrong thing. `u16::try_from` drops what cannot be a port instead. Its two `ss` invocations also ran without a timeout, so a wedged call hung the poller behind it; both take `RUN_TIMEOUT` now. `netwatch` had the worse one. When an `ss` read failed, `absorb` advanced the clock while leaving the counter baselines untouched - half a baseline, and the wrong half. The next successful read then divided a normal delta by a window that had grown across the failure, so a socket that had done 500 and 1000 bytes reported 1000500 and 2001000: three orders out, presented as a rate. The counters and the clock are kept or dropped together now, because they only mean anything as a pair. The test names the numbers rather than recomputing them, so it would have failed against the old code for the stated reason rather than agreeing with it. docs/netwatch.md's note on what HTTPS hides said "the file", which reads as the local file FILES names directly above it. It hides the request path and the remote filename; it does not hide the local file being written, nor who the transfer is with. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- docs/netwatch.md | 4 +- widgets/src/bin/link.rs | 80 ++++++++++++++++++++++++++------- widgets/src/bin/netwatch.rs | 89 ++++++++++++++++++++++++++++++++++++- 3 files changed, 154 insertions(+), 19 deletions(-) diff --git a/docs/netwatch.md b/docs/netwatch.md index abd1d19..68c69e2 100644 --- a/docs/netwatch.md +++ b/docs/netwatch.md @@ -311,8 +311,8 @@ it as a machine honestly can: ~/tmp/big.bin 3.0 MB +425.7 KB/s ── DISK ── read 0 B · written 3.0 MB since it started - HTTPS hides the URL and the filename. Who it talks to and what it writes - are above. + HTTPS hides the request path and the remote filename — not the local file + it is writing, which FILES names above, nor who it is talking to. ``` Every list is drawn in full, always, and `↑` `↓` scroll the screen. `tab` diff --git a/widgets/src/bin/link.rs b/widgets/src/bin/link.rs index 0fb63e0..2fc9439 100644 --- a/widgets/src/bin/link.rs +++ b/widgets/src/bin/link.rs @@ -90,6 +90,15 @@ struct Session { raw: HashMap<String, String>, } +/// Seconds before an external command is given up on, as link.py gave it. +/// +/// One polling thread feeds this whole widget, and `.output()` waits for +/// ever: a wedged `ss` used to hold that thread open with the pane still +/// drawing its last frame, which is the failure a frozen pane is worst at +/// showing. Bounded, the poll comes back with "ss did not answer in 5s" on +/// the error line and tries again at the next interval. +const RUN_TIMEOUT: u64 = 5; + /// A command's output, or why it could not be had. /// /// `run` folds every failure into an empty string, which is right for the @@ -98,18 +107,11 @@ struct Session { /// reporting no sockets are the same thing, and one of them is a quiet /// machine while the other is a broken pane imitating one. fn run_or(args: &[&str]) -> Result<String, String> { - match std::process::Command::new(args[0]).args(&args[1..]).output() { - Ok(out) if out.status.success() => Ok(String::from_utf8_lossy(&out.stdout).to_string()), - Ok(out) => Err(format!("{} exited {}", args[0], out.status)), - Err(e) => Err(format!("{} did not run: {}", args[0], e)), - } + tc::run(args, RUN_TIMEOUT) } fn run(args: &[&str]) -> String { - match std::process::Command::new(args[0]).args(&args[1..]).output() { - Ok(out) if out.status.success() => String::from_utf8_lossy(&out.stdout).to_string(), - _ => String::new(), - } + tc::run(args, RUN_TIMEOUT).unwrap_or_default() } /// Ports this machine accepts connections on. @@ -121,6 +123,26 @@ fn run(args: &[&str]) -> String { /// reports them listening right now. Set once at startup. static CONFIGURED_PORTS: std::sync::OnceLock<Vec<u16>> = std::sync::OnceLock::new(); +/// The `ports` key, read as port numbers. +/// +/// A checked conversion, not `as`: a port is sixteen bits and JSON numbers +/// are not, so `70000 as u16` wraps to 4464 and the widget would go on to +/// treat sessions on 4464 as inbound while ignoring the port the operator +/// asked for - a wrong answer wearing the shape of a right one. An entry +/// that is not a port is dropped instead, which leaves the setting doing +/// nothing rather than doing something else. +fn configured_ports(cfg: &serde_json::Value) -> Vec<u16> { + cfg.get("ports") + .and_then(|v| v.as_array()) + .map(|a| { + a.iter() + .filter_map(|v| v.as_u64()) + .filter_map(|n| u16::try_from(n).ok()) + .collect() + }) + .unwrap_or_default() +} + fn listening_ports() -> Result<Vec<u16>, String> { // Seeded from config, as link.py does, then whatever is actually // listening. The key exists for the ports that are not visibly @@ -404,11 +426,7 @@ struct State { fn main() { tc::maybe_help(include_str!("link_help.txt")); let cfg = tc::load_config("link"); - let named: Vec<u16> = cfg - .get("ports") - .and_then(|v| v.as_array()) - .map(|a| a.iter().filter_map(|v| v.as_u64()).map(|n| n as u16).collect()) - .unwrap_or_default(); + let named = configured_ports(&cfg); if !named.is_empty() { let _ = CONFIGURED_PORTS.set(named); } @@ -1769,10 +1787,42 @@ mod tests { // rendered as "No inbound sessions". let why = run_or(&["definitely-not-a-real-binary-xyz", "--version"]) .expect_err("a missing binary must not read as empty output"); - assert!(why.contains("did not run"), "{}", why); + // The wording belongs to the shared runner; what this widget needs + // is that the failure names the command and is not empty. assert!(why.contains("definitely-not-a-real-binary-xyz"), "{}", why); // A command that does run still comes back as Ok. assert!(run_or(&["true"]).is_ok()); + // And one that runs and fails is an error, not empty output - the + // whole reason this returns a Result. + assert!(run_or(&["false"]).is_err()); + } + + #[test] + fn a_command_that_never_answers_is_given_up_on() { + // The one polling thread feeds every pane here, so an unbounded + // wait froze the widget on its last frame with nothing said. A + // second is enough to prove the bound; RUN_TIMEOUT itself is five, + // which is too long to spend in a test. + let began = std::time::Instant::now(); + let why = tc::run(&["sleep", "30"], 1).expect_err("a wedged child must not wait for ever"); + assert!(began.elapsed() < Duration::from_secs(20), "{:?}", began.elapsed()); + assert!(why.contains("did not answer"), "{}", why); + } + + #[test] + fn a_port_too_big_to_be_one_is_dropped_rather_than_wrapped() { + // `70000 as u16` is 4464, a real port belonging to somebody else: + // the widget would have called sessions on 4464 inbound and never + // looked at what was asked for. Nothing on screen could say so. + let cfg = serde_json::json!({"ports": [22, 70000, 65535, 4_294_967_296u64]}); + let got = configured_ports(&cfg); + assert!(!got.contains(&4464), "70000 wrapped into a different port: {:?}", got); + assert!(!got.contains(&0), "a multiple of 65536 wrapped to port 0: {:?}", got); + // The two that are ports survive, including the top of the range. + assert_eq!(got, vec![22, 65535]); + // A key that is absent or the wrong shape is simply no ports. + assert!(configured_ports(&serde_json::json!({})).is_empty()); + assert!(configured_ports(&serde_json::json!({"ports": 22})).is_empty()); } #[test] diff --git a/widgets/src/bin/netwatch.rs b/widgets/src/bin/netwatch.rs index f854dc7..5b8927c 100644 --- a/widgets/src/bin/netwatch.rs +++ b/widgets/src/bin/netwatch.rs @@ -548,12 +548,44 @@ fn sample(state: &mut State, external: bool) { } else { socket_owners() }; + absorb(state, stamp, &found, &owners, counters, err); +} + +/// Fold one reading into the running totals. +/// +/// Split from `sample` so the arithmetic can be exercised without a machine +/// that happens to have the right sockets open on it. +fn absorb( + state: &mut State, + stamp: f64, + found: &HashMap<String, Seen>, + owners: &HashMap<String, (i32, String)>, + counters: Option<(u64, u64, Vec<String>)>, + err: String, +) { + // A failed `ss` is not a machine with no sockets, and the difference + // matters more than it looks: this used to say why and then go on to + // overwrite `state.last` with the empty map it had been handed. The + // next good poll found no baseline for a socket that had been open for + // hours, counted its whole lifetime as one interval's traffic, and + // divided that by the gap since the failed poll. The number that + // reached the screen was not merely wrong, it was enormous, and it + // stayed in the totals afterwards. + // + // `state.last` and `state.stamp` are one baseline and have to move + // together: keeping the counters while advancing the clock would divide + // two intervals of traffic by one interval of time, which is the same + // bug with a smaller number on it. So a failed reading advances + // neither - it records why and changes nothing else. + state.err = err; + if !state.err.is_empty() { + return; + } let gap = if state.stamp > 0.0 { (stamp - state.stamp).max(1e-6) } else { 0.0 }; - state.err = err; // A row with nothing left in the window really is idle, and says so. for row in state.totals.values_mut() { @@ -567,7 +599,7 @@ fn sample(state: &mut State, external: bool) { } let first = state.stamp == 0.0; - for (inode, seen) in &found { + for (inode, seen) in found { let was = state.last.get(inode).copied(); // A socket opened since the last sample started at zero when it was // created, so all of its counters are traffic that happened while @@ -2424,6 +2456,59 @@ fn palette() -> Palette { mod tests { use super::*; + #[test] + fn a_failed_ss_read_does_not_reset_the_counter_baselines() { + // One socket, open throughout, whose kernel counters only ever + // climb. `ss` answers, fails, then answers again. + let socket = |sent, recv| { + let mut one = HashMap::new(); + one.insert( + "42".to_string(), + Seen { + sent, + recv, + peer: "192.0.2.1".into(), + port: 443, + mine: 51000, + cgroup: String::new(), + }, + ); + one + }; + let owners = HashMap::new(); + let mut state = State::default(); + + // The first reading is a baseline: a socket already open when we + // started did its megabytes before we were watching. + absorb(&mut state, 1000.0, &socket(1_000_000, 2_000_000), &owners, None, String::new()); + assert_eq!(state.stamp, 1000.0); + assert_eq!(state.last.get("42"), Some(&(1_000_000, 2_000_000))); + + // `ss` wedges or will not run. It must say so and leave the + // baseline alone - both halves of it, the counters and the clock + // they were read at. + absorb(&mut state, 1001.0, &HashMap::new(), &owners, None, "ss would not run".into()); + assert_eq!(state.err, "ss would not run"); + assert_eq!(state.last.get("42"), Some(&(1_000_000, 2_000_000)), "baseline cleared"); + assert_eq!(state.stamp, 1000.0, "clock advanced without the counters it pairs with"); + + // Two seconds after the last good reading, half a kilobyte up and a + // kilobyte down. Before the fix this socket had no baseline left, + // so the whole megabyte of its lifetime counted as traffic in the + // one second since the failed poll. + absorb(&mut state, 1002.0, &socket(1_000_500, 2_001_000), &owners, None, String::new()); + assert!(state.err.is_empty(), "a good reading must clear the error: {}", state.err); + let row = state + .totals + .get(&(0, "(unattributed)".to_string())) + .expect("the socket has a row"); + assert_eq!((row.up, row.down), (500, 1000), "counted a lifetime as one interval"); + // 500 bytes and 1000 bytes over the two seconds since the last + // reading that had numbers in it. + assert!((row.up_rate - 250.0).abs() < 1.0, "{}", row.up_rate); + assert!((row.down_rate - 500.0).abs() < 1.0, "{}", row.down_rate); + } + /// Colour is not width: `len()` counts escape bytes, so every column /// check below measures the text alone. fn bare(line: &str) -> String { From bff6789a53447994089e7f45c4088b80586dcbd2 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Wed, 26 Aug 2026 12:13:48 +0800 Subject: [PATCH 129/147] usage: ask x.ai every five minutes, not every hour `grok_ping_minutes` defaulted to 60 on the reasoning that the window it reports moves over days, so an hour is current enough. The window does, but the spend inside it does not: it moves while you work, and an hour-old reading of a live session is the stale figure the ping exists to replace. Five minutes is one small GET twelve times an hour. Unchanged: `grok_ping` is still off by default, so nothing here starts talking to a vendor on launch. This only sets the pace for readers who have turned it on. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- config.example.json | 2 +- docs/usage.md | 2 +- widgets/src/bin/usage.rs | 10 ++++++---- 3 files changed, 8 insertions(+), 6 deletions(-) diff --git a/config.example.json b/config.example.json index 24161a8..19cb9c7 100644 --- a/config.example.json +++ b/config.example.json @@ -110,7 +110,7 @@ "plan_cost": {}, "_grok_ping_comment": "Grok is the only agent with no live quota: its figures come from the log its own CLI writes, so they move only when you use Grok on this machine. Turn grok_ping on to ask x.ai instead, using the token the CLI leaves in ~/.grok/auth.json. That also runs the Grok CLI once after a session goes quiet, which is what refreshes the token - without it the asking works until the token lapses and then silently stops. Off by default: a widget that reads should not start talking to a vendor, or starting somebody else's program, because it was launched.", "grok_ping": false, - "grok_ping_minutes": 60 + "grok_ping_minutes": 5 }, "link": { "_comment": "Every established connection into a port this machine listens on. Empty ports means all of them, which is the useful default. No network traffic: the numbers come from the kernel's own accounting via ss.", diff --git a/docs/usage.md b/docs/usage.md index e823085..8f27e46 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -885,7 +885,7 @@ Three settings, all off or hourly by default: | key | default | what it does | |---|---|---| | `grok_ping` | `false` | GET `cli-chat-proxy.grok.com/v1/billing` with the bearer token the Grok CLI leaves in `~/.grok/auth.json`, **and** run `grok agent stdio` once after a session goes quiet to refresh that token | -| `grok_ping_minutes` | `60` | how often. The window moves over days; an hour is current without being traffic | +| `grok_ping_minutes` | `5` | how often. The window moves over days, but the spend inside it moves while you work, so five minutes keeps the figure actionable; one small GET twelve times an hour | **One setting, not two.** The refresh was a second key for one release and should not have been. The token expires — mine had lapsed 8.6 days before I diff --git a/widgets/src/bin/usage.rs b/widgets/src/bin/usage.rs index 85ead7a..f7279df 100644 --- a/widgets/src/bin/usage.rs +++ b/widgets/src/bin/usage.rs @@ -1187,9 +1187,11 @@ struct Config { /// then stops, silently, which is the failure the refresh exists to /// prevent. Nobody wants the first without the second. grok_ping: bool, - /// Minutes between those requests. The window it reports moves over - /// days, so an hour is frequent enough to be current and rare enough - /// not to be traffic. + /// Minutes between those requests. Five, so the figure on screen is + /// one a reader can act on: the window it reports moves over days, but + /// the spend inside it moves while they work, and an hour-old reading + /// of a live session is exactly the stale number this asks the server + /// to avoid. One small GET twelve times an hour is not traffic. grok_ping_minutes: f64, } @@ -1226,7 +1228,7 @@ fn read_config() -> Config { .get("grok_ping") .and_then(|v| v.as_bool()) .unwrap_or(false), - grok_ping_minutes: tc::cfg_f64(&raw, "grok_ping_minutes", 60.0), + grok_ping_minutes: tc::cfg_f64(&raw, "grok_ping_minutes", 5.0), } } From dcdac01d7df964db0a950d95aa111318c38d1abf Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Wed, 26 Aug 2026 12:25:35 +0800 Subject: [PATCH 130/147] usage: grok asked, was answered, and still said "not live" MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two defects behind one badge, both found by turning the ping on and watching it fail on a machine that had it configured correctly. **The refresh could not fire when it was needed.** It was gated on a session having ended in the last six hours, and the token turns out to last about six hours - measured here at 6h from issue. So the gate opens only while the token is healthy and is shut for good by the time it lapses. Anyone who had not run Grok since yesterday had asking silently switched off, which is word for word the failure the refresh exists to prevent, as its own comment says. It is now also keyed on the token: within ten minutes of expiry it refreshes, whatever the last session was. Both original guards are kept - asking must be on, and nothing may be running that the CLI would start underneath. Attempts are deduped on the expiry value, so a login that has genuinely run out costs one attempt and not one every five minutes; a CLI respawned forever is a worse failure than the stale row it was fixing. Verified rather than assumed: this machine's token had lapsed 3h07m, and running the exact command the widget runs moved `expires_at` from 01:01:33 to 10:16:24 with no interaction, after which billing returned 200 where it had returned 401. **"not live" was one phrase for four situations.** A lapsed token, a missing one, an endpoint that did not answer, and a 200 carrying a null percentage all collapsed to the same two words, and three of the four are the reader's to fix. `live_quota` threw the reason away by returning None; it is split into `token_of`, which decides over a value and a clock so it is testable without a token on disk, and `fetch_billing`. The row now reads `not live · polled x.ai just now, every 5m · the token lapsed 3h ago - the Grok CLI refreshes it`. Both tests were watched to fail: dropping the expiry branch, and dropping the reason from the render. Not changed, and worth a look separately: a 200 that names the current period but sends a null percentage is still discarded whole, so the row falls back to the log's percentage from a window that has closed and rolls the reset forward with a `~`. The live answer knows the real window. Which of the two belongs on screen is a display decision, not a bug fix, so it is left alone and said out loud here. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- docs/usage.md | 29 ++++- widgets/src/bin/usage/grok.rs | 212 +++++++++++++++++++++++++++++++--- 2 files changed, 220 insertions(+), 21 deletions(-) diff --git a/docs/usage.md b/docs/usage.md index 8f27e46..91761c9 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -884,7 +884,7 @@ Three settings, all off or hourly by default: | key | default | what it does | |---|---|---| -| `grok_ping` | `false` | GET `cli-chat-proxy.grok.com/v1/billing` with the bearer token the Grok CLI leaves in `~/.grok/auth.json`, **and** run `grok agent stdio` once after a session goes quiet to refresh that token | +| `grok_ping` | `false` | GET `cli-chat-proxy.grok.com/v1/billing` with the bearer token the Grok CLI leaves in `~/.grok/auth.json`, **and** run `grok agent stdio` to refresh that token — once after a session goes quiet, and once when the token is within ten minutes of lapsing | | `grok_ping_minutes` | `5` | how often. The window moves over days, but the spend inside it moves while you work, so five minutes keeps the figure actionable; one small GET twelve times an hour | **One setting, not two.** The refresh was a second key for one release and @@ -894,6 +894,15 @@ for a while and then silently stops, which is the failure the refresh exists to prevent. Nobody wants the first without the second, so turning on `grok_ping` turns on both. +**The refresh is keyed on the token, not on a session.** For a while it fired +only in the six hours after a session ended, and the token turned out to last +about six hours too — so anyone who had not run Grok since yesterday was in the +failure above with the fix switched on. It now also fires when the token is +about to lapse, whatever the last session was, subject to the same two guards: +`grok_ping` is on, and nothing is running that the CLI would start underneath. +It is attempted once per expiry value, so a login that has genuinely run out +costs one attempt rather than one every five minutes. + **Off by default**, because it does two things a widget that reads has no business doing unasked: it talks to a vendor, and it starts somebody else's program. @@ -908,9 +917,25 @@ The screen says which state it is in, in both places it appears: ``` ── WEEKLY QUOTA ── resets in 1.1 days - live · polled x.ai just now, every 1h + live · polled x.ai just now, every 5m +``` + +When asking is on and the figure still is not the server's, the row says +which of the reasons applies rather than leaving `not live` to cover all of +them — only some are the reader's to fix: + +``` + not live · polled x.ai just now, every 5m · the token lapsed 3h ago - the Grok CLI refreshes it + not live · polled x.ai 4m ago, every 5m · x.ai did not answer + not live · polled x.ai just now, every 5m · x.ai sent no percentage for this period ``` +The last of those is a 200 that names the billing period but sends a null +percentage. The log's reading is kept, because it is the only percentage +there is — but it belongs to an earlier window, so the row stays marked +`not live` and its reset keeps the `~` that says the date is rolled forward +rather than stated. + The age quoted is the **reading's**, not the file's. The CLI touches that log whenever it starts, so a file written minutes ago can still hold a credit figure from a fortnight back, and "written 17m ago" beside a percentage reads diff --git a/widgets/src/bin/usage/grok.rs b/widgets/src/bin/usage/grok.rs index 14c50f1..8424b4c 100644 --- a/widgets/src/bin/usage/grok.rs +++ b/widgets/src/bin/usage/grok.rs @@ -45,6 +45,11 @@ const CLI: &str = ".grok/bin/grok"; const PING_KEY: &str = "grok:billing"; /// Cache key for the last session-end refresh, so one ending refreshes once. const SEEN_KEY: &str = "grok:session-seen"; +/// Cache key for the last expiry a refresh was attempted against. +const EXPIRY_KEY: &str = "grok:token-expiry"; +/// Refresh this long before the token actually lapses, so the ask that +/// follows is not the one that discovers it has. +const TOKEN_MARGIN: f64 = 600.0; /// How long a session must be quiet before it counts as over. Long enough /// that a pause for thought is not an ending. const SESSION_QUIET: f64 = 120.0; @@ -105,6 +110,9 @@ pub struct Data { /// Seconds between asks, so the tab can say what the interval is rather /// than leaving the reader to find it in a config file. quota_every: f64, + /// Why the figure on screen is not the server's, when it is not. Empty + /// when it is, or when nothing is asking. + quota_why: String, } /// The integer following `key` on a line. @@ -225,21 +233,39 @@ fn newest_quota<'a>(lines: impl Iterator<Item = &'a str>) -> Option<Quota> { /// Held between asks rather than asked on every frame: the pane redraws /// every thirty seconds and this window moves over days, so the interval is /// the configured one and the reading in between is the one already had. -fn quota_now(caches: &mut Caches, cfg: &Config) -> (Option<Quota>, bool, f64) { +/// The credit window, whether it came from the server, when it was asked +/// for, and - when it did not - which of the four reasons applies. +fn quota_now(caches: &mut Caches, cfg: &Config) -> (Option<Quota>, bool, f64, String) { let from_log = || { newest_quota(tail_lines(&under_home(LOG), LOG_TAIL).iter().map(String::as_str)) }; if !cfg.grok_ping { - return (from_log(), false, 0.0); + return (from_log(), false, 0.0, String::new()); } + let key = match usable_token() { + Ok(k) => k, + Err(why) => return (from_log(), false, 0.0, why), + }; let ttl = (cfg.grok_ping_minutes * 60.0).max(60.0); - let got = cached(caches, PING_KEY, ttl, || live_quota(QUOTA_TIMEOUT)); + let got = cached(caches, PING_KEY, ttl, || fetch_billing(&key, QUOTA_TIMEOUT)); // When the ask was actually made, which is not this frame most of the // time. The tab reports it, so it has to be the fetch and not the read. let at = caches.live.get(PING_KEY).map(|(when, _, _)| *when).unwrap_or(0.0); - match got.as_ref().and_then(quota_from) { - Some(q) => (Some(q), true, at), - None => (from_log(), false, at), + match got.as_ref() { + None => (from_log(), false, at, "x.ai did not answer".to_string()), + Some(body) => match quota_from(body) { + Some(q) => (Some(q), true, at, String::new()), + // A 200 that names the period but sends a null percentage. The + // log reading is kept, because it is the only percentage there + // is, but the row must not read as though the server confirmed + // it - it did not, and it is a window older than this one. + None => ( + from_log(), + false, + at, + "x.ai sent no percentage for this period".to_string(), + ), + }, } } @@ -285,11 +311,12 @@ pub fn read(caches: &mut Caches, cfg: &Config) -> Data { // missing is the failure this repo keeps paying for. ok stays false, // so the tab says there are no sessions - under the quota, not // instead of it. - let (quota, quota_live, quota_at) = quota_now(caches, cfg); + let (quota, quota_live, quota_at, quota_why) = quota_now(caches, cfg); return Data { quota, quota_live, quota_at, + quota_why, quota_every: cfg.grok_ping.then(|| cfg.grok_ping_minutes * 60.0).unwrap_or(0.0), ..Data::default() }; @@ -358,6 +385,43 @@ pub fn read(caches: &mut Caches, cfg: &Config) -> Data { caches.live.remove(PING_KEY); } } + // The gate above fires only in the six hours after a session ends, and + // the token lapses on its own clock about that often - measured at six + // hours on the machine this was found on. So anyone who has not run + // Grok since yesterday had the asking silently switched off, which is + // the exact failure the refresh above exists to prevent and says so in + // its own comment. Reaching it needs a gate keyed on the token rather + // than on a session. + // + // Both of the original guards are kept: nothing happens unless asking + // was turned on, and nothing starts the CLI underneath somebody who is + // using it. What is dropped is the upper bound on how long ago they + // last did. + // + // Deduped on the expiry value, not on time. A refresh that does not + // move the expiry - a login that has genuinely run out - must be tried + // once and then left alone; a CLI respawned every five minutes for ever + // is a worse failure than the stale row it was trying to fix. + if cfg.grok_ping { + let quiet = if newest > 0.0 { now() - newest } else { f64::MAX }; + let expiry = token_expiry(); + if let Some(expiry) = expiry { + let tried = caches + .live + .get(EXPIRY_KEY) + .and_then(|(_, v, _)| v.as_ref()) + .and_then(|v| v.as_f64()) + .unwrap_or(f64::NAN); + if quiet > SESSION_QUIET && expiry <= now() + TOKEN_MARGIN && tried != expiry { + refresh_token(); + caches.live.insert( + EXPIRY_KEY.to_string(), + (now(), Some(serde_json::json!(expiry)), f64::MAX), + ); + caches.live.remove(PING_KEY); + } + } + } let quota_read = quota_now(caches, cfg); Data { ok: true, @@ -369,6 +433,7 @@ pub fn read(caches: &mut Caches, cfg: &Config) -> Data { quota: quota_read.0, quota_live: quota_read.1, quota_at: quota_read.2, + quota_why: quota_read.3, quota_every: cfg.grok_ping.then(|| cfg.grok_ping_minutes * 60.0).unwrap_or(0.0), } } @@ -391,21 +456,61 @@ pub fn read(caches: &mut Caches, cfg: &Config) -> Data { /// a round trip, and the log is a better answer than a failed request. The /// CLI refreshes the token whenever it runs, so this works for as long as /// Grok is in use and stops when it is not, which is the honest shape. -fn live_quota(seconds: u64) -> Option<serde_json::Value> { - let raw = std::fs::read_to_string(under_home(AUTH)).ok()?; - let parsed: serde_json::Value = serde_json::from_str(&raw).ok()?; - // Keyed by issuer and account, so the entry is found by shape rather - // than by a name that is different on every machine. - let entry = parsed - .as_object()? - .values() - .find(|v| v.get("key").and_then(|k| k.as_str()).is_some_and(|k| !k.is_empty()))?; - let key = entry["key"].as_str()?; +/// The token entry the CLI left on disk, or why there is not one. +/// +/// Keyed by issuer and account, so the entry is found by shape rather than +/// by a name that is different on every machine. +fn token_entry() -> Result<serde_json::Value, String> { + let raw = std::fs::read_to_string(under_home(AUTH)) + .map_err(|_| "the Grok CLI has left no token on this disk".to_string())?; + let parsed: serde_json::Value = serde_json::from_str(&raw) + .map_err(|_| "the token the CLI left is not readable JSON".to_string())?; + parsed + .as_object() + .and_then(|o| { + o.values() + .find(|v| v.get("key").and_then(|k| k.as_str()).is_some_and(|k| !k.is_empty())) + }) + .cloned() + .ok_or_else(|| "the token file names no account".to_string()) +} + +/// When the token on disk lapses, as epoch seconds. +fn token_expiry() -> Option<f64> { + iso_epoch(&text(&token_entry().ok()?, "expires_at")) +} + +/// The bearer token to ask with, or why the ask cannot even be tried. +/// +/// The expiry is checked here rather than left to the server so a lapsed +/// token costs no request - but the reason is carried out instead of being +/// flattened to None, because "not live" for a token that lapsed an hour +/// ago and "not live" for an endpoint that is down are the same two words +/// for two different things, and only one of them is fixed by waiting. +fn usable_token() -> Result<String, String> { + token_of(&token_entry()?, now()) +} + +/// The same decision, over a value and a clock, so it can be tested without +/// a token on disk and without waiting for one to lapse. +fn token_of(entry: &serde_json::Value, at: f64) -> Result<String, String> { + let key = entry["key"] + .as_str() + .filter(|k| !k.is_empty()) + .ok_or_else(|| "the token file names no account".to_string())? + .to_string(); if let Some(expiry) = iso_epoch(&text(entry, "expires_at")) { - if expiry <= now() { - return None; + if expiry <= at { + return Err(format!( + "the token lapsed {} ago - the Grok CLI refreshes it", + left_span(at - expiry) + )); } } + Ok(key) +} + +fn fetch_billing(key: &str, seconds: u64) -> Option<serde_json::Value> { get_json( BILLING, &[("Authorization", &format!("Bearer {}", key))], @@ -539,6 +644,18 @@ fn freshness(d: &Data, w: usize, p: &Palette) -> Vec<String> { p.dim.as_str(), format!(" · polled x.ai {}, every {}", last, every(d.quota_every)), ), + // "not live" alone is one phrase for four situations, and + // three of them are fixable by the reader. Saying which + // costs a clause and is the difference between a widget + // that looks broken and one that says what to do. + ( + p.dim.as_str(), + if d.quota_why.is_empty() { + String::new() + } else { + format!(" · {}", d.quota_why) + }, + ), ], w - 1, )); @@ -1051,6 +1168,62 @@ mod tests { assert!(!plan_block(&d, 80, &palette()).is_empty()); } + #[test] + fn a_lapsed_token_is_reported_as_lapsed_not_as_missing() { + // These were one answer - None - and the tab said "not live" for + // both. Only one of them is the reader's to fix, so they have to + // read differently. + // 2001-09-09T01:46:40Z, so the ISO stamps below are readable. + let at = 1_000_000_000.0; + let live = serde_json::json!({ + "key": "k", "expires_at": "2001-09-09T01:46:40Z" // at + 0, see below + }); + // A token with no expiry at all is usable: the server is the judge. + assert_eq!(token_of(&serde_json::json!({"key": "k"}), at), Ok("k".into())); + + // Lapsed an hour ago. + let gone = serde_json::json!({"key": "k", "expires_at": "2001-09-09T00:46:40Z"}); + let why = token_of(&gone, at).unwrap_err(); + assert!(why.contains("lapsed"), "{}", why); + assert!(why.contains("Grok CLI"), "says what refreshes it: {}", why); + + // Still good for an hour. + let good = serde_json::json!({"key": "k", "expires_at": "2001-09-09T02:46:40Z"}); + assert_eq!(token_of(&good, at), Ok("k".into())); + + // Exactly at the boundary counts as lapsed, not as usable. + assert!(token_of(&live, at).is_err()); + + // No key is a different reason again. + let why = token_of(&serde_json::json!({"expires_at": "x"}), at).unwrap_err(); + assert!(why.contains("no account"), "{}", why); + } + + #[test] + fn the_badge_says_which_of_the_reasons_applies() { + // "not live" on its own was the same two words for a lapsed token, + // a dead endpoint and a null percentage. + let p = palette(); + let d = Data { + quota: newest_quota([LOG_LINE].into_iter()), + quota_live: false, + quota_at: now() - 30.0, + quota_every: 300.0, + quota_why: "the token lapsed 3h ago - the Grok CLI refreshes it".into(), + ..Data::default() + }; + let rows = freshness(&d, 110, &p); + let joined = rows.join("\n"); + assert!(joined.contains("not live"), "{}", joined); + assert!(joined.contains("token lapsed"), "reason missing: {}", joined); + + // And says nothing extra when the reading is the server's. + let ok = Data { quota_live: true, quota_why: String::new(), ..d.clone() }; + let joined = freshness(&ok, 110, &p).join("\n"); + assert!(joined.contains("live"), "{}", joined); + assert!(!joined.contains(" · the"), "invented a reason: {}", joined); + } + #[test] fn the_tab_carries_its_subscription_at_every_width_the_wall_uses() { // The bar's width is what is left after the labels, and this pane @@ -1069,6 +1242,7 @@ mod tests { quota_live: false, quota_at: 0.0, quota_every: 0.0, + quota_why: String::new(), }; for w in [40usize, 80, 200] { let rows = tab(&d, w, 24, &Config::default(), &p); From 05bf030d448cbecb69b6e680325a57773b11d3be Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Wed, 26 Aug 2026 12:30:31 +0800 Subject: [PATCH 131/147] widgets: the code the port stopped using, and one doc that stopped being complete The release build carried five dead-code warnings, all of them from the port rather than from this round of review, and a build that warns every time is a build whose warnings stop being read. `link` kept `sparkline` and its `SPARK` ramp after the shared chart helpers replaced them. The compiler called the function unused because nothing draws with it; a test still referenced it, which is what kept it compiling, so the test went with it. A test whose only subject is a function no screen calls is not coverage. `link` also carried a typed `cwnd` field that nothing read. The value is not lost - the detail row shows it out of the `raw` map, which is where it was always read from, and the parser test exercises `num` directly. `netwatch` kept a `SECTIONS` constant orphaned when the section rule moved into one place. `clocks` keeps its three unused palette fields, with the reason written down. They are clocks.py's palette carried over whole, and a palette is a set - taking the unused thirds out would leave the rest looking chosen rather than inherited, and the file they came from is deleted now, so nothing remains to check a replacement against. docs/herdr-panes.md described PROCESSES and IDLE as the two answers. There are three: a pane the CLI could not be asked about is neither, and it sorts to the top with its reason rather than being folded into either list. The doc says so, including why `[i]` cannot hide one. Release build is warning-free. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- docs/herdr-panes.md | 8 ++++++++ widgets/src/bin/clocks.rs | 8 ++++++++ widgets/src/bin/link.rs | 26 -------------------------- widgets/src/bin/netwatch.rs | 2 -- 4 files changed, 16 insertions(+), 28 deletions(-) diff --git a/docs/herdr-panes.md b/docs/herdr-panes.md index f890463..f06d855 100644 --- a/docs/herdr-panes.md +++ b/docs/herdr-panes.md @@ -51,6 +51,14 @@ monitors, builds — with the command, CPU and memory. **IDLE** lists panes at a shell prompt by directory, because the panel is also how you navigate: a shell sitting in a repo is somewhere you want to jump to even with nothing running. +There is a third answer, and PROCESSES carries it too. A pane the CLI could +not be asked about is neither running something nor resting: it sorts to the +top with `⚠ could not be read` and the reason on its own row, and the heading +counts it apart — `3 panes running something · 29 could not be read`. It is +kept visible on purpose, and `[i]` hides only panes known to be at a prompt, +because an unreadable pane filtered out of sight is exactly the shape this +widget exists to avoid: a failure that looks like an empty list. + ## How it knows Everything comes from the Herdr CLI, so this is a Herdr client rather than a diff --git a/widgets/src/bin/clocks.rs b/widgets/src/bin/clocks.rs index ca06201..9220d7b 100644 --- a/widgets/src/bin/clocks.rs +++ b/widgets/src/bin/clocks.rs @@ -1202,8 +1202,16 @@ struct Palette { head: String, big_top: String, big_base: String, + // Nothing draws these three. They are clocks.py's palette carried + // over whole, and a palette is a set: taking the unused thirds out + // would leave the rest looking chosen rather than inherited, and the + // file they were inherited from is now deleted, so there would be + // nothing left to check them against. + #[allow(dead_code)] bar: String, + #[allow(dead_code)] sun: String, + #[allow(dead_code)] moon: String, } diff --git a/widgets/src/bin/link.rs b/widgets/src/bin/link.rs index 2fc9439..f5a5aba 100644 --- a/widgets/src/bin/link.rs +++ b/widgets/src/bin/link.rs @@ -44,7 +44,6 @@ const MIN_CHART: usize = 12; fn scroll_label(first: usize, last: usize, total: usize) -> String { format!("rows {:>3}-{:>3} of {:>3}", first, last, total) } -const SPARK: &[char] = &['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█']; /// The hues sessions are drawn in, kept as numbers so a faded set can be /// mixed from the same six. const HUES: &[(u8, u8, u8)] = &[ @@ -83,7 +82,6 @@ struct Session { /// that has the previous reading to subtract. recent_loss: Option<f64>, delivery: Option<f64>, - cwnd: Option<f64>, mss: Option<f64>, lastsnd: Option<f64>, lastrcv: Option<f64>, @@ -248,7 +246,6 @@ fn sessions() -> Result<Vec<Session>, String> { retrans_bytes: num(&m, "bytes_retrans").unwrap_or(0.0), recent_loss: None, delivery: num(&m, "delivery_rate"), - cwnd: num(&m, "cwnd"), mss: num(&m, "mss"), lastsnd: num(&m, "lastsnd"), lastrcv: num(&m, "lastrcv"), @@ -368,20 +365,6 @@ fn colour_for<'a>(ratio: Option<f64>, loss: Option<f64>, p: &'a Palette) -> &'a } } -fn sparkline(values: &[f64], width: usize) -> String { - if values.is_empty() { - return String::new(); - } - let window: Vec<f64> = values.iter().rev().take(width).rev().copied().collect(); - let hi = window.iter().cloned().fold(0.0f64, f64::max).max(1e-9); - window - .iter() - .map(|v| { - let level = ((v / hi) * (SPARK.len() - 1) as f64).round() as usize; - SPARK[level.min(SPARK.len() - 1)] - }) - .collect() -} /// Fit samples to the columns available, by median. /// @@ -1685,15 +1668,6 @@ mod tests { assert_eq!(condense(&[1.0, 2.0], 8), vec![1.0, 2.0]); } - #[test] - fn a_sparkline_scales_to_its_own_peak() { - let line = sparkline(&[0.0, 5.0, 10.0], 3); - let chars: Vec<char> = line.chars().collect(); - assert_eq!(chars.len(), 3); - assert_eq!(chars[0], '▁'); - assert_eq!(chars[2], '█'); - } - #[test] fn window_labels_are_short() { assert_eq!(window_label(60.0), "1m"); diff --git a/widgets/src/bin/netwatch.rs b/widgets/src/bin/netwatch.rs index 5b8927c..95dfb33 100644 --- a/widgets/src/bin/netwatch.rs +++ b/widgets/src/bin/netwatch.rs @@ -858,8 +858,6 @@ fn braille_row(masks: &[u8], colour: &str) -> Vec<(String, String)> { // processes and out of nothing at all for anybody else's, which is why the // screen says so rather than showing empty lists. -const SECTIONS: [&str; 3] = ["endpoints", "connections", "files"]; - /// Reverse DNS, off the drawing thread. /// /// A PTR lookup takes half a second when it works and longer when it does From 6a76fc559120ad8d7e023ddc069b4e37596c2411 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Wed, 26 Aug 2026 12:33:12 +0800 Subject: [PATCH 132/147] core: the version stamp had stopped being rebuilt at all The previous commit removed build.rs's `rerun-if-changed` watches and said that running the script on every build was what made the stamp true. It did the opposite, and the claim was never tested against a moving commit - only against a rebuild timed at 0.03s, which is exactly what not running looks like. Cargo reruns a build script when any file in the package changes only while the script emits no `rerun-if-*` directive at all. This one has always emitted `rerun-if-env-changed=SOURCE_DATE_EPOCH`, which overrides that default outright: with the watches gone, the only thing that could rerun it was a change to that variable. Nothing ever changed it. Measured on this tree: four commits after the change, with a clean working tree, `usage --version` reported a commit four behind and a `-dirty` marker that had not been true for hours. A `cargo build` that recompiled every crate for thirty-two seconds did not move it. A path that does not exist cannot be stat-ed, and cargo answers that by rerunning the script. `.stamp-every-build` is a sentinel and nothing should ever create it. Verified in both directions this time: clean tree stamps the current commit with no marker, an edited tree gains `-dirty` on the next build, and reverting the edit takes it away again. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- core/build.rs | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/core/build.rs b/core/build.rs index 13deaec..95fa4f4 100644 --- a/core/build.rs +++ b/core/build.rs @@ -65,9 +65,21 @@ fn main() { println!("cargo:rustc-env=TOYS_COMMIT={}", commit); println!("cargo:rustc-env=TOYS_BUILD_DATE={}", date); - // No `rerun-if-changed` at all, which makes cargo run this on every - // build. That is deliberate and it is the only thing that makes the - // stamp true. + // Run on every build, which is the only thing that makes the stamp + // true - and getting that takes a directive, not the absence of one. + // + // "Emit no `rerun-if-*` and cargo reruns when any file in the package + // changes" is true only while the script emits none at all. This one + // has always emitted `rerun-if-env-changed` below, which overrides the + // default outright: the script then reruns when SOURCE_DATE_EPOCH + // changes and at no other time. Removing the watches did not make it + // run always, it made it run almost never - a full rebuild of every + // crate left the stamp naming a commit four ahead of it and carrying a + // `-dirty` the tree had not had for hours. + // + // A path that does not exist cannot be stat-ed, and cargo answers that + // by rerunning. It is a sentinel, not a file: nothing should ever + // create it. // // Watching `.git/HEAD` does not work: on a branch checkout that file // holds `ref: refs/heads/<branch>` and does not move when a commit @@ -81,5 +93,6 @@ fn main() { // dependents when it changes, so a no-op rebuild is 0.03s. The first // build after the tree goes from clean to dirty relinks the fourteen // binaries, which is exactly when their stamp has genuinely changed. + println!("cargo:rerun-if-changed=.stamp-every-build"); println!("cargo:rerun-if-env-changed=SOURCE_DATE_EPOCH"); } From 25998e357e83df2c06e984331300686bb54eb18a Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Wed, 26 Aug 2026 12:37:41 +0800 Subject: [PATCH 133/147] core: watch the git refs and the source trees, not everything and not nothing Running build.rs unconditionally made the stamp true and cost twenty-eight seconds on every no-op build, because a rerun relinks all fourteen binaries whether or not the stamp changed. `cargo test` is the ritual before every commit here, so that is the wrong trade. Both halves are watched explicitly instead: the git files git itself resolves - which is the only way that works in a linked worktree, where `.git` is a file - cover the commit, and the two source trees cover `-dirty` at no cost, because a source edit was going to rebuild those crates anyway. No-op build measured at 0.04s. Stamp verified across all four transitions: clean, edited, reverted, and a new commit. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- core/build.rs | 82 +++++++++++++++++++++++++++++++++++---------------- 1 file changed, 57 insertions(+), 25 deletions(-) diff --git a/core/build.rs b/core/build.rs index 95fa4f4..722d538 100644 --- a/core/build.rs +++ b/core/build.rs @@ -65,34 +65,66 @@ fn main() { println!("cargo:rustc-env=TOYS_COMMIT={}", commit); println!("cargo:rustc-env=TOYS_BUILD_DATE={}", date); - // Run on every build, which is the only thing that makes the stamp - // true - and getting that takes a directive, not the absence of one. + // What has to rerun this script, and what must not. // - // "Emit no `rerun-if-*` and cargo reruns when any file in the package - // changes" is true only while the script emits none at all. This one - // has always emitted `rerun-if-env-changed` below, which overrides the - // default outright: the script then reruns when SOURCE_DATE_EPOCH - // changes and at no other time. Removing the watches did not make it - // run always, it made it run almost never - a full rebuild of every - // crate left the stamp naming a commit four ahead of it and carrying a - // `-dirty` the tree had not had for hours. + // Two false starts are worth recording, because each looked right. // - // A path that does not exist cannot be stat-ed, and cargo answers that - // by rerunning. It is a sentinel, not a file: nothing should ever - // create it. + // Watching `.git/HEAD` alone fails twice over: on a branch checkout + // that file holds `ref: refs/heads/<branch>` and does not move when a + // commit lands, and in a linked worktree there is no `.git` directory + // at all. So git is asked where these actually live, and the ref HEAD + // names is followed to the file that does move. // - // Watching `.git/HEAD` does not work: on a branch checkout that file - // holds `ref: refs/heads/<branch>` and does not move when a commit - // lands. Watching the ref it names fixes the commit half - but nothing - // in `.git` moves when a source file is edited, so `-dirty` stayed - // absent while the tree was dirty. A marker that says "clean" over a - // modified tree is worse than no marker: it is a claim, and it is false. + // Then the watches were removed altogether, on the theory that a + // script emitting no `rerun-if-changed` runs on every build. That rule + // holds only for a script emitting no `rerun-if-*` of any kind, and + // this one emits `rerun-if-env-changed` below - which overrides the + // default outright. The result was a script that ran almost never: a + // clean tree four commits later still stamped the old sha and a + // `-dirty` that was hours stale, and a thirty-second full rebuild did + // not move it. // - // The cost was measured rather than feared. The script is three git - // calls; cargo compares the environment it emits and only rebuilds - // dependents when it changes, so a no-op rebuild is 0.03s. The first - // build after the tree goes from clean to dirty relinks the fourteen - // binaries, which is exactly when their stamp has genuinely changed. - println!("cargo:rerun-if-changed=.stamp-every-build"); + // Running it unconditionally does work, and costs twenty-eight seconds + // on every no-op build, because a rerun relinks all fourteen binaries + // whether or not the stamp changed. `cargo test` is the ritual before + // every commit here, so that is the wrong trade. + // + // So both halves are watched explicitly. The git files cover the + // commit; the source trees cover `-dirty`, and cost nothing, because a + // source edit was going to rebuild those crates anyway. What this + // cannot see is a new untracked file that no crate compiles - the + // stamp stays clean for one build longer than it should, which is the + // one gap left and a smaller lie than either of the above. + let watch_git = |path: &str| { + let resolved = Command::new("git") + .args(["rev-parse", "--git-path", path]) + .output() + .ok() + .filter(|o| o.status.success()) + .and_then(|o| String::from_utf8(o.stdout).ok()) + .map(|s| s.trim().to_string()) + .filter(|s| !s.is_empty()); + if let Some(file) = resolved { + println!("cargo:rerun-if-changed={}", file); + } + }; + watch_git("HEAD"); + watch_git("packed-refs"); + if let Some(head_ref) = Command::new("git") + .args(["symbolic-ref", "-q", "HEAD"]) + .output() + .ok() + .filter(|o| o.status.success()) + .and_then(|o| String::from_utf8(o.stdout).ok()) + .map(|s| s.trim().to_string()) + .filter(|s| !s.is_empty()) + { + watch_git(&head_ref); + } + // Cargo walks a directory watch recursively, so these two cover every + // source file in the workspace without naming one. + for dir in ["../core/src", "../widgets/src", "../Cargo.toml", "../Cargo.lock"] { + println!("cargo:rerun-if-changed={}", dir); + } println!("cargo:rerun-if-env-changed=SOURCE_DATE_EPOCH"); } From 5cac9236d98b17e6a02633f14dc26cbea2ca10f1 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Wed, 26 Aug 2026 12:40:01 +0800 Subject: [PATCH 134/147] AGENTS.md: one rerun-if-* directive turns off all the others Cost a version stamp that silently stopped updating and reported a four-commit-old sha over a clean tree, then a twenty-eight second no-op build when that was over-corrected. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- AGENTS.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 1940ca6..234d3ee 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -156,6 +156,18 @@ which the compiler now makes impossible. It went with the Python. because the stale line it was written to catch had already been corrected in another session's dirty tree. Run a new check against `HEAD` — stash, or `git show HEAD:<path>` the files it reads — before believing it. +- **A build script that emits any `rerun-if-*` stops watching files.** The + rule that cargo reruns a script when any file in the package changes + applies only to a script emitting no `rerun-if-*` directive at all. One + `rerun-if-env-changed` is enough to override it, so deleting the + `rerun-if-changed` watches here did not make the version stamp always + rebuild - it made it rebuild almost never, and `--version` reported a + four-commit-old sha with a stale `-dirty` while the tree was clean. A + full thirty-second rebuild did not move it. Watching nothing and watching + everything are both wrong: unconditional reruns relink all fourteen + binaries on every no-op build, measured at 28s against 0.04s. Watch the + git files `git rev-parse --git-path` resolves - the only form that works + in a linked worktree, where `.git` is a file - plus the source trees. - **The commit that removes a secret is the likeliest place to restate it.** "The fixture used `<the actual name>`, which is a device on this tailnet" is the most natural sentence to write when documenting the fix, and it From f1fec797b2b86b41c4b52b729a1ab4e2003d0e8a Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Wed, 26 Aug 2026 13:21:16 +0800 Subject: [PATCH 135/147] usage: Grok Bot, the Cursor allowance that was not on any bar Cursor grants a weekly included allowance for its Grok Bot, separate from the monthly plan. Nothing here showed it. Its spend was visible all along under the names Cursor gives it - `sand-default` and `sand-automation` are the top two rows of the 30-day breakdown - but there was no bar, no percentage and no reset, so the one number that says whether it is about to run out was the one number missing. `POST cursor.com/api/dashboard/get-sand-usage-status` is where it lives. It draws as a fourth bar under the three plan lanes and as its own lane on `[+]`, which it reaches through `lanes()` like every other quota. Three things about it are not like the rest of this tab. **It needs a different credential.** The dashboard host refuses the bearer token Cursor's app leaves in `~/.config/cursor/auth.json` - both as a token and as a cookie, it answers with a redirect to the login provider. Only a browser session cookie works, so it comes from `usage.cursor_cookie` in config.json rather than off the disk. Empty by default, and an account without one is unaffected: the three plan bars render exactly as before, which is verified rather than assumed. **It keeps its own week.** The plan lanes run to the monthly billing cycle; this resets weekly on a date the response states. Handing it the cycle's dates would put its pace marker in the wrong place and print the wrong countdown, so it carries `currentPeriodStart` to `nextResetTimestampUtc` through to both the bar and the summary, and its row prints its own reset because the heading above cannot speak for it. **It is drawn only when the account has one.** Cursor states that as `hasNonZeroIncludedLimit`, and a 0% bar for an account that was never granted the allowance would invent a limit that does not exist - which is also exactly what an untouched allowance looks like, so the flag is the only thing telling the two apart. The colour was measured, not chosen. The percentage is drawn in the bar's own hue, and the ramp had no room left: api at 0.62 already measures 5.29 against the background, the next step that reads as distinct from it measures 4.10 - under AA - and the step that clears at 4.66 is indistinguishable from api by eye. So it takes the full hue at 10.74 and a blank line above it, which also says the truer thing: it is not a fourth slice of the plan, it is a separate allowance. Both gates were watched to fail: dropping the allowance flag, and giving the lane the billing cycle's window instead of its own. Not verified against the live endpoint - there is no cookie on this machine, and the shape here follows the field names CodexBar's Cursor provider decodes. Set usage.cursor_cookie and the bar appears; if the answer disagrees, the row says so rather than the tab breaking. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- config.example.json | 2 + docs/usage.md | 25 ++++ widgets/src/bin/usage.rs | 10 ++ widgets/src/bin/usage/cursor.rs | 233 +++++++++++++++++++++++++++++++- 4 files changed, 269 insertions(+), 1 deletion(-) diff --git a/config.example.json b/config.example.json index 19cb9c7..07328bf 100644 --- a/config.example.json +++ b/config.example.json @@ -108,6 +108,8 @@ "rates": {}, "_plan_cost_comment": "What each subscription costs you per month, keyed by agent, for example claude: 200. Nothing ships here: Anthropic lists Max as 'from $100' because it varies by tier, and no invoice is on this machine. Set it and METERED adds 'the plan saves'.", "plan_cost": {}, + "_cursor_cookie_comment": "A cursor.com session cookie (WorkosCursorSessionToken), which is the only credential the Grok Bot weekly allowance can be read with - Cursor's dashboard host refuses the bearer token its app leaves on disk. Empty by default: without it the three plan lanes are unaffected and the Grok Bot lane is simply absent. This is a live session credential; config.json is git-ignored and should stay that way.", + "cursor_cookie": "", "_grok_ping_comment": "Grok is the only agent with no live quota: its figures come from the log its own CLI writes, so they move only when you use Grok on this machine. Turn grok_ping on to ask x.ai instead, using the token the CLI leaves in ~/.grok/auth.json. That also runs the Grok CLI once after a session goes quiet, which is what refreshes the token - without it the asking works until the token lapses and then silently stops. Off by default: a widget that reads should not start talking to a vendor, or starting somebody else's program, because it was launched.", "grok_ping": false, "grok_ping_minutes": 5 diff --git a/docs/usage.md b/docs/usage.md index 91761c9..dfc6107 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -884,9 +884,34 @@ Three settings, all off or hourly by default: | key | default | what it does | |---|---|---| +| `cursor_cookie` | *(empty)* | a cursor.com session cookie (`WorkosCursorSessionToken`). Enables the **Grok Bot** lane — Cursor's weekly included allowance, which its API calls `sand` and which is what `sand-default` and `sand-automation` in the spend breakdown are drawn from | | `grok_ping` | `false` | GET `cli-chat-proxy.grok.com/v1/billing` with the bearer token the Grok CLI leaves in `~/.grok/auth.json`, **and** run `grok agent stdio` to refresh that token — once after a session goes quiet, and once when the token is within ten minutes of lapsing | | `grok_ping_minutes` | `5` | how often. The window moves over days, but the spend inside it moves while you work, so five minutes keeps the figure actionable; one small GET twelve times an hour | +### Grok Bot (Cursor's weekly allowance) + +Cursor grants a weekly included allowance for its Grok Bot, separate from +the monthly plan. It is not part of `included` / `auto` / `api` and does not +share their reset, so it draws as a fourth bar carrying its own countdown, +and appears on `[+]` as its own lane. + +`POST cursor.com/api/dashboard/get-sand-usage-status` is where it lives. Two +things make it unlike every other reading here: + +- **It needs a different credential.** The bearer token Cursor's app leaves + in `~/.config/cursor/auth.json` is refused by the dashboard host — both as + a token and as a cookie, it is answered with a redirect to the login + provider. Only a browser session cookie works, which is why this is a + config key rather than something read off the disk. +- **It is best-effort by contract.** A missing, refused or unparseable + answer leaves the three plan bars exactly as they were. An extra lane must + never be able to take the tab down with it. + +The bar is drawn only when the account actually has an allowance — +Cursor states that as `hasNonZeroIncludedLimit`, and a 0% bar for an account +that was never granted one would invent a limit that does not exist. With a +cookie set and the lane still absent, the row says why instead. + **One setting, not two.** The refresh was a second key for one release and should not have been. The token expires — mine had lapsed 8.6 days before I looked, on the same day the CLI last ran — so asking without refreshing works diff --git a/widgets/src/bin/usage.rs b/widgets/src/bin/usage.rs index f7279df..9b7bded 100644 --- a/widgets/src/bin/usage.rs +++ b/widgets/src/bin/usage.rs @@ -1187,6 +1187,15 @@ struct Config { /// then stops, silently, which is the failure the refresh exists to /// prevent. Nobody wants the first without the second. grok_ping: bool, + /// A cursor.com session cookie, which is the only credential the Grok + /// Bot allowance is readable with. + /// + /// Cursor's dashboard host does not accept the bearer token its app + /// leaves in `~/.config/cursor/auth.json` - both that token and the + /// same string sent as a cookie are answered with a redirect to the + /// login provider. Empty by default, so the lane is simply absent + /// until somebody supplies one. + cursor_cookie: String, /// Minutes between those requests. Five, so the figure on screen is /// one a reader can act on: the window it reports moves over days, but /// the spend inside it moves while they work, and an hour-old reading @@ -1229,6 +1238,7 @@ fn read_config() -> Config { .and_then(|v| v.as_bool()) .unwrap_or(false), grok_ping_minutes: tc::cfg_f64(&raw, "grok_ping_minutes", 5.0), + cursor_cookie: tc::cfg_str(&raw, "cursor_cookie", ""), } } diff --git a/widgets/src/bin/usage/cursor.rs b/widgets/src/bin/usage/cursor.rs index 677edf1..bbea695 100644 --- a/widgets/src/bin/usage/cursor.rs +++ b/widgets/src/bin/usage/cursor.rs @@ -54,6 +54,22 @@ const CURSOR_LANES: &[(&str, &str, f64)] = &[ ("api", "apiPercentUsed", 0.62), ]; +/// Grok Bot's weekly included allowance, which Cursor's own API calls +/// "sand" - the name that shows up in the spend breakdown as +/// `sand-default` and `sand-automation`. +/// +/// It is not one of the three plan lanes and does not share their window: +/// the plan lanes run to the monthly billing cycle, this one resets +/// weekly on a date the response states. Drawing it against the cycle's +/// clock would put its pace marker in the wrong place every time. +/// +/// A different host from the RPC above, and a different credential: this +/// one is cookie-authenticated and rejects the app's bearer token. +const SAND: &str = "https://cursor.com/api/dashboard/get-sand-usage-status"; +const SAND_KEY: &str = "cursor:sand"; +/// The allowance is weekly, so this need not be brisk. +const SAND_TTL: f64 = 900.0; + /// The events RPC's own ceiling per request. const EVENT_PAGE: usize = 1000; /// Enough pages to reach past any sane window. @@ -78,6 +94,12 @@ pub struct Data { events: Option<serde_json::Value>, /// GetAggregatedUsageEvents: per-model cents over the window. spend: Option<serde_json::Value>, + /// get-sand-usage-status: the Grok Bot weekly allowance, when a cookie + /// was configured and the account has one. + sand: Option<serde_json::Value>, + /// Why it is not showing, when a cookie was configured and it still is + /// not. Empty when none was configured - that is not a failure. + sand_why: String, hashes: i64, conversations: i64, models: i64, @@ -162,6 +184,52 @@ fn cursor_plan() -> Option<serde_json::Value> { cursor_rpc("GetPlanInfo", &serde_json::json!({})) } +/// The Grok Bot allowance, or why it could not be read. +/// +/// Best-effort by contract: every failure here has to leave Cursor's three +/// monthly bars exactly as they were, because this is an extra lane and not +/// a precondition for the rest of the tab. +fn sand_status(cookie: &str, seconds: u64) -> Result<serde_json::Value, String> { + if cookie.is_empty() { + return Err(String::new()); + } + let jar = format!("WorkosCursorSessionToken={}", cookie); + post_json_said( + SAND, + &[ + ("Cookie", jar.as_str()), + ("Content-Type", "application/json"), + // The dashboard checks this for CSRF and refuses without it. + ("Origin", "https://cursor.com"), + ("User-Agent", "terminal-toys"), + ], + "{}", + seconds, + ) +} + +/// The percentage, the window it covers, and when it resets - or nothing. +/// +/// Nothing is the right answer in two different situations, and neither is +/// an error: an account with no Bot allowance at all, and a response that +/// carries the flag but no percentage. Cursor states the first as +/// `hasNonZeroIncludedLimit`, and drawing a 0% bar for an account that was +/// never given the allowance would invent a limit that does not exist. +fn sand_lane(v: &serde_json::Value) -> Option<(f64, Option<f64>, Option<f64>)> { + if v["hasNonZeroIncludedLimit"].as_bool() != Some(true) { + return None; + } + let pct = loose(&v["usagePercent"])?; + let start = iso_epoch(&text(v, "currentPeriodStart")); + let reset = iso_epoch(&text(v, "nextResetTimestampUtc")); + // The window only means anything as a pair, and only forwards. + let secs = match (start, reset) { + (Some(s), Some(e)) if e > s => Some(e - s), + _ => None, + }; + Some((pct.clamp(0.0, 100.0), secs, reset)) +} + /// Per-model tokens and real cost over a window. /// /// This is what the plan percentages are made of: which model spent the @@ -349,7 +417,7 @@ fn read_tracking(con: &Connection) -> rusqlite::Result<Tracking> { }) } -pub fn read(caches: &mut Caches, _cfg: &Config) -> Data { +pub fn read(caches: &mut Caches, cfg: &Config) -> Data { let mut d = Data::default(); // The published sections do not depend on the local database, so a // locked or missing file must not take the live quota down with it - @@ -358,6 +426,28 @@ pub fn read(caches: &mut Caches, _cfg: &Config) -> Data { d.plan = cached(caches, "cursor-plan", PLAN_TTL, cursor_plan); d.events = cached(caches, "cursor-events", EVENTS_TTL, || cursor_events(30)); d.spend = cached(caches, "cursor-spend", LIVE_TTL, || cursor_spend(30)); + // Deliberately last of the four and deliberately unable to affect them: + // this is an extra allowance, and an account without one is the normal + // case rather than a fault. + if !cfg.cursor_cookie.is_empty() { + let mut why = String::new(); + d.sand = cached(caches, SAND_KEY, SAND_TTL, || { + match sand_status(&cfg.cursor_cookie, 20) { + Ok(v) => Some(v), + Err(e) => { + why = e; + None + } + } + }); + if d.sand.is_none() { + d.sand_why = if why.is_empty() { + "cursor.com did not answer".to_string() + } else { + why + }; + } + } let path = under_home(".cursor/ai-tracking/ai-code-tracking.db"); if !std::path::Path::new(&path).exists() { d.why = "no tracking database".into(); @@ -419,6 +509,19 @@ pub fn lanes(d: &Data) -> Vec<Lane> { projected: false, }); } + // Its own window, not the billing cycle's. The summary ranks lanes + // against each other and prints each one's reset, so handing it the + // monthly dates for a weekly allowance would misreport both. + if let Some((pct, secs, reset)) = d.sand.as_ref().and_then(sand_lane) { + out.push(Lane { + label: "grok bot".to_string(), + pct, + window_secs: secs, + reset, + stale: false, + projected: false, + }); + } out } @@ -498,6 +601,57 @@ fn cursor_quota(d: &Data, w: usize, p: &Palette) -> Vec<String> { let refs: Vec<(&str, String)> = line.iter().map(|(c, t)| (c.as_str(), t.clone())).collect(); rows.push(tc::seg(&refs, w - 1)); } + // Grok Bot sits under the three plan lanes, after a gap, because it is + // not one of them: a separate weekly allowance with its own reset, + // which the heading above cannot speak for. So this row carries its + // own countdown, and the blank line says it is not a fourth slice of + // the thing above it. + // + // Full hue rather than a fourth step down the ramp, for two measured + // reasons. The ramp encodes narrowing scope - included, then auto, + // then api - and this allowance is not narrower than any of them, so a + // darker tint would state a relationship that does not exist. And the + // ramp has no room left: the percentage is drawn in the bar's own + // colour, api at 0.62 already measures 5.29 against the background, + // and the next step that reads as distinct from it, 0.50, measures + // 4.10 - under AA. 0.56 clears at 4.66 and is indistinguishable from + // api by eye. Full hue is 10.74, and the gap above does the work the + // colour would have been doing badly. + if let Some((pct, secs, reset)) = d.sand.as_ref().and_then(sand_lane) { + let used = (pct / 100.0).clamp(0.0, 1.0); + let hue = base; + rows.push(String::new()); + let (pace_colour, pace_txt) = pace_cell(lead(pct, secs, reset), p); + let resets = match reset.map(|e| e - now()) { + Some(left) if left > 0.0 => format!(" {}", left_span(left)), + Some(_) => " resetting".to_string(), + None => String::new(), + }; + let mut line: Vec<(String, String)> = + vec![(p.dim.clone(), format!(" {:<9}", "grok bot"))]; + line.extend(paced_bar( + used, + elapsed_of(secs, reset), + // Narrower than the plan lanes by the width of the reset cell, + // so adding that column cannot push this row into a clip. + w.saturating_sub(50).max(8), + Some(hue), + p, + )); + line.push((pct_colour(pct, Some(hue), p), pct_text(pct))); + line.push((pace_colour, pace_txt)); + line.push((p.dim.clone(), resets)); + let refs: Vec<(&str, String)> = line.iter().map(|(c, t)| (c.as_str(), t.clone())).collect(); + rows.push(tc::seg(&refs, w - 1)); + } else if !d.sand_why.is_empty() { + rows.push(tc::seg( + &[ + (p.dim.as_str(), " grok bot ".into()), + (p.warn.as_str(), d.sand_why.clone()), + ], + w - 1, + )); + } if let Some(limit) = loose(&plan["limit"]).filter(|v| *v != 0.0) { // Deliberately dollars rather than a fourth bar. This is spend // against the plan limit - a different denominator from the three @@ -972,6 +1126,83 @@ mod tests { assert!(!why.is_empty(), "a missing table must carry a reason"); } + /// A real-shaped response, from the field names CodexBar's Cursor + /// provider decodes. Weekly window: 1700000000 -> 1700604800. + fn sand(flag: serde_json::Value, pct: serde_json::Value) -> serde_json::Value { + serde_json::json!({ + "hasNonZeroIncludedLimit": flag, + "usagePercent": pct, + "currentPeriodStart": "2023-11-14T22:13:20Z", + "nextResetTimestampUtc": "2023-11-21T22:13:20Z", + "hasAvailableUsage": true, + }) + } + + #[test] + fn an_account_with_no_bot_allowance_draws_no_bot_bar() { + // The whole point of the flag. A 0% bar here would state a limit + // the account was never given, which is the one thing this widget + // must not do - and 0% is exactly what an untouched allowance + // looks like, so the two are indistinguishable without it. + assert_eq!(sand_lane(&sand(serde_json::json!(false), serde_json::json!(0.0))), None); + assert_eq!(sand_lane(&sand(serde_json::json!(null), serde_json::json!(12.0))), None); + assert_eq!(sand_lane(&serde_json::json!({})), None); + // The flag alone is not enough: no percentage, no bar. + assert_eq!(sand_lane(&sand(serde_json::json!(true), serde_json::json!(null))), None); + } + + #[test] + fn the_bot_lane_keeps_its_own_week_not_the_billing_cycle() { + let got = sand_lane(&sand(serde_json::json!(true), serde_json::json!(62.5))); + let (pct, secs, reset) = got.expect("an allowance the account has"); + assert!((pct - 62.5).abs() < 1e-9); + // Seven days, not the month the plan lanes run to. + assert_eq!(secs, Some(604_800.0)); + assert_eq!(reset, Some(1_700_604_800.0)); + + // And it reaches the summary screen as its own lane, alongside the + // plan's - which is what puts it on [+]. + let d = Data { + live: Some(serde_json::json!({ + "planUsage": { "totalPercentUsed": 9.5 }, + "billingCycleStart": "1700000000000", + "billingCycleEnd": "1702592000000", + })), + sand: Some(sand(serde_json::json!(true), serde_json::json!(62.5))), + ..Data::default() + }; + let lanes = lanes(&d); + assert_eq!(lanes.len(), 2); + let bot = lanes.iter().find(|l| l.label == "grok bot").expect("a grok bot lane"); + assert_eq!(bot.window_secs, Some(604_800.0), "took the monthly window"); + assert_eq!(bot.reset, Some(1_700_604_800.0), "took the monthly reset"); + // The plan lane beside it must be untouched by any of this. + let inc = lanes.iter().find(|l| l.label == "included").unwrap(); + assert_eq!(inc.window_secs, Some(2_592_000.0)); + } + + #[test] + fn a_bot_reading_that_failed_leaves_the_plan_bars_alone() { + // Best-effort by contract: this lane is an extra, and an extra that + // can take the tab down with it is worse than no extra. + let d = Data { + live: Some(serde_json::json!({ + "planUsage": { "totalPercentUsed": 9.5, "limit": 40000.0, "totalSpend": 33099.0 }, + "billingCycleStart": "1700000000000", + "billingCycleEnd": "1702592000000", + })), + sand: None, + sand_why: "cursor.com did not answer".into(), + ..Data::default() + }; + assert_eq!(lanes(&d).len(), 1, "a failed extra invented or removed a lane"); + let rows = cursor_quota(&d, 110, &palette()); + let joined = rows.join("\n"); + assert!(joined.contains("included"), "plan bar lost: {}", joined); + assert!(joined.contains("$330.99"), "spend lost: {}", joined); + assert!(joined.contains("did not answer"), "reason not shown: {}", joined); + } + #[test] fn a_lane_that_publishes_nothing_is_absent_not_zero() { // autoPercentUsed is missing, so no "auto" lane may appear - a From 1b33341f695ae96113fa8a7ceb3af5a19465e498 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Wed, 26 Aug 2026 13:34:52 +0800 Subject: [PATCH 136/147] usage: the Grok Bot lane needed no cookie after all The previous commit read Cursor's documented route for this - `POST cursor.com/api/dashboard/get-sand-usage-status` - found it cookie-authenticated, confirmed the app's bearer token is answered with a redirect to the login provider, and concluded a browser session cookie was the only way in. So it shipped a `usage.cursor_cookie` config key, a lane nobody would see until they pasted a live session credential into a file, and a note admitting it had never been run against the real thing. All three were unnecessary. The same call exists on the Connect service the three plan lanes already use, as `DashboardService/GetSandUsageStatus`, and the token Cursor leaves in `~/.config/cursor/auth.json` is enough. The website's route being cookie-only says nothing about the RPC service's, and checking took one request. So the config key is gone from the code, the example and the docs, and the lane now appears on its own for anyone with Cursor installed. Verified against the live account rather than against a fixture: the weekly allowance reads 42%, and it draws on both surfaces with its own window - `4d 20h` on the Grok Bot row beside `17d 1h` on the three plan lanes, which is the visible proof the two are not sharing a clock. The summary heading went from 10 limits to 11. The docs keep the dead end rather than quietly presenting the answer, because the website's route is the one that turns up first and following it costs a credential in config.json for nothing. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- config.example.json | 2 -- docs/usage.md | 26 ++++++++------- widgets/src/bin/usage.rs | 10 ------ widgets/src/bin/usage/cursor.rs | 58 +++++++++++++++------------------ 4 files changed, 41 insertions(+), 55 deletions(-) diff --git a/config.example.json b/config.example.json index 07328bf..19cb9c7 100644 --- a/config.example.json +++ b/config.example.json @@ -108,8 +108,6 @@ "rates": {}, "_plan_cost_comment": "What each subscription costs you per month, keyed by agent, for example claude: 200. Nothing ships here: Anthropic lists Max as 'from $100' because it varies by tier, and no invoice is on this machine. Set it and METERED adds 'the plan saves'.", "plan_cost": {}, - "_cursor_cookie_comment": "A cursor.com session cookie (WorkosCursorSessionToken), which is the only credential the Grok Bot weekly allowance can be read with - Cursor's dashboard host refuses the bearer token its app leaves on disk. Empty by default: without it the three plan lanes are unaffected and the Grok Bot lane is simply absent. This is a live session credential; config.json is git-ignored and should stay that way.", - "cursor_cookie": "", "_grok_ping_comment": "Grok is the only agent with no live quota: its figures come from the log its own CLI writes, so they move only when you use Grok on this machine. Turn grok_ping on to ask x.ai instead, using the token the CLI leaves in ~/.grok/auth.json. That also runs the Grok CLI once after a session goes quiet, which is what refreshes the token - without it the asking works until the token lapses and then silently stops. Off by default: a widget that reads should not start talking to a vendor, or starting somebody else's program, because it was launched.", "grok_ping": false, "grok_ping_minutes": 5 diff --git a/docs/usage.md b/docs/usage.md index dfc6107..33cd392 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -884,7 +884,6 @@ Three settings, all off or hourly by default: | key | default | what it does | |---|---|---| -| `cursor_cookie` | *(empty)* | a cursor.com session cookie (`WorkosCursorSessionToken`). Enables the **Grok Bot** lane — Cursor's weekly included allowance, which its API calls `sand` and which is what `sand-default` and `sand-automation` in the spend breakdown are drawn from | | `grok_ping` | `false` | GET `cli-chat-proxy.grok.com/v1/billing` with the bearer token the Grok CLI leaves in `~/.grok/auth.json`, **and** run `grok agent stdio` to refresh that token — once after a session goes quiet, and once when the token is within ten minutes of lapsing | | `grok_ping_minutes` | `5` | how often. The window moves over days, but the spend inside it moves while you work, so five minutes keeps the figure actionable; one small GET twelve times an hour | @@ -895,17 +894,20 @@ the monthly plan. It is not part of `included` / `auto` / `api` and does not share their reset, so it draws as a fourth bar carrying its own countdown, and appears on `[+]` as its own lane. -`POST cursor.com/api/dashboard/get-sand-usage-status` is where it lives. Two -things make it unlike every other reading here: - -- **It needs a different credential.** The bearer token Cursor's app leaves - in `~/.config/cursor/auth.json` is refused by the dashboard host — both as - a token and as a cookie, it is answered with a redirect to the login - provider. Only a browser session cookie works, which is why this is a - config key rather than something read off the disk. -- **It is best-effort by contract.** A missing, refused or unparseable - answer leaves the three plan bars exactly as they were. An extra lane must - never be able to take the tab down with it. +It needs no configuration: `DashboardService/GetSandUsageStatus` is reached +with the same bearer token, on the same RPC service, as the three plan lanes. + +That is worth stating, because the obvious route is a dead end. Cursor's own +website calls this as `POST cursor.com/api/dashboard/get-sand-usage-status`, +which is cookie-authenticated and answers the app's bearer token — and that +same token sent as a cookie — with a redirect to the login provider. Reading +only the website's route leads to putting a browser session cookie in +`config.json`; the Connect service exposes the same call, and the token +already on disk is enough. + +It is **best-effort by contract**: a missing, refused or unparseable answer +leaves the three plan bars exactly as they were. An extra lane must never be +able to take the tab down with it. The bar is drawn only when the account actually has an allowance — Cursor states that as `hasNonZeroIncludedLimit`, and a 0% bar for an account diff --git a/widgets/src/bin/usage.rs b/widgets/src/bin/usage.rs index 9b7bded..f7279df 100644 --- a/widgets/src/bin/usage.rs +++ b/widgets/src/bin/usage.rs @@ -1187,15 +1187,6 @@ struct Config { /// then stops, silently, which is the failure the refresh exists to /// prevent. Nobody wants the first without the second. grok_ping: bool, - /// A cursor.com session cookie, which is the only credential the Grok - /// Bot allowance is readable with. - /// - /// Cursor's dashboard host does not accept the bearer token its app - /// leaves in `~/.config/cursor/auth.json` - both that token and the - /// same string sent as a cookie are answered with a redirect to the - /// login provider. Empty by default, so the lane is simply absent - /// until somebody supplies one. - cursor_cookie: String, /// Minutes between those requests. Five, so the figure on screen is /// one a reader can act on: the window it reports moves over days, but /// the spend inside it moves while they work, and an hour-old reading @@ -1238,7 +1229,6 @@ fn read_config() -> Config { .and_then(|v| v.as_bool()) .unwrap_or(false), grok_ping_minutes: tc::cfg_f64(&raw, "grok_ping_minutes", 5.0), - cursor_cookie: tc::cfg_str(&raw, "cursor_cookie", ""), } } diff --git a/widgets/src/bin/usage/cursor.rs b/widgets/src/bin/usage/cursor.rs index bbea695..88509f2 100644 --- a/widgets/src/bin/usage/cursor.rs +++ b/widgets/src/bin/usage/cursor.rs @@ -63,9 +63,16 @@ const CURSOR_LANES: &[(&str, &str, f64)] = &[ /// weekly on a date the response states. Drawing it against the cycle's /// clock would put its pace marker in the wrong place every time. /// -/// A different host from the RPC above, and a different credential: this -/// one is cookie-authenticated and rejects the app's bearer token. -const SAND: &str = "https://cursor.com/api/dashboard/get-sand-usage-status"; +/// Reached through the same RPC service and the same bearer token as the +/// three plan lanes. Cursor's own dashboard calls this over the website as +/// `POST /api/dashboard/get-sand-usage-status`, which is cookie-only and +/// answers the app's token with a redirect to the login provider - so the +/// obvious reading is that this needs a browser session. It does not: the +/// Connect service exposes the same call, and the token already on disk is +/// enough. Worth stating, because the website's route is the documented +/// one and following it would have put a credential in config.json for no +/// reason at all. +const SAND_METHOD: &str = "GetSandUsageStatus"; const SAND_KEY: &str = "cursor:sand"; /// The allowance is weekly, so this need not be brisk. const SAND_TTL: f64 = 900.0; @@ -189,22 +196,19 @@ fn cursor_plan() -> Option<serde_json::Value> { /// Best-effort by contract: every failure here has to leave Cursor's three /// monthly bars exactly as they were, because this is an extra lane and not /// a precondition for the rest of the tab. -fn sand_status(cookie: &str, seconds: u64) -> Result<serde_json::Value, String> { - if cookie.is_empty() { - return Err(String::new()); - } - let jar = format!("WorkosCursorSessionToken={}", cookie); +fn sand_status() -> Result<serde_json::Value, String> { + let tok = cursor_token().ok_or("no Cursor token on this disk")?; + let bearer = format!("Bearer {}", tok); post_json_said( - SAND, + &format!("{}{}", CURSOR_RPC, SAND_METHOD), &[ - ("Cookie", jar.as_str()), + ("Authorization", bearer.as_str()), ("Content-Type", "application/json"), - // The dashboard checks this for CSRF and refuses without it. - ("Origin", "https://cursor.com"), + ("Connect-Protocol-Version", "1"), ("User-Agent", "terminal-toys"), ], "{}", - seconds, + 20, ) } @@ -417,7 +421,7 @@ fn read_tracking(con: &Connection) -> rusqlite::Result<Tracking> { }) } -pub fn read(caches: &mut Caches, cfg: &Config) -> Data { +pub fn read(caches: &mut Caches, _cfg: &Config) -> Data { let mut d = Data::default(); // The published sections do not depend on the local database, so a // locked or missing file must not take the live quota down with it - @@ -429,24 +433,16 @@ pub fn read(caches: &mut Caches, cfg: &Config) -> Data { // Deliberately last of the four and deliberately unable to affect them: // this is an extra allowance, and an account without one is the normal // case rather than a fault. - if !cfg.cursor_cookie.is_empty() { - let mut why = String::new(); - d.sand = cached(caches, SAND_KEY, SAND_TTL, || { - match sand_status(&cfg.cursor_cookie, 20) { - Ok(v) => Some(v), - Err(e) => { - why = e; - None - } - } - }); - if d.sand.is_none() { - d.sand_why = if why.is_empty() { - "cursor.com did not answer".to_string() - } else { - why - }; + let mut why = String::new(); + d.sand = cached(caches, SAND_KEY, SAND_TTL, || match sand_status() { + Ok(v) => Some(v), + Err(e) => { + why = e; + None } + }); + if d.sand.is_none() && !why.is_empty() { + d.sand_why = why; } let path = under_home(".cursor/ai-tracking/ai-code-tracking.db"); if !std::path::Path::new(&path).exists() { From bc1d629d1a2d3a6a1e4c89763a8b2f78adaa94d7 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Wed, 26 Aug 2026 14:09:22 +0800 Subject: [PATCH 137/147] usage: three the summary and the Grok tab were each telling differently MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit **Cursor's bars are in the same order on both screens.** The summary sorted every agent's lanes by percentage except Claude's, whose exemption was written down as "except where the lanes nest". Cursor's nest too - api inside auto inside included - and now carry a fourth that is not part of that ramp at all, so the summary was reordering them by number and putting Grok Bot first while the agent's own tab drew them in scope order. Two screens disagreeing about the order of the very same four bars. Cursor joins Claude in keeping its own order, and the break above Grok Bot is carried on the lane itself rather than inferred from its label, so the tab and the summary cannot drift apart on it again. **Switching tabs lands at the top.** The offset was kept per tab so that switching away and back returned you to where you were reading. In use that is the wrong trade: the tabs are different lengths and shapes, so a remembered offset opens the next one part-way down with its heading scrolled off, and the first thing anyone does on arriving somewhere new is look at the top of it. **Grok is judged by the age of its reading, not by where it came from.** This is the rule claude.rs already had, and its comment already says why: marking by source flags the fresher of two readings as the doubtful one. Here the same mistake was hiding a worse one. `quota_from` refused any answer without `creditUsagePercent`, and x.ai has stopped sending it for accounts on unified billing - both `/v1/billing` and `?format=credits` answer 200, name the current weekly period, and omit it, every other figure zero, three months of history zero. So a working ping was throwing its answer away and falling back to the newest log line, which on this machine was written eleven days ago about a window that had closed a week before that. The row said "not live" whether the ping worked or not, and turning it on changed nothing anyone could see. A named period is a reading now, percentage or not, and the server's answer wins. Where it names the window but no figure, the log's percentage is taken only if it is about that same window, because a percentage from a window that has closed is not this one's. Otherwise the row says there is no figure rather than drawing an empty gauge, which would read as nought per cent used - and the section is no longer hidden outright for it, which had left the tab blank where a reader cannot tell an account with no quota from a widget that has stopped working. With no percentage there is no bar to rank, so Grok moves to "No quota published by" on the summary. That line covered two situations wanting opposite things from the reader - nobody is asking, or the ask worked and x.ai had nothing to report - so it now says which, the way Antigravity's already did. Measured on the live account: the tab reads `live · polled x.ai just now` over `window 26 Aug → 2 Sep`, where it had read `not live` over a `12 Aug → 19 Aug` window rolled forward with a `~`. The test that asserted a live reading is "current by definition" asserted the rule this replaces; it now covers both directions and the undateable case, and was watched to fail on each. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- docs/usage.md | 35 +++- widgets/src/bin/usage.rs | 19 +- widgets/src/bin/usage/antigravity.rs | 1 + widgets/src/bin/usage/claude.rs | 1 + widgets/src/bin/usage/codex.rs | 3 + widgets/src/bin/usage/copilot.rs | 1 + widgets/src/bin/usage/cursor.rs | 2 + widgets/src/bin/usage/grok.rs | 261 ++++++++++++++++++++++----- widgets/src/bin/usage/shared.rs | 6 + widgets/src/bin/usage/vendors.rs | 35 +++- 10 files changed, 302 insertions(+), 62 deletions(-) diff --git a/docs/usage.md b/docs/usage.md index 33cd392..05dc89a 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -934,6 +934,31 @@ costs one attempt rather than one every five minutes. business doing unasked: it talks to a vendor, and it starts somebody else's program. +**Cached or live is a question about age, not about source.** A reading is +shown as current when it was taken within the last half hour, whatever +fetched it — the same rule and the same half hour as Claude's. Marking by +source instead put a star on a figure thirty seconds old while a live one +four minutes old carried none, and here it was worse: the live answer was +being discarded (below), so the row read `not live` whether the ping was +working or not, and turning it on changed nothing a reader could see. + +**A period without a percentage is still a reading.** x.ai has stopped +sending `creditUsagePercent` for accounts on unified billing — both +`/v1/billing` and `?format=credits` answer 200, name the current weekly +period, and omit it, with every other figure zero. Refusing that answer +meant falling back to the newest line in the client log, which can be a +fossil: on the machine this was found on it was eleven days old and about a +window that had closed a week before that, shown as current with a rolled +forward reset. The server's answer now wins. Where it names the window but +no percentage, the log's figure is used **only if it is about that same +window** — a percentage from a window that has closed is not this one's — +and otherwise the row says there is no figure rather than drawing a bar. + +An agent that publishes no percentage has no bar to rank, so it moves to +`No quota published by:` on `[+]`, with a line saying which of the two +reasons applies: nobody is asking, or the ask worked and x.ai had nothing +to report. + The screen says which state it is in, in both places it appears: ``` @@ -947,6 +972,14 @@ The screen says which state it is in, in both places it appears: live · polled x.ai just now, every 5m ``` +``` +── WEEKLY QUOTA ── resets in 6d 20h + live · polled x.ai just now, every 5m + + no credit figure for this period + window 26 Aug → 2 Sep +``` + When asking is on and the figure still is not the server's, the row says which of the reasons applies rather than leaving `not live` to cover all of them — only some are the reader's to fix: @@ -1104,7 +1137,7 @@ refresh makes a tab a row longer. | Key | Action | |---|---| -| `←` `→` / `tab` | switch agent | +| `←` `→` / `tab` | switch agent. The new tab opens at its top: the tabs are different lengths and shapes, so a remembered offset opens the next one part-way down with its heading scrolled off | | `↑` `↓` | scroll the tab | | `pgup` `pgdn` | scroll a page | | `home` `end` | jump to the top or bottom | diff --git a/widgets/src/bin/usage.rs b/widgets/src/bin/usage.rs index f7279df..2586238 100644 --- a/widgets/src/bin/usage.rs +++ b/widgets/src/bin/usage.rs @@ -1488,9 +1488,17 @@ fn main() { // wrap; rem_euclid then brings it back into range the way Python's // % does for a negative index. let (mut active, mut tick) = (0i64, 0usize); - // One offset per tab. Switching away and back keeps your place, which - // matters when a tab is forty rows and you were reading the bottom of it. - let mut offsets: HashMap<String, usize> = HashMap::new(); + // Switching tabs lands at the top of the new one. + // + // This used to be one offset per tab, kept so that switching away and + // back returned you to where you were reading. In use that is the wrong + // trade: the tabs are different lengths and different shapes, so a + // remembered offset from a forty-row tab opens the next one part-way + // down with its heading scrolled off, and the first thing a reader does + // on arriving somewhere new is look at the top of it. Only one offset is + // needed now, carried across frames of the same tab and dropped the + // moment the tab changes. + let (mut carried, mut shown) = (0usize, String::new()); loop { tick += 1; @@ -1574,7 +1582,7 @@ fn main() { let reserved = tc::pack_hints(&hints, w - 2, " ").len(); let avail = h.saturating_sub(rows.len() + reserved).max(1); let top = body.len().saturating_sub(avail); - let mut off = offsets.get(&name).copied().unwrap_or(0).min(top); + let mut off = if name == shown { carried.min(top) } else { 0 }; if to_top { off = 0; } @@ -1589,7 +1597,8 @@ fn main() { off = (off as i64 + move_).clamp(0, top as i64) as usize; } off = off.min(top); - offsets.insert(name.clone(), off); + carried = off; + shown = name.clone(); let view: Vec<String> = body.iter().skip(off).take(avail).cloned().collect(); let where_ = if top > 0 { diff --git a/widgets/src/bin/usage/antigravity.rs b/widgets/src/bin/usage/antigravity.rs index 4189ebd..499fe31 100644 --- a/widgets/src/bin/usage/antigravity.rs +++ b/widgets/src/bin/usage/antigravity.rs @@ -450,6 +450,7 @@ pub fn lanes(d: &Data) -> Vec<Lane> { reset: iso_epoch(&text(bucket, "resetTime")), stale: false, projected: false, + apart: false, }); } } diff --git a/widgets/src/bin/usage/claude.rs b/widgets/src/bin/usage/claude.rs index 2d4c020..9c80e4c 100644 --- a/widgets/src/bin/usage/claude.rs +++ b/widgets/src/bin/usage/claude.rs @@ -1178,6 +1178,7 @@ pub fn lanes(c: &Data) -> Vec<Lane> { reset: rolled.0, stale: reading_is_old(c.quota_at), projected: rolled.1, + apart: false, } }) .collect() diff --git a/widgets/src/bin/usage/codex.rs b/widgets/src/bin/usage/codex.rs index df5193f..43d4a32 100644 --- a/widgets/src/bin/usage/codex.rs +++ b/widgets/src/bin/usage/codex.rs @@ -782,6 +782,7 @@ pub fn lanes(d: &Data) -> Vec<Lane> { reset: win["resets_at"].as_f64(), stale: true, projected: false, + apart: false, }]; }; let mut out: Vec<Lane> = Vec::new(); @@ -798,6 +799,7 @@ pub fn lanes(d: &Data) -> Vec<Lane> { reset: win["reset_at"].as_f64(), stale: false, projected: false, + apart: false, }); } for extra in live["additional_rate_limits"].as_array().into_iter().flatten() { @@ -817,6 +819,7 @@ pub fn lanes(d: &Data) -> Vec<Lane> { reset: win["reset_at"].as_f64(), stale: false, projected: false, + apart: false, }); } out diff --git a/widgets/src/bin/usage/copilot.rs b/widgets/src/bin/usage/copilot.rs index 71d8795..e0228fc 100644 --- a/widgets/src/bin/usage/copilot.rs +++ b/widgets/src/bin/usage/copilot.rs @@ -351,6 +351,7 @@ pub fn lanes(d: &Data) -> Vec<Lane> { reset: stamp, stale: false, projected: false, + apart: false, }); } out diff --git a/widgets/src/bin/usage/cursor.rs b/widgets/src/bin/usage/cursor.rs index 88509f2..95592ef 100644 --- a/widgets/src/bin/usage/cursor.rs +++ b/widgets/src/bin/usage/cursor.rs @@ -503,6 +503,7 @@ pub fn lanes(d: &Data) -> Vec<Lane> { reset, stale: false, projected: false, + apart: false, }); } // Its own window, not the billing cycle's. The summary ranks lanes @@ -516,6 +517,7 @@ pub fn lanes(d: &Data) -> Vec<Lane> { reset, stale: false, projected: false, + apart: true, }); } out diff --git a/widgets/src/bin/usage/grok.rs b/widgets/src/bin/usage/grok.rs index 8424b4c..ae96728 100644 --- a/widgets/src/bin/usage/grok.rs +++ b/widgets/src/bin/usage/grok.rs @@ -78,6 +78,10 @@ const CACHE: &str = "grok:session:"; #[derive(Clone, Default)] struct Quota { pct: Option<f64>, + /// When this reading was taken, as epoch seconds - the log line's own + /// `ts`, or the moment of the fetch. Not when it was read: the tab + /// judges a reading by its age, and those are different numbers. + taken: Option<f64>, kind: String, start: String, end: String, @@ -207,6 +211,7 @@ fn newest_quota<'a>(lines: impl Iterator<Item = &'a str>) -> Option<Quota> { let period = &cfg["currentPeriod"]; let got = Quota { pct: val_of(&cfg["creditUsagePercent"]), + taken: iso_epoch(&text(&d, "ts")), kind: text(period, "type"), start: text(period, "start"), end: text(period, "end"), @@ -254,17 +259,30 @@ fn quota_now(caches: &mut Caches, cfg: &Config) -> (Option<Quota>, bool, f64, St match got.as_ref() { None => (from_log(), false, at, "x.ai did not answer".to_string()), Some(body) => match quota_from(body) { - Some(q) => (Some(q), true, at, String::new()), - // A 200 that names the period but sends a null percentage. The - // log reading is kept, because it is the only percentage there - // is, but the row must not read as though the server confirmed - // it - it did not, and it is a window older than this one. - None => ( - from_log(), - false, - at, - "x.ai sent no percentage for this period".to_string(), - ), + Some(mut q) => { + let why = String::new(); + if q.pct.is_none() { + // The server named the window but not the spend. The log + // may still hold a percentage, and it is usable only if + // it is about this same window: a figure from a window + // that has closed is not this one's, however it got here. + match from_log() { + Some(l) if l.start == q.start && l.end == q.end => { + q.pct = l.pct; + q.taken = l.taken; + } + // No reason recorded here on purpose. The row that + // stands where the bar would be already says there + // is no figure for this period, and the freshness + // line saying it too was the same sentence twice. + // quota_why is for the cases that line cannot show: + // a lapsed token, a refusal, an unreadable answer. + _ => {} + } + } + (Some(q), true, at, why) + } + None => (from_log(), false, at, "x.ai sent no usable reading".to_string()), }, } } @@ -518,18 +536,58 @@ fn fetch_billing(key: &str, seconds: u64) -> Option<serde_json::Value> { ) } +/// How old a reading may be and still be shown as current. +/// +/// Half an hour, the same figure and the same reasoning as Claude's +/// CLAUDE_FRESH_FOR: a credit window that turns over weekly does not move +/// enough in half an hour to mislead anyone. +/// +/// This tab used to mark by *where* a reading came from - `stale` was +/// simply "not from the server" - and that is the mistake claude.rs already +/// wrote down: it flags the fresher of two readings as the doubtful one. +/// Here it was worse, because the live answer was being discarded (see +/// quota_from) and the fallback was a log line eleven days old, so the row +/// said "not live" whether the ping was working or not, and turning the +/// ping on changed nothing a reader could see. +const GROK_FRESH_FOR: f64 = 1800.0; + +/// True when the reading is old enough to be worth flagging, whatever its +/// source. A reading with no timestamp at all is treated as old, because +/// unknown age is not evidence of youth. +fn reading_is_old(taken: Option<f64>) -> bool { + taken.is_none_or(|t| now() - t > GROK_FRESH_FOR) +} + /// The billing body in the same shape the log parser produces, so the rest /// of the tab cannot tell which of the two it is looking at. fn quota_from(d: &serde_json::Value) -> Option<Quota> { let cfg = &d["config"]; let period = &cfg["currentPeriod"]; - let pct = val_of(&cfg["creditUsagePercent"]); - pct?; + // The period is what makes this a reading; the percentage is optional. + // + // It used to be the other way round - no percentage, no reading - and + // that has stopped being true of the endpoint. x.ai no longer sends + // `creditUsagePercent` for unified-billing accounts: both `/v1/billing` + // and `?format=credits` answer 200, name the current weekly period, and + // omit it entirely. Refusing the whole answer for that meant falling + // back to the newest log line, which on this machine was written eleven + // days ago about a window that closed a week before that - a fossil + // shown as current while the server's own answer, naming the window we + // are actually in, was thrown away. + // + // The log parser has always accepted a reading whose percentage is + // absent, for exactly this reason. The two are consistent now. + let start = text(period, "start"); + let end = text(period, "end"); + if start.is_empty() || end.is_empty() { + return None; + } Some(Quota { - pct, + pct: val_of(&cfg["creditUsagePercent"]), + taken: Some(now()), kind: text(period, "type"), - start: text(period, "start"), - end: text(period, "end"), + start, + end, tier: String::new(), on_demand_used: val_of(&cfg["onDemandUsed"]["val"]), on_demand_cap: val_of(&cfg["onDemandCap"]["val"]), @@ -588,17 +646,36 @@ pub fn lanes(d: &Data) -> Vec<Lane> { _ => None, }, reset, - // Not live means the percentage was measured in some earlier window - // and this one's spend is unknown. The row says so rather than - // letting a stale figure read as current. - stale: !d.quota_live, + // By age, not by source. A figure the server sent four minutes ago + // and one the log recorded thirty seconds ago are both current; a + // live fetch of a reading taken days earlier is not. + stale: reading_is_old(q.taken), projected, + apart: false, }] } /// True when nothing is asking the server on the reader's behalf, so the /// figures move only when they use Grok on this machine. The summary says so /// under the row; once asking is on, the tab reports the interval instead. +/// Why Grok publishes no bar, when it does not. +/// +/// "No quota published" covers two situations that want opposite things +/// from the reader. Nobody is asking, and they could turn asking on - or +/// the ask is working and x.ai is the one with nothing to report, in which +/// case there is nothing for them to do and a prompt to change a setting +/// would be a wild goose chase. +pub fn why_no_lane(d: &Data) -> &'static str { + if d.quota.is_none() { + return ""; + } + if d.quota_live { + "x.ai answered, and published no credit figure for this period. Accounts on unified billing stopped carrying one; the window it does state is on the GROK tab." + } else { + "" + } +} + pub fn asks_nobody(d: &Data) -> bool { d.quota_every <= 0.0 } @@ -626,6 +703,7 @@ fn every(seconds: f64) -> String { fn freshness(d: &Data, w: usize, p: &Palette) -> Vec<String> { let mut out = Vec::new(); if d.quota_every > 0.0 { + let fresh = !reading_is_old(d.quota.as_ref().and_then(|q| q.taken)); let ago = now() - d.quota_at; let last = if d.quota_at <= 0.0 { "not yet".to_string() @@ -636,9 +714,13 @@ fn freshness(d: &Data, w: usize, p: &Palette) -> Vec<String> { }; out.push(tc::seg( &[ + // Whether the figure is current, which is a question about + // its age. It used to be a question about its source, so a + // working ping still read "not live" for as long as the + // answer it fetched was being discarded. ( - if d.quota_live { p.ok.as_str() } else { p.warn.as_str() }, - if d.quota_live { " live" } else { " not live" }.to_string(), + if fresh { p.ok.as_str() } else { p.warn.as_str() }, + if fresh { " live" } else { " not live" }.to_string(), ), ( p.dim.as_str(), @@ -727,9 +809,13 @@ fn seg_of(parts: &[(String, String)], w: usize) -> String { fn grok_tab(d: &Data, w: usize, p: &Palette) -> Vec<String> { let hue = agent_hue("grok"); let mut rows: Vec<String> = Vec::new(); - let quota = d.quota.as_ref().filter(|q| q.pct.is_some()); - if let Some(q) = quota { - let pct = q.pct.unwrap_or(0.0); + // Not filtered on the percentage any more. A reading that names the + // window but not the spend is still a reading, and hiding the whole + // section for it is the failure this repo keeps paying for: the pane + // goes blank and a reader cannot tell an account with no quota from a + // widget that has stopped working. The window, the countdown and the + // reason are all still true; only the bar needs a number. + if let Some(q) = d.quota.as_ref() { // The one real remaining-quota figure in this widget: everything // else here counts what was spent. It leads the tab for that // reason. @@ -771,20 +857,31 @@ fn grok_tab(d: &Data, w: usize, p: &Palette) -> Vec<String> { (Some(b), Some(e)) if e > b => (Some(e - b), Some(e)), _ => (None, None), }; - let mut line: Vec<(String, String)> = vec![( - pct_colour(pct, hue, p), - format!(" {:<5}", format!("{:.0}%", pct)), - )]; - line.extend(paced_bar( - (pct / 100.0).clamp(0.0, 1.0), - elapsed_of(span, reset), - w.saturating_sub(38).max(10), - hue, - p, - )); - line.push((p.dim.clone(), " credits used".into())); - line.push(pace_cell(lead(pct, span, reset), p)); - rows.push(seg_of(&line, w)); + // The bar is the one part that needs a number. Without one the row + // says so in words rather than drawing an empty gauge, which would + // read as nought per cent used. + match q.pct { + Some(pct) => { + let mut line: Vec<(String, String)> = vec![( + pct_colour(pct, hue, p), + format!(" {:<5}", format!("{:.0}%", pct)), + )]; + line.extend(paced_bar( + (pct / 100.0).clamp(0.0, 1.0), + elapsed_of(span, reset), + w.saturating_sub(38).max(10), + hue, + p, + )); + line.push((p.dim.clone(), " credits used".into())); + line.push(pace_cell(lead(pct, span, reset), p)); + rows.push(seg_of(&line, w)); + } + None => rows.push(tc::seg( + &[(p.dim.as_str(), " no credit figure for this period".into())], + w - 1, + )), + } let (from, to) = (short_day(&q.start), short_day(&q.end)); let window = if from.is_empty() || to.is_empty() { @@ -897,11 +994,17 @@ fn grok_tab(d: &Data, w: usize, p: &Palette) -> Vec<String> { let mut note = "Totals are a running count per session, summed as deltas so a session \ spanning days lands on the right one." .to_string(); - if quota.is_some() { - note.push_str( + // Either way it is the server's own figure and not an inference - but + // which of the two routes it took is a different sentence, and the note + // named only the log for as long as the log was the only route that + // ever produced one. + if d.quota.is_some() { + note.push_str(if d.quota_live { + " The quota above is the server's own figure, asked for directly - not inferred." + } else { " The quota above is the server's own figure, read from the client log - not \ - inferred.", - ); + inferred." + }); } for line in wrap_text(¬e, w.saturating_sub(4).max(20)) { rows.push(tc::seg(&[(p.dim.as_str(), format!(" {}", line))], w - 1)); @@ -1104,25 +1207,85 @@ mod tests { } #[test] - fn a_live_reading_is_neither_stale_nor_projected() { - // The same fixture, marked as having come from the server. Its - // window is then the window we are in: nothing to roll forward, and - // nothing to qualify. + fn a_reading_is_judged_by_its_age_not_by_where_it_came_from() { + // This asserted the opposite until the rule changed: that a reading + // is current "by definition" when it came from the server. That is + // the mistake claude.rs already wrote down - it flags the fresher of + // two readings as the doubtful one - and here it meant a working + // ping still read "not live", because the answer it fetched was + // being discarded and an eleven-day-old log line shown instead. + let base = newest_quota([LOG_LINE].into_iter()).expect("a reading"); + + // Taken a minute ago: current, and its window is the one we are in. let d = Data { ok: true, - quota: newest_quota([LOG_LINE].into_iter()), + quota: Some(Quota { taken: Some(now() - 60.0), ..base.clone() }), quota_live: true, ..Default::default() }; let got = lanes(&d); assert_eq!(got.len(), 1); - assert!(!got[0].stale, "a live reading is current by definition"); + assert!(!got[0].stale, "a minute-old reading is current"); assert!(!got[0].projected, "a live window was read, not worked out"); assert_eq!( got[0].reset, iso_epoch("2026-08-17T00:00:00.000000+00:00"), "a live window is reported as the server gave it, not rolled" ); + + // Fetched just now, but of a reading taken days ago. Still old: + // fetching an old number does not make it a new one. + let d = Data { + ok: true, + quota: Some(Quota { taken: Some(now() - 5.0 * 86400.0), ..base.clone() }), + quota_live: true, + ..Default::default() + }; + assert!(lanes(&d)[0].stale, "a live fetch of an old reading read as current"); + + // And the other direction: nothing was fetched, the log supplied it + // thirty seconds ago, and that is current whatever its source. + let d = Data { + ok: true, + quota: Some(Quota { taken: Some(now() - 30.0), ..base.clone() }), + quota_live: false, + ..Default::default() + }; + assert!(!lanes(&d)[0].stale, "flagged for its source rather than its age"); + + // A reading that cannot say when it was taken is treated as old: + // unknown age is not evidence of youth. + let d = Data { + ok: true, + quota: Some(Quota { taken: None, ..base }), + quota_live: true, + ..Default::default() + }; + assert!(lanes(&d)[0].stale, "an undateable reading passed as current"); + } + + #[test] + fn a_period_the_server_names_is_a_reading_even_with_no_percentage() { + // x.ai stopped sending creditUsagePercent for unified-billing + // accounts: 200, the current weekly period, and no percentage at + // all. Refusing that answer meant falling back to a log line about + // a window that had already closed - a fossil shown as current + // while the server's own answer was thrown away. + let body = serde_json::json!({"config": { + "currentPeriod": { + "type": "USAGE_PERIOD_TYPE_WEEKLY", + "start": "2026-08-26T02:09:41.289406+00:00", + "end": "2026-09-02T02:09:41.289406+00:00" + }, + "onDemandCap": {"val": 0}, "onDemandUsed": {"val": 0}, + }}); + let q = quota_from(&body).expect("a named period is a reading"); + assert_eq!(q.pct, None, "invented a percentage the server did not send"); + assert_eq!(q.start, "2026-08-26T02:09:41.289406+00:00"); + assert!(q.taken.is_some(), "a live reading knows when it was taken"); + + // An answer naming no period at all is still not a reading. + assert!(quota_from(&serde_json::json!({"config": {}})).is_none()); } /// The roll itself, on a fixed clock - `lanes` has to ask the real one. diff --git a/widgets/src/bin/usage/shared.rs b/widgets/src/bin/usage/shared.rs index b82bb31..1c1d24f 100644 --- a/widgets/src/bin/usage/shared.rs +++ b/widgets/src/bin/usage/shared.rs @@ -183,6 +183,12 @@ pub struct Lane { /// shown with a `~`, because a date this widget calculated and a date /// the server sent are not the same kind of fact. pub projected: bool, + /// True when this lane is not part of the group above it and should be + /// separated from it. Cursor's Grok Bot allowance is the case this + /// exists for: three plan lanes on the monthly cycle, then a weekly + /// allowance that is not a fourth slice of them. Carried on the lane so + /// the agent's own tab and the summary cannot drift apart on it. + pub apart: bool, } /// What a refused request said, in words a reader can act on. diff --git a/widgets/src/bin/usage/vendors.rs b/widgets/src/bin/usage/vendors.rs index 81913d4..c49ae9f 100644 --- a/widgets/src/bin/usage/vendors.rs +++ b/widgets/src/bin/usage/vendors.rs @@ -156,17 +156,25 @@ fn summary_tab(s: &State, w: usize, p: &Palette) -> Vec<String> { )], w - 1, )); - // Ranked by usage, except where the lanes nest. Claude's five-hour - // window sits inside its weekly one, which contains the - // model-scoped limit in turn, and reading them widest-last says - // more than reading them by percentage - which also reorders itself - // as the numbers move, so the bar under the cursor is not the one - // that was there a refresh ago. + // Ranked by usage, except where the agent's own order already means + // something. Claude's five-hour window sits inside its weekly one, + // which contains the model-scoped limit in turn; Cursor's three plan + // lanes are a widening scope - api inside auto inside included - + // followed by an allowance that is not part of them at all. For both, + // reading them in the agent's order says more than reading them by + // percentage, and percentage reorders itself as the numbers move, so + // the bar under the cursor is not the one that was there a refresh + // ago. It also made this screen disagree with the agent's own tab + // about the order of the very same bars. let mut inner = lanes.clone(); - if *name != "claude" { + if !matches!(*name, "claude" | "cursor") { inner.sort_by(|a, b| b.pct.total_cmp(&a.pct)); } for lane in &inner { + // The same break the agent's tab draws, for the same reason. + if lane.apart { + rows.push(String::new()); + } let used = (lane.pct / 100.0).clamp(0.0, 1.0); // "cached" used to replace the countdown outright, which threw // away a fact to report an adjective. A reading a few minutes old @@ -303,6 +311,18 @@ fn summary_tab(s: &State, w: usize, p: &Palette) -> Vec<String> { // machine that has never signed in and one whose token lapsed an // hour ago. Its own heading, under that line, so the sentence has // something to belong to. + if quiet.contains(&"grok") { + let note = crate::grok::why_no_lane(&s.grok); + if !note.is_empty() { + rows.push(String::new()); + rows.push(tc::seg(&[(p.lbl.as_str(), " GROK".into())], w - 1)); + rows.extend( + wrap_text(note, w.saturating_sub(5).max(20)) + .into_iter() + .map(|l| tc::seg(&[(p.dim.as_str(), format!(" {}", l))], w - 1)), + ); + } + } if quiet.contains(&"antigravity") { let note = crate::antigravity::tier_note(s.antigravity.why_no_tier()); if !note.is_empty() { @@ -398,6 +418,7 @@ mod tests { reset: None, stale: false, projected: false, + apart: false, }; // grok has more lanes and a higher total, and still ranks below the // provider with the single worst one - which a flat sort by From f19b1540a39517fc23b77507e3984098a1e8b182 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Wed, 26 Aug 2026 14:29:23 +0800 Subject: [PATCH 138/147] usage: an omitted percentage is nought, and the answer proves it itself MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The previous commit read x.ai's credits endpoint returning no `creditUsagePercent`, checked that every other figure it sent was zero and that three months of history were zero too, and concluded the field had been withdrawn for accounts on unified billing. So the row said there was no figure for the period. The true figure was nought, and the evidence was inside the same response the whole time. Beside the credit percentage the endpoint returns `productUsage`, one entry per product. On this account: [{"product":"GrokBuild","usagePercent":1.0}, {"product":"GrokChat"},{"product":"GrokImagine"}] The product with usage carries the key. The two at nought omit it - same array, same answer, same serialisation. It is proto3 leaving out a scalar at its default, not a field being taken away. Confirmed over time as well, which is the part that could not be faked: this account's weekly window reset at 02:09 with nothing spent and the endpoint sent no percentage at all; once something had been spent it began sending one, rising 1.0 -> 3.0 across successive polls on the same endpoint, the same headers and the same token. An A/B ruled out the other candidate before it reached the code. Codexbar sends `x-xai-token-auth: xai-grok-cli` where this did not, and our own earlier 401 had named `x_xai_token_auth=none`, which made the missing header look like the cause. Three variants - bare, with that header, with `Accept: application/json` - all returned the same percentage at the same moment. The header changes nothing; the spend had changed. So an absent percentage against a named period reads as nought, and the comment carries the evidence rather than the conclusion. A response naming no period is still refused: nought is only knowable against a window the server stated. A percentage present on the wire is taken as sent, a real 0.0 included. `productUsage` is kept and drawn under the window. The bar above is one number for three different things, and which of them is spending is the part a reader can act on. Measured live: 3% used, window 26 Aug to 2 Sep, `by product GrokBuild 3.0% · GrokChat 0% · GrokImagine 0%`. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- docs/usage.md | 54 +++++++++++------ widgets/src/bin/usage/grok.rs | 107 +++++++++++++++++++++++++++++++--- 2 files changed, 134 insertions(+), 27 deletions(-) diff --git a/docs/usage.md b/docs/usage.md index 05dc89a..fe086d4 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -942,22 +942,39 @@ four minutes old carried none, and here it was worse: the live answer was being discarded (below), so the row read `not live` whether the ping was working or not, and turning it on changed nothing a reader could see. -**A period without a percentage is still a reading.** x.ai has stopped -sending `creditUsagePercent` for accounts on unified billing — both -`/v1/billing` and `?format=credits` answer 200, name the current weekly -period, and omit it, with every other figure zero. Refusing that answer -meant falling back to the newest line in the client log, which can be a -fossil: on the machine this was found on it was eleven days old and about a -window that had closed a week before that, shown as current with a rolled -forward reset. The server's answer now wins. Where it names the window but -no percentage, the log's figure is used **only if it is about that same -window** — a percentage from a window that has closed is not this one's — -and otherwise the row says there is no figure rather than drawing a bar. - -An agent that publishes no percentage has no bar to rank, so it moves to -`No quota published by:` on `[+]`, with a line saying which of the two -reasons applies: nobody is asking, or the ask worked and x.ai had nothing -to report. +**A period without a percentage means nought used, not unknown.** The +credits endpoint omits `creditUsagePercent` when it is zero — proto3 leaves +out a scalar sitting at its default. That was briefly mistaken here for the +field having been withdrawn for accounts on unified billing, and the row +said there was no figure when the true figure was nought. + +The answer settles it against itself. Alongside the credit percentage it +returns `productUsage`, one entry per product: + +```json +"productUsage": [{"product": "GrokBuild", "usagePercent": 3.0}, + {"product": "GrokChat"}, + {"product": "GrokImagine"}] +``` + +The product with usage carries the key; the two at nought omit it, in the +same array of the same response. Watched over time as well: a weekly window +that had just reset returned no percentage at all, and began reporting one +once anything had been spent — same endpoint, same headers, same token. So +nought here is the reading rather than a guess, which is the only reason it +may be drawn. A response naming no period at all is still refused: nought +is only knowable against a window the server stated. + +That split is drawn under the window, because the bar above is one number +for three different things and which of them is spending is the part a +reader can act on. + +**The server's answer wins over the log.** Where the live answer names the +window but the log holds a percentage, the log's figure is used only if it +is about that same window — a percentage from a window that has closed is +not this one's. Before that rule the tab preferred an eleven-day-old log +line, about a window that had closed a week earlier, over the server's +current one, and rolled its reset forward with a `~`. The screen says which state it is in, in both places it appears: @@ -973,11 +990,12 @@ The screen says which state it is in, in both places it appears: ``` ``` -── WEEKLY QUOTA ── resets in 6d 20h +── WEEKLY QUOTA ── resets in 6d 19h live · polled x.ai just now, every 5m - no credit figure for this period + 3% ██┃░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ credits used window 26 Aug → 2 Sep + by product GrokBuild 3.0% · GrokChat 0% · GrokImagine 0% ``` When asking is on and the figure still is not the server's, the row says diff --git a/widgets/src/bin/usage/grok.rs b/widgets/src/bin/usage/grok.rs index ae96728..d5a1da7 100644 --- a/widgets/src/bin/usage/grok.rs +++ b/widgets/src/bin/usage/grok.rs @@ -78,6 +78,11 @@ const CACHE: &str = "grok:session:"; #[derive(Clone, Default)] struct Quota { pct: Option<f64>, + /// The same week split by product, where the answer carries it: + /// GrokBuild, GrokChat, GrokImagine. Empty when it does not, which is + /// every reading the log recorded - this arrived with the credits + /// endpoint and the log lines predate it. + products: Vec<(String, f64)>, /// When this reading was taken, as epoch seconds - the log line's own /// `ts`, or the moment of the fetch. Not when it was read: the tab /// judges a reading by its age, and those are different numbers. @@ -211,6 +216,7 @@ fn newest_quota<'a>(lines: impl Iterator<Item = &'a str>) -> Option<Quota> { let period = &cfg["currentPeriod"]; let got = Quota { pct: val_of(&cfg["creditUsagePercent"]), + products: products_of(cfg), taken: iso_epoch(&text(&d, "ts")), kind: text(period, "type"), start: text(period, "start"), @@ -558,6 +564,30 @@ fn reading_is_old(taken: Option<f64>) -> bool { taken.is_none_or(|t| now() - t > GROK_FRESH_FOR) } +/// The week split by product, in the order the server lists them. +/// +/// A product with nothing spent omits `usagePercent` exactly as the total +/// does, and for the same reason, so an absent one reads as nought here +/// too. Products are kept even at nought: which of the three is idle is +/// part of the answer, and dropping them would leave a reader unable to +/// tell an unused product from one the server stopped reporting. +fn products_of(cfg: &serde_json::Value) -> Vec<(String, f64)> { + cfg["productUsage"] + .as_array() + .map(|list| { + list.iter() + .filter_map(|entry| { + let name = text(entry, "product"); + if name.is_empty() { + return None; + } + Some((name, val_of(&entry["usagePercent"]).unwrap_or(0.0))) + }) + .collect() + }) + .unwrap_or_default() +} + /// The billing body in the same shape the log parser produces, so the rest /// of the tab cannot tell which of the two it is looking at. fn quota_from(d: &serde_json::Value) -> Option<Quota> { @@ -583,7 +613,29 @@ fn quota_from(d: &serde_json::Value) -> Option<Quota> { return None; } Some(Quota { - pct: val_of(&cfg["creditUsagePercent"]), + // An absent percentage against a named period means nought, not + // unknown. This is proto3 omitting a scalar at its default, and it + // was mistaken here for the field having been withdrawn. + // + // The evidence is inside a single response. Alongside the credit + // figure the endpoint returns `productUsage`, one entry per product, + // and on this account it reads: + // + // [{"product":"GrokBuild","usagePercent":1.0}, + // {"product":"GrokChat"},{"product":"GrokImagine"}] + // + // The product with usage carries the key; the two at zero omit it, + // in the same array, in the same answer. Watched over time as well: + // this account's weekly window reset at 02:09, read with no + // percentage at all while nothing had been spent, and began + // reporting 1.0 once it had - same endpoint, same headers, same + // token. + // + // So nought is the real reading and not a guess, which is the only + // reason it may be drawn. A period this cannot parse is still + // unknown, and still refused above. + pct: Some(val_of(&cfg["creditUsagePercent"]).unwrap_or(0.0)), + products: products_of(cfg), taken: Some(now()), kind: text(period, "type"), start, @@ -915,6 +967,24 @@ fn grok_tab(d: &Data, w: usize, p: &Palette) -> Vec<String> { ], w - 1, )); + // The same week split by product. Worth a row of its own because + // the bar above is one number for three different things, and which + // of them is spending is the part a reader can act on. + if !q.products.is_empty() { + let split = q + .products + .iter() + .map(|(name, pct)| format!("{} {}", name, pct_text(*pct).trim())) + .collect::<Vec<_>>() + .join(" · "); + rows.push(tc::seg( + &[ + (p.dim.as_str(), " by product ".into()), + (p.txt.as_str(), split), + ], + w - 1, + )); + } rows.push(String::new()); } @@ -1265,12 +1335,13 @@ mod tests { } #[test] - fn a_period_the_server_names_is_a_reading_even_with_no_percentage() { - // x.ai stopped sending creditUsagePercent for unified-billing - // accounts: 200, the current weekly period, and no percentage at - // all. Refusing that answer meant falling back to a log line about - // a window that had already closed - a fossil shown as current - // while the server's own answer was thrown away. + fn a_named_period_with_no_percentage_is_nought_used() { + // This asserted `None` for one commit, on the reading that x.ai had + // withdrawn the field for unified-billing accounts. It had not: + // proto3 omits a scalar sitting at its default, so no key means + // nought. The answer's own `productUsage` array settles it - the + // product with usage carries `usagePercent`, the two at nought omit + // it, in the same array of the same response. let body = serde_json::json!({"config": { "currentPeriod": { "type": "USAGE_PERIOD_TYPE_WEEKLY", @@ -1278,14 +1349,32 @@ mod tests { "end": "2026-09-02T02:09:41.289406+00:00" }, "onDemandCap": {"val": 0}, "onDemandUsed": {"val": 0}, + "productUsage": [ + {"product": "GrokBuild", "usagePercent": 1.0}, + {"product": "GrokChat"}, + {"product": "GrokImagine"} + ], }}); let q = quota_from(&body).expect("a named period is a reading"); - assert_eq!(q.pct, None, "invented a percentage the server did not send"); + assert_eq!(q.pct, Some(0.0), "an omitted default read as unknown"); assert_eq!(q.start, "2026-08-26T02:09:41.289406+00:00"); assert!(q.taken.is_some(), "a live reading knows when it was taken"); - // An answer naming no period at all is still not a reading. + // A percentage that is present is taken as sent, nought included - + // a real 0.0 on the wire and an omitted one mean the same thing. + let mut with = body.clone(); + with["config"]["creditUsagePercent"] = serde_json::json!(1.0); + assert_eq!(quota_from(&with).unwrap().pct, Some(1.0)); + with["config"]["creditUsagePercent"] = serde_json::json!(0.0); + assert_eq!(quota_from(&with).unwrap().pct, Some(0.0)); + + // An answer naming no period at all is still not a reading: nought + // is only knowable against a window the server stated. assert!(quota_from(&serde_json::json!({"config": {}})).is_none()); + assert!(quota_from(&serde_json::json!({"config": { + "creditUsagePercent": 5.0 + }})) + .is_none()); } /// The roll itself, on a fixed clock - `lanes` has to ask the real one. From 783c69ad03ce53664b3623ecf0f18f5b95a6f430 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Wed, 26 Aug 2026 14:47:59 +0800 Subject: [PATCH 139/147] usage: antigravity was named as quiet without being asked why The summary lists agents publishing no quota, and gives a reason for the one that can. Antigravity's reason came from `tier_note`, which answers a different question - what is wrong with the credential - and returns nothing at all when the credential is fine. That is the ordinary case, so the ordinary outcome was "No quota published by: antigravity." followed by silence. The real reason is not a fault and is worth stating plainly: this is the only agent here with no account-wide quota endpoint. Every other tab can report a limit from a server whatever is running locally. Antigravity's percentages come from a language server that lives inside the running app - found by matching the process and reading its listening port out of /proc - so with the app closed there is nothing to ask, on any machine, for anybody. Its own tab has always said so. The summary now does too, still deferring to the tier reason when that is what is actually wrong, so the two cannot both be printed at once. Nothing changed about what is fetched or drawn - only whether the screen says why a section is absent, which is the same rule the rest of this widget already follows. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- docs/usage.md | 17 ++++++++++ widgets/src/bin/usage/antigravity.rs | 47 ++++++++++++++++++++++++++++ widgets/src/bin/usage/vendors.rs | 2 +- 3 files changed, 65 insertions(+), 1 deletion(-) diff --git a/docs/usage.md b/docs/usage.md index fe086d4..7ea2d8d 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -325,6 +325,23 @@ a Claude/GPT pair at 0%; those are real limits and are left in. It is present only while Antigravity is running, which the pane does not disguise: no process, no port, no section. +This is the one agent here with **no account-wide quota endpoint at all**. +Every other tab can report a limit from a server whatever is running locally; +this one cannot, because the numbers exist in a process rather than on an +account. So `[+]` lists it under `No quota published by:` and says which of +the two reasons applies — a tier it could not read, or the commoner one: + +``` + ANTIGRAVITY + no quota · Antigravity publishes none to any server. The percentages come + from a language server that runs inside the app, so start it and they + appear here. +``` + +That line used to be empty whenever the tier read perfectly well, which is +most of the time — so the summary named the agent as quiet and then said +nothing about why. + The tier comes from the endpoint the CLI authenticates against: ``` diff --git a/widgets/src/bin/usage/antigravity.rs b/widgets/src/bin/usage/antigravity.rs index 499fe31..3b318bc 100644 --- a/widgets/src/bin/usage/antigravity.rs +++ b/widgets/src/bin/usage/antigravity.rs @@ -275,6 +275,24 @@ pub fn tier_note(why: Missing) -> String { } } +/// Why Antigravity publishes no bar, for the summary screen. +/// +/// A missing tier is one reason and was the only one this said out loud, +/// so an account whose tier reads perfectly well produced an empty note +/// and "No quota published by: antigravity" with nothing after it. The +/// commoner reason by far is the other one: unlike every other agent here +/// Antigravity has no account-wide quota endpoint at all, and its +/// percentages live in a language server that exists only while the app is +/// running. Its own tab has always said so; the summary had not. +pub fn why_no_lane(d: &Data) -> String { + let tier = tier_note(d.why_no_tier()); + if !tier.is_empty() { + return tier; + } + "no quota · Antigravity publishes none to any server. The percentages come from a language server that runs inside the app, so start it and they appear here." + .into() +} + /// The same, with the server's own words when there are any. pub fn tier_note_said(why: Missing, said: &str) -> String { let base = tier_note(why); @@ -705,6 +723,35 @@ pub fn tab(d: &Data, w: usize, _h: usize, _cfg: &Config, p: &Palette) -> Vec<Str #[cfg(test)] mod tests { + + #[test] + fn a_signed_in_account_with_no_running_app_still_says_why() { + // The summary said "No quota published by: antigravity" and then + // nothing, because the only reason it knew how to give was a + // missing tier - and this account's tier is fine. The commoner + // reason went unsaid: there is no server to ask. + let signed_in = Data { + live: Some(serde_json::json!({"currentTier": {"id": "free"}})), + quota: Vec::new(), + ..Data::default() + }; + assert!(lanes(&signed_in).is_empty(), "no language server, no lanes"); + let note = why_no_lane(&signed_in); + assert!(!note.is_empty(), "a quiet agent with no reason given"); + assert!(note.contains("language server"), "{}", note); + assert!(note.contains("start it"), "says nothing to do about it: {}", note); + + // A missing tier is still the reason when that is what is wrong, + // and it must not be replaced by the general one. + let lapsed = Data { + live: None, + tier_why: Missing::Expired(3600.0), + ..Data::default() + }; + let note = why_no_lane(&lapsed); + assert!(note.contains("expired"), "tier reason lost: {}", note); + assert!(!note.contains("language server"), "two reasons at once: {}", note); + } use super::*; /// A conversation store built here rather than found on this machine: diff --git a/widgets/src/bin/usage/vendors.rs b/widgets/src/bin/usage/vendors.rs index c49ae9f..2327b04 100644 --- a/widgets/src/bin/usage/vendors.rs +++ b/widgets/src/bin/usage/vendors.rs @@ -324,7 +324,7 @@ fn summary_tab(s: &State, w: usize, p: &Palette) -> Vec<String> { } } if quiet.contains(&"antigravity") { - let note = crate::antigravity::tier_note(s.antigravity.why_no_tier()); + let note = crate::antigravity::why_no_lane(&s.antigravity); if !note.is_empty() { rows.push(String::new()); rows.push(tc::seg( From db49a37d04e421535baca36a6cfdb0770ebc9aa7 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Wed, 26 Aug 2026 14:59:13 +0800 Subject: [PATCH 140/147] usage: the quiet agents are named before they are explained, not after `[+]` led its quiet block with one roll-call - "No quota published by: grok, antigravity." - and put the headings explaining them underneath. That reads backwards. A reader meets a list of names, then has to carry those names down to the paragraphs to find out which is which. And it said the same thing twice for every agent that had a reason, because each reason already opens by saying there is no quota. Each agent that can explain itself now leads with its own heading and the sentence sits under the name it is about. The roll-call is what is left over: only agents with nothing to say appear in it, and when they have all explained themselves there is no such line at all. Split into `quiet_block` to be testable. The State it would otherwise need cannot be built from another module - every agent's Data keeps its fields private - so a pure function over the notes is the only shape the ordering can be pinned in. Two tests: the heading precedes its sentence and no roll-call remains when everything is explained, and an agent with nothing to say is still named while an explained one is not named twice. Both were watched to fail against the old order. Antigravity keeps the warning tone, because its reason can be a credential that has lapsed, which is the reader's to fix. Grok's stays dim: nothing is wrong there, the server simply has nothing to report. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- docs/usage.md | 16 ++- widgets/src/bin/usage/vendors.rs | 165 ++++++++++++++++++++++++------- 2 files changed, 141 insertions(+), 40 deletions(-) diff --git a/docs/usage.md b/docs/usage.md index 7ea2d8d..5a21309 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -328,8 +328,8 @@ disguise: no process, no port, no section. This is the one agent here with **no account-wide quota endpoint at all**. Every other tab can report a limit from a server whatever is running locally; this one cannot, because the numbers exist in a process rather than on an -account. So `[+]` lists it under `No quota published by:` and says which of -the two reasons applies — a tier it could not read, or the commoner one: +account. So on `[+]` it appears under its own name, with which of the two reasons +applies — a tier it could not read, or the commoner one: ``` ANTIGRAVITY @@ -338,10 +338,18 @@ the two reasons applies — a tier it could not read, or the commoner one: appear here. ``` -That line used to be empty whenever the tier read perfectly well, which is -most of the time — so the summary named the agent as quiet and then said +That sentence used to be empty whenever the tier read perfectly well, which +is most of the time — so the summary named the agent as quiet and then said nothing about why. +**The roll-call is what is left over.** `No quota published by: …` once led +this block and named every quiet agent, with the explanations below it. That +reads backwards, and it said the same thing twice for any agent that had a +reason, since each reason already opens by saying there is no quota. Now +each agent that can explain itself leads with its own heading, and the +roll-call lists only those with nothing to say — vanishing entirely when +they all have. + The tier comes from the endpoint the CLI authenticates against: ``` diff --git a/widgets/src/bin/usage/vendors.rs b/widgets/src/bin/usage/vendors.rs index 2327b04..7b35872 100644 --- a/widgets/src/bin/usage/vendors.rs +++ b/widgets/src/bin/usage/vendors.rs @@ -87,6 +87,53 @@ fn rank_by_worst_lane<T>(groups: &mut [(T, Vec<Lane>)]) { groups.sort_by(|a, b| worst(&b.1).total_cmp(&worst(&a.1))); } +/// The agents publishing nothing, each under its own name. +/// +/// The order used to be the other way round: one "No quota published by: +/// grok, antigravity." and then, below it, the headings explaining them. +/// That reads backwards - the reader meets a list of names and has to carry +/// them down to the paragraphs - and it stated the same fact twice for +/// every agent that had a reason, because each reason already opens by +/// saying there is no quota. +/// +/// So the roll-call is what is left over. Only agents with nothing to say +/// appear in it, and when every quiet agent has explained itself there is +/// no such line at all. +/// +/// Split out from summary_tab because the State it needs cannot be built +/// from another module - every agent's Data keeps its fields private - so +/// this is the only shape the ordering is testable in. +fn quiet_block(said: &[(&str, String, bool)], w: usize, p: &Palette) -> Vec<String> { + let mut rows = Vec::new(); + let mut unexplained: Vec<&str> = Vec::new(); + for (name, note, warn) in said { + if note.is_empty() { + unexplained.push(name); + continue; + } + rows.push(tc::seg( + &[(p.lbl.as_str(), format!(" {}", name.to_uppercase()))], + w - 1, + )); + let tone = if *warn { p.warn.as_str() } else { p.dim.as_str() }; + rows.extend( + wrap_text(note, w.saturating_sub(5).max(20)) + .into_iter() + .map(|l| tc::seg(&[(tone, format!(" {}", l))], w - 1)), + ); + rows.push(String::new()); + } + if !unexplained.is_empty() { + rows.extend(no_local( + &format!("No quota published by: {}.", unexplained.join(", ")), + "", + w, + p, + )); + } + rows +} + fn summary_tab(s: &State, w: usize, p: &Palette) -> Vec<String> { let mut groups: Vec<(&str, Vec<Lane>)> = Vec::new(); let mut quiet: Vec<&str> = Vec::new(); @@ -300,44 +347,19 @@ fn summary_tab(s: &State, w: usize, p: &Palette) -> Vec<String> { } if !quiet.is_empty() { rows.push(String::new()); - rows.extend(no_local( - &format!("No quota published by: {}.", quiet.join(", ")), - "", - w, - p, - )); - // Antigravity is quiet for a reason it can name, and the reason is - // the useful part - "no quota published" says the same thing about a - // machine that has never signed in and one whose token lapsed an - // hour ago. Its own heading, under that line, so the sentence has - // something to belong to. - if quiet.contains(&"grok") { - let note = crate::grok::why_no_lane(&s.grok); - if !note.is_empty() { - rows.push(String::new()); - rows.push(tc::seg(&[(p.lbl.as_str(), " GROK".into())], w - 1)); - rows.extend( - wrap_text(note, w.saturating_sub(5).max(20)) - .into_iter() - .map(|l| tc::seg(&[(p.dim.as_str(), format!(" {}", l))], w - 1)), - ); - } - } - if quiet.contains(&"antigravity") { - let note = crate::antigravity::why_no_lane(&s.antigravity); - if !note.is_empty() { - rows.push(String::new()); - rows.push(tc::seg( - &[(p.lbl.as_str(), " ANTIGRAVITY".into())], - w - 1, - )); - rows.extend( - wrap_text(¬e, w.saturating_sub(5).max(20)) - .into_iter() - .map(|l| tc::seg(&[(p.warn.as_str(), format!(" {}", l))], w - 1)), - ); + let mut said: Vec<(&str, String, bool)> = Vec::new(); + for name in &quiet { + match *name { + "grok" => said.push((name, crate::grok::why_no_lane(&s.grok).to_string(), false)), + // Antigravity's can be a credential that has lapsed, which + // is the reader's to fix, so it keeps the warning tone. + "antigravity" => { + said.push((name, crate::antigravity::why_no_lane(&s.antigravity), true)) + } + _ => said.push((name, String::new(), false)), } } + rows.extend(quiet_block(&said, w, p)); } rows } @@ -395,6 +417,77 @@ fn unknown(name: &str, installed: &HashMap<String, Presence>, w: usize, p: &Pale mod tests { use super::*; + /// Rendered rows with the colour escapes stripped, so a test can read + /// what is on screen rather than how it was painted. + fn plain(rows: &[String]) -> Vec<String> { + let strip = |s: &String| { + let mut out = String::new(); + let mut chars = s.chars(); + while let Some(c) = chars.next() { + if c == '\u{1b}' { + for c in chars.by_ref() { + if c.is_ascii_alphabetic() { + break; + } + } + } else { + out.push(c); + } + } + out.trim_end().to_string() + }; + rows.iter().map(strip).collect() + } + + #[test] + fn a_quiet_agent_is_explained_under_its_own_name() { + let p = palette(); + let said = vec![( + "antigravity", + "no quota - it publishes none to any server.".to_string(), + true, + )]; + let rows = plain(&quiet_block(&said, 90, &p)); + let head = rows + .iter() + .position(|r| r.contains("ANTIGRAVITY")) + .expect("a heading"); + let line = rows + .iter() + .position(|r| r.contains("publishes none")) + .expect("the reason"); + assert!(head < line, "the sentence came before the name it is about:\n{:#?}", rows); + + // And when every quiet agent has said why, the roll-call that used + // to lead is gone rather than repeating them. + assert!( + !rows.iter().any(|r| r.contains("No quota published by")), + "named twice:\n{:#?}", + rows + ); + } + + #[test] + fn an_agent_with_nothing_to_say_is_still_named() { + // The roll-call is not dropped, only reduced to what is left. + let p = palette(); + let said = vec![ + ("antigravity", "no quota - the app is closed.".to_string(), true), + ("copilot", String::new(), false), + ]; + let rows = plain(&quiet_block(&said, 90, &p)); + let roll = rows + .iter() + .find(|r| r.contains("No quota published by")) + .expect("a roll-call for the one with no reason"); + assert!(roll.contains("copilot"), "{}", roll); + assert!(!roll.contains("antigravity"), "explained and listed: {}", roll); + // The explained one still leads with its heading. + let head = rows.iter().position(|r| r.contains("ANTIGRAVITY")).unwrap(); + let rollat = rows.iter().position(|r| r.contains("No quota published by")).unwrap(); + assert!(head < rollat, "roll-call above the explanations:\n{:#?}", rows); + } + #[test] fn an_agent_with_no_quota_is_named_rather_than_dropped() { // Six agents, none publishing anything: the screen says so instead From 927b24ddd215097c08b28191a7d79f76de5ec922 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Wed, 26 Aug 2026 15:52:01 +0800 Subject: [PATCH 141/147] usage: antigravity's quota does not need the app open after all An hour ago this widget said, and its doc said in the strongest terms, that Antigravity was the one agent with no account-wide quota endpoint at all - that with the app closed there was nothing to ask, on any machine, for anybody. That was wrong, and reading how CodexBar does it is what showed it: among its four sources is a Google OAuth path this had none of. Google serves the same summary the language server does, on the endpoint the tier already comes from: POST cloudcode-pa.googleapis.com/v1internal:retrieveUserQuotaSummary Same bearer token out of the same file. The reason it looked absent is the body. `loadCodeAssist` wants `{"metadata":{"pluginType":"GEMINI"}}`, and sending that here answers 400 naming `metadata` as an unknown field, which is indistinguishable from an endpoint that does not exist. It takes `{}`. What comes back needs no parser of its own: `groups[].displayName`, `buckets[].window`, `remainingFraction`, `resetTime` - group for group and bucket for bucket what the local server sends. Measured against it on this machine within a minute: Gemini weekly 0.05% local, 0.08% remote. The local server stays preferred. It is the app's own answer and moves as the app is used, where Google's is a record; and it is on this machine, where the other is a request that leaves it. So the remote one is asked only when there is no server to ask, held for an hour rather than two minutes, and the heading says which was read - `from Google - the app is not running` against `from the local language server`. Verified by disabling the local probe on a build and watching the tab draw real numbers from Google with the app still running, then restoring it. What still cannot be recovered is a lapsed token, so the quiet note now names both sources rather than sending a reader to open an app that would not have helped. Not taken from CodexBar: it also launches the `agy` CLI in a PTY to get a server where none was running, and reaps its own stale processes. That is a reader starting somebody else's program, which this repo has already decided against for Grok, and the remote path makes it unnecessary here. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- docs/usage.md | 38 +++++++-- widgets/src/bin/usage/antigravity.rs | 112 ++++++++++++++++++++++++--- 2 files changed, 130 insertions(+), 20 deletions(-) diff --git a/docs/usage.md b/docs/usage.md index 5a21309..aec2685 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -325,17 +325,39 @@ a Claude/GPT pair at 0%; those are real limits and are left in. It is present only while Antigravity is running, which the pane does not disguise: no process, no port, no section. -This is the one agent here with **no account-wide quota endpoint at all**. -Every other tab can report a limit from a server whatever is running locally; -this one cannot, because the numbers exist in a process rather than on an -account. So on `[+]` it appears under its own name, with which of the two reasons -applies — a tier it could not read, or the commoner one: +That was written here as *"the one agent with no account-wide quota endpoint +at all"*, and it was wrong. Google serves the same summary the language +server does: + +``` +POST https://cloudcode-pa.googleapis.com/v1internal:retrieveUserQuotaSummary +``` + +Same bearer token the tier already uses, and the reason it looked absent is +the body: `loadCodeAssist` wants `{"metadata":{"pluginType":"GEMINI"}}`, and +sending that here is a 400 naming `metadata` as an unknown field — which +reads exactly like an endpoint that is not there. It takes `{}`. What comes +back is the same shape group for group and bucket for bucket, so it needs no +parser of its own. + +The local server is still preferred: it is the app's own answer and moves as +the app is used, where Google's is a record. The remote one is asked only +when there is no server to ask, held for an hour rather than two minutes, +and the heading says which was read: + +``` + ── QUOTA ── live · account-wide, from Google - the app is not running +``` + +So the quota survives the app being closed. What still does not is a lapsed +token — and when neither answers, `[+]` names the agent with both reasons at +once rather than sending the reader to open an app that would not have +helped: ``` ANTIGRAVITY - no quota · Antigravity publishes none to any server. The percentages come - from a language server that runs inside the app, so start it and they - appear here. + no quota · neither the language server inside the app nor Google + answered. Open Antigravity, or sign in again if its token has lapsed. ``` That sentence used to be empty whenever the tier read perfectly well, which diff --git a/widgets/src/bin/usage/antigravity.rs b/widgets/src/bin/usage/antigravity.rs index 3b318bc..ecf926d 100644 --- a/widgets/src/bin/usage/antigravity.rs +++ b/widgets/src/bin/usage/antigravity.rs @@ -43,6 +43,23 @@ fn token_path() -> String { const CODE_ASSIST_API: &str = "https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist"; +/// The same quota summary the language server answers, from Google. +/// +/// This was thought not to exist. The tab said so, and said it in the +/// strongest terms - that with the app closed there was nothing to ask, on +/// any machine, for anybody - because the only quota this widget knew about +/// came out of a process that dies with the IDE. +/// +/// It does exist, it is on the endpoint the tier already comes from, and the +/// body is empty rather than the `pluginType` metadata `loadCodeAssist` +/// wants: sending that here is a 400 naming `metadata` as an unknown field, +/// which reads exactly like an endpoint that is not there. +/// +/// What comes back is the same shape the language server sends, group for +/// group and bucket for bucket, so it needs no parser of its own. +const REMOTE_QUOTA_API: &str = + "https://cloudcode-pa.googleapis.com/v1internal:retrieveUserQuotaSummary"; + /// The Connect method the language server answers the quota on. const ANTIGRAVITY_RPC: &str = "/exa.language_server_pb.LanguageServerService/RetrieveUserQuotaSummary"; @@ -72,8 +89,14 @@ pub struct Data { tier_why: Missing, /// What the endpoint said, when it said anything. Empty otherwise. tier_said: String, - /// The quota groups, empty when the language server is not running. + /// The quota groups, empty when neither source answered. quota: Vec<serde_json::Value>, + /// True when the groups above came from Google rather than from the + /// language server on this machine. The two agree in shape and very + /// nearly in value, so nothing else can tell them apart - and a reader + /// wondering why there are numbers with the app shut deserves the + /// answer. + quota_remote: bool, /// How the CLI authenticated. Read once here rather than per frame: /// the tab is redrawn on every keypress and this is a file on disk. auth: String, @@ -289,7 +312,8 @@ pub fn why_no_lane(d: &Data) -> String { if !tier.is_empty() { return tier; } - "no quota · Antigravity publishes none to any server. The percentages come from a language server that runs inside the app, so start it and they appear here." + "no quota · neither the language server inside the app nor Google \ + answered. Open Antigravity, or sign in again if its token has lapsed." .into() } @@ -338,6 +362,32 @@ fn antigravity_said() -> Result<serde_json::Value, String> { /// The same call, keeping why it failed. fn post_try(url: &str, access: &str) -> Result<serde_json::Value, String> { + post_body(url, access, "{\"metadata\":{\"pluginType\":\"GEMINI\"}}") +} + +/// The quota summary Google holds, when nothing local is serving one. +/// +/// Preferred second, not first: the language server is the app's own answer +/// and moves as it is used, while this is what Google has recorded. They +/// agree in shape and very nearly in value, so the tab cannot tell them +/// apart - which is the point, and why the row says which it read. +fn remote_quota() -> Option<Vec<serde_json::Value>> { + let file = read_json(&token_path())?; + let tok = &file["token"]; + let access = text(tok, "access_token"); + let expiry = iso_epoch(&text(tok, "expiry")); + if access.is_empty() || expiry.is_some_and(|at| at <= now()) { + return None; + } + let got = post_body(REMOTE_QUOTA_API, &access, "{}").ok()?; + let groups = got["groups"].as_array()?; + if groups.is_empty() { + return None; + } + Some(groups.clone()) +} + +fn post_body(url: &str, access: &str, body: &str) -> Result<serde_json::Value, String> { post_json_said( url, &[ @@ -350,7 +400,7 @@ fn post_try(url: &str, access: &str) -> Result<serde_json::Value, String> { // actually calling. ("User-Agent", "terminal-toys (antigravity-cli)"), ], - "{\"metadata\":{\"pluginType\":\"GEMINI\"}}", + body, 20, ) } @@ -404,6 +454,20 @@ pub fn read(caches: &mut Caches, _cfg: &Config) -> Data { .unwrap_or_default(), ..Data::default() }; + // Local first: it is the app's own answer and moves as the app is used. + // Google's is asked only when there is no server to ask, and is held far + // longer - it is a record rather than a live meter, and unlike the local + // one it is a request that leaves this machine. + if d.quota.is_empty() { + if let Some(groups) = cached(caches, "antigravity-remote", PLAN_TTL, || { + remote_quota().map(serde_json::Value::Array) + }) + .and_then(|got| got.as_array().cloned()) + { + d.quota = groups; + d.quota_remote = true; + } + } let mut files: Vec<String> = std::fs::read_dir(format!("{}/conversations", antigravity_dir())) .into_iter() .flatten() @@ -481,15 +545,27 @@ pub fn lanes(d: &Data) -> Vec<Lane> { /// red means the same here as on every other tab. Every plan reports every /// family it covers, so a Gemini-only account still gets a Claude/GPT pair /// sitting at 0% - they are real limits, not padding, and are left in. -fn antigravity_quota_rows(groups: &[serde_json::Value], w: usize, p: &Palette) -> Vec<String> { +fn antigravity_quota_rows( + groups: &[serde_json::Value], + remote: bool, + w: usize, + p: &Palette, +) -> Vec<String> { if groups.is_empty() { return Vec::new(); } // The long form names where the number comes from, which matters here // more than elsewhere; the short one still says it is not this machine's // own tally. Shortened before it can clip, as the other headers are. - let mut note = " · account-wide, from the local language server"; - for shorter in [" · from the local server", " · local"] { + let mut note = if remote { + " · account-wide, from Google - the app is not running" + } else { + " · account-wide, from the local language server" + }; + for shorter in [ + if remote { " · from Google" } else { " · from the local server" }, + if remote { " · remote" } else { " · local" }, + ] { if 13 + "live".len() + note.chars().count() <= w.saturating_sub(1) { break; } @@ -686,7 +762,7 @@ fn antigravity_activity(d: &Data, w: usize, p: &Palette) -> Vec<String> { } fn antigravity_body(d: &Data, w: usize, p: &Palette) -> Vec<String> { - let mut rows = antigravity_quota_rows(&d.quota, w, p); + let mut rows = antigravity_quota_rows(&d.quota, d.quota_remote, w, p); if d.live.is_none() { rows.extend( wrap_text(&tier_note_said(d.tier_why, &d.tier_said), w.saturating_sub(4).max(20)) @@ -735,11 +811,20 @@ mod tests { quota: Vec::new(), ..Data::default() }; - assert!(lanes(&signed_in).is_empty(), "no language server, no lanes"); + assert!(lanes(&signed_in).is_empty(), "no groups, no lanes"); let note = why_no_lane(&signed_in); assert!(!note.is_empty(), "a quiet agent with no reason given"); + // Both sources are named, because reaching this line means both + // were tried - the language server inside the app, and Google. + // Naming only the first would send a reader to open an app that + // would not have helped when the token is what has lapsed. assert!(note.contains("language server"), "{}", note); - assert!(note.contains("start it"), "says nothing to do about it: {}", note); + assert!(note.contains("Google"), "the remote source went unmentioned: {}", note); + assert!( + note.contains("Open Antigravity") && note.contains("sign in"), + "says nothing to do about it: {}", + note + ); // A missing tier is still the reason when that is what is wrong, // and it must not be replaced by the general one. @@ -959,6 +1044,7 @@ mod tests { ("Gemini 3 Pro", "5h", 0.996), ("Claude Sonnet 4.5", "weekly", 1.0), ]), + false, 96, &p, ); @@ -977,6 +1063,7 @@ mod tests { let p = palette(); let rows = antigravity_quota_rows( &[serde_json::json!({"displayName": "GPT", "buckets": []})], + false, 96, &p, ); @@ -989,9 +1076,9 @@ mod tests { fn the_source_note_shortens_before_it_can_clip() { let p = palette(); let quota = groups(&[("Gemini 3 Pro", "weekly", 0.5)]); - let wide = antigravity_quota_rows("a, 120, &p)[0].clone(); - let narrow = antigravity_quota_rows("a, 60, &p)[0].clone(); - let tight = antigravity_quota_rows("a, 30, &p)[0].clone(); + let wide = antigravity_quota_rows("a, false, 120, &p)[0].clone(); + let narrow = antigravity_quota_rows("a, false, 60, &p)[0].clone(); + let tight = antigravity_quota_rows("a, false, 30, &p)[0].clone(); assert!(wide.contains("from the local language server")); assert!(narrow.contains("from the local server")); assert!(tight.contains("local")); @@ -1121,6 +1208,7 @@ mod tests { let p = palette(); let cfg = Config::default(); let d = Data { + quota_remote: false, quota: groups(&[ ("Gemini 3 Pro", "weekly", 0.25), ("Gemini 3 Pro", "5h", 0.996), From 878ec5719304b1adec4e712f257eba73f063bfad Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Wed, 26 Aug 2026 16:46:05 +0800 Subject: [PATCH 142/147] usage: antigravity says which step failed, and the remote ask has a switch `usage.antigravity_remote`, on by default. It decides one thing: whether Antigravity's quota may be asked of Google when no language server is running. On rather than off, unlike `grok_ping`, because the request is not the same kind. Grok's asks a vendor for a reading nothing on this machine has; this asks for the reading the app itself serves over localhost, from the host the tier is already fetched from every hour, with the same credential. Turning it off spares nothing that request has not already spent, and costs the quota whenever the app is shut. The larger half is that "no quota" covered four situations wanting different things from the reader, and now says which: - asking Google is off - set usage.antigravity_remote to true - Antigravity has not signed in on this machine - run `agy` once - Antigravity's token expired 51m ago - it refreshes them itself - Google refused the Antigravity token: <what it said> The first three are decided before the request and before the cache, and that ordering is the fix rather than a tidiness. `cached` holds a refusal without re-running the closure that produced it, so a reason captured inside that closure is gone by the next frame. Measured: the tab reported "Google did not answer" about a token that had expired an hour earlier and was never sent. Both the tab and `[+]` carry it. The tab's sentence used to say the quota "comes from the language server while Antigravity is running, so start it" - true, and the wrong instruction for three of the four cases. Two things were tested before being relied on. `agy models` runs non-interactively and authenticates, but the token file is byte-identical afterwards: it refreshes in memory and writes nothing back, so running it cannot extend the remote path's hour. And this machine's `agy` log reads "You are not logged into Antigravity", which is why the remote ask is refused here at all - a signed-out session, not merely a lapsed hour, and exactly the case the old sentence would have sent someone to fix the wrong way. Not taken from CodexBar: launching `agy` in a PTY and holding it open for its local server. That is a reader starting somebody else's program and keeping it running, and it is the one thing here that would need to be off by default rather than on. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- config.example.json | 2 + docs/usage.md | 32 ++++- widgets/src/bin/usage.rs | 15 ++ widgets/src/bin/usage/antigravity.rs | 196 ++++++++++++++++++++------- 4 files changed, 194 insertions(+), 51 deletions(-) diff --git a/config.example.json b/config.example.json index 19cb9c7..cea3da4 100644 --- a/config.example.json +++ b/config.example.json @@ -108,6 +108,8 @@ "rates": {}, "_plan_cost_comment": "What each subscription costs you per month, keyed by agent, for example claude: 200. Nothing ships here: Anthropic lists Max as 'from $100' because it varies by tier, and no invoice is on this machine. Set it and METERED adds 'the plan saves'.", "plan_cost": {}, + "_antigravity_remote_comment": "Antigravity publishes its quota two ways: a language server that runs inside the app, and Google, which serves the same summary on the endpoint the tier already comes from. The local one is preferred and this only decides whether the remote one may be asked when the app is shut. On by default - it is the same host and the same credential the tier request already uses. Turn it off and the quota is absent whenever Antigravity is closed; the tab then says so, and names this key.", + "antigravity_remote": true, "_grok_ping_comment": "Grok is the only agent with no live quota: its figures come from the log its own CLI writes, so they move only when you use Grok on this machine. Turn grok_ping on to ask x.ai instead, using the token the CLI leaves in ~/.grok/auth.json. That also runs the Grok CLI once after a session goes quiet, which is what refreshes the token - without it the asking works until the token lapses and then silently stops. Off by default: a widget that reads should not start talking to a vendor, or starting somebody else's program, because it was launched.", "grok_ping": false, "grok_ping_minutes": 5 diff --git a/docs/usage.md b/docs/usage.md index aec2685..5cc3eb6 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -349,10 +349,33 @@ and the heading says which was read: ── QUOTA ── live · account-wide, from Google - the app is not running ``` -So the quota survives the app being closed. What still does not is a lapsed -token — and when neither answers, `[+]` names the agent with both reasons at -once rather than sending the reader to open an app that would not have -helped: +So the quota survives the app being closed — for as long as the token lasts, +which is an hour, because the refresh token beside it is deliberately left +alone. Running `agy` does not extend that: it refreshes in memory and writes +nothing back, verified by running `agy models` and finding the token file +byte-identical afterwards. + +**Every step that can fail says which step it was**, on the tab and on `[+]`, +because "no quota" covered four situations wanting different things from the +reader: + +``` + no quota either: Antigravity's token expired 51m ago - it refreshes them + itself, so open it or run `agy` once and sign in + no quota either: asking Google is off - set usage.antigravity_remote to true + no quota either: Antigravity has not signed in on this machine - run `agy` + once and sign in + no quota either: Google refused the Antigravity token: … +``` + +The first three are decided before anything leaves the machine, and before +the cache, so the sentence survives a held failure. A reason captured inside +the fetch closure does not: `cached` holds a refusal without re-running it, +so the row reverted to a generic "Google did not answer" about a token that +had expired an hour earlier and was never sent. + +When neither source answers, `[+]` names the agent with the reason rather +than sending the reader to open an app that would not have helped: ``` ANTIGRAVITY @@ -931,6 +954,7 @@ Three settings, all off or hourly by default: | key | default | what it does | |---|---|---| +| `antigravity_remote` | `true` | may Antigravity's quota be asked of Google (`cloudcode-pa.googleapis.com/v1internal:retrieveUserQuotaSummary`) when no language server is running. Same host and same credential as the tier request. Off means no quota while the app is closed, and the tab says so | | `grok_ping` | `false` | GET `cli-chat-proxy.grok.com/v1/billing` with the bearer token the Grok CLI leaves in `~/.grok/auth.json`, **and** run `grok agent stdio` to refresh that token — once after a session goes quiet, and once when the token is within ten minutes of lapsing | | `grok_ping_minutes` | `5` | how often. The window moves over days, but the spend inside it moves while you work, so five minutes keeps the figure actionable; one small GET twelve times an hour | diff --git a/widgets/src/bin/usage.rs b/widgets/src/bin/usage.rs index 2586238..6b432a4 100644 --- a/widgets/src/bin/usage.rs +++ b/widgets/src/bin/usage.rs @@ -1187,6 +1187,17 @@ struct Config { /// then stops, silently, which is the failure the refresh exists to /// prevent. Nobody wants the first without the second. grok_ping: bool, + /// Whether Antigravity's quota may be asked of Google when nothing is + /// serving it locally. + /// + /// On by default, unlike `grok_ping`, and the difference is what the + /// request is. Grok's asks a vendor for a reading nothing on this + /// machine has. This one asks for the same reading the app already + /// serves over localhost, from the same host and with the same + /// credential the tier is already fetched with. Turning it off costs + /// the quota whenever Antigravity is closed and spares nothing that the + /// tier request has not already spent. + antigravity_remote: bool, /// Minutes between those requests. Five, so the figure on screen is /// one a reader can act on: the window it reports moves over days, but /// the spend inside it moves while they work, and an hour-old reading @@ -1229,6 +1240,10 @@ fn read_config() -> Config { .and_then(|v| v.as_bool()) .unwrap_or(false), grok_ping_minutes: tc::cfg_f64(&raw, "grok_ping_minutes", 5.0), + antigravity_remote: raw + .get("antigravity_remote") + .and_then(|v| v.as_bool()) + .unwrap_or(true), } } diff --git a/widgets/src/bin/usage/antigravity.rs b/widgets/src/bin/usage/antigravity.rs index ecf926d..2d0d888 100644 --- a/widgets/src/bin/usage/antigravity.rs +++ b/widgets/src/bin/usage/antigravity.rs @@ -91,6 +91,8 @@ pub struct Data { tier_said: String, /// The quota groups, empty when neither source answered. quota: Vec<serde_json::Value>, + /// Why there is no quota, when there is none. Empty when there is. + quota_why: String, /// True when the groups above came from Google rather than from the /// language server on this machine. The two agree in shape and very /// nearly in value, so nothing else can tell them apart - and a reader @@ -312,9 +314,12 @@ pub fn why_no_lane(d: &Data) -> String { if !tier.is_empty() { return tier; } - "no quota · neither the language server inside the app nor Google \ - answered. Open Antigravity, or sign in again if its token has lapsed." - .into() + // The remote attempt knows exactly which step failed, and that is more + // use than any sentence written in advance. + if !d.quota_why.is_empty() { + return format!("no quota · {}", d.quota_why); + } + "no quota · neither the language server inside the app nor Google answered.".into() } /// The same, with the server's own words when there are any. @@ -371,20 +376,64 @@ fn post_try(url: &str, access: &str) -> Result<serde_json::Value, String> { /// and moves as it is used, while this is what Google has recorded. They /// agree in shape and very nearly in value, so the tab cannot tell them /// apart - which is the point, and why the row says which it read. -fn remote_quota() -> Option<Vec<serde_json::Value>> { - let file = read_json(&token_path())?; +/// Everything that can be decided without leaving the machine, decided +/// before anything is cached. +/// +/// The reason has to survive a cache hit. `cached` holds a failure for a +/// while and does not re-run the closure that produced it, so a reason +/// captured inside that closure is gone by the next frame and the row falls +/// back to whatever generic sentence is left - which is how this said +/// "Google did not answer" about a token that had expired an hour earlier +/// and was never sent. +fn remote_token(allowed: bool) -> Result<String, String> { + if !allowed { + return Err("asking Google is off - set usage.antigravity_remote to true".into()); + } + let Some(file) = read_json(&token_path()) else { + return Err( + "Antigravity has not signed in on this machine - run `agy` once and sign in".into(), + ); + }; let tok = &file["token"]; let access = text(tok, "access_token"); - let expiry = iso_epoch(&text(tok, "expiry")); - if access.is_empty() || expiry.is_some_and(|at| at <= now()) { - return None; + if access.is_empty() { + return Err("the Antigravity token file holds no session - sign in again".into()); } - let got = post_body(REMOTE_QUOTA_API, &access, "{}").ok()?; - let groups = got["groups"].as_array()?; - if groups.is_empty() { - return None; + // A lapsed token is not sent. It would be refused, and the refusal would + // then be the only thing reported, which says less than the expiry does: + // this one names how long ago and what refreshes it. + if let Some(expiry) = iso_epoch(&text(tok, "expires")) { + if expiry <= now() { + return Err(expired_note(now() - expiry)); + } + } + if let Some(expiry) = iso_epoch(&text(tok, "expiry")) { + if expiry <= now() { + return Err(expired_note(now() - expiry)); + } + } + Ok(access) +} + +fn expired_note(ago: f64) -> String { + format!( + "Antigravity's token expired {} ago - it refreshes them itself, so open it \ + or run `agy` once and sign in", + left_span(ago) + ) +} + +/// The ask itself, once the credential is known to be worth sending. +fn remote_quota(access: &str) -> Result<Vec<serde_json::Value>, String> { + let got = post_body(REMOTE_QUOTA_API, access, "{}") + .map_err(|said| format!("Google refused the Antigravity token: {}", said))?; + match got["groups"].as_array() { + Some(groups) if !groups.is_empty() => Ok(groups.clone()), + // A 200 with nothing in it. Not a failure to report as one, but not + // a reading either, and the difference matters when the reader is + // deciding whether to go and open something. + _ => Err("Google answered with no quota groups for this account".into()), } - Some(groups.clone()) } fn post_body(url: &str, access: &str, body: &str) -> Result<serde_json::Value, String> { @@ -427,7 +476,7 @@ fn conversation_steps(path: &str) -> Option<f64> { /// Each conversation is its own SQLite file with a `steps` table - one row /// per step the agent took - so the counts are real work done. No table /// anywhere carries a token count. -pub fn read(caches: &mut Caches, _cfg: &Config) -> Data { +pub fn read(caches: &mut Caches, cfg: &Config) -> Data { use std::os::unix::fs::MetadataExt; // The refusal is cached with the failure, so it is shown for as long as // the failure lasts rather than only on the frame the call was made. @@ -459,13 +508,36 @@ pub fn read(caches: &mut Caches, _cfg: &Config) -> Data { // longer - it is a record rather than a live meter, and unlike the local // one it is a request that leaves this machine. if d.quota.is_empty() { - if let Some(groups) = cached(caches, "antigravity-remote", PLAN_TTL, || { - remote_quota().map(serde_json::Value::Array) - }) - .and_then(|got| got.as_array().cloned()) - { - d.quota = groups; - d.quota_remote = true; + match remote_token(cfg.antigravity_remote) { + // Decided here, so it survives a held failure and is the same + // sentence on every frame until the thing it names changes. + Err(why) => d.quota_why = why, + Ok(access) => { + let mut why = String::new(); + let got = cached(caches, "antigravity-remote", PLAN_TTL, || { + match remote_quota(&access) { + Ok(groups) => Some(serde_json::Value::Array(groups)), + Err(said) => { + why = said; + None + } + } + }) + .and_then(|got| got.as_array().cloned()); + match got { + Some(groups) => { + d.quota = groups; + d.quota_remote = true; + } + None => { + d.quota_why = if why.is_empty() { + "Google did not answer, and the refusal is still held".to_string() + } else { + why + } + } + } + } } } let mut files: Vec<String> = std::fs::read_dir(format!("{}/conversations", antigravity_dir())) @@ -775,11 +847,27 @@ fn antigravity_body(d: &Data, w: usize, p: &Palette) -> Vec<String> { // The absence is only worth explaining while it is one. With the quota // drawn above, a paragraph about why there is no quota contradicts the // screen. + // + // When there is no quota, the sentence carries the step that failed + // rather than the shape of the problem. "It comes from the language + // server while Antigravity is running" is true and was all this said, + // and it sends a reader to open an app when the actual fault can be a + // session signed out, a token an hour old, or a setting turned off - + // none of which opening the app on its own would settle. + let absent = if d.quota_why.is_empty() { + "No tokens are recorded locally, and no quota either: it comes \ + from the language server while Antigravity is running, so start \ + it and this fills in." + .to_string() + } else { + format!( + "No tokens are recorded locally, and no quota either: {}", + d.quota_why + ) + }; rows.extend(no_local( if d.quota.is_empty() { - "No tokens are recorded locally, and no quota either: it comes \ - from the language server while Antigravity is running, so start \ - it and this fills in." + absent.as_str() } else { "No per-token usage is recorded locally - the conversations and \ steps above are what there is." @@ -801,41 +889,54 @@ pub fn tab(d: &Data, w: usize, _h: usize, _cfg: &Config, p: &Palette) -> Vec<Str mod tests { #[test] - fn a_signed_in_account_with_no_running_app_still_says_why() { - // The summary said "No quota published by: antigravity" and then - // nothing, because the only reason it knew how to give was a - // missing tier - and this account's tier is fine. The commoner - // reason went unsaid: there is no server to ask. - let signed_in = Data { + fn the_note_says_which_step_failed_not_that_something_did() { + // "No quota" covered four situations wanting different things from + // the reader: never signed in, signed out since, an hour-old token, + // and a Google that said no. Only one of them is fixed by opening + // the app, so the note carries whichever actually happened. + let with = |why: &str| Data { live: Some(serde_json::json!({"currentTier": {"id": "free"}})), quota: Vec::new(), + quota_why: why.to_string(), ..Data::default() }; - assert!(lanes(&signed_in).is_empty(), "no groups, no lanes"); - let note = why_no_lane(&signed_in); - assert!(!note.is_empty(), "a quiet agent with no reason given"); - // Both sources are named, because reaching this line means both - // were tried - the language server inside the app, and Google. - // Naming only the first would send a reader to open an app that - // would not have helped when the token is what has lapsed. - assert!(note.contains("language server"), "{}", note); - assert!(note.contains("Google"), "the remote source went unmentioned: {}", note); - assert!( - note.contains("Open Antigravity") && note.contains("sign in"), - "says nothing to do about it: {}", - note - ); - // A missing tier is still the reason when that is what is wrong, - // and it must not be replaced by the general one. + let d = with("Antigravity's token expired 2h ago - it refreshes them itself"); + assert!(lanes(&d).is_empty(), "no groups, no lanes"); + let note = why_no_lane(&d); + assert!(note.starts_with("no quota · "), "{}", note); + assert!(note.contains("expired 2h ago"), "the step that failed was dropped: {}", note); + + // Off by configuration is a reason too, and names the key. + let note = why_no_lane(&with( + "asking Google is off - set usage.antigravity_remote to true", + )); + assert!(note.contains("usage.antigravity_remote"), "{}", note); + + // A tier that cannot be read still wins: it is the older problem and + // opening the app is what fixes it. let lapsed = Data { live: None, tier_why: Missing::Expired(3600.0), + quota_why: "Google refused the Antigravity token".into(), ..Data::default() }; let note = why_no_lane(&lapsed); assert!(note.contains("expired"), "tier reason lost: {}", note); - assert!(!note.contains("language server"), "two reasons at once: {}", note); + assert!(!note.contains("Google refused"), "two reasons at once: {}", note); + } + + #[test] + fn the_remote_ask_refuses_before_it_leaves_the_machine() { + // Turned off, and there is no request to make - the reason names the + // key rather than blaming the network. + let off = remote_token(false).unwrap_err(); + assert!(off.contains("usage.antigravity_remote"), "{}", off); + // It may name Google - that is where the request would have gone - + // but it must not report a refusal or a silence that never happened. + for blame in ["refused", "did not answer", "no quota groups"] { + assert!(!off.contains(blame), "blamed the server for a setting: {}", off); + } } use super::*; @@ -1209,6 +1310,7 @@ mod tests { let cfg = Config::default(); let d = Data { quota_remote: false, + quota_why: String::new(), quota: groups(&[ ("Gemini 3 Pro", "weekly", 0.25), ("Gemini 3 Pro", "5h", 0.996), From 8da8c2d6659690fb2c0d5dc5a9d39b8986d6159c Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Wed, 26 Aug 2026 17:07:05 +0800 Subject: [PATCH 143/147] usage: antigravity gets a third source, and the widget may start it `usage.antigravity_start`, on by default. When nothing else has the quota, the widget starts `agy`, reads what it serves, and stops it again. Three sources now, cheapest first: a language server already running, then Google, then the CLI started here. Being last is not being disfavoured, it is being expensive - the first costs a socket read, the second one request, the third a process and several seconds. Only the third always works, and only the third runs another program. Both switches are the reader's: `antigravity_remote` for the request that leaves the machine, `antigravity_start` for the one that starts something. Four things were measured rather than assumed, and two of them changed the design. The pseudo-terminal is required. Started with its input on /dev/null the CLI opens ports within milliseconds and answers nothing on them for as long as you wait; given a pty it serves the quota in seconds. CodexBar's note that this needs a pty is exactly right, and it is the difference between the feature working and appearing not to exist. The port that answers belonged to a *child* of the process launched, so the search covers descendants. Scoped to the pid alone it finds two ports that answer nothing and gives up - which is what the first attempt did. `agy` never persists a refreshed token, so starting it cannot extend Google's hour: this was tested by backdating the `expiry` field and running `agy models` against it, and the file came back byte-identical, mtime included. That killed the simpler design, where a short run would have refreshed the credential and the remote path would have done the rest. And it is http, not https, wrapped in a `response` envelope the parser already unwrapped for other builds. Nothing outlives the fetch. The child is killed by the pid `forkpty` returned and then reaped - never matched by name, so a CLI the reader started themselves cannot be shut down by this, and would have been found by the first source long before the third ran. Verified by counting `agy` processes either side of a frame that used it: zero both times. Not built: CodexBar's other half, its own Google OAuth login writing credentials it owns to ~/.codexbar. That needs an interactive browser flow and Antigravity's OAuth client id and secret, and it buys nothing the third source does not already give. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- config.example.json | 2 + docs/usage.md | 29 ++- widgets/src/bin/usage.rs | 17 ++ widgets/src/bin/usage/antigravity.rs | 299 ++++++++++++++++++++++++--- 4 files changed, 315 insertions(+), 32 deletions(-) diff --git a/config.example.json b/config.example.json index cea3da4..75647a6 100644 --- a/config.example.json +++ b/config.example.json @@ -110,6 +110,8 @@ "plan_cost": {}, "_antigravity_remote_comment": "Antigravity publishes its quota two ways: a language server that runs inside the app, and Google, which serves the same summary on the endpoint the tier already comes from. The local one is preferred and this only decides whether the remote one may be asked when the app is shut. On by default - it is the same host and the same credential the tier request already uses. Turn it off and the quota is absent whenever Antigravity is closed; the tab then says so, and names this key.", "antigravity_remote": true, + "_antigravity_start_comment": "Whether the widget may start the `agy` CLI to read the quota it serves, when nothing else has one. On by default, and the only setting here that runs another program. It is your own CLI, already installed and signed in; it is started under a pseudo-terminal, killed by pid as soon as the reading is taken, and reaped, so nothing outlives the fetch; and a CLI you started yourself is found by the ordinary local probe long before this runs, so this can never shut one of yours down. Off means the quota lasts an hour past the last time Antigravity ran, which is the token's life.", + "antigravity_start": true, "_grok_ping_comment": "Grok is the only agent with no live quota: its figures come from the log its own CLI writes, so they move only when you use Grok on this machine. Turn grok_ping on to ask x.ai instead, using the token the CLI leaves in ~/.grok/auth.json. That also runs the Grok CLI once after a session goes quiet, which is what refreshes the token - without it the asking works until the token lapses and then silently stops. Off by default: a widget that reads should not start talking to a vendor, or starting somebody else's program, because it was launched.", "grok_ping": false, "grok_ping_minutes": 5 diff --git a/docs/usage.md b/docs/usage.md index 5cc3eb6..616abb1 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -352,8 +352,32 @@ and the heading says which was read: So the quota survives the app being closed — for as long as the token lasts, which is an hour, because the refresh token beside it is deliberately left alone. Running `agy` does not extend that: it refreshes in memory and writes -nothing back, verified by running `agy models` and finding the token file -byte-identical afterwards. +nothing back, verified by backdating the `expiry` field, running `agy models` +against it, and finding the file byte-identical afterwards, mtime included. + +**Three sources, cheapest first**, each of them optional: + +| order | source | costs | works when | +|---|---|---|---| +| 1 | a language server already running — the app's, or an `agy` you started | a socket read | Antigravity is open | +| 2 | Google, `retrieveUserQuotaSummary` | one request | within an hour of the last run | +| 3 | `agy`, started by the widget (`antigravity_start`) | a process, a few seconds | whenever the CLI is signed in | + +Being last is not being disfavoured — it is being expensive. The third is the +only one that always works, and the only one that runs another program. + +**The pty is not decoration.** Started with its input on `/dev/null` the CLI +opens ports that answer nothing for as long as you wait; given a pseudo-terminal +it serves the quota within seconds. Both were measured before this was written. +The port that answers also belonged to a *child* of the process launched, so +the search covers descendants — scoped to the pid alone it finds two ports that +answer nothing and gives up. + +Nothing outlives the fetch: the child is killed by the pid `forkpty` returned +and then reaped, never matched by name, so a CLI you started yourself can +never be shut down by this — and it would have been found by source 1 long +before source 3 ran. Verified by counting `agy` processes before and after a +frame that used it: zero either side. **Every step that can fail says which step it was**, on the tab and on `[+]`, because "no quota" covered four situations wanting different things from the @@ -954,6 +978,7 @@ Three settings, all off or hourly by default: | key | default | what it does | |---|---|---| +| `antigravity_start` | `true` | may the widget start the `agy` CLI to read the quota it serves, when nothing else has one. Started under a pty, killed by pid and reaped as soon as the reading is taken. Never touches a CLI you started | | `antigravity_remote` | `true` | may Antigravity's quota be asked of Google (`cloudcode-pa.googleapis.com/v1internal:retrieveUserQuotaSummary`) when no language server is running. Same host and same credential as the tier request. Off means no quota while the app is closed, and the tab says so | | `grok_ping` | `false` | GET `cli-chat-proxy.grok.com/v1/billing` with the bearer token the Grok CLI leaves in `~/.grok/auth.json`, **and** run `grok agent stdio` to refresh that token — once after a session goes quiet, and once when the token is within ten minutes of lapsing | | `grok_ping_minutes` | `5` | how often. The window moves over days, but the spend inside it moves while you work, so five minutes keeps the figure actionable; one small GET twelve times an hour | diff --git a/widgets/src/bin/usage.rs b/widgets/src/bin/usage.rs index 6b432a4..ed66fd7 100644 --- a/widgets/src/bin/usage.rs +++ b/widgets/src/bin/usage.rs @@ -1198,6 +1198,19 @@ struct Config { /// the quota whenever Antigravity is closed and spares nothing that the /// tier request has not already spent. antigravity_remote: bool, + /// Whether the widget may start the `agy` CLI to read the quota it + /// serves, when nothing else has one. + /// + /// On by default, and the only thing here that runs somebody else's + /// program. Three things make that defensible where Grok's equivalent + /// is off: it is the reader's own CLI, already installed and signed in; + /// it is started under a pseudo-terminal of ours, killed by pid the + /// moment the reading is taken, and reaped, so nothing outlives the + /// fetch; and a CLI the reader started themselves is found by the + /// ordinary local probe long before this runs, so this can never shut + /// one down. Turn it off and the quota lasts an hour past the last time + /// Antigravity ran, which is the token's life. + antigravity_start: bool, /// Minutes between those requests. Five, so the figure on screen is /// one a reader can act on: the window it reports moves over days, but /// the spend inside it moves while they work, and an hour-old reading @@ -1244,6 +1257,10 @@ fn read_config() -> Config { .get("antigravity_remote") .and_then(|v| v.as_bool()) .unwrap_or(true), + antigravity_start: raw + .get("antigravity_start") + .and_then(|v| v.as_bool()) + .unwrap_or(true), } } diff --git a/widgets/src/bin/usage/antigravity.rs b/widgets/src/bin/usage/antigravity.rs index 2d0d888..a6b0840 100644 --- a/widgets/src/bin/usage/antigravity.rs +++ b/widgets/src/bin/usage/antigravity.rs @@ -43,6 +43,186 @@ fn token_path() -> String { const CODE_ASSIST_API: &str = "https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist"; +/// How long to wait for a started `agy` to serve its quota. +/// +/// Measured at a few seconds on this machine: the ports open immediately +/// and answer nothing, and the quota service comes up behind them. So the +/// wait is on an endpoint that parses, never on a port that exists. +const AGY_READY: f64 = 25.0; +/// A started `agy` is expensive next to reading a socket, so its answer is +/// held far longer than the local probe's. +const AGY_TTL: f64 = 900.0; + +/// Where the CLI might be, in the order CodexBar looks. +fn agy_path() -> Option<String> { + if let Ok(named) = std::env::var("ANTIGRAVITY_CLI_PATH") { + if !named.is_empty() && std::path::Path::new(&named).exists() { + return Some(named); + } + } + let mut seen = Vec::new(); + if let Ok(path) = std::env::var("PATH") { + seen.extend(path.split(':').map(|dir| format!("{}/agy", dir))); + } + seen.push(under_home(".local/bin/agy")); + seen.push("/opt/homebrew/bin/agy".into()); + seen.push("/usr/local/bin/agy".into()); + seen.into_iter().find(|p| std::path::Path::new(p).exists()) +} + +/// Every listening TCP port belonging to `pid` or anything it started. +/// +/// Descendants matter: the port that answers is not always the process that +/// was launched. On this machine the quota came from a child, so a search +/// scoped to the pid alone finds two ports that answer nothing and gives up. +fn ports_under(pid: i32) -> Vec<u16> { + let mut family = vec![pid.to_string()]; + for entry in std::fs::read_dir("/proc").into_iter().flatten().flatten() { + let child = entry.file_name().to_string_lossy().to_string(); + if !child.chars().all(|c| c.is_ascii_digit()) { + continue; + } + let Ok(stat) = std::fs::read_to_string(format!("/proc/{}/stat", child)) else { + continue; + }; + // The command name sits in brackets and may itself contain spaces, + // so the fields after it are found from the last ')' rather than by + // splitting the whole line. + let Some(after) = stat.rsplit_once(')') else { continue }; + if after.1.split_whitespace().nth(1) == Some(&pid.to_string()) { + family.push(child); + } + } + let mut inodes = std::collections::HashSet::new(); + for who in &family { + for fd in std::fs::read_dir(format!("/proc/{}/fd", who)) + .into_iter() + .flatten() + .flatten() + { + let Ok(target) = std::fs::read_link(fd.path()) else { + continue; + }; + if let Some(rest) = target.to_string_lossy().strip_prefix("socket:[") { + inodes.insert(rest.trim_end_matches(']').to_string()); + } + } + } + let mut ports = Vec::new(); + for table in ["/proc/net/tcp", "/proc/net/tcp6"] { + let Ok(body) = std::fs::read_to_string(table) else { + continue; + }; + ports.extend(listening_ports(&body, &inodes)); + } + ports.sort_unstable(); + ports.dedup(); + ports +} + +/// Start `agy`, read the quota it serves, and stop it again. +/// +/// A pseudo-terminal is not decoration. Started with its input on +/// /dev/null the CLI opens ports that answer nothing for as long as you +/// wait; given a pty it serves the quota within seconds. Both were measured +/// here before this was written. +/// +/// The child is ours alone: it is killed by the pid we were handed and +/// nothing is matched by name, so a CLI the reader started themselves can +/// never be shut by this. That one is found by the ordinary local probe +/// long before this runs. +fn agy_quota() -> Result<Vec<serde_json::Value>, String> { + let Some(path) = agy_path() else { + return Err("no `agy` on this machine - install the Antigravity CLI, \ + or set ANTIGRAVITY_CLI_PATH" + .into()); + }; + let mut master: libc::c_int = 0; + // SAFETY: forkpty writes the master fd through the pointer and returns + // in both processes, 0 in the child. The child immediately execs and + // never returns, so nothing here runs twice. + let pid = unsafe { + libc::forkpty( + &mut master, + std::ptr::null_mut(), + std::ptr::null_mut(), + std::ptr::null_mut(), + ) + }; + if pid < 0 { + return Err("could not start `agy`: no pseudo-terminal available".into()); + } + if pid == 0 { + // SAFETY: child side. Replace this process with the CLI; if that + // fails there is nothing to return to, so it exits. + unsafe { + let c = std::ffi::CString::new(path.clone()).unwrap_or_default(); + let argv = [c.as_ptr(), std::ptr::null()]; + libc::execv(c.as_ptr(), argv.as_ptr()); + libc::_exit(127); + } + } + let out = agy_wait(pid, master); + // SAFETY: our own child, by pid. Reaped so it cannot be left a zombie + // for as long as the widget runs. + unsafe { + libc::kill(pid, libc::SIGKILL); + libc::waitpid(pid, std::ptr::null_mut(), 0); + libc::close(master); + } + out +} + +/// Poll a started CLI until its quota endpoint parses, or time runs out. +fn agy_wait(pid: i32, master: libc::c_int) -> Result<Vec<serde_json::Value>, String> { + // The pty has to be drained or the child blocks writing into a full + // buffer and never finishes starting. Nothing it prints is read for + // meaning - this widget does not scrape terminal output. + // SAFETY: setting O_NONBLOCK on a descriptor we own. + unsafe { + let flags = libc::fcntl(master, libc::F_GETFL); + libc::fcntl(master, libc::F_SETFL, flags | libc::O_NONBLOCK); + } + let mut scratch = [0u8; 8192]; + let deadline = now() + AGY_READY; + let mut ports_seen = false; + while now() < deadline { + // SAFETY: reading into our own buffer from our own descriptor. + loop { + let got = unsafe { + libc::read(master, scratch.as_mut_ptr() as *mut libc::c_void, scratch.len()) + }; + if got <= 0 { + break; + } + } + std::thread::sleep(Duration::from_millis(700)); + for port in ports_under(pid) { + ports_seen = true; + let url = format!("http://127.0.0.1:{}{}", port, ANTIGRAVITY_RPC); + let Some(got) = post_json(&url, &[("Content-Type", "application/json")], "{}", 4) + else { + continue; + }; + let body = if got["response"].as_object().is_some_and(|o| !o.is_empty()) { + &got["response"] + } else { + &got + }; + if let Some(groups) = body["groups"].as_array() { + if !groups.is_empty() { + return Ok(groups.clone()); + } + } + } + } + Err(if ports_seen { + "`agy` started but served no quota - it may not be signed in".into() + } else { + "`agy` started and opened no port".into() + }) +} + /// The same quota summary the language server answers, from Google. /// /// This was thought not to exist. The tab said so, and said it in the @@ -93,12 +273,10 @@ pub struct Data { quota: Vec<serde_json::Value>, /// Why there is no quota, when there is none. Empty when there is. quota_why: String, - /// True when the groups above came from Google rather than from the - /// language server on this machine. The two agree in shape and very - /// nearly in value, so nothing else can tell them apart - and a reader - /// wondering why there are numbers with the app shut deserves the - /// answer. - quota_remote: bool, + /// Which of the three answered. They agree in shape and very nearly in + /// value, so nothing else can tell them apart - and a reader wondering + /// why there are numbers with the app shut deserves the answer. + quota_from: From, /// How the CLI authenticated. Read once here rather than per frame: /// the tab is redrawn on every keypress and this is a file on disk. auth: String, @@ -258,6 +436,20 @@ impl Data { } } +/// Which source the quota on screen came from. +#[derive(Clone, Copy, Default, PartialEq)] +pub enum From { + /// A language server already running - the app's, or a CLI the reader + /// started. Nothing was launched and nothing left the machine. + #[default] + Local, + /// Google, on the endpoint the tier comes from. Works for as long as + /// the token lasts, which is an hour past the last run. + Google, + /// A CLI this widget started, read, and stopped again. + Agy, +} + /// Why the tier is missing, in the three ways it can be. #[derive(Clone, Copy, Default, PartialEq)] pub enum Missing { @@ -507,18 +699,26 @@ pub fn read(caches: &mut Caches, cfg: &Config) -> Data { // Google's is asked only when there is no server to ask, and is held far // longer - it is a record rather than a live meter, and unlike the local // one it is a request that leaves this machine. + // Three sources, cheapest first, and every one of them optional. + // + // A language server already running costs a socket read, so it is + // always tried. Google costs one request and works for as long as the + // token lasts. Starting the CLI costs a process and several seconds, so + // it is last however preferred it is - being last is not being + // disfavoured, it is being expensive. if d.quota.is_empty() { + let mut why = String::new(); match remote_token(cfg.antigravity_remote) { - // Decided here, so it survives a held failure and is the same - // sentence on every frame until the thing it names changes. - Err(why) => d.quota_why = why, + // Decided before the cache, so it survives a held failure and + // is the same sentence on every frame until it changes. + Err(said) => why = said, Ok(access) => { - let mut why = String::new(); + let mut asked = String::new(); let got = cached(caches, "antigravity-remote", PLAN_TTL, || { match remote_quota(&access) { Ok(groups) => Some(serde_json::Value::Array(groups)), Err(said) => { - why = said; + asked = said; None } } @@ -527,18 +727,48 @@ pub fn read(caches: &mut Caches, cfg: &Config) -> Data { match got { Some(groups) => { d.quota = groups; - d.quota_remote = true; + d.quota_from = From::Google; } None => { - d.quota_why = if why.is_empty() { + why = if asked.is_empty() { "Google did not answer, and the refusal is still held".to_string() } else { - why + asked } } } } } + if d.quota.is_empty() && cfg.antigravity_start { + let mut asked = String::new(); + let got = cached(caches, "antigravity-agy", AGY_TTL, || match agy_quota() { + Ok(groups) => Some(serde_json::Value::Array(groups)), + Err(said) => { + asked = said; + None + } + }) + .and_then(|got| got.as_array().cloned()); + match got { + Some(groups) => { + d.quota = groups; + d.quota_from = From::Agy; + why.clear(); + } + // Both failed. The CLI's reason is the later and more + // specific one, so it wins - "Google refused the token" and + // "`agy` is not signed in" are the same fault said twice, + // and the second names what to do. + None => { + if !asked.is_empty() { + why = asked; + } + } + } + } + if d.quota.is_empty() { + d.quota_why = why; + } } let mut files: Vec<String> = std::fs::read_dir(format!("{}/conversations", antigravity_dir())) .into_iter() @@ -619,7 +849,7 @@ pub fn lanes(d: &Data) -> Vec<Lane> { /// sitting at 0% - they are real limits, not padding, and are left in. fn antigravity_quota_rows( groups: &[serde_json::Value], - remote: bool, + from: From, w: usize, p: &Palette, ) -> Vec<String> { @@ -629,15 +859,24 @@ fn antigravity_quota_rows( // The long form names where the number comes from, which matters here // more than elsewhere; the short one still says it is not this machine's // own tally. Shortened before it can clip, as the other headers are. - let mut note = if remote { - " · account-wide, from Google - the app is not running" - } else { - " · account-wide, from the local language server" + let (mut note, short, tiny) = match from { + From::Google => ( + " · account-wide, from Google - the app is not running", + " · from Google", + " · remote", + ), + From::Agy => ( + " · account-wide, from `agy`, started for this reading", + " · from `agy`", + " · agy", + ), + From::Local => ( + " · account-wide, from the local language server", + " · from the local server", + " · local", + ), }; - for shorter in [ - if remote { " · from Google" } else { " · from the local server" }, - if remote { " · remote" } else { " · local" }, - ] { + for shorter in [short, tiny] { if 13 + "live".len() + note.chars().count() <= w.saturating_sub(1) { break; } @@ -834,7 +1073,7 @@ fn antigravity_activity(d: &Data, w: usize, p: &Palette) -> Vec<String> { } fn antigravity_body(d: &Data, w: usize, p: &Palette) -> Vec<String> { - let mut rows = antigravity_quota_rows(&d.quota, d.quota_remote, w, p); + let mut rows = antigravity_quota_rows(&d.quota, d.quota_from, w, p); if d.live.is_none() { rows.extend( wrap_text(&tier_note_said(d.tier_why, &d.tier_said), w.saturating_sub(4).max(20)) @@ -1145,7 +1384,7 @@ mod tests { ("Gemini 3 Pro", "5h", 0.996), ("Claude Sonnet 4.5", "weekly", 1.0), ]), - false, + From::Local, 96, &p, ); @@ -1164,7 +1403,7 @@ mod tests { let p = palette(); let rows = antigravity_quota_rows( &[serde_json::json!({"displayName": "GPT", "buckets": []})], - false, + From::Local, 96, &p, ); @@ -1177,9 +1416,9 @@ mod tests { fn the_source_note_shortens_before_it_can_clip() { let p = palette(); let quota = groups(&[("Gemini 3 Pro", "weekly", 0.5)]); - let wide = antigravity_quota_rows("a, false, 120, &p)[0].clone(); - let narrow = antigravity_quota_rows("a, false, 60, &p)[0].clone(); - let tight = antigravity_quota_rows("a, false, 30, &p)[0].clone(); + let wide = antigravity_quota_rows("a, From::Local, 120, &p)[0].clone(); + let narrow = antigravity_quota_rows("a, From::Local, 60, &p)[0].clone(); + let tight = antigravity_quota_rows("a, From::Local, 30, &p)[0].clone(); assert!(wide.contains("from the local language server")); assert!(narrow.contains("from the local server")); assert!(tight.contains("local")); @@ -1309,7 +1548,7 @@ mod tests { let p = palette(); let cfg = Config::default(); let d = Data { - quota_remote: false, + quota_from: From::Local, quota_why: String::new(), quota: groups(&[ ("Gemini 3 Pro", "weekly", 0.25), From 08eb73b7189da627cbe041418c4a09ad3cfb175e Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Wed, 26 Aug 2026 17:12:41 +0800 Subject: [PATCH 144/147] docs: a README that points, and pages that point back The README had grown to carry three audiences at once: someone deciding whether to run any of this, someone configuring it, and someone changing it. The third is the largest and the least urgent, so it moves out. `docs/design.md` takes the conventions - width before padding, never truncate a hint, measure contrast rather than eyeball it, say what a number means. They are for whoever changes a widget, and each was paid for by something that shipped wrong first. `docs/internals.md` takes `toys-core`, the chart helpers, the two braille canvases that are deliberately not shared, and what `widgets/tests/check.rs` reads the sources for. It says which rule each check is defending, so the two pages are the same subject from either end. `docs/README.md` is new: one line per widget, taken from that page's own first sentence rather than written twice, and the four repository pages under it. `matrix` is listed as having no page on purpose - a document explaining that it computes nothing would be the joke explained. Every page under docs/ now opens with a link back to that index, which none of them had. The widget table in the README still links straight to each page, so nothing got further away. README is 209 lines down to 164, and nothing was deleted - the two new pages are where it went. Every relative link in every markdown file was resolved against the filesystem; all 60 land. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- README.md | 89 +++++++++-------------------------- docs/README.md | 36 ++++++++++++++ docs/building-herdr-panels.md | 2 + docs/clocks.md | 2 + docs/deployments.md | 2 + docs/design.md | 42 +++++++++++++++++ docs/github.md | 2 + docs/herdr-panes.md | 2 + docs/internals.md | 39 +++++++++++++++ docs/latency.md | 2 + docs/linear.md | 2 + docs/link.md | 2 + docs/netwatch.md | 2 + docs/port-decisions.md | 2 + docs/ports.md | 2 + docs/pr.md | 2 + docs/start.md | 2 + docs/tailnet.md | 2 + docs/usage.md | 2 + 19 files changed, 169 insertions(+), 67 deletions(-) create mode 100644 docs/README.md create mode 100644 docs/design.md create mode 100644 docs/internals.md diff --git a/README.md b/README.md index 7a3fe16..b5da4b5 100644 --- a/README.md +++ b/README.md @@ -118,35 +118,20 @@ configuration at all. cannot work without its tool says so rather than drawing an empty pane; and **none needs root** -## Design - -A few conventions hold across all of them, and the reasoning is worth knowing -before changing one: - -- **Spend extra width on more content, not padding.** Widgets add columns as a - pane grows and drop them as it shrinks, rather than truncating. -- **Never truncate a key hint.** Footers wrap across as many lines as they need - and never split a hint, because `[±]25` teaches a key that does not exist. -- **A directional glyph points the way the thing goes.** `▲`/`▼` mark which - half of a diverging chart a series occupies — `▲ opened` above the baseline, - `▼ merged` below it. `↑`/`↓` mean upload and download. Where both meanings - meet, in `netwatch`'s chart, the halves are arranged so they agree: tx - above and rx below, because a `↓` label over a line that climbs asks the - reader to hold two directions at once, and they will believe the arrow. -- **Measure contrast, do not eyeball it.** Every colour that draws text clears - WCAG AA against both the terminal background *and* the selected-row tint, - with the measured ratios recorded beside the definitions. -- **Say what a number means when it is not obvious.** Counters that reset with - a daemon, durations that predate the process, aggregates that hide their - outliers — each is labelled rather than left to mislead. -- **Never show a stale figure under a fresh label.** Change a setting and the - numbers it governs shimmer until real ones land, rather than sitting there - looking current. The same rule kills silent truncation: a chart that cannot - fit its window says `54d of 90d`, and a token missing a scope is named rather - than left to quietly undercount. -- **Optional enhancements, never requirements.** The clipboard goes through - OSC 52 so it survives SSH; Herdr toasts and `sudo`-gated data are added where - available and skipped silently where not. +## Documentation + +Every widget has a page of its own — what it shows, where each number comes +from, every key it answers to, and the settings it reads. They are linked +from the table above, and listed together in [`docs/`](docs/README.md). + +Four pages are about the repository rather than a widget: + +| | | +|---|---| +| [Design conventions](docs/design.md) | the rules every widget holds to, and why each was paid for | +| [Internals](docs/internals.md) | `toys-core`, the chart helpers, and what `cargo test` checks that a compiler cannot | +| [Port decisions](docs/port-decisions.md) | what the Rust port changed from the Python and why — the answer to most questions beginning *why does this key do that* | +| [Building Herdr panels](docs/building-herdr-panels.md) | resize semantics, focus, and the layout mistakes worth skipping | ## Bundled skill @@ -163,44 +148,14 @@ in Linear: <https://linear.app/stealth-company/project/terminal-toys-e829b47d84b canonical list either way, so a feature that looks missing may already be filed there with a reason. -## Building your own - -[`docs/building-herdr-panels.md`](docs/building-herdr-panels.md) collects what -was learned building these against Herdr: resize semantics, focus, detecting -what a pane is running, notification gating, and the layout mistakes worth -skipping. - -These began as Python and were ported to Rust widget by widget; -[`docs/port-decisions.md`](docs/port-decisions.md) records what the port -changed and why — the keys it consolidated, the three it renamed, the charts -it draws differently, and what was built afterwards on the Rust side alone. It -is history now rather than a comparison, but it is the answer to most -questions beginning *why does this key do that*. - -`cargo test` from the root runs each widget's tests plus -`widgets/tests/check.rs`, which reads the sources and fails on a poller that -dies without saying why, a footer or `--help` line naming a key nothing -answers, a hint missing from the widget's doc, a config key read but never -documented in `config.example.json` — or documented there and never read, or -read with no fallback behind it — and a colour that draws text on the -selected-row tint below WCAG AA. - -`toys-core` holds the shared pieces — terminal sizing, a full-frame `draw()`, -24-bit colour, a green→amber→red `heat()` ramp, `seg()` for clipping coloured -text to a cell budget, `pack_hints()` for wrapping footers, `follow()` for a -window that keeps a cursor in view, non-blocking `Keyboard` input with -arrow-key decoding, and `clipboard()` over OSC 52. - -The chart helpers are worth knowing before drawing anything new: `vbars()` and -its mirror `vbars_down()` (pair them on a shared scale for a diverging chart), -`stacked_bar()` for proportions, `meter()` for a gauge, and `skeleton()` for -the shimmer that stands in for a figure still being fetched. - -Braille line charts are not among them. `latency` and `link` each keep their -own `braille_canvas`, and the two are not the same function: latency's series -carries the gaps a ping can leave, and link's is told how many slots the axis -holds, so that a session younger than the chart takes its own share of the -width rather than being stretched across all of it. +## Contributing + +`cargo test` from the root is the gate: each widget's own tests, plus +[`widgets/tests/check.rs`](widgets/tests/check.rs), which reads the sources +and fails on the things a compiler cannot see — a poller that dies without +saying why, a key hinted but unanswered, a setting read but undocumented, a +colour below WCAG AA on a selected row. [Internals](docs/internals.md) +explains what each check is defending. ## License diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..edaaddb --- /dev/null +++ b/docs/README.md @@ -0,0 +1,36 @@ +# Documentation + +[← terminal-toys](../README.md) + +One page per widget: what it shows, where every number on it comes from, +each key it answers to, and the settings it reads. + +## Widgets + +| | | +|---|---| +| [`start`](start.md) | The front door: every widget, what it does, and whether it will work on this machine. | +| [`latency`](latency.md) | Continuous latency to a list of hosts, with the statistics that actually explain a bad connection. | +| [`deployments`](deployments.md) | Vercel deployments — how they are going over time, not just what shipped last. | +| [`tailnet`](tailnet.md) | Tailscale peers, and — the part plain `tailscale status` buries — *how* you are reaching each one. | +| [`herdr-panes`](herdr-panes.md) | Everything running under [Herdr](https://herdr.dev), across every workspace — and one keypress to get to any of it. | +| [`github`](github.md) | Pull requests across every org you work in — not what shipped, but whether work is actually moving. | +| [`pr`](pr.md) | The pull requests you have to follow up on, and a dashboard for whichever one you open. | +| [`linear`](linear.md) | Linear across every team at once — what is outstanding, which cycles are running, and whether issues are being closed faster than they arrive. | +| [`usage`](usage.md) | How much the coding agents on this machine have actually been used — one tab per agent, from each agent's own local state, plus a live quota reading for the four that publish one and a subscription for the five that do. | +| [`ports`](ports.md) | What is listening on this machine, what started it, and who can reach it. | +| [`netwatch`](netwatch.md) | Which processes are using the network, how much they have used, and how fast they are going right now. | +| [`link`](link.md) | How good the connection is between this machine and whoever is connected to it — measured, not probed. | +| [`clocks`](clocks.md) | This server's clock, the clocks counting down, a pomodoro, and everyone else's clock — the four things you need to know about time while working across timezones. | + +`matrix` has no page. It computes nothing on purpose, and a document +saying so at length would be the joke explained. + +## About the repository + +| | | +|---|---| +| [Design](design.md) | The rules every widget holds to, and what each one cost to learn. | +| [Internals](internals.md) | `toys-core`, the chart helpers, and what `cargo test` checks that a compiler cannot. | +| [Port decisions](port-decisions.md) | What the Rust port changed from the Python, and why. | +| [Building herdr panels](building-herdr-panels.md) | Driving these from Herdr: resize semantics, focus, and the layout mistakes worth skipping. | diff --git a/docs/building-herdr-panels.md b/docs/building-herdr-panels.md index ea61dec..6a391f9 100644 --- a/docs/building-herdr-panels.md +++ b/docs/building-herdr-panels.md @@ -1,5 +1,7 @@ # Building panels for Herdr +[← all docs](README.md) + Notes from building the widgets in this repo against [Herdr](https://herdr.dev), a terminal multiplexer for coding agents. None of this is in `herdr --skill`, which documents the CLI surface; this is what the surface does not tell you. diff --git a/docs/clocks.md b/docs/clocks.md index 15fd0fc..b24173d 100644 --- a/docs/clocks.md +++ b/docs/clocks.md @@ -1,5 +1,7 @@ # `clocks` +[← all docs](README.md) + This server's clock, the clocks counting down, a pomodoro, and everyone else's clock — the four things you need to know about time while working across timezones. diff --git a/docs/deployments.md b/docs/deployments.md index 3500919..2588d2f 100644 --- a/docs/deployments.md +++ b/docs/deployments.md @@ -1,5 +1,7 @@ # `deployments` +[← all docs](README.md) + Vercel deployments — how they are going over time, not just what shipped last. ``` diff --git a/docs/design.md b/docs/design.md new file mode 100644 index 0000000..98b8911 --- /dev/null +++ b/docs/design.md @@ -0,0 +1,42 @@ +# Design conventions + +[← all docs](README.md) + +A few rules hold across all fourteen widgets. They are here rather than in +the README because they are for whoever changes one, not for whoever runs +one — and because each of them was paid for by something that shipped +wrong first. + +- **Spend extra width on more content, not padding.** Widgets add columns as a + pane grows and drop them as it shrinks, rather than truncating. +- **Never truncate a key hint.** Footers wrap across as many lines as they need + and never split a hint, because `[±]25` teaches a key that does not exist. +- **A directional glyph points the way the thing goes.** `▲`/`▼` mark which + half of a diverging chart a series occupies — `▲ opened` above the baseline, + `▼ merged` below it. `↑`/`↓` mean upload and download. Where both meanings + meet, in `netwatch`'s chart, the halves are arranged so they agree: tx + above and rx below, because a `↓` label over a line that climbs asks the + reader to hold two directions at once, and they will believe the arrow. +- **Measure contrast, do not eyeball it.** Every colour that draws text clears + WCAG AA against both the terminal background *and* the selected-row tint, + with the measured ratios recorded beside the definitions. +- **Say what a number means when it is not obvious.** Counters that reset with + a daemon, durations that predate the process, aggregates that hide their + outliers — each is labelled rather than left to mislead. +- **Never show a stale figure under a fresh label.** Change a setting and the + numbers it governs shimmer until real ones land, rather than sitting there + looking current. The same rule kills silent truncation: a chart that cannot + fit its window says `54d of 90d`, and a token missing a scope is named rather + than left to quietly undercount. +- **Optional enhancements, never requirements.** The clipboard goes through + OSC 52 so it survives SSH; Herdr toasts and `sudo`-gated data are added where + available and skipped silently where not. + +## Where these are enforced + +Four of them are not prose. `cargo test` runs +[`widgets/tests/check.rs`](../widgets/tests/check.rs), which reads the +sources and fails on a footer hint naming a key nothing answers, a hint +missing from the widget's doc, a config key read but never documented, +and a colour drawing text on the selected-row tint below WCAG AA. See +[internals](internals.md#the-checks). diff --git a/docs/github.md b/docs/github.md index 3406cfc..68a28c3 100644 --- a/docs/github.md +++ b/docs/github.md @@ -1,5 +1,7 @@ # `github` +[← all docs](README.md) + Pull requests across every org you work in — not what shipped, but whether work is actually moving. diff --git a/docs/herdr-panes.md b/docs/herdr-panes.md index f06d855..412b8de 100644 --- a/docs/herdr-panes.md +++ b/docs/herdr-panes.md @@ -1,5 +1,7 @@ # `herdr-panes` +[← all docs](README.md) + Everything running under [Herdr](https://herdr.dev), across every workspace — and one keypress to get to any of it. diff --git a/docs/internals.md b/docs/internals.md new file mode 100644 index 0000000..9445586 --- /dev/null +++ b/docs/internals.md @@ -0,0 +1,39 @@ +# Internals + +[← all docs](README.md) + +What is shared between the widgets, and what the test suite checks that a +compiler cannot. For the rules these implement, see +[design conventions](design.md). + +## The checks + +`cargo test` from the root runs each widget's tests plus +`widgets/tests/check.rs`, which reads the sources and fails on a poller that +dies without saying why, a footer or `--help` line naming a key nothing +answers, a hint missing from the widget's doc, a config key read but never +documented in `config.example.json` — or documented there and never read, or +read with no fallback behind it — and a colour that draws text on the +selected-row tint below WCAG AA. + +Every one of them exists because something shipped broken and looked, on +screen, exactly like "there is no data". + +## `toys-core` + +`toys-core` holds the shared pieces — terminal sizing, a full-frame `draw()`, +24-bit colour, a green→amber→red `heat()` ramp, `seg()` for clipping coloured +text to a cell budget, `pack_hints()` for wrapping footers, `follow()` for a +window that keeps a cursor in view, non-blocking `Keyboard` input with +arrow-key decoding, and `clipboard()` over OSC 52. + +The chart helpers are worth knowing before drawing anything new: `vbars()` and +its mirror `vbars_down()` (pair them on a shared scale for a diverging chart), +`stacked_bar()` for proportions, `meter()` for a gauge, and `skeleton()` for +the shimmer that stands in for a figure still being fetched. + +Braille line charts are not among them. `latency` and `link` each keep their +own `braille_canvas`, and the two are not the same function: latency's series +carries the gaps a ping can leave, and link's is told how many slots the axis +holds, so that a session younger than the chart takes its own share of the +width rather than being stretched across all of it. diff --git a/docs/latency.md b/docs/latency.md index 62ee352..491aeed 100644 --- a/docs/latency.md +++ b/docs/latency.md @@ -1,5 +1,7 @@ # `latency` +[← all docs](README.md) + Continuous latency to a list of hosts, with the statistics that actually explain a bad connection. diff --git a/docs/linear.md b/docs/linear.md index 0a12b4f..eacf460 100644 --- a/docs/linear.md +++ b/docs/linear.md @@ -1,5 +1,7 @@ # `linear` +[← all docs](README.md) + Linear across every team at once — what is outstanding, which cycles are running, and whether issues are being closed faster than they arrive. diff --git a/docs/link.md b/docs/link.md index 9d0147a..b597f25 100644 --- a/docs/link.md +++ b/docs/link.md @@ -1,5 +1,7 @@ # `link` +[← all docs](README.md) + How good the connection is between this machine and whoever is connected to it — measured, not probed. diff --git a/docs/netwatch.md b/docs/netwatch.md index 68c69e2..23e8671 100644 --- a/docs/netwatch.md +++ b/docs/netwatch.md @@ -1,5 +1,7 @@ # `netwatch` +[← all docs](README.md) + Which processes are using the network, how much they have used, and how fast they are going right now. diff --git a/docs/port-decisions.md b/docs/port-decisions.md index 41b222d..f5d2cc3 100644 --- a/docs/port-decisions.md +++ b/docs/port-decisions.md @@ -1,5 +1,7 @@ # What the port changed, and why +[← all docs](README.md) + For the length of the port every widget here existed twice, and the Rust was never a transliteration: some of it answers differently on purpose. Telling *on purpose* from *a defect the port introduced* was the whole point of the diff --git a/docs/ports.md b/docs/ports.md index cf15008..55e5cb7 100644 --- a/docs/ports.md +++ b/docs/ports.md @@ -1,5 +1,7 @@ # `ports` +[← all docs](README.md) + What is listening on this machine, what started it, and who can reach it. ``` diff --git a/docs/pr.md b/docs/pr.md index ac093fb..9ea1f90 100644 --- a/docs/pr.md +++ b/docs/pr.md @@ -1,5 +1,7 @@ # `pr` +[← all docs](README.md) + The pull requests you have to follow up on, and a dashboard for whichever one you open. diff --git a/docs/start.md b/docs/start.md index 65dbc80..35fab39 100644 --- a/docs/start.md +++ b/docs/start.md @@ -1,5 +1,7 @@ # `start` +[← all docs](README.md) + The front door: every widget, what it does, and whether it will work on this machine. diff --git a/docs/tailnet.md b/docs/tailnet.md index c64c8d1..4aa9aaa 100644 --- a/docs/tailnet.md +++ b/docs/tailnet.md @@ -1,5 +1,7 @@ # `tailnet` +[← all docs](README.md) + Tailscale peers, and — the part plain `tailscale status` buries — *how* you are reaching each one. diff --git a/docs/usage.md b/docs/usage.md index 616abb1..4293954 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -1,5 +1,7 @@ # `usage` +[← all docs](README.md) + How much the coding agents on this machine have actually been used — one tab per agent, from each agent's own local state, plus a live quota reading for the four that publish one and a subscription for the five that do. From ad75b06129391583b39e13d9e1ab66ca2fefbd50 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Wed, 26 Aug 2026 17:34:07 +0800 Subject: [PATCH 145/147] ci: CodeQL for Rust, in advanced setup, and why it cannot run yet Default setup was still scanning `python` in a repository whose last .py file was deleted four days ago - which is to say scanning nothing. It cannot be pointed at Rust either: its API accepts actions, c-cpp, csharp, go, java-kotlin, javascript-typescript, python, ruby and swift, and answers 422 for `rust`. Advanced setup can. Rust is a builtin language in github/codeql-action, public preview since CodeQL 2.22.1, and it needs no build step - the extractor reads the sources, which is how the action's own Rust check runs. `actions` is scanned beside it, because this repository now publishes a release workflow that handles a tag and writes to the releases API. The action is pinned by sha, as the release workflow pins its own, with `security-extended` rather than the default suite: fourteen binaries that read a machine's state and hold three API tokens are worth the extra queries. It does not run yet, and the file says so at the top rather than looking broken. GitHub disables advanced workflows while default setup is on, and default setup here is pinned by an enforced organisation configuration, so the repository cannot turn it off - the API answers "controlled by organization administrators". Detaching the repository from that configuration would do it and is the wrong move: the same configuration enforces secret scanning, push protection, Dependabot alerts and private vulnerability reporting. Giving up push protection on a public repository whose first rule is that secrets never enter the tree, in exchange for static analysis, is a bad bargain. A sibling configuration with only code_scanning_default_setup disabled, attached to this repository alone, costs nothing and is the thing to do - it needs an organisation admin, so it is not done here. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- .github/workflows/codeql.yml | 76 ++++++++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 .github/workflows/codeql.yml diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml new file mode 100644 index 0000000..57e1212 --- /dev/null +++ b/.github/workflows/codeql.yml @@ -0,0 +1,76 @@ +# CodeQL, in advanced setup rather than default. +# +# Default setup cannot do this. Its API accepts only actions, c-cpp, csharp, +# go, java-kotlin, javascript-typescript, python, ruby and swift - `rust` is +# refused with a 422 - so the repository was still scanning `python` months +# after the last .py file was deleted, which is to say scanning nothing. +# +# Rust support is public preview, from CodeQL 2.22.1. It needs no build step: +# the extractor reads the sources, so there is no `autobuild` here and no +# `build-mode`, which is how github/codeql-action's own Rust check runs. +# +# `actions` is scanned alongside it, and is not padding - this repository +# publishes a release workflow that handles a tag and writes to the releases +# API, and that file is exactly the kind of thing the actions queries read. +# +# THIS FILE DOES NOT RUN YET, and that is not a mistake in it. GitHub disables +# advanced workflows while default setup is on, and default setup here is +# pinned by an enforced organisation configuration ("GitHub recommended"), +# so the repository cannot turn it off: the API answers 422, "controlled by +# organization administrators". +# +# The fix is not to detach this repository from that configuration. The same +# configuration enforces secret scanning, push protection, Dependabot alerts +# and private vulnerability reporting, and this repository is public with +# "secrets never enter the tree" as its first rule - trading push protection +# for Rust analysis would be a bad bargain. What is needed is a sibling +# configuration, identical but with code_scanning_default_setup disabled, +# attached to this repository alone. Then this file starts working and +# nothing else is given up. +name: CodeQL + +on: + push: + branches: [main] + pull_request: + branches: [main] + schedule: + # Weekly, as default setup had it. Monday, early, off the hour so it is + # not queued behind everything else that asks for midnight. + - cron: "17 4 * * 1" + +permissions: {} + +jobs: + analyze: + name: Analyze ${{ matrix.language }} + runs-on: ubuntu-24.04 + timeout-minutes: 30 + permissions: + # The three this needs and nothing else: read the code, write the + # findings, and read Actions metadata for the workflow scan. + contents: read + security-events: write + actions: read + strategy: + fail-fast: false + matrix: + language: [rust, actions] + steps: + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + with: + persist-credentials: false + + - name: Initialise CodeQL + uses: github/codeql-action/init@486fec2a3ea2626afcd8c7e9208b4f515078dd7e # codeql-bundle-v2.26.4 + with: + languages: ${{ matrix.language }} + # security-extended over the default suite. This is fourteen + # binaries that read a machine's own state and hold three API + # tokens; the extra queries are the point of running this at all. + queries: security-extended + + - name: Analyse + uses: github/codeql-action/analyze@486fec2a3ea2626afcd8c7e9208b4f515078dd7e # codeql-bundle-v2.26.4 + with: + category: "/language:${{ matrix.language }}" From d981e01c4f2f29e5d815e9e11f575fad3155e6b3 Mon Sep 17 00:00:00 2001 From: wiiiimm <email@wiiiimm.codes> Date: Wed, 26 Aug 2026 18:04:22 +0800 Subject: [PATCH 146/147] ci: park CodeQL's triggers until the org config allows the upload It ran, and it worked. The Rust extractor read the whole crate and built a database; only the submission was refused - "CodeQL analyses from advanced configurations cannot be processed when the default setup is enabled", which is the block this file already documents. That left a check that can only ever be red, on the PR now and on every push to main after the port lands. A check that cannot go green teaches nothing and trains people to ignore the colour, so the automatic triggers are parked and written down verbatim in the comment beside them, ready to be pasted back. `workflow_dispatch` stays, so it can still be run by hand to confirm the analysis end to end. Nothing about the analysis is in doubt - it is the one part already proven. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JSw8PExXQWsc9oP79JWFe1 --- .github/workflows/codeql.yml | 27 +++++++++++++++++++-------- 1 file changed, 19 insertions(+), 8 deletions(-) diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index 57e1212..64bdd64 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -29,15 +29,26 @@ # nothing else is given up. name: CodeQL +# Manual only, until the organisation configuration above is sorted. +# +# This ran once on push and did exactly what it should: the Rust extractor +# read the whole crate and produced a database, and then the upload was +# refused - "CodeQL analyses from advanced configurations cannot be +# processed when the default setup is enabled". The analysis is fine; the +# submission is what is blocked. +# +# A check that can only ever be red teaches nothing, and would be red on +# every push to main after the port lands. So the automatic triggers are +# parked here, in the order they should be restored: +# +# push: { branches: [main] } +# pull_request: { branches: [main] } +# schedule: [ { cron: "17 4 * * 1" } ] # weekly, as default setup had +# +# Put those back the moment the repository is attached to a configuration +# with code_scanning_default_setup disabled, and delete this comment. on: - push: - branches: [main] - pull_request: - branches: [main] - schedule: - # Weekly, as default setup had it. Monday, early, off the hour so it is - # not queued behind everything else that asks for midnight. - - cron: "17 4 * * 1" + workflow_dispatch: permissions: {} From e1e917f93c48a50698963150714e968a9e177584 Mon Sep 17 00:00:00 2001 From: Cursor Agent <cursoragent@cursor.com> Date: Wed, 26 Aug 2026 10:32:16 +0000 Subject: [PATCH 147/147] fix: restore the terminal on signal and reject a broken refresh MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Ctrl-C skipped Keyboard Drop, so the shell lost echo, and a negative refresh panicked the poller after the first read — the same silence a dead thread leaves. The handler now restores termios with async-signal-safe calls, poll_secs clamps every wait, an empty system_ports list stays empty, and a widget killed by a signal is no longer reported as success. Co-authored-by: wiiiimm <email@wiiiimm.codes> --- core/src/lib.rs | 95 ++++++++++++++++++++++++++++++++-- widgets/src/bin/clocks.rs | 17 +++++- widgets/src/bin/deployments.rs | 4 +- widgets/src/bin/github.rs | 3 +- widgets/src/bin/herdr-panes.rs | 4 +- widgets/src/bin/linear.rs | 23 +++++++- widgets/src/bin/link.rs | 9 +++- widgets/src/bin/netwatch.rs | 15 ++++-- widgets/src/bin/ports.rs | 54 ++++++++++++++++--- widgets/src/bin/pr.rs | 4 +- widgets/src/bin/start.rs | 39 +++++++++++++- widgets/src/bin/tailnet.rs | 6 +-- widgets/src/bin/usage.rs | 4 +- 13 files changed, 242 insertions(+), 35 deletions(-) diff --git a/core/src/lib.rs b/core/src/lib.rs index 268696a..df5d8be 100644 --- a/core/src/lib.rs +++ b/core/src/lib.rs @@ -22,8 +22,9 @@ //! Python behaviour rather than the more idiomatic Rust one. use std::io::{Read, Write}; -use std::os::unix::fs::PermissionsExt; use std::os::fd::AsRawFd; +use std::os::unix::fs::PermissionsExt; +use std::sync::atomic::{AtomicBool, AtomicI32, Ordering}; pub const HIDE: &str = "\x1b[?25l"; pub const SHOW: &str = "\x1b[?25h"; @@ -157,10 +158,55 @@ pub fn setup() { flush(); } -extern "C" fn handle_signal(_sig: libc::c_int) { - out(&format!("{}{}{}{}", SHOW, RST, CLEAR, HOME)); - flush(); - std::process::exit(0); +/// The bytes `handle_signal` writes. Built as a constant so the handler +/// never formats, allocates, or takes the stdout lock - any of which can +/// deadlock if the signal arrives while `draw` is already writing. +const SCREEN_RESTORE: &str = concat!("\x1b[?25h", "\x1b[0m", "\x1b[2J", "\x1b[H"); + +/// Saved cbreak settings, written by `Keyboard` and read by the handler. +/// +/// The flag is published after the struct, so a handler that sees it true +/// sees a complete copy. A mutex is not an option: locking one from a +/// signal handler is how the previous version could hang instead of +/// restoring the terminal. +static TERM_FD: AtomicI32 = AtomicI32::new(-1); +static HAS_TERMIOS: AtomicBool = AtomicBool::new(false); +static mut SAVED_IOS: libc::termios = unsafe { std::mem::zeroed() }; + +fn remember_termios(fd: i32, ios: libc::termios) { + unsafe { + SAVED_IOS = ios; + } + TERM_FD.store(fd, Ordering::Release); + HAS_TERMIOS.store(true, Ordering::Release); +} + +fn forget_termios() { + HAS_TERMIOS.store(false, Ordering::Release); +} + +/// Restore the saved termios and the screen, using only async-signal-safe +/// calls, then `_exit`. `process::exit` runs atexit handlers and can +/// deadlock on the same stdout lock `draw` holds; Drop on `Keyboard` never +/// runs either way, so the handler has to give the shell its echo back. +extern "C" fn handle_signal(sig: libc::c_int) { + if HAS_TERMIOS.load(Ordering::Acquire) { + let fd = TERM_FD.load(Ordering::Acquire); + if fd >= 0 { + let ios = unsafe { SAVED_IOS }; + unsafe { + libc::tcsetattr(fd, libc::TCSANOW, &ios); + } + } + } + unsafe { + libc::write( + libc::STDOUT_FILENO, + SCREEN_RESTORE.as_ptr() as *const libc::c_void, + SCREEN_RESTORE.len(), + ); + libc::_exit(128 + sig); + } } /// Put the terminal back the way it was found. @@ -265,6 +311,22 @@ pub fn cfg_f64(cfg: &serde_json::Value, key: &str, fallback: f64) -> f64 { cfg.get(key).and_then(|v| v.as_f64()).unwrap_or(fallback) } +/// A wait that `Duration::from_secs_f64` will accept. +/// +/// A missing or malformed setting falls back. A value that is finite and +/// positive is kept. Anything else - negative, NaN, infinite - used to +/// panic the poller after the first read, which froze the pane on its +/// initial data with no error, the same silence a dead thread leaves. +pub fn poll_secs(value: f64, fallback: f64) -> f64 { + if value.is_finite() && value > 0.0 { + value + } else if fallback.is_finite() && fallback > 0.0 { + fallback + } else { + 1.0 + } +} + pub fn cfg_usize(cfg: &serde_json::Value, key: &str, fallback: usize) -> usize { cfg.get(key) .and_then(|v| v.as_u64()) @@ -929,6 +991,7 @@ impl Keyboard { raw.c_cc[libc::VMIN] = 0; raw.c_cc[libc::VTIME] = 0; unsafe { libc::tcsetattr(fd, libc::TCSANOW, &raw) }; + remember_termios(fd, saved); Some(saved) } else { None @@ -944,6 +1007,7 @@ impl Keyboard { pub fn restore(&mut self) { if let Some(saved) = self.saved.take() { + forget_termios(); unsafe { libc::tcsetattr(self.fd, libc::TCSADRAIN, &saved) }; } } @@ -969,6 +1033,7 @@ impl Keyboard { raw.c_cc[libc::VMIN] = 0; raw.c_cc[libc::VTIME] = 0; unsafe { libc::tcsetattr(self.fd, libc::TCSANOW, &raw) }; + remember_termios(self.fd, saved); self.saved = Some(saved); self.buf.clear(); } @@ -1824,6 +1889,26 @@ mod tests { ); } + #[test] + fn a_broken_refresh_does_not_reach_from_secs_f64() { + // Duration::from_secs_f64 panics on anything that is not finite + // and positive. A config of -1, or `nan` from a mistyped `-n`, + // used to take the poller down after the first read. + assert_eq!(poll_secs(-1.0, 120.0), 120.0); + assert_eq!(poll_secs(f64::NAN, 30.0), 30.0); + assert_eq!(poll_secs(f64::INFINITY, 4.0), 4.0); + assert_eq!(poll_secs(0.0, 2.0), 2.0); + assert_eq!(poll_secs(15.0, 120.0), 15.0); + // A broken fallback still has to be a duration. + assert_eq!(poll_secs(-1.0, f64::NAN), 1.0); + // And the bytes the handler writes are the same four sequences + // restore_screen formats - so a drift here is a drift on Ctrl-C. + assert_eq!( + format!("{}{}{}{}", SHOW, RST, CLEAR, HOME), + SCREEN_RESTORE + ); + } + /// The status names that a request was refused; only the body names /// what to do about it. #[test] diff --git a/widgets/src/bin/clocks.rs b/widgets/src/bin/clocks.rs index 9220d7b..47ebb32 100644 --- a/widgets/src/bin/clocks.rs +++ b/widgets/src/bin/clocks.rs @@ -125,8 +125,11 @@ impl Office { .unwrap_or_else(|| vec![0, 1, 2, 3, 4]); Office { days, - start: tc::cfg_usize(cfg, "work_start_hour", 9) as u32, - end: tc::cfg_usize(cfg, "work_end_hour", 18) as u32, + // Hours are 0..=23. An out-of-range value used to reach + // NaiveTime::from_hms_opt and unwrap, so a typo of 24 aborted + // the widget on the first frame instead of rendering. + start: (tc::cfg_usize(cfg, "work_start_hour", 9) as u32).min(23), + end: (tc::cfg_usize(cfg, "work_end_hour", 18) as u32).min(23), } } @@ -1496,6 +1499,16 @@ mod tests { // And nonsense falls back rather than emptying the week. let junk = Office::from_config(&serde_json::json!({"work_days": []})); assert_eq!(junk.days, vec![0, 1, 2, 3, 4]); + // An hour that is not an hour used to unwrap on the first frame. + let wild = Office::from_config(&serde_json::json!({ + "work_start_hour": 24, + "work_end_hour": 99 + })); + assert!(wild.start <= 23 && wild.end <= 23); + let noon = Local.with_ymd_and_hms(2026, 8, 24, 12, 0, 0).unwrap(); + let _ = wild.next_open(&noon); + let _ = wild.prev_close(&noon); + let _ = countdowns(noon, &wild); } #[test] diff --git a/widgets/src/bin/deployments.rs b/widgets/src/bin/deployments.rs index 2b5f7f1..6bad1ca 100644 --- a/widgets/src/bin/deployments.rs +++ b/widgets/src/bin/deployments.rs @@ -804,7 +804,7 @@ fn copy_overlay( fn main() { tc::maybe_help(include_str!("deployments_help.txt")); let cfg = tc::load_config("deployments"); - let mut refresh = tc::cfg_f64(&cfg, "refresh", 15.0); + let mut refresh = tc::poll_secs(tc::cfg_f64(&cfg, "refresh", 15.0), 15.0).max(5.0); let limit = tc::cfg_usize(&cfg, "limit", 100); let mut teams = tc::cfg_strings(&cfg, "teams", &[]); let configured: Vec<String> = tc::cfg_strings(&cfg, "projects", &[]); @@ -815,7 +815,7 @@ fn main() { while i < args.len() { match args[i].as_str() { "-n" | "--refresh" if i + 1 < args.len() => { - refresh = args[i + 1].parse::<f64>().unwrap_or(15.0).max(5.0); + refresh = tc::poll_secs(args[i + 1].parse().unwrap_or(15.0), 15.0).max(5.0); i += 2; } "-t" | "--team" if i + 1 < args.len() => { diff --git a/widgets/src/bin/github.rs b/widgets/src/bin/github.rs index 14288fe..5c68a9e 100644 --- a/widgets/src/bin/github.rs +++ b/widgets/src/bin/github.rs @@ -1104,7 +1104,7 @@ fn main() { let cfg = tc::load_config("github"); let mut refresh = tc::cfg_f64(&cfg, "refresh", 120.0); let configured: Vec<String> = tc::cfg_strings(&cfg, "accounts", &[]); - let start_window = tc::cfg_f64(&cfg, "window_days", 14.0) as i64; + let start_window = (tc::cfg_f64(&cfg, "window_days", 14.0) as i64).max(1); let args: Vec<String> = std::env::args().skip(1).collect(); let mut named: Vec<String> = Vec::new(); @@ -1122,6 +1122,7 @@ fn main() { _ => i += 1, } } + refresh = tc::poll_secs(refresh, 120.0).max(30.0); let absent = tc::missing(&["curl"]); if !absent.is_empty() { diff --git a/widgets/src/bin/herdr-panes.rs b/widgets/src/bin/herdr-panes.rs index 0a7eeb3..834ca89 100644 --- a/widgets/src/bin/herdr-panes.rs +++ b/widgets/src/bin/herdr-panes.rs @@ -663,10 +663,10 @@ fn main() { // this widget is hyphenated. A mismatched key is read as absent rather // than as an error, so it is worth saying out loud. let cfg = tc::load_config("herdr_panes"); - let mut refresh = tc::cfg_f64(&cfg, "refresh", 4.0); + let mut refresh = tc::poll_secs(tc::cfg_f64(&cfg, "refresh", 4.0), 4.0); let args: Vec<String> = std::env::args().skip(1).collect(); if args.len() >= 2 && (args[0] == "-n" || args[0] == "--refresh") { - refresh = args[1].parse::<f64>().unwrap_or(4.0).max(1.0); + refresh = tc::poll_secs(args[1].parse().unwrap_or(4.0), 4.0).max(1.0); } let absent = tc::missing(&["herdr"]); diff --git a/widgets/src/bin/linear.rs b/widgets/src/bin/linear.rs index 6d1ca38..ca0122a 100644 --- a/widgets/src/bin/linear.rs +++ b/widgets/src/bin/linear.rs @@ -1553,6 +1553,8 @@ fn project_detail( p.dim.as_str(), ); } + // Same honesty as members: this connection is five nodes, and + // presenting that page as the list would hide the rest. let inits: Vec<String> = v["initiatives"]["nodes"] .as_array() .into_iter() @@ -1560,8 +1562,24 @@ fn project_detail( .map(|i| text(i, "name")) .filter(|n| !n.is_empty()) .collect(); + let more_inits = v["initiatives"]["pageInfo"]["hasNextPage"] + .as_bool() + .unwrap_or(false); if !inits.is_empty() { - field("initiative", String::new(), inits.join(" · "), p.dim.as_str()); + field( + "initiative", + if more_inits { + format!("{}+", inits.len()) + } else { + String::new() + }, + if more_inits { + format!("{} · …", inits.join(" · ")) + } else { + inits.join(" · ") + }, + p.dim.as_str(), + ); } } if let Some((age, ident)) = oldest { @@ -1759,7 +1777,7 @@ fn main() { let cfg = tc::load_config("linear"); let mut refresh = tc::cfg_f64(&cfg, "refresh", 120.0); let exclude: Vec<String> = tc::cfg_strings(&cfg, "exclude_teams", &[]); - let start_window = tc::cfg_f64(&cfg, "window_days", 14.0) as i64; + let start_window = (tc::cfg_f64(&cfg, "window_days", 14.0) as i64).max(1); let args: Vec<String> = std::env::args().skip(1).collect(); let mut keep: Vec<String> = Vec::new(); @@ -1777,6 +1795,7 @@ fn main() { _ => i += 1, } } + refresh = tc::poll_secs(refresh, 120.0); let absent = tc::missing(&["curl"]); if !absent.is_empty() { diff --git a/widgets/src/bin/link.rs b/widgets/src/bin/link.rs index f5a5aba..b6db368 100644 --- a/widgets/src/bin/link.rs +++ b/widgets/src/bin/link.rs @@ -413,12 +413,17 @@ fn main() { if !named.is_empty() { let _ = CONFIGURED_PORTS.set(named); } - let refresh = tc::cfg_f64(&cfg, "refresh", 2.0).max(0.5); + let refresh = tc::poll_secs(tc::cfg_f64(&cfg, "refresh", 2.0), 2.0).max(0.5); let windows: Vec<f64> = { let got = cfg .get("windows") .and_then(|v| v.as_array()) - .map(|a| a.iter().filter_map(|v| v.as_f64()).collect::<Vec<f64>>()) + .map(|a| { + a.iter() + .filter_map(|v| v.as_f64()) + .filter(|v| v.is_finite() && *v > 0.0) + .collect::<Vec<f64>>() + }) .unwrap_or_default(); if got.is_empty() { vec![60.0, 300.0, 900.0, 3600.0] diff --git a/widgets/src/bin/netwatch.rs b/widgets/src/bin/netwatch.rs index 95dfb33..ccab4e9 100644 --- a/widgets/src/bin/netwatch.rs +++ b/widgets/src/bin/netwatch.rs @@ -1644,7 +1644,7 @@ fn main() { // which is the precedence netwatch.py uses. These five were documented // in config.example.json and read by nobody. let cfg = tc::load_config("netwatch"); - let mut interval = tc::cfg_f64(&cfg, "interval", 1.0).max(0.2); + let mut interval = tc::poll_secs(tc::cfg_f64(&cfg, "interval", 1.0), 1.0).max(0.2); let mut limit = tc::cfg_usize(&cfg, "limit", 0); let mut external = cfg .get("external") @@ -1658,7 +1658,7 @@ fn main() { while i < args.len() { match args[i].as_str() { "-i" | "--interval" if i + 1 < args.len() => { - interval = args[i + 1].parse::<f64>().unwrap_or(1.0).max(0.2); + interval = tc::poll_secs(args[i + 1].parse().unwrap_or(1.0), 1.0).max(0.2); i += 2; } "-n" | "--limit" if i + 1 < args.len() => { @@ -1702,12 +1702,21 @@ fn main() { })); let poller = Arc::clone(&state); std::thread::spawn(move || loop { + // A poller that dies takes its explanation with it, and an empty + // table looks exactly like a machine with no sockets on it. { let mut guard = match poller.lock() { Ok(g) => g, Err(_) => return, }; - sample(&mut guard, external); + if std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| { + sample(&mut guard, external); + })) + .is_err() + { + guard.err = "poller stopped - see the pane it was started from".into(); + return; + } } std::thread::sleep(Duration::from_secs_f64(interval)); }); diff --git a/widgets/src/bin/ports.rs b/widgets/src/bin/ports.rs index e8fbb6c..1afd2cb 100644 --- a/widgets/src/bin/ports.rs +++ b/widgets/src/bin/ports.rs @@ -44,6 +44,31 @@ const SYSTEM_PORTS: &[u16] = &[22, 53, 123, 323, 631, 5353]; static CONFIGURED_PORTS: std::sync::OnceLock<Vec<u16>> = std::sync::OnceLock::new(); /// Whether a port belongs to the machine rather than to something started. +/// The configured system-port list, or None when the key is absent. +/// +/// Present-and-empty is an answer: hide nothing. Absent means use the +/// built-in defaults. A number that is not a port is dropped rather than +/// wrapped - `65558 as u16` is 22, and hiding SSH because of a typo is +/// worse than ignoring the typo. +fn configured_system_ports(cfg: &serde_json::Value) -> Option<Vec<u16>> { + // Asking whether the key is there has no value to default: empty + // means hide nothing, absent means the built-in list. + if cfg.get("system_ports").is_none() { + return None; + } + Some( + cfg["system_ports"] + .as_array() + .map(|a| { + a.iter() + .filter_map(|v| v.as_u64()) + .filter_map(|n| u16::try_from(n).ok()) + .collect() + }) + .unwrap_or_default(), + ) +} + fn is_system_port(port: u16) -> bool { match CONFIGURED_PORTS.get() { Some(list) => list.contains(&port), @@ -2113,20 +2138,15 @@ fn main() { // Both of ports' config keys were documented and read by nobody. // Config is the default; argv still overrides. let cfg = tc::load_config("ports"); - let listed: Vec<u16> = cfg - .get("system_ports") - .and_then(|v| v.as_array()) - .map(|a| a.iter().filter_map(|v| v.as_u64()).map(|n| n as u16).collect()) - .unwrap_or_default(); - if !listed.is_empty() { + if let Some(listed) = configured_system_ports(&cfg) { let _ = CONFIGURED_PORTS.set(listed); } - let mut refresh = tc::cfg_f64(&cfg, "refresh", 4.0).max(1.0); + let mut refresh = tc::poll_secs(tc::cfg_f64(&cfg, "refresh", 4.0), 4.0).max(1.0); let args: Vec<String> = std::env::args().skip(1).collect(); let mut i = 0; while i < args.len() { if (args[i] == "-n" || args[i] == "--refresh") && i + 1 < args.len() { - refresh = args[i + 1].parse::<f64>().unwrap_or(4.0).max(1.0); + refresh = tc::poll_secs(args[i + 1].parse().unwrap_or(4.0), 4.0).max(1.0); i += 2; } else { i += 1; @@ -3289,6 +3309,24 @@ mod tests { assert_eq!(quick_url("INF starting tunnel"), ""); } + #[test] + fn an_empty_system_port_list_is_not_the_defaults() { + // Absent means the built-in list. Present and empty means hide + // nothing. The two used to collapse because `[]` was read as + // unset, so `"system_ports": []` kept hiding 22 and 53. + assert!(configured_system_ports(&serde_json::json!({})).is_none()); + assert_eq!( + configured_system_ports(&serde_json::json!({"system_ports": []})), + Some(vec![]) + ); + // A number that is not a port is dropped, not wrapped. 65558 as + // u16 is 22, and hiding SSH for a typo is worse than ignoring it. + assert_eq!( + configured_system_ports(&serde_json::json!({"system_ports": [22, 65558, 65535]})), + Some(vec![22, 65535]) + ); + } + #[test] fn spans_read_as_a_person_would_say_them() { assert_eq!(span(Some(45.0)), "45s"); diff --git a/widgets/src/bin/pr.rs b/widgets/src/bin/pr.rs index 29d00cf..b02abc8 100644 --- a/widgets/src/bin/pr.rs +++ b/widgets/src/bin/pr.rs @@ -697,7 +697,7 @@ fn main() { tc::maybe_help(include_str!("pr_help.txt")); let cfg = tc::load_config("pr"); let gh = tc::load_config("github"); - let mut refresh = tc::cfg_f64(&cfg, "refresh", 60.0); + let mut refresh = tc::poll_secs(tc::cfg_f64(&cfg, "refresh", 60.0), 60.0); let limit = tc::cfg_usize(&cfg, "limit", 50); // GitHub search has no OR, so anything that is a union of conditions has // to be several searches merged. @@ -719,7 +719,7 @@ fn main() { while i < args.len() { match args[i].as_str() { "-n" | "--refresh" if i + 1 < args.len() => { - refresh = args[i + 1].parse().unwrap_or(60.0); + refresh = tc::poll_secs(args[i + 1].parse().unwrap_or(60.0), 60.0); i += 2; } other if !other.starts_with('-') => { diff --git a/widgets/src/bin/start.rs b/widgets/src/bin/start.rs index 535c005..5072ab3 100644 --- a/widgets/src/bin/start.rs +++ b/widgets/src/bin/start.rs @@ -299,6 +299,25 @@ fn run_widget(keyboard: &mut tc::Keyboard, stem: &str) { tc::flush(); } +/// The status a supervisor should see for a launched widget. +/// +/// `ExitStatus::code()` is `None` when the child died from a signal, and +/// treating that as 0 made a crash look like a successful run. Unix +/// convention is 128 plus the signal; anywhere else, a plain failure. +fn child_exit(status: std::process::ExitStatus) -> i32 { + if let Some(code) = status.code() { + return code; + } + #[cfg(unix)] + { + use std::os::unix::process::ExitStatusExt; + if let Some(sig) = status.signal() { + return 128 + sig; + } + } + 1 +} + fn main() { // A widget name is resolved before --help is looked at, so that // `start netwatch --help` is netwatch's help, not this one's. Every @@ -330,7 +349,7 @@ fn main() { // something to sit between you and a widget you already named. let status = std::process::Command::new(&path).args(&args[1..]).status(); std::process::exit(match status { - Ok(s) => s.code().unwrap_or(0), + Ok(s) => child_exit(s), Err(e) => { eprintln!("{}: {}", path.display(), e); 2 @@ -618,6 +637,24 @@ mod tests { assert!(wrap("", 8).is_empty()); } + #[cfg(unix)] + #[test] + fn a_child_killed_by_signal_is_not_success() { + // `kill -s TERM $$` exits by signal, so `code()` is None. The + // previous fallback turned that into 0, which is how a crashed + // widget became a successful launch. + let status = std::process::Command::new("sh") + .args(["-c", "kill -s TERM $$"]) + .status() + .expect("spawn sh"); + assert!( + status.code().is_none(), + "expected a signal death, got {:?}", + status.code() + ); + assert_eq!(child_exit(status), 128 + 15); + } + #[test] fn the_list_is_in_a_settled_order() { // Alphabetical, as start.py's sorted glob produces - so the row a diff --git a/widgets/src/bin/tailnet.rs b/widgets/src/bin/tailnet.rs index e92e143..914933f 100644 --- a/widgets/src/bin/tailnet.rs +++ b/widgets/src/bin/tailnet.rs @@ -652,11 +652,11 @@ fn activity_rows( fn main() { tc::maybe_help(include_str!("tailnet_help.txt")); let cfg = tc::load_config("tailnet"); - let mut refresh = tc::cfg_f64(&cfg, "refresh", 2.0); + let mut refresh = tc::poll_secs(tc::cfg_f64(&cfg, "refresh", 2.0), 2.0); let history = tc::cfg_usize(&cfg, "history", 180); let args: Vec<String> = std::env::args().skip(1).collect(); if args.len() >= 2 && (args[0] == "-n" || args[0] == "--refresh") { - refresh = args[1].parse::<f64>().unwrap_or(2.0).max(1.0); + refresh = tc::poll_secs(args[1].parse().unwrap_or(2.0), 2.0).max(1.0); } let absent = tc::missing(&["tailscale"]); @@ -714,7 +714,7 @@ fn main() { g.endpoints_at = now(); } } - let wait = poller_refresh.lock().map(|g| *g).unwrap_or(2.0); + let wait = tc::poll_secs(poller_refresh.lock().map(|g| *g).unwrap_or(2.0), 2.0); let (lock, cond) = &*poller_wake; let mut asked = match lock.lock() { Ok(g) => g, diff --git a/widgets/src/bin/usage.rs b/widgets/src/bin/usage.rs index ed66fd7..f9c3b53 100644 --- a/widgets/src/bin/usage.rs +++ b/widgets/src/bin/usage.rs @@ -1247,7 +1247,7 @@ fn read_config() -> Config { .flatten() .filter_map(|(k, v)| v.as_f64().map(|v| (k.clone(), v))) .collect(), - refresh: tc::cfg_f64(&raw, "refresh", 30.0), + refresh: tc::poll_secs(tc::cfg_f64(&raw, "refresh", 30.0), 30.0), grok_ping: raw .get("grok_ping") .and_then(|v| v.as_bool()) @@ -1468,7 +1468,7 @@ fn main() { let mut refresh = cfg.refresh; let args: Vec<String> = std::env::args().skip(1).collect(); if args.len() >= 2 && (args[0] == "-n" || args[0] == "--refresh") { - refresh = args[1].parse().unwrap_or(refresh); + refresh = tc::poll_secs(args[1].parse().unwrap_or(refresh), refresh); } let p = palette();