(c6a61b4) Resolve a board through a pointer file and a shared boards repo, and bump to 0.33.0

This commit is contained in:
Ansho Rei
2026-09-01 17:41:05 +02:00
parent 3892afe819
commit f877e6dbf2
13 changed files with 1200 additions and 32 deletions
+63
View File
@@ -8,6 +8,7 @@
- `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
@@ -52,6 +53,68 @@ rule and the argument traps are written down. Read it before working a ticket in
repo. Do not restate any of it in this file: a second copy is a copy that goes stale,
and this file is for what someone changing worklane's own code needs.
## Shared Boards
- **A project's board is on one of two layouts, and `src/board.rs` is the whole of the
second one.** The local layout is the `.worklane` directory a project has always had.
The shared layout answers `.worklane` being gitignored and not a git repo so a clone
elsewhere has no board: the project commits a `.worklane.toml` naming its board by
uuid, one boards repo is cloned once per machine, and `.worklane` in the project
becomes a *symlink* into it. The symlink is the point: with no `.worklane` directory
`cat .worklane/backlog/*.md` and `ls .worklane/reviewing` would stop working, and that
is the belief the whole file format exists to serve. Because the link is transparent,
`find_worklane_dir` gains 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 optional `dir` overriding 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/share` without it).
- **The pointer is `.worklane.toml`, committed at the project root:**
`[worklane] board = "<uuid>"`, and nothing else. Read and written by `read_pointer` /
`write_pointer`. `write_pointer` leaves 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 is
`util::slug` of 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 to `ls`, 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 as `init` always made
it (AC 12);
- no pointer, config present → create the board, write the pointer, symlink `.worklane`
to 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 --create` as 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. **`--create` is the
`create` field on `Command::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 `.worklane` directory under a pointer → refuse and name the adopt path
(aa80db4), never walk over it (AC 11).
- **The three symlink states are told apart by `classify_worklane`:** `Absent`,
`RealDir`, `Symlink`, `Dangling` and `NotADirectory`. The `Symlink` comparison is
canonicalized, the `Dangling` one 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, `init` still runs once per project per machine,
which is the price of transparent access.
- **Everything under `.worklane` is layout-agnostic.** `create_board_contents` makes the
same status directories, `campaigns/` and `tags.md` for a local and a shared board,
and every reader below `find_worklane_dir` works through the link unchanged.
## Testing
- **Run `make check` before committing**: `cargo fmt --check`, then `cargo clippy --all-targets -- -D warnings`, then `cargo test`, cheapest first. That is the whole of the enforcement, and it is deliberate rather than a stopgap: this repo has no CI and does not want any, and a git hook is a per-clone opt-in the way `blame.ignoreRevsFile` is, so neither can be relied on. What was missing was one name to type, so the two rules below are a command and not a memory. `-D warnings` is what makes clippy's opinion an exit code; a warning printed into a wall of cargo output is unread, not clean. The completion checks are inside `cargo test` rather than a target of their own, since a second thing to remember is the problem this solves
- Run one suite: `cargo test`