diff --git a/AGENTS.md b/AGENTS.md index f0f1cc3..1809229 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,7 +21,8 @@ ## Ticket File Format - Filenames: `_.md` - The slug is the title through `slug()`: lowercased, alphanumerics plus `-` and `_` kept, spaces turned into dashes. `Ticket 06` lands as `_ticket-06.md`. Derive fixture filenames through `slug()`, never by hand -- Metadata fields parsed by `parse_ticket_field()`: `ID`, `Priority`, `Tags`, `Due`, `Owner`, `Created At`, `Campaign`, `Status`. `Campaign` is the one no ticket is born with: `add` does not write it, so it is inserted on demand +- Metadata fields parsed by `parse_ticket_field()`: `ID`, `Priority`, `Tags`, `Due`, `Owner`, `Created At`, `Committed On`, `Submitted On`, `Completed On`, `Campaign`, `Status`. The last four are the ones no ticket is born with: `add` writes none of them, so they are inserted on demand, against `METADATA_ORDER`, which is also what keeps `Status` last +- The three stamps are `mv`'s, written by `set_status_stamp` from `Status::stamp_field`, and they are mutually exclusive: entering a status writes its field, leaving removes it, re-entering restamps. So a ticket carries at most one, the one for the status it is sitting in, and a backward move under `-f` leaves no stale `Completed On` behind. They are current state, like `Status` itself; the trail of how the ticket got there is d4ce964's job and must not be grown here. `backlog` has no stamp, `Created At` already answers for it - Format: `**Field Name**: value` - Ticket structure: `# Title` → `## Description` → `## Acceptance Criteria` → `## Implementation Plan` → `## Metadata` - Comments stored in `.worklane/comments//.md` with `**Comment**`, `**Author**`, `**Time**` fields @@ -86,7 +87,7 @@ and this file is for what someone changing worklane's own code needs. ### Editing a Ticket - `set` replaces a field, `append` adds to a section. The verb carries the meaning, so no flag needs a replace-or-append prefix, and `append` only offers the sections that hold multiple lines -- **One field, one writer.** `set` has no `--owner` (that is `chown`'s) and no `--status` (that is `mv`'s). Do not add either +- **One field, one writer.** `set` has no `--owner` (that is `chown`'s) and no `--status` (that is `mv`'s), and neither `add`, `set`, `append` nor `chown` can reach the three status stamps, which `mv` writes as a side effect of the move. Do not add any of them - `chown` takes the **user first and the ticket second**, after Unix `chown`, and is the only command that does not start with the ticket. Deliberate: the name borrows the Unix association, so the order borrows it too. A swap is left to `resolve_ticket`, which refuses a bare username as a ticket. No argument is inspected to see whether it *also* names a ticket, since such a check would only fire where resolution already fails and would stay silent on the one case it cannot catch, a ticket whose title is the username - `cmd_chown` is `set_metadata_field` plus `save_ticket`, with the same whole-file no-op comparison `set` uses and the same `report()` output, so nothing about writing a field lives twice - Sections are a table in `util.rs`: `DESCRIPTION`, `ACCEPTANCE`, `PLAN`, each with a heading, a label, the placeholder `add` writes when empty, and a `SectionKind`. Adding a section later is one entry, not edits in both commands diff --git a/Cargo.lock b/Cargo.lock index e100763..d3506f2 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1503,7 +1503,7 @@ dependencies = [ [[package]] name = "worklane" -version = "0.17.0" +version = "0.17.1" dependencies = [ "anyhow", "assert_cmd", diff --git a/Cargo.toml b/Cargo.toml index bcbb7b1..c9f2b3c 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "worklane" -version = "0.17.0" +version = "0.17.1" edition = "2024" [dependencies] diff --git a/assets/SKILL.md b/assets/SKILL.md index 9dbffb8..44db4ff 100644 --- a/assets/SKILL.md +++ b/assets/SKILL.md @@ -35,6 +35,12 @@ skipping move, for correcting a mistake. A move is also refused while the ticket is blocked by one that is not done yet, see [Relating tickets](#relating-tickets). +`mv` stamps the time as it goes: `Committed On`, `Submitted On` and `Completed On`, one +field for the status the ticket is in now, shown by `show` among the rest of the +metadata. Only the current one is kept, so the stamp says how long the ticket has been +where it is, not how long each earlier stage took. Nothing else writes them, and moving +a ticket back removes the stamp of the status it left. + ## Reading the board ``` diff --git a/src/handlers.rs b/src/handlers.rs index deb330b..0ce011a 100644 --- a/src/handlers.rs +++ b/src/handlers.rs @@ -662,6 +662,16 @@ pub fn cmd_mv(ticket_id: &str, target: Status, force: bool, start: &Path) -> Res // refused for that reason rather than for whatever the lookup notices first. let content = set_status_field(&resolved, target_status, &title)?; + // Behind every refusal above, so a move that does not happen writes no stamp, and + // spliced in here rather than after the rename so it travels with the same + // crash-safe write the Status field does. + let content = set_status_stamp( + &content, + target, + &Local::now().format(TIMESTAMP_FORMAT).to_string(), + &title, + )?; + let found_filename = find_ticket_file(¤t_path, &parse_ticket_field(&resolved, "ID"), &title)?; diff --git a/src/util.rs b/src/util.rs index 82fa77b..3f35438 100644 --- a/src/util.rs +++ b/src/util.rs @@ -1064,6 +1064,35 @@ fn set_metadata_line( if found { Some(updated) } else { None } } +/// Drop one field from the Metadata section, leaving every other line untouched. +/// +/// Scoped to the section for the same reason as [`set_metadata_line`], and shaped like +/// it: nothing means there was no such field, so a caller that removes a field a ticket +/// never carried leaves the content exactly as it found it rather than rewriting it +/// into an identical string. +fn remove_metadata_line(content: &str, field: &str) -> Option { + let prefix = format!("**{}**:", field); + let mut updated = String::with_capacity(content.len()); + let mut in_metadata = false; + let mut found = false; + + for line in content.lines() { + if line.starts_with("## ") { + in_metadata = is_metadata_heading(line); + } + + if in_metadata && !found && metadata_field_body(line).starts_with(&prefix) { + found = true; + continue; + } + + updated.push_str(line); + updated.push('\n'); + } + + if found { Some(updated) } else { None } +} + pub fn set_status_field(content: &str, target_status: &str, title: &str) -> Result { set_metadata_line(content, "Status", target_status, is_status_line).ok_or_else(|| { anyhow!( @@ -1136,20 +1165,26 @@ pub fn parse_tags(content: &str) -> Vec { .collect() } -/// The metadata fields in the order `add` writes them, with `Campaign` in its place -/// among them. +/// The metadata fields in the order `add` writes them, with the fields no ticket is +/// born with in their places among them. /// /// The anchor list for inserting a field the file does not have yet, exactly as /// [`SECTION_ORDER`] is for a missing section. Campaign sits beside Status because the /// two answer the same kind of question, where the ticket belongs rather than what it -/// is, and Status stays last, which is where every file already keeps it. -const METADATA_ORDER: [&str; 8] = [ +/// is, and Status stays last, which is where every file already keeps it. The three +/// stamps follow `Created At`, since they answer the same question it does about a +/// later moment, and they are in flow order for a reader who sees one after another +/// across a board. +const METADATA_ORDER: [&str; 11] = [ "ID", "Priority", "Tags", "Due", "Owner", "Created At", + COMMITTED_ON_FIELD, + SUBMITTED_ON_FIELD, + COMPLETED_ON_FIELD, CAMPAIGN_FIELD, "Status", ]; @@ -1228,6 +1263,52 @@ fn insert_metadata_field(content: &str, field: &str, value: &str, title: &str) - Ok(join_lines(&out)) } +// The metadata fields `mv` stamps with the time a ticket entered a status. Backlog has +// none: a ticket is filed there, and `Created At` already records when, so a fourth +// field would say the same thing for every ticket that has never moved. +pub const COMMITTED_ON_FIELD: &str = "Committed On"; +pub const SUBMITTED_ON_FIELD: &str = "Submitted On"; +pub const COMPLETED_ON_FIELD: &str = "Completed On"; + +/// Stamp the field of the status being entered and drop the other two. +/// +/// A stamp is present exactly while the ticket sits in its status, so the three are +/// mutually exclusive: entering writes one, leaving removes it, and re-entering +/// restamps rather than keeping the first value. That is what keeps a ticket moved +/// backward under `-f` from carrying a `Completed On` for work it has undone, and it is +/// the line between these fields and d4ce964's history log. Metadata carries current +/// state, which is why `Status` is a field at all; the trail of how the ticket got here +/// belongs to the log, and a stamp left behind would be a second copy of that job. +/// +/// The time comes in as a string rather than being read here, so the caller stamps the +/// same moment it reports and a test can pin the value. +pub fn set_status_stamp(content: &str, target: Status, now: &str, title: &str) -> Result { + let mut content = content.to_string(); + + // Every status but the target, so a skipping move under `-f` clears the stamps of + // the stages it jumped over as well as the one it left. + for status in Status::ALL { + if status == target { + continue; + } + + let Some(field) = status.stamp_field() else { + continue; + }; + + if let Some(updated) = remove_metadata_line(&content, field) { + content = updated; + } + } + + match target.stamp_field() { + // Inserted on demand, the way Campaign is: every ticket written before these + // fields existed carries none of them. + Some(field) => set_or_insert_metadata_field(&content, field, now, title), + None => Ok(content), + } +} + /// Rewrite the title heading, the first `# ` line in the file. /// /// `## ` headings do not match: the second character has to be a space. @@ -2190,6 +2271,20 @@ impl Status { Status::Done, ]; + /// The field `mv` stamps on entering this status, for the three that have one. + /// + /// Derived from the status rather than spelled at the call site, so the mapping is + /// in one place and a fifth status either brings its own stamp or explicitly has + /// none. + pub const fn stamp_field(self) -> Option<&'static str> { + match self { + Status::Backlog => None, + Status::Committed => Some(COMMITTED_ON_FIELD), + Status::Reviewing => Some(SUBMITTED_ON_FIELD), + Status::Done => Some(COMPLETED_ON_FIELD), + } + } + /// The directory name, which is also what clap accepts and what the `Status` field /// holds. A `const fn` so [`DONE`] can be defined from it. pub const fn as_str(self) -> &'static str { @@ -3059,6 +3154,106 @@ mod tests { assert!(error.to_string().contains("Campaign"), "{error}"); } + /// The one stamp the target status carries, and nothing of the others: the fields + /// are current state, not a record of every stage the ticket has been through. + #[test] + fn entering_a_status_stamps_its_field_and_clears_the_rest() { + let content = with_metadata( + "- **ID**: abc\n- **Committed On**: 2026-08-01 09:00:00\n- **Status**: committed\n", + ); + + let updated = + set_status_stamp(&content, Status::Reviewing, "2026-08-22 10:11:12", "T").unwrap(); + + assert!( + updated.contains("- **Submitted On**: 2026-08-22 10:11:12"), + "{updated}" + ); + assert!(!updated.contains("**Committed On**"), "{updated}"); + } + + /// Backlog has no stamp of its own, so a backward move under `-f` leaves the ticket + /// carrying none rather than a Completed On for work it has undone. + #[test] + fn moving_back_to_backlog_leaves_no_stamp_behind() { + let content = with_metadata( + "- **ID**: abc\n- **Completed On**: 2026-08-01 09:00:00\n- **Status**: done\n", + ); + + let updated = + set_status_stamp(&content, Status::Backlog, "2026-08-22 10:11:12", "T").unwrap(); + + assert!(!updated.contains("**Completed On**"), "{updated}"); + assert!(!updated.contains("2026-08-22 10:11:12"), "{updated}"); + assert!(updated.contains("- **ID**: abc\n- **Status**: done\n"), "{updated}"); + } + + /// Re-entry is the time of the move that brought it back, not the first one. + #[test] + fn re_entering_a_status_restamps_rather_than_keeping_the_earlier_value() { + let content = with_metadata( + "- **ID**: abc\n- **Committed On**: 2026-08-01 09:00:00\n- **Status**: backlog\n", + ); + + let updated = + set_status_stamp(&content, Status::Committed, "2026-08-22 10:11:12", "T").unwrap(); + + assert_eq!(updated.matches("**Committed On**:").count(), 1, "{updated}"); + assert!(!updated.contains("2026-08-01 09:00:00"), "{updated}"); + } + + /// Against METADATA_ORDER, like Campaign: after Created At, which answers the same + /// kind of question, and never past Status, which every file keeps last. + #[test] + fn a_stamp_is_inserted_in_its_place_on_a_ticket_that_predates_the_field() { + let content = with_metadata( + "- **ID**: abc\n\ + - **Created At**: 2026-08-01 09:00:00\n\ + - **Campaign**: c-uuid\n\ + - **Status**: reviewing\n", + ); + + let updated = + set_status_stamp(&content, Status::Done, "2026-08-22 10:11:12", "T").unwrap(); + + assert!( + updated.contains( + "- **Created At**: 2026-08-01 09:00:00\n\ + - **Completed On**: 2026-08-22 10:11:12\n\ + - **Campaign**: c-uuid\n\ + - **Status**: reviewing\n" + ), + "{updated}" + ); + } + + /// Removal is scoped to the section for the same reason the write is: a description + /// quoting a field marker is prose, and rewriting it would corrupt the ticket text + /// while leaving the real field in place. + #[test] + fn a_marker_in_the_description_is_not_the_field_being_removed() { + let content = "# T\n\n## Description\n- **Committed On**: not a field\n\n\ + ## Metadata\n\n- **ID**: abc\n- **Status**: backlog\n"; + + let updated = + set_status_stamp(content, Status::Backlog, "2026-08-22 10:11:12", "T").unwrap(); + + assert!(updated.contains("- **Committed On**: not a field"), "{updated}"); + } + + /// Nothing to remove is not a rewrite: the content comes back byte for byte, which + /// is what keeps a move that stamps nothing from touching the file's shape. + #[test] + fn removing_a_field_the_ticket_does_not_carry_leaves_the_content_alone() { + let content = with_metadata("- **ID**: abc\n- **Status**: backlog\n"); + + assert_eq!(remove_metadata_line(&content, COMPLETED_ON_FIELD), None); + assert_eq!( + set_status_stamp(&content, Status::Backlog, "2026-08-22 10:11:12", "T").unwrap(), + content + ); + } + #[test] fn a_campaign_field_that_is_unset_or_absent_reads_as_no_campaign() { assert_eq!(parse_campaign(&with_metadata("- **ID**: abc\n")), None); diff --git a/tests/cmd_ls.rs b/tests/cmd_ls.rs index 4ce79ed..b10e3d6 100644 --- a/tests/cmd_ls.rs +++ b/tests/cmd_ls.rs @@ -662,3 +662,34 @@ fn ls_names_the_four_statuses_when_given_another() { assert!(stderr.contains(status), "{status} is not offered: {stderr}"); } } + +/// The listing reads the fields it prints and nothing else, so the stamps `mv` writes +/// do not reach it. Pinned against a ticket carrying one, since a listing that started +/// showing them would change the output every board and completion script parses. +#[test] +fn ls_output_is_unchanged_by_a_status_stamp() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + + create_ticket(&worklane, "committed", "Stamped", "alice", "2026-06-01"); + let path = worklane + .join("committed") + .join("00000000-0000-0000-0000-000000000001_stamped.md"); + let before = { + let mut cmd = Command::cargo_bin(BIN_NAME).unwrap(); + cmd.current_dir(temp.path()).arg("ls").arg("committed"); + get_stdout(&mut cmd) + }; + + let stamped = fs::read_to_string(&path) + .unwrap() + .replace("- **Status**:", "- **Committed On**: 2026-08-22 09:14:30\n- **Status**:"); + fs::write(&path, stamped).unwrap(); + + let mut cmd = Command::cargo_bin(BIN_NAME).unwrap(); + cmd.current_dir(temp.path()).arg("ls").arg("committed"); + let after = get_stdout(&mut cmd); + + assert_eq!(after, before); + assert!(!after.contains("Committed On"), "{after}"); +} diff --git a/tests/cmd_mv.rs b/tests/cmd_mv.rs index 6390f8f..a082b52 100644 --- a/tests/cmd_mv.rs +++ b/tests/cmd_mv.rs @@ -888,3 +888,173 @@ fn mv_ignores_the_kinds_that_are_not_blockers() { assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr)); assert!(worklane.join("committed").join(&filename).exists()); } + +/// The value of a metadata field, or nothing when the ticket does not carry it. +fn field(content: &str, name: &str) -> Option { + let prefix = format!("- **{}**: ", name); + content + .lines() + .find_map(|line| line.strip_prefix(prefix.as_str())) + .map(str::to_string) +} + +/// `%Y-%m-%d %H:%M:%S`, checked by shape. A test cannot pin the clock, so what it can +/// assert is that the stamp carries the same format `Created At` does. +fn is_timestamp(value: &str) -> bool { + value.len() == 19 + && value.chars().enumerate().all(|(index, c)| match index { + 4 | 7 => c == '-', + 10 => c == ' ', + 13 | 16 => c == ':', + _ => c.is_ascii_digit(), + }) +} + +fn stamped_ticket(worklane: &Path, status: &str) -> String { + create_ticket( + worklane, + status, + "Stamped Task", + "Carries the stamps.", + "cccc3333cccc3333cccc3333cccc3333cccc", + "alice", + "_Not set_", + "test", + ) +} + +fn ticket_at(worklane: &Path, status: &str, filename: &str) -> String { + fs::read_to_string(worklane.join(status).join(filename)).unwrap() +} + +/// One field per status, written with the time of the move, and only the current one: +/// the stamps are where the ticket is now, not the trail of how it got there. +#[test] +fn mv_stamps_the_field_of_the_status_it_enters() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + let filename = stamped_ticket(&worklane, "backlog"); + + for (status, stamp, cleared) in [ + ("committed", "Committed On", "Submitted On"), + ("reviewing", "Submitted On", "Committed On"), + ("done", "Completed On", "Submitted On"), + ] { + let out = move_ticket(&temp, "cccc3333", status, false); + assert!(out.status.success(), "{:?}", out); + + let content = ticket_at(&worklane, status, &filename); + let value = field(&content, stamp) + .unwrap_or_else(|| panic!("no {stamp} after moving to {status}: {content}")); + + assert!(is_timestamp(&value), "{stamp} reads '{value}'"); + assert_eq!(field(&content, cleared), None, "{content}"); + } +} + +/// Backlog has no stamp of its own, so a ticket forced back to it carries none at all +/// rather than a Completed On for work that has been undone. +#[test] +fn mv_removes_the_stamp_of_the_status_it_leaves() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + let filename = stamped_ticket(&worklane, "backlog"); + + move_ticket(&temp, "cccc3333", "done", true); + let done = ticket_at(&worklane, "done", &filename); + assert!(field(&done, "Completed On").is_some(), "{done}"); + + move_ticket(&temp, "cccc3333", "backlog", true); + + let content = ticket_at(&worklane, "backlog", &filename); + for stamp in ["Committed On", "Submitted On", "Completed On"] { + assert_eq!(field(&content, stamp), None, "{content}"); + } +} + +/// Re-entry is the time of the move that brought the ticket back, not the first one. +#[test] +fn mv_restamps_a_status_the_ticket_is_re_entering() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + let filename = stamped_ticket(&worklane, "committed"); + + // Hand-written so the earlier value is old enough to tell from the move's own time, + // which two moves in the same second would not be. + let path = worklane.join("committed").join(&filename); + let seeded = fs::read_to_string(&path) + .unwrap() + .replace("- **Status**:", "- **Committed On**: 2020-01-01 00:00:00\n- **Status**:"); + fs::write(&path, seeded).unwrap(); + + move_ticket(&temp, "cccc3333", "backlog", true); + move_ticket(&temp, "cccc3333", "committed", false); + + let content = ticket_at(&worklane, "committed", &filename); + let value = field(&content, "Committed On").expect(&content); + + assert!(is_timestamp(&value), "{value}"); + assert_ne!(value, "2020-01-01 00:00:00"); + assert_eq!(content.matches("**Committed On**:").count(), 1, "{content}"); +} + +/// The fixture predates the fields, as every ticket on a real board does, so the line +/// is inserted rather than rewritten. Against METADATA_ORDER, which keeps Status last. +#[test] +fn mv_inserts_the_stamp_before_the_status_field() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + let filename = stamped_ticket(&worklane, "backlog"); + + move_ticket(&temp, "cccc3333", "committed", false); + + let content = ticket_at(&worklane, "committed", &filename); + let value = field(&content, "Committed On").expect(&content); + + assert!( + content.contains(&format!( + "- **Owner**: alice\n- **Committed On**: {}\n- **Status**: committed\n", + value + )), + "{content}" + ); + assert!(content.ends_with("- **Status**: committed\n"), "{content}"); +} + +/// Behind the refusals, all of them: a move that does not happen leaves the file exactly +/// as it was, stamp included. +#[test] +fn mv_writes_no_stamp_when_the_move_is_refused() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + + let backward = stamped_ticket(&worklane, "committed"); + let before = ticket_at(&worklane, "committed", &backward); + + let out = move_ticket(&temp, "cccc3333", "backlog", false); + assert!(!out.status.success()); + assert_eq!(ticket_at(&worklane, "committed", &backward), before); + + // The blocked ticket takes the other refusal, which sits after the no-op return. + let blocked = create_gated_pair(&worklane, &temp, "backlog"); + let before = ticket_at(&worklane, "backlog", &blocked); + + let out = move_ticket(&temp, "aaaa1111", "committed", false); + assert!(!out.status.success()); + assert_eq!(ticket_at(&worklane, "backlog", &blocked), before); +} + +/// A move to the status the ticket is already in returns before anything is written, so +/// it does not restamp either. +#[test] +fn mv_does_not_restamp_a_no_op_move() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + let filename = stamped_ticket(&worklane, "committed"); + let before = ticket_at(&worklane, "committed", &filename); + + let out = move_ticket(&temp, "cccc3333", "committed", false); + assert!(out.status.success()); + + assert_eq!(ticket_at(&worklane, "committed", &filename), before); +} diff --git a/tests/cmd_show.rs b/tests/cmd_show.rs index 66d8619..7f63bdf 100644 --- a/tests/cmd_show.rs +++ b/tests/cmd_show.rs @@ -489,6 +489,39 @@ fn show_renders_the_metadata_as_an_aligned_table() { assert!(content.contains("- **Owner**: alice")); } +/// The stamps `mv` writes are fields like any other: the table renders what the file +/// holds, so nothing here knows their names, and the column widens to the longest of +/// them the way it does for anything else. +#[test] +fn show_renders_a_status_stamp_in_the_metadata_table() { + let temp = TempDir::new().unwrap(); + let worklane = setup_worklane(&temp); + + let filename = "abc123def456789012345678901234567890_stamped.md"; + fs::write( + worklane.join("committed").join(filename), + "# Stamped Ticket\n\n## Metadata\n\n\ + - **ID**: abc123def456789012345678901234567890\n\ + - **Created At**: 2026-08-20 15:51:01\n\ + - **Committed On**: 2026-08-22 09:14:30\n\ + - **Status**: committed\n", + ) + .unwrap(); + + let mut cmd = Command::cargo_bin(BIN_NAME).unwrap(); + cmd.current_dir(temp.path()).arg("show").arg("Stamped"); + let stdout = get_stdout(&mut cmd); + + assert!( + stdout.contains( + "Created At 2026-08-20 15:51:01\n\ + Committed On 2026-08-22 09:14:30\n\ + Status committed\n" + ), + "{stdout:?}" + ); +} + /// Write a ticket with an exact uuid and title, since both matter to resolution. fn ticket_with(worklane: &std::path::Path, status: &str, uuid: &str, title: &str, slug: &str) { fs::write(