Files
worklane/docs/architecture.md

9.5 KiB

Architecture

Where the code lives and what each file owns.

Project Structure

  • src/main.rs - dispatch, the one mapping from a parsed command to its handler, the SIGPIPE reset, and the TUI event loop
  • src/command.rs - CLI argument definitions using clap derive
  • src/completions.rs - the generated completion script and the fish half that asks the board
  • src/handlers.rs - one cmd_* per subcommand
  • src/util.rs - the ticket format, resolution, rendering and the palette
  • src/campaign.rs - the campaign file format, its resolution, its index and its members
  • src/history.rs - the history log: the path, the kinds, the reader, the writer, the card's counter and the block show and the board both render
  • src/board.rs - the shared-board layout: the machine config, the boards directory, the .worklane.toml pointer and the init decision table that decides which layout a project is on
  • src/tui.rs - board state, the change digest, and the ratatui draw
  • src/split.rs - one pure function turning a typed line into arguments the way a shell does, plus what the half-typed line is still inside and where the cursor sits among them
  • src/clipboard.rs - the OSC 52 write and the base64 it carries, the board's only way out to the clipboard
  • src/install.rs - the embedded agent assets and the compare-and-refuse install
  • assets/SKILL.md - the agent skill for the CLI itself, embedded with include_str!
  • assets/REVIEW.md - the agent skill for reviewing a finished ticket, shipped the same way. Assets are named after the role they teach; SKILL.md keeps its name because the role it teaches is the CLI
  • assets/PLAN.md - the agent skill for grooming the whole board: priorities, due dates, tags and campaigns
  • assets/ADMIN.md - the agent skill for the board itself: designing and annotating the tag vocabulary, and repairing a board whose files and fields have come apart. The one asset written to hold for a board that tracks no software, so its examples span three subjects on purpose. It draws the line against PLAN.md in both directions: this one decides the vocabulary, that one applies it
  • assets/TOOL.ts - the opencode tool definitions wrapping the CLI, embedded the same way and installed by install-tool. The only asset that is not a document and the only one that reaches a single agent
  • tests/ - Integration tests using assert_cmd and assert_fs, one file per command
  • Unit tests live beside the code in #[cfg(test)] mod tests, in util.rs, history.rs and tui.rs
  • Ticket files stored as .md in .worklane/<status>/ directories
  • History entries stored as .md in .worklane/history/<ticket_uuid>/, one file per entry, beside the status directories for the reason campaigns are
  • Campaign files stored as .md in .worklane/campaigns/, which is beside the status directories and deliberately not in status_dirs()

