9.5 KiB
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 loopsrc/command.rs- CLI argument definitions using clap derivesrc/completions.rs- the generated completion script and the fish half that asks the boardsrc/handlers.rs- onecmd_*per subcommandsrc/util.rs- the ticket format, resolution, rendering and the palettesrc/campaign.rs- the campaign file format, its resolution, its index and its memberssrc/history.rs- the history log: the path, the kinds, the reader, the writer, the card's counter and the blockshowand the board both rendersrc/board.rs- the shared-board layout: the machine config, the boards directory, the.worklane.tomlpointer and theinitdecision table that decides which layout a project is onsrc/tui.rs- board state, the change digest, and the ratatui drawsrc/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 themsrc/clipboard.rs- the OSC 52 write and the base64 it carries, the board's only way out to the clipboardsrc/install.rs- the embedded agent assets and the compare-and-refuse installassets/SKILL.md- the agent skill for the CLI itself, embedded withinclude_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.mdkeeps its name because the role it teaches is the CLIassets/PLAN.md- the agent skill for grooming the whole board: priorities, due dates, tags and campaignsassets/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 againstPLAN.mdin both directions: this one decides the vocabulary, that one applies itassets/TOOL.ts- the opencode tool definitions wrapping the CLI, embedded the same way and installed byinstall-tool. The only asset that is not a document and the only one that reaches a single agenttests/- Integration tests usingassert_cmdandassert_fs, one file per command- Unit tests live beside the code in
#[cfg(test)] mod tests, inutil.rs,history.rsandtui.rs - Ticket files stored as
.mdin.worklane/<status>/directories - History entries stored as
.mdin.worklane/history/<ticket_uuid>/, one file per entry, beside the status directories for the reason campaigns are - Campaign files stored as
.mdin.worklane/campaigns/, which is beside the status directories and deliberately not instatus_dirs()
Code Organization
changeandsplit_changeare a pair, and they live beside each other inhistory.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 issplit_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
Fromand 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 inquoted_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, andshowdoes not wrap by hand. The board quotes as geometry instead (8020e48): aHistoryPart::Quotedrun 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.Detailholds 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_BARlives inutil.rsbecause both renderers draw it, not because they draw it the same way history.rsowns the log end to end: the path, the kinds, the parse, the write, the count and the render. It came out ofutil.rsandhandlers.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 waycampaign.rsandtag.rsanswer their own questions- The body's painters return cells, not strings:
ordered_cells,inline_cells,metadata_cells,metadata_value_cells,tag_cellsandpush_heading.content_trim_coloredis the CLI entry point andpaint_cellsis the only thing that writes an escape.colorize_lineis gone: it was apubalias for the bold pass with one caller, and the only thing it added was asking the terminal inline_cellswalks 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[36mcarries 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 wascolorize_boldwhile links lived in a branch of their own incontent_parts; that branch is gone, which is also what gives the criteria text and the metadataOtherrows their links, since those already went through this functionshowrenders the Metadata section as a two column table viametadata_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()iscolor_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_coloredskips 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 filenameparse_ticket_field()handles extracting metadata values from markdown formatmove_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 nextmvcorrects- 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_ticketreads 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-fnor 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 realmv, 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
## Metadataheading 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