diff --git a/AGENTS.md b/AGENTS.md index cc07511..84c6de3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -53,6 +53,10 @@ and this file is for what someone changing worklane's own code needs. ### 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 +- **`--due` is validated at parse time by `iso_date`, the way `--priority` is by `priority_level`.** A date that is not real is a usage error, exit 2, with nothing written, which is the whole point of leaving the scalars without `PROSE`. One parser serves `add` and `set`: the field has one definition of what it accepts, and validating only `add` would leave `set` open, which is the command a grooming sweep actually uses +- **The shape is checked before chrono is asked.** `%Y-%m-%d` accepts an unpadded `2026-8-9`, which would be stored exactly as typed and sort before `2026-10-01` in any string comparison. Checking the length and the two dashes first is what lets a valid date be stored unchanged instead of normalised on the way in, which is the difference between validating and rewriting +- **Strict on the way in, tolerant on the way out.** `util::due_date` still cuts `2026-12-31T09:30:00Z` down to its date. A file written before the parser existed, or by hand, can hold one and still has to render; refusing to display what is already stored would punish the reader for the writer's mistake +- An empty `--due` keeps `non_empty`'s message about clearing rather than the date message. Somebody typing it is reaching for a way to clear the field, and the useful answer is that clearing is not supported yet - The ticket positionals (`show `, `mv `, `comment `) 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 -- --`. 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 diff --git a/Cargo.lock b/Cargo.lock index 57cd5ba..c26485b 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1494,7 +1494,7 @@ dependencies = [ [[package]] name = "worklane" -version = "0.13.2" +version = "0.13.3" dependencies = [ "anyhow", "assert_cmd", diff --git a/Cargo.toml b/Cargo.toml index 2672e8f..3c19eb2 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "worklane" -version = "0.13.2" +version = "0.13.3" edition = "2024" [dependencies] diff --git a/README.md b/README.md index 9d787ef..80c4983 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ Worklane is a local Kanban flow for agentic software development. |---------|-------------| | `worklane` or `worklane tui [path...]` | Opens the board: four status columns, redrawn when the tree changes. Read only. Opens on backlog, committed and reviewing; `d` shows or hides done, whose count stays in the footer either way. Arrows or `hjkl` to move, `enter` for detail, `pgup`/`pgdn` to scroll an open ticket, `q` to quit. Each path opens the first `.worklane` at or above it, the working directory by default. Several paths are monitored together, as a tab per project plus an `all` tab that merges them, with `tab` and `shift+tab` between them | | `worklane init` | Creates `.worklane/` with backlog, committed, reviewing, done directories | -| `worklane add` | Creates a ticket in backlog with `--title`, `--description`, `--acceptance`, `--plan`, `--tags`, `--due`, `--owner`, `--priority` flags | +| `worklane add` | Creates a ticket in backlog with `--title`, `--description`, `--acceptance`, `--plan`, `--tags`, `--due`, `--owner`, `--priority` flags. `--due` takes `YYYY-MM-DD` and refuses anything else at parse time | | `worklane ls [status]` | Lists tickets, sorted by priority then title. Optional positional status, and `--priority <1-5>` | | `worklane show ` | Shows ticket by UUID prefix (4+ chars), title substring, or filename substring | | `worklane mv --status [-f]` | Moves ticket between statuses. Default: forward only, one stage at a time. `-f` bypasses both restrictions | diff --git a/assets/PLAN.md b/assets/PLAN.md index 29ce6e1..b24fff8 100644 --- a/assets/PLAN.md +++ b/assets/PLAN.md @@ -17,7 +17,7 @@ which command owns which field. Read it too. This document is the judgement. **Propose the whole set of edits, wait, then apply exactly what was approved.** Every job here writes to many tickets at once, and no field can be cleared back to unset -yet, so a due date written by mistake can only be overwritten with another guess. A wrong +yet, so a date written onto the wrong ticket can only be overwritten, never taken off. A wrong edit to one ticket is a mistake; a wrong sweep is thirty of them with no undo. So a proposal is a list, one line per intended edit, each naming the ticket and the command that would make it: @@ -96,9 +96,10 @@ What to look for: `worklane set --due 2026-08-29`, format `YYYY-MM-DD`. -**The value is not validated.** A typo is stored as written rather than refused, and it -cannot be cleared afterwards, only replaced. Write it once, carefully, and read it back -with `show`. +A value that is not a real calendar date in that exact form is refused before anything +is written, so a typo costs nothing. `2026-8-9` is refused too: the padding is part of +the format. What is still true is that a date, once written, **cannot be cleared**, only +replaced by another date, so a plan applied to the wrong ticket has no undo. Ask the system what today is rather than assuming it. A plan built on a guessed date is wrong by however much the guess was wrong. diff --git a/assets/SKILL.md b/assets/SKILL.md index b98896e..86d04b0 100644 --- a/assets/SKILL.md +++ b/assets/SKILL.md @@ -85,6 +85,9 @@ worklane add \ checked off as true or false. - **`--plan`** takes one step per flag, numbered for you. - **`--priority`** runs 1 (most urgent) to 5 (least), and is left unset if omitted. +- **`--due`** takes `YYYY-MM-DD` and nothing else. Anything that is not a real calendar + date in that exact form, `2026-8-9` and `2026-02-30` included, is a usage error with + nothing written. The same parser guards `set --due`. Editing afterwards, on a ticket in any status: diff --git a/src/command.rs b/src/command.rs index 8e9a50e..cd3700e 100644 --- a/src/command.rs +++ b/src/command.rs @@ -2,6 +2,8 @@ use clap::Parser; use std::sync::LazyLock; +use chrono::NaiveDate; + use crate::util::{PRIORITY_RANGE, RelationKind, priority_legend}; /// clap wants a `&str` with a long enough lifetime, and the legend is built from @@ -53,6 +55,42 @@ fn non_empty(raw: &str) -> Result { Ok(raw.to_string()) } +/// Reject a due date that is not a real calendar date in the promised form. +/// +/// At parse time, like `priority_level`, so a mistyped date is a usage error with +/// nothing written rather than a value the board goes on showing. `--due` is one of the +/// scalars deliberately left without `PROSE`, so this is the same bargain: nothing here +/// holds prose, and a wrong value should stop the command. +/// +/// **The shape is checked before chrono sees it.** `%Y-%m-%d` accepts an unpadded +/// `2026-8-9`, which would then be stored exactly as typed and sort before `2026-10-01` +/// in any comparison of the strings. Checking the length and the two dashes first is +/// what lets a valid date be stored unchanged rather than normalised on the way in. +/// +/// Strict on the way in, tolerant on the way out: `util::due_date` still cuts a +/// datetime down to its date, because a file written before this existed, or by hand, +/// can hold one and still has to render. +fn iso_date(raw: &str) -> Result { + // An empty value keeps the message that explains why it is refused, since somebody + // typing it is reaching for a way to clear the field rather than mistyping a date. + non_empty(raw)?; + + let bytes = raw.as_bytes(); + let shaped = raw.len() == 10 && bytes[4] == b'-' && bytes[7] == b'-'; + + if !shaped || NaiveDate::parse_from_str(raw, "%Y-%m-%d").is_err() { + // Not echoing the value: clap has already printed `invalid value '...' for + // '--due '` above this line, and `priority_level` says its piece the same + // way. + return Err( + "due date must be a real calendar date written as YYYY-MM-DD, for example 2026-08-29" + .to_string(), + ); + } + + Ok(raw.to_string()) +} + /// Arguments that carry prose, and therefore have to accept a value starting with /// a hyphen. /// @@ -275,7 +313,7 @@ pub struct AddArgs { pub tags: Vec, /// Due date (YYYY-MM-DD) - #[arg(long)] + #[arg(long, value_parser = iso_date)] pub due: Option, /// Owner @@ -324,7 +362,11 @@ pub struct SetArgs { pub tags: Vec, /// Replace the due date (YYYY-MM-DD) - #[arg(long, value_parser = non_empty)] + /// + /// The same parser as `add`: one field, one definition of what a due date is. The + /// planning skill sets dates through `set` rather than `add`, so validating only + /// the one that files a ticket would leave the path that is actually used open. + #[arg(long, value_parser = iso_date)] pub due: Option, /// Replace the priority, 1 (most urgent) to 5 (least) diff --git a/src/install.rs b/src/install.rs index 4b42d69..6afebda 100644 --- a/src/install.rs +++ b/src/install.rs @@ -387,7 +387,7 @@ mod tests { for required in [ "Propose the whole set of edits", "replaces the whole\nfield", // `set --tags` is the destructive one - "not validated", // and a due date cannot be taken back + "cannot be cleared", // and a due date cannot be taken back "blocked by", // ordering constrains any dating plan "worklane campaign ls", "does not touch", diff --git a/tests/cmd_add.rs b/tests/cmd_add.rs index 2a6c5db..d2bbc04 100644 --- a/tests/cmd_add.rs +++ b/tests/cmd_add.rs @@ -457,3 +457,107 @@ fn add_treats_an_all_blank_description_as_none() { "was {content:?}" ); } + +/// The help, the README and the skill all promise `YYYY-MM-DD`, and until this the +/// value was written to the ticket whatever it said. +#[test] +fn add_stores_a_valid_due_date_unchanged() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + + let mut cmd = Command::cargo_bin(BIN_NAME).unwrap(); + cmd.current_dir(temp.path()) + .arg("add") + .args(["--title", "Dated"]) + .args(["--due", "2026-08-29"]) + .assert() + .success(); + + let content = read_only_ticket(&worklane.join("backlog")); + assert!(content.contains("- **Due**: 2026-08-29"), "{content}"); +} + +/// Every one of these is refused at parse time, so the exit code is 2 and nothing is +/// written. A date that cannot happen is as wrong as a word: `2026-02-30` has the shape +/// and is not a day. +#[test] +fn add_refuses_a_due_date_that_is_not_a_real_iso_date() { + for value in ["next friday", "29-08-2026", "2026-13-01", "2026-02-30", "2026/08/29", ""] { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + + let mut cmd = Command::cargo_bin(BIN_NAME).unwrap(); + let out = cmd + .current_dir(temp.path()) + .arg("add") + .args(["--title", "Dated"]) + .args(["--due", value]) + .assert() + .failure() + .get_output() + .clone(); + + assert_eq!(out.status.code(), Some(2), "{value:?} was not a usage error"); + assert_eq!( + fs::read_dir(worklane.join("backlog")).unwrap().count(), + 0, + "{value:?} wrote a ticket anyway" + ); + } +} + +/// An unpadded date parses as a date and would be stored as typed, which sorts before +/// `2026-10-01` and is not the format anything promises. +#[test] +fn add_refuses_an_unpadded_due_date_rather_than_padding_it() { + let temp = TempDir::new().unwrap(); + setup_worklane(&temp); + + let mut cmd = Command::cargo_bin(BIN_NAME).unwrap(); + let stderr = String::from_utf8_lossy( + &cmd.current_dir(temp.path()) + .arg("add") + .args(["--title", "Dated"]) + .args(["--due", "2026-8-9"]) + .assert() + .failure() + .get_output() + .stderr, + ) + .to_string(); + + assert!(stderr.contains("YYYY-MM-DD"), "the error never names the format: {stderr}"); +} + +/// An empty value keeps the message about clearing, since that is what somebody typing +/// it is reaching for. +#[test] +fn an_empty_due_date_says_clearing_is_not_supported() { + let temp = TempDir::new().unwrap(); + setup_worklane(&temp); + + let mut cmd = Command::cargo_bin(BIN_NAME).unwrap(); + let stderr = String::from_utf8_lossy( + &cmd.current_dir(temp.path()) + .arg("add") + .args(["--title", "Dated"]) + .args(["--due", ""]) + .assert() + .failure() + .get_output() + .stderr, + ) + .to_string(); + + assert!(stderr.contains("clearing a field is not supported"), "{stderr}"); +} + +fn read_only_ticket(dir: &Path) -> String { + let file = fs::read_dir(dir) + .unwrap() + .filter_map(|e| e.ok()) + .find(|e| e.path().extension().is_some_and(|ext| ext == "md")) + .expect("no ticket written"); + + fs::read_to_string(file.path()).unwrap() +} diff --git a/tests/cmd_set.rs b/tests/cmd_set.rs index 94847e5..ddc05f0 100644 --- a/tests/cmd_set.rs +++ b/tests/cmd_set.rs @@ -415,3 +415,50 @@ fn neither_command_can_write_owner_or_status() { assert!(content.contains("- **Owner**: alice")); assert!(content.contains("- **Status**: backlog")); } + +/// The same parser `add` uses, from one definition. Grooming a board sets dates through +/// `set`, so validating only the command that files a ticket would leave the path that +/// is actually used wide open. +#[test] +fn set_refuses_a_due_date_that_is_not_a_real_iso_date() { + for value in ["next friday", "2026-02-30", "2026-8-9"] { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + let filename = create_ticket(&worklane); + let before = fs::read_to_string(worklane.join("backlog").join(&filename)).unwrap(); + + let mut cmd = Command::cargo_bin(BIN_NAME).unwrap(); + let out = cmd + .current_dir(temp.path()) + .args(["set", UUID]) + .args(["--due", value]) + .assert() + .failure() + .get_output() + .clone(); + + assert_eq!(out.status.code(), Some(2), "{value:?} was not a usage error"); + assert_eq!( + fs::read_to_string(worklane.join("backlog").join(&filename)).unwrap(), + before, + "{value:?} changed the ticket anyway" + ); + } +} + +#[test] +fn set_stores_a_valid_due_date_unchanged() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + let filename = create_ticket(&worklane); + + let mut cmd = Command::cargo_bin(BIN_NAME).unwrap(); + cmd.current_dir(temp.path()) + .args(["set", UUID]) + .args(["--due", "2026-12-31"]) + .assert() + .success(); + + let content = fs::read_to_string(worklane.join("backlog").join(&filename)).unwrap(); + assert!(content.contains("- **Due**: 2026-12-31"), "{content}"); +}