Code Organization

  • change and split_change are a pair, and they live beside each other in history.rs. The mechanical body is stored as one string, before → after, so painting the halves means splitting it, and the separator is a constant the writer and the reader share. A renderer with its own copy of the spacing would go on splitting on a separator the writer no longer emits, and would say so by drawing a whole body as one half. The split is split_once, so a value carrying the arrow itself keeps it
  • The history block quotes who is talking. Every line of a comment's body draws behind a grey bar spanning the whole run, paragraph breaks included, the way quoted text is drawn — d447e04, taking the review of 2733b10's answer over that ticket's uniform prefix and b304b17's per-line indent, both of which left the continuation at column 0. The reason under a mechanical row draws the same bar. The author line stays at column 0 and is told from a mechanical row by its From and its colour instead; the rule a reader learns is that a barred line is somebody's own words and a line of values at column 0 is the tool reporting itself. With colour off the glyph goes but the width it occupied stays, as spaces derived from the drawn form in quoted_cells, so a pipe keeps the column without an escape byte
  • A quote is one segmentation, two shapes, and the shapes split on wrapping. The CLI prefixes each stored line — quoted_cells, which is why a terminal soft-wrapping a wide line draws continuations bare: a pipe has no width to honour, and show does not wrap by hand. The board quotes as geometry instead (8020e48): a HistoryPart::Quoted run becomes an overlay section laid out as two columns, a two-cell gutter holding the grey bar top to bottom and the body beside it, so a row the prose wraps onto inherits the mark from the gutter rather than from its own first characters. Detail holds sections for this reason — flow stretches full width, quotes beside their gutters — and the clamp sums the sections' wrapped heights, so scroll and draw measure one total. The newline history writes after every quote is consumed by the section builder rather than drawn: it used to close the quote's last line and the section boundary does that now, so drawing it would bank a blank row no entry ever had. QUOTE_BAR lives in util.rs because both renderers draw it, not because they draw it the same way
  • history.rs owns the log end to end: the path, the kinds, the parse, the write, the count and the render. It came out of util.rs and handlers.rs, where the reader, the writer, the counter and the renderer sat in three files and one of them was 5,500 lines. The test for the reason is the module doc: a reader asking what an entry is has one file to open, the way campaign.rs and tag.rs answer their own questions
  • The body's painters return cells, not strings: ordered_cells, inline_cells, metadata_cells, metadata_value_cells, tag_cells and push_heading. content_trim_colored is the CLI entry point and paint_cells is the only thing that writes an escape. colorize_line is gone: it was a pub alias for the bold pass with one caller, and the only thing it added was asking the terminal
  • inline_cells walks the line once for both inline markers, **bold** and [text](url), rather than running one pass over the output of the other. A second pass would be scanning text that already holds escape sequences, and \x1b[36m carries an opening bracket, so the link scan would take the escape for markup. The source is the only string in which either marker means what it says. It was colorize_bold while links lived in a branch of their own in content_parts; that branch is gone, which is also what gives the criteria text and the metadata Other rows their links, since those already went through this function
  • show renders the Metadata section as a two column table via metadata_cells, not line by line. Column width is measured on the raw field names in characters and the padding goes into a cell of its own, so nothing is ever measured with a colour on it: measuring a painted string counts its escapes towards its width. paint() is color_text() with the colour decision passed in, which is what lets a test render both ways in one process
  • The title is printed once, by cmd_show. content_trim_colored skips the # heading in the file content
  • Rules under headings are measured on the displayed name in characters, never on the raw line or in bytes
  • resolve_ticket() scans all status directories — it's the single source for ticket lookup by UUID prefix, title, or filename
  • parse_ticket_field() handles extracting metadata values from markdown format
  • move_ticket_file() stages the updated content in a temp file under .worklane/, renames it over the source, and only then renames the file into the target directory. Do not reorder these: renaming first and writing second leaves a ticket in its new directory claiming the old status, and writing to the target then deleting the source puts it in two directories at once. The temp lives outside the status directories so a leftover is never read as a ticket. A failure at the last step leaves the ticket in its old directory with a Status one move ahead, which the next mv corrects
  • A move whose target equals the directory the file already sits in repairs a Status field that disagrees with it, instead of refusing as a no-op. resolve_ticket reads the current status off the directory, so the old comparison was the directory agreeing with itself and could never see the field; a hand-moved file was stuck with moving it away and back to fix it. Now the field is compared first: agreement is the ordinary already-in-status report with nothing written, disagreement rewrites the field alone through the same in-place save every edit uses, and reports it as a correction rather than a move. It is gated on neither -f nor the dependency guards behind them, because it is not a transition; it writes no stamp, since presence still answers how far the work got and the work arrived nowhere new; and it logs nothing, because an entry shaped like a transition would record a journey the ticket never took. The mirror case is unchanged: a field ahead of its directory after a crash mid-move is corrected by the next real mv, because there the target is a status the ticket is not sitting in
  • Field lookup, read and write, is scoped to the lines under the ## Metadata heading and anchored to the start of the line. Prose above it is free text: tickets in this repo quote field markers in their descriptions, and an unscoped search reads or rewrites those instead. set_status_field() carries the same scoping