6.4 KiB
6.4 KiB
Boards on Disk
The two board layouts, the pointer file, and how a board is found from a working directory.
Shared Boards
- A project's board is on one of two layouts, and
src/board.rsis the whole of the second one. The local layout is the.worklanedirectory a project has always had. The shared layout answers.worklanebeing gitignored and not a git repo so a clone elsewhere has no board: the project commits a.worklane.tomlnaming its board by uuid, one boards repo is cloned once per machine, and.worklanein the project becomes a symlink into it. The symlink is the point: with no.worklanedirectorycat .worklane/backlog/*.mdandls .worklane/reviewingwould stop working, and that is the belief the whole file format exists to serve. Because the link is transparent,find_worklane_dirgains no resolution code at all (c6a61b4 AC 14). - The machine config lives at
$XDG_CONFIG_HOME/worklane/config.toml(default~/.config, empty counts as unset). It carries a[boards]section holding the url of the boards repo and an optionaldiroverriding where the boards directory sits — the config is this machine's answer, and the pointer carries no server address, so a client repo never holds an internal hostname. The boards directory itself defaults to$XDG_DATA_HOME/worklane/boards(~/.local/sharewithout it). - The pointer is
.worklane.toml, committed at the project root:[worklane] board = "<uuid>", and nothing else. Read and written byread_pointer/write_pointer.write_pointerleaves a pointer that already names the same board alone — it is a committed file and rewriting it writes nothing new, which is what keeps "init symlinks it and creates nothing" true for a fresh clone. - A board directory is
<uuid>_<slug>, named after the ticket files. The slug isutil::slugof the project's directory name, and resolution (resolve_board) is a uuid prefix match, the bargain the ticket filenames already make: the directory stays readable tols, identity is stable, and renaming a board breaks no committed pointer. - The decision table is
decide_init, one match. The reason it is a table rather than a fallback is that no branch may fall through into creating a board, so each row returns its own outcome. The rows:- no pointer, no
[boards]config → local.worklane, exactly asinitalways made it (AC 12); - no pointer, config present → create the board, write the pointer, symlink
.worklaneto it (AC 4); - pointer present, board found → symlink it and create nothing (AC 5);
- pointer present, board absent → refuse. A committed pointer is proof the board exists
somewhere, so a missing board is an unsynced machine, and creating a second board
there produces two boards with one name and a manual merge — the worst outcome in the
design. The refusal says so and names
init --createas the only way to make one (AC 6/7). The fetch-and-look-again half of the ticket is deferred: nothing pulls the boards repo yet, and the refusal names it rather than doing it.--createis thecreatefield onCommand::Init, the escape hatch under that row; - the boards directory itself missing → a distinct refusal saying the boards repo is not cloned here (AC 8);
- the correct symlink already in place → no change, nothing written (AC 9);
- a symlink to a different board → refuse rather than repoint it: changing what a project is on without asking is how two machines come to disagree about the work (AC 10);
- a symlink that dangles → refuse rather than replace it without asking;
- a real
.worklanedirectory under a pointer → refuse and name the adopt path (aa80db4), never walk over it (AC 11).
- no pointer, no
- The three symlink states are told apart by
classify_worklane:Absent,RealDir,Symlink,DanglingandNotADirectory. TheSymlinkcomparison is canonicalized, theDanglingone is lexical (a dangling link cannot be canonicalized) and checks for the relative spelling this tool writes or the absolute board path. - The symlink target is relative to the link's own parent, so it uses no home
directory path and the link is portable in that limited sense; an absolute target
appearing anywhere is how a home directory leaks into a write. Because a relative
target depends on how deep a repo sits,
initstill runs once per project per machine, which is the price of transparent access. - Everything under
.worklaneis layout-agnostic.create_board_contentsmakes the same status directories,campaigns/andtags.mdfor a local and a shared board, and every reader belowfind_worklane_dirworks through the link unchanged.
Finding the Board
find_worklane_dirclassifies the entry before it follows it.exists()follows a link, so a.worklanethat was a dangling symlink answered the same as no.worklaneat all: the walk carried on up the tree and the first board above the project became the one every write landed in, silently.classifyreadssymlink_metadatafirst and answers one of four,Absent,Board,DanglingorNotADirectory, andAbsentis the only one the walk carries on from. A.worklanethat is there but unusable is this project's board and is reported, not handed upward- Anything other than
NotFoundfromsymlink_metadatais an error rather than anAbsent. Reading a filesystem that could not answer as nothing-there is how the walk-past worked in the first place - The dangling failure names the target and says the boards repo may not be cloned, and deliberately does not say to run
worklane init. Once the boards live outside the project a dangling link is an ordinary state, what you have before the boards repo is cloned and after a board directory is renamed, so "no board found, run init" points at the wrong problem - A link that resolves is indistinguishable from a real directory, and what comes back is the link rather than its target.
.worklane/backlog/*.mdhas to read the same either way and nothing downstream learns whether the board is local, which is the property the shared-boards layout rests on - A regular file at that path is an error as well. It is a plausible future pointer form, and reading it as one is that change's decision to make; stepping over it and writing to a board above is the one answer that is wrong today