(c6a61b4) Resolve a board through a pointer file and a shared boards repo, and bump to 0.33.0
This commit is contained in:
@@ -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`
|
||||
|
||||
Reference in New Issue
Block a user