diff --git a/AGENTS.md b/AGENTS.md index 28ad6e4..f1c90a9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -37,6 +37,7 @@ - Reset color with `\x1b[0m` after colored text - Bold uses `\x1b[1;35m` (magenta bold) - Always test color output works correctly in both terminal and pipe modes +- `quiet_broken_pipe()` runs first in `main`, restoring the default `SIGPIPE` disposition. A truncated pipe therefore kills the process with signal 13, which a shell reports as 141, instead of making `println!` panic. Do not wrap prints to handle write errors and do not reinstate `SIG_IGN`; the exit codes are documented in the README ### Color Guideline - UUID → red (31) diff --git a/Cargo.lock b/Cargo.lock index 9e25868..c155934 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1029,13 +1029,14 @@ dependencies = [ [[package]] name = "worklane" -version = "0.3.0" +version = "0.3.1" dependencies = [ "anyhow", "assert_cmd", "assert_fs", "chrono", "clap", + "libc", "tempfile", "uuid", ] diff --git a/Cargo.toml b/Cargo.toml index 928ff06..eb80556 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "worklane" -version = "0.3.0" +version = "0.3.1" edition = "2024" [dependencies] @@ -8,6 +8,7 @@ clap = { version = "4", features = ["derive"] } anyhow = "1" uuid = { version = "1", features = ["v4"] } chrono = { version = "0.4", features = ["serde"] } +libc = "0.2" [dev-dependencies] assert_cmd = "2" diff --git a/README.md b/README.md index ba3be74..9d90e67 100644 --- a/README.md +++ b/README.md @@ -11,3 +11,16 @@ Worklane is a local Kanban flow for agentic software development. | `worklane show ` | Shows ticket by UUID prefix (8+ chars) or title substring | | `worklane mv --status [-f]` | Moves ticket between statuses. Default: forward only, one stage at a time. `-f` bypasses both restrictions | | `worklane comment ` | Adds a comment to a ticket by UUID or title | + +## Exit codes +| Code | Meaning | +|------|---------| +| 0 | Success | +| 1 | An error, such as no matching ticket or an ambiguous search | +| 2 | A usage mistake, such as an unknown flag | +| 141 | Output was piped to a reader that stopped early, for example `worklane ls \| head -3` | + +141 is 128 + 13, the shell's way of reporting death by `SIGPIPE`. Worklane restores +the default signal disposition so a truncated pipe is quiet, the way `head` and +`sort` are, rather than printing a panic. A script using `set -o pipefail` will see +141 for a case that is not a failure, so guard for it there. diff --git a/src/main.rs b/src/main.rs index 7756165..5c2ec80 100644 --- a/src/main.rs +++ b/src/main.rs @@ -9,7 +9,28 @@ use command::*; use handlers::*; use util::*; +/// Die quietly when stdout is closed early, the way every other Unix tool does. +/// +/// Rust sets `SIGPIPE` to `SIG_IGN` at startup, which turns a closed pipe into an +/// io error that `println!` panics on. So `worklane ls | head -3` printed a panic +/// and a backtrace instead of three lines, which is both alarming and easy to +/// mistake for a real fault. Restoring the default handler makes `| head` behave. +/// +/// The cost is that a truncated pipe now kills the process with signal 13 rather +/// than returning a code, so `pipefail` sees 141 instead of 101. That is what +/// `head` and `sort` do, and it is recorded in the README. +fn quiet_broken_pipe() { + // SAFETY: setting a signal disposition to the default is always valid, and + // this runs before any thread is spawned. + unsafe { + libc::signal(libc::SIGPIPE, libc::SIG_DFL); + } +} + fn main() -> Result<()> { + // Before any output, so no write can beat it to a closed pipe. + quiet_broken_pipe(); + let cli = Cli::parse(); let start = std::env::current_dir()?; diff --git a/tests/broken_pipe.rs b/tests/broken_pipe.rs new file mode 100644 index 0000000..224dcf2 --- /dev/null +++ b/tests/broken_pipe.rs @@ -0,0 +1,173 @@ +use assert_fs::TempDir; +use assert_fs::fixture::{PathChild, PathCreateDir}; +use std::fs; +use std::os::unix::process::ExitStatusExt; +use std::process::{Command, Stdio}; + +const BIN_NAME: &str = env!("CARGO_BIN_EXE_worklane"); + +/// What a truncated pipe costs: the process dies by signal rather than returning a +/// code, so a shell reports 128 + 13. Asserted here so the README and the code stay +/// honest about what `pipefail` sees. +const SIGPIPE: i32 = 13; + +/// A pipe holds 64 KiB on Linux before a write blocks. Below that the whole listing +/// lands in the buffer, the writer never notices the reader is gone, and a test +/// proves nothing. Every ticket here is one `ls` row of roughly a hundred bytes. +const TICKETS: usize = 1200; + +fn setup_crowded_board(temp: &TempDir) -> std::path::PathBuf { + let worklane = temp.child(".worklane"); + worklane.create_dir_all().unwrap(); + + for dir in ["backlog", "committed", "reviewing", "done"] { + worklane.child(dir).create_dir_all().unwrap(); + } + + let backlog = worklane.path().join("backlog"); + for i in 0..TICKETS { + let id = format!("{:08x}-0000-4000-8000-000000000000", i); + let title = format!("A ticket with a title long enough to fill a row {}", i); + fs::write( + backlog.join(format!("{}_ticket-{}.md", id, i)), + format!( + "# {}\n\n## Metadata\n\n\ + - **ID**: {}\n\ + - **Owner**: someone with a name\n\ + - **Status**: backlog\n", + title, id + ), + ) + .unwrap(); + } + + temp.path().to_path_buf() +} + +fn panic_text(stderr: &str) -> bool { + stderr.contains("panicked") + || stderr.contains("failed printing to stdout") + || stderr.contains("Broken pipe") +} + +/// The reader closed before the writer finished: dropping the read end here is the +/// same thing `head` does when it has seen enough, without the timing luck. +fn run_with_stdout_dropped(dir: &std::path::Path, args: &[&str]) -> std::process::Output { + let mut child = Command::new(BIN_NAME) + .args(args) + .current_dir(dir) + .stdout(Stdio::piped()) + .stderr(Stdio::piped()) + .spawn() + .unwrap(); + + drop(child.stdout.take().unwrap()); + child.wait_with_output().unwrap() +} + +#[test] +fn ls_says_nothing_when_the_reader_goes_away() { + let temp = TempDir::new().unwrap(); + let dir = setup_crowded_board(&temp); + + let output = run_with_stdout_dropped(&dir, &["ls", "backlog"]); + let stderr = String::from_utf8_lossy(&output.stderr); + + assert!(!panic_text(&stderr), "stderr was {stderr:?}"); + assert_ne!(output.status.code(), Some(101), "panicked instead of dying"); + assert_eq!( + output.status.signal(), + Some(SIGPIPE), + "expected death by SIGPIPE, got {:?}", + output.status + ); +} + +#[test] +fn show_says_nothing_when_the_reader_goes_away() { + let temp = TempDir::new().unwrap(); + let dir = setup_crowded_board(&temp); + + // A ticket carrying more comments than a pipe will hold, since the comment list + // is the longest thing show prints and the last thing it reaches. + let comments = temp + .path() + .join(".worklane") + .join("comments") + .join("00000000-0000-4000-8000-000000000000"); + fs::create_dir_all(&comments).unwrap(); + for i in 0..800 { + fs::write( + comments.join(format!("2026082{}_120000_{:06}.md", i % 10, i)), + format!( + "**Comment**\nA comment body long enough to be worth buffering, number {}.\n\n\ + **Author**: someone\n**Time**: 2026-08-20 12:00:00\n", + i + ), + ) + .unwrap(); + } + + let output = run_with_stdout_dropped(&dir, &["show", "00000000-0000-4000"]); + let stderr = String::from_utf8_lossy(&output.stderr); + + assert!(!panic_text(&stderr), "stderr was {stderr:?}"); + assert_ne!(output.status.code(), Some(101), "panicked instead of dying"); + assert_eq!( + output.status.signal(), + Some(SIGPIPE), + "expected death by SIGPIPE, got {:?}", + output.status + ); +} + +/// The real invocation, through a shell into `head`, which is how this was found. +/// Whether the writer gets far enough to notice is up to the scheduler, so this +/// asserts only what must hold either way: `head` gets its lines and nothing +/// alarming reaches stderr. +#[test] +fn a_shell_pipeline_into_head_prints_lines_and_not_a_panic() { + let temp = TempDir::new().unwrap(); + let dir = setup_crowded_board(&temp); + + let output = Command::new("sh") + .arg("-c") + .arg(format!("{} ls backlog | head -3", BIN_NAME)) + .current_dir(&dir) + .output() + .unwrap(); + + let stdout = String::from_utf8_lossy(&output.stdout); + let stderr = String::from_utf8_lossy(&output.stderr); + + assert_eq!(stdout.lines().count(), 3, "stdout was {stdout:?}"); + assert!(!panic_text(&stderr), "stderr was {stderr:?}"); +} + +/// The reset must not touch anything else: a real failure still returns its code. +#[test] +fn real_exit_codes_are_unchanged() { + let temp = TempDir::new().unwrap(); + let dir = setup_crowded_board(&temp); + + let ok = Command::new(BIN_NAME) + .args(["ls", "backlog"]) + .current_dir(&dir) + .output() + .unwrap(); + assert_eq!(ok.status.code(), Some(0)); + + let missing = Command::new(BIN_NAME) + .args(["show", "no-such-ticket-anywhere"]) + .current_dir(&dir) + .output() + .unwrap(); + assert_eq!(missing.status.code(), Some(1)); + + let misuse = Command::new(BIN_NAME) + .arg("--bogus") + .current_dir(&dir) + .output() + .unwrap(); + assert_eq!(misuse.status.code(), Some(2)); +}