Compare commits

...
2 Commits
Author SHA1 Message Date
Ansho ReiandClaude Opus 5 f5204f6d8b (866a4eb) Accept prose values that begin with a hyphen, and bump to 0.3.2
clap read any value starting with a hyphen as a flag, so a criterion quoting
--print was refused with "unexpected argument found" and no ticket was written
at all. Ticket text quotes flag names constantly, and the space form is what
both a person and the opencode wrapper produce, so the failure was routine.

allow_hyphen_values on the five arguments that carry prose: add --title,
--description, --acceptance, --plan, and the comment body. The trade is that a
genuinely mistyped flag there now lands as content instead of raising a usage
error, which is the right way round for prose and the wrong way round for
anything else, so due, priority, tags, owner and status are left alone and still
fail with exit 2. Written down in AGENTS.md.

The bare double hyphen is the one shape this does not reach: as an option value
it is stored as text, but in a positional it is clap's end-of-options marker and
is consumed before assignment. A comment body of exactly -- therefore needs its
own separator. Without it the body is reported missing and nothing is written,
so it is a clear failure rather than a silent drop. Tested, along with the
ordering that lets mv reach a hyphen-leading title.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-20 18:00:52 +02:00
Ansho ReiandClaude Opus 5 b28ddb9210 (eed7309) Die quietly on a truncated pipe, and bump to 0.3.1
Rust sets SIGPIPE to SIG_IGN at startup, so a write to a closed pipe returned
EPIPE and println panicked on it. `worklane ls | head -3` printed a panic and a
backtrace on stderr instead of three lines, which reads as a real fault and is
not what any other tool in a pipeline does.

main now restores the default disposition before any output, the same six lines
frig carries for the same reason. The cost is that a truncated pipe kills the
process with signal 13, so a shell reports 141 rather than 101. That is what
head and sort do, and it is now in the README next to the other exit codes.

The tests drop the read end rather than racing head for it, over a listing large
enough to exceed the 64 KiB a pipe holds, since a smaller one lands entirely in
the buffer and proves nothing. A shell pipeline into head is covered too, and
the exit codes for a real error and a usage mistake are pinned so the reset
cannot quietly change them.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-20 17:34:45 +02:00
9 changed files with 442 additions and 6 deletions
+8
View File
@@ -31,12 +31,20 @@
- Use `unwrap_or_else(|| expr)` for lazy defaults, `unwrap_or(val)` for eager defaults
- Use `anyhow!()` with context strings that include identifying info (e.g. UUID, title) not bare values
### CLI Arguments
- The prose arguments carry `allow_hyphen_values`, via the `PROSE` constant in `command.rs`: `add --title`, `--description`, `--acceptance`, `--plan`, and the `comment` body. Ticket text quotes flag names constantly, and without it a criterion reading `--print is supported` is parsed as a flag and the whole ticket is refused with nothing written
- **The trade:** on those five arguments a genuinely mistyped flag now lands as content rather than raising a usage error. That is the right way round for prose and the wrong way round for anything else, which is why `due`, `priority`, `tags`, `owner` and `status` are deliberately left without it. A mistyped flag there is still a usage error, exit 2, and no ticket is written. Do not add `PROSE` to a new argument unless it holds prose
- The ticket positionals (`show <id>`, `mv <ticket>`, `comment <ticket>`) are also left alone, so a search term starting with a hyphen is a usage error. Reachable now that a hyphen-leading title can be stored: use the UUID, or put the flags first and separate with `--`, as in `mv --status committed -- -leading-title`
- A bare `--` is a value when it follows an option (`--title -- ` stores `--`) and clap's end-of-options marker when it sits in a positional. So a `comment` body of exactly `--` needs its own separator, `comment <ticket> -- --`. Without it the body is reported missing and nothing is written, which is a clear failure rather than a silent drop
- `add` has no positionals, so anything after a bare `--` is an unexpected argument and fails
### Color and Output
- Use `color_text()` helper for colored output — it respects `should_use_colors()` (terminal detection)
- Color codes are defined in `get_color()`: red (31), cyan (36), orange (33), green (32), grey (38;5;8), magenta (1;35), brightred (38;5;9)
- 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)
Generated
+2 -1
View File
@@ -1029,13 +1029,14 @@ dependencies = [
[[package]]
name = "worklane"
version = "0.3.0"
version = "0.3.2"
dependencies = [
"anyhow",
"assert_cmd",
"assert_fs",
"chrono",
"clap",
"libc",
"tempfile",
"uuid",
]
+2 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "worklane"
version = "0.3.0"
version = "0.3.2"
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"
+13
View File
@@ -11,3 +11,16 @@ Worklane is a local Kanban flow for agentic software development.
| `worklane show <id>` | Shows ticket by UUID prefix (8+ chars) or title substring |
| `worklane mv <id> --status <target> [-f]` | Moves ticket between statuses. Default: forward only, one stage at a time. `-f` bypasses both restrictions |
| `worklane comment <ticket> <body>` | 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.
+16 -4
View File
@@ -37,6 +37,17 @@ pub struct Cli {
pub command: Command,
}
/// Arguments that carry prose, and therefore have to accept a value starting with
/// a hyphen.
///
/// Ticket text quotes flag names constantly, and without this a criterion reading
/// "--print is supported" is parsed as a flag and the whole ticket is refused. The
/// trade, spelled out in AGENTS.md: on these arguments a genuinely mistyped flag
/// now lands as content instead of raising a usage error. That is the right way
/// round for prose, and it is why `due`, `priority`, `tags`, `owner` and `status`
/// are deliberately left without it.
const PROSE: bool = true;
#[derive(clap::Subcommand)]
pub enum Command {
/// Initialize worklane in the current project
@@ -45,19 +56,19 @@ pub enum Command {
/// Add a new ticket to the backlog
Add {
/// Ticket title
#[arg(short, long)]
#[arg(short, long, allow_hyphen_values = PROSE)]
title: String,
/// Ticket description. Use multiple flags to create multiline descriptions.
#[arg(short, long)]
#[arg(short, long, allow_hyphen_values = PROSE)]
description: Vec<String>,
/// Acceptance criteria. Accepts multiple flags, each will be interpreted as a single criterium
#[arg(short, long)]
#[arg(short, long, allow_hyphen_values = PROSE)]
acceptance: Vec<String>,
/// Implementation plan. Accepts multiple flags, each will be interpreted as a single step
#[arg(short, long)]
#[arg(short, long, allow_hyphen_values = PROSE)]
plan: Vec<String>,
/// Tags (comma-separated)
@@ -114,6 +125,7 @@ pub enum Command {
ticket: String,
/// Comment body (required)
#[arg(allow_hyphen_values = PROSE)]
body: String,
/// Owner
+21
View File
@@ -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()?;
+173
View File
@@ -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));
}
+118
View File
@@ -262,3 +262,121 @@ fn add_rejects_a_level_outside_the_range() {
let count = fs::read_dir(worklane.join("backlog")).unwrap().count();
assert_eq!(count, 0, "a ticket was written despite a bad level");
}
/// Ticket text quotes flag names constantly, and the space form is what both a
/// person and the opencode wrapper produce. Every one of these used to be refused
/// with "unexpected argument found", writing no ticket at all.
#[test]
fn add_accepts_prose_values_that_begin_with_a_hyphen() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(&temp.path())
.args(["add", "--title", "-t is a flag name"])
.args(["--description", "-x does nothing"])
.args(["--acceptance", "--print should be supported"])
.args(["--plan", "-f skips the check"])
.assert()
.success();
let content = only_ticket(&worklane);
// Stored verbatim, hyphens and all
assert!(content.contains("# -t is a flag name"), "was {content:?}");
assert!(content.contains("-x does nothing"), "was {content:?}");
assert!(
content.contains("- [ ] --print should be supported"),
"was {content:?}"
);
assert!(content.contains("1. -f skips the check"), "was {content:?}");
}
/// The docs and the habit both use it, and it reaches the parser as one token, so
/// it has to keep working alongside the space form.
#[test]
fn add_still_accepts_the_equals_form() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(&temp.path())
.args(["add", "--title=-x equals form"])
.args(["--acceptance=--print via equals"])
.assert()
.success();
let content = only_ticket(&worklane);
assert!(content.contains("# -x equals form"), "was {content:?}");
assert!(
content.contains("- [ ] --print via equals"),
"was {content:?}"
);
}
/// Never silently dropped: a value that is nothing but hyphens is content.
#[test]
fn add_stores_a_title_that_is_only_hyphens() {
for bare in ["-", "--", "---"] {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(&temp.path())
.args(["add", "--title", bare])
.assert()
.success();
let content = only_ticket(&worklane);
assert!(
content.starts_with(&format!("# {}\n", bare)),
"for {bare:?}: {content:?}"
);
}
}
/// The other half of the trade. These arguments were deliberately left alone, so a
/// mistyped flag there is still a usage error rather than stored text.
#[test]
fn add_still_rejects_a_mistyped_flag_on_a_non_prose_argument() {
for flag in ["--due", "--priority", "--tags", "--owner"] {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(&temp.path())
.args(["add", "--title", "Mistyped", flag, "--bogus"])
.assert()
.failure();
let count = fs::read_dir(worklane.join("backlog")).unwrap().count();
assert_eq!(count, 0, "{flag} wrote a ticket anyway");
}
}
/// `add` has no positionals, so a bare `--` ends the options and whatever follows
/// has nowhere to go. Recorded because clap's separator and a hyphen-leading value
/// are easy to confuse.
#[test]
fn add_rejects_arguments_after_a_bare_separator() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(&temp.path())
.args(["add", "--title", "Sep", "--", "--title", "second"])
.assert()
.failure();
let count = fs::read_dir(worklane.join("backlog")).unwrap().count();
assert_eq!(count, 0);
}
fn only_ticket(worklane: &PathBuf) -> String {
let files: Vec<_> = fs::read_dir(worklane.join("backlog"))
.unwrap()
.filter_map(|e| e.ok())
.collect();
assert_eq!(files.len(), 1, "expected exactly one ticket");
fs::read_to_string(files[0].path()).unwrap()
}
+89
View File
@@ -250,3 +250,92 @@ fn comments_added_back_to_back_are_both_kept() {
let third = stdout.find("third comment").expect("third comment missing");
assert!(first < second && second < third, "comments out of order");
}
/// The body is a positional, and the case that motivated this: a review comment
/// quoting a flag name used to be refused outright.
#[test]
fn comment_accepts_a_body_that_begins_with_a_hyphen() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let uuid = create_ticket(&worklane, "backlog", "Hyphen body");
for body in ["--print is the flag I mean", "-f skips the check", "-"] {
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(&temp.path())
.args(["comment", &uuid, body])
.assert()
.success();
}
let bodies: String = fs::read_dir(worklane.join("comments").join(&uuid))
.unwrap()
.filter_map(|e| e.ok())
.map(|e| fs::read_to_string(e.path()).unwrap())
.collect();
for body in ["--print is the flag I mean", "-f skips the check"] {
assert!(bodies.contains(body), "{body:?} missing from {bodies:?}");
}
}
/// The ticket positional was deliberately left alone, so a hyphen-leading search
/// term is still a usage error. A bare separator is the way through, and it is the
/// only way through for `comment` since the body follows in the same position.
#[test]
fn comment_needs_a_separator_for_a_hyphen_leading_ticket() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog", "-leading");
let mut without = Command::cargo_bin(BIN_NAME).unwrap();
without
.current_dir(&temp.path())
.args(["comment", "-leading", "a body"])
.assert()
.failure();
let mut with = Command::cargo_bin(BIN_NAME).unwrap();
with.current_dir(&temp.path())
.args(["comment", "--", "-leading", "a body"])
.assert()
.success();
}
/// The one shape `allow_hyphen_values` does not reach: a lone `--` in a positional
/// is clap's end-of-options marker, consumed before any value is assigned. So a
/// comment body of exactly `--` needs its own separator in front of it.
///
/// Not a silent drop either way, which is what matters: without the separator the
/// body is reported missing and nothing is written.
#[test]
fn a_bare_double_hyphen_body_needs_a_separator() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let uuid = create_ticket(&worklane, "backlog", "Bare separator");
let mut without = Command::cargo_bin(BIN_NAME).unwrap();
let assert = without
.current_dir(&temp.path())
.args(["comment", &uuid, "--"])
.assert()
.failure();
let stderr = String::from_utf8(assert.get_output().stderr.clone()).unwrap();
assert!(stderr.contains("<BODY>"), "unclear error: {stderr}");
assert!(
!worklane.join("comments").join(&uuid).exists(),
"a comment was written despite the error"
);
let mut with = Command::cargo_bin(BIN_NAME).unwrap();
with.current_dir(&temp.path())
.args(["comment", &uuid, "--", "--"])
.assert()
.success();
let stored: String = fs::read_dir(worklane.join("comments").join(&uuid))
.unwrap()
.filter_map(|e| e.ok())
.map(|e| fs::read_to_string(e.path()).unwrap())
.collect();
assert!(stored.contains("**Comment**\n--\n"), "was {stored:?}");
}