Compare commits

..
5 Commits
10 changed files with 1212 additions and 128 deletions
+13 -7
View File
@@ -277,7 +277,7 @@ and this file is for what someone changing worklane's own code needs.
- **The expanded height is a share, not a second constant: half of what the frame and the columns divide.** That is the screen less the tab row and the footer, so the split is even between the two of them rather than even against rows neither gets all of. Half rather than most of it for the same reason the frame is not an overlay: the columns below are the campaign's members, and a reader inspecting the campaign has to go on seeing what it is made of. Floored, so the odd row goes to the cards. `Chrome::frame_rows` takes the height because of this, and `screen_rows` is where it is called, since that is the one place that already has an area to take a share of — which is what keeps `Chrome` itself pure and copyable from `Board::chrome` with no screen to hand
- **The share is bounded at both ends, and `COLUMN_MIN_ROWS` is why.** `Constraint::Min(COLUMN_MIN_ROWS)` would take rows back from a frame that asked for too many, silently, and the frame's own measurement would then disagree with what is drawn — the fault `Chrome` exists to prevent. So the share is capped at what leaves the columns those rows, and floored at `FRAME_ROWS`, since expanding must never shrink the frame. On a board too short to divide, `enter` gives the collapsed height back rather than a height nothing measured. `the_expanded_share_is_bounded_at_both_ends` sweeps every height from 4 to 60, tabbed and not, because one screen that happens to work says nothing about the arithmetic
- **The frame says the rest of what it has to say on its borders**, the trade the detail overlay makes with its title and its page indicator: `(id) ~codename · Name` on the top one, the standing on the bottom right, and `q board` then the page indicator on the bottom left. Every row spent here is a row of cards
- **The frame slot is shared between the two filters, not doubled.** One filter is on at a time, per `Filter`, so a tag frame is the campaign frame with its three slots filled differently: `#tag` in `tag_color` on the top border where the campaign's identity goes, how many tickets carry it on the bottom right where the standing goes, and the annotation in the prose rows. `FrameContent` is what the two are told apart into, and **`frame_content` is the one place they are told apart at all** — the borders, the colour, `q board`, the page indicator, the scroll and the focus are all the campaign frame's, and a second `match` on the filter below that is how the two frames come to behave differently in a way nobody decided
- **The frame slot is shared between the filters, not doubled.** One filter is on at a time, per `Filter`, so a tag frame is the campaign frame with its three slots filled differently: `#tag` in `tag_color` on the top border where the campaign's identity goes, how many tickets carry it on the bottom right where the standing goes, and the annotation in the prose rows. `FrameContent` is what they are told apart into, and **`frame_content` is the one place they are told apart at all** — the borders, the colour, `q board`, the page indicator, the scroll and the focus are all the campaign frame's, and a second `match` on the filter below that is how the frames come to behave differently in a way nobody decided
- **A tag frame draws the annotation, which is the payoff for declaring a tag.** Whoever is browsing a tag is deciding whether the next ticket belongs in it, and the sentence saying when the tag is appropriate is then on the screen at that moment rather than in `tags.md`, which they would have to know to open. An undeclared tag draws `NO_ANNOTATION` in grey, which is also the frame saying the word was never agreed on — the vocabulary file's own placeholder rather than the description section's, so the frame and the file say the same thing about the same tag. A tag declared with nothing said about it draws the same, since here the two have the same nothing to show; the picker's sections are where the difference is actionable
- **A tag has no id, so `y` on its frame copies the word.** A tag *is* its name, matched whole by `ls --tag`, so there are no seven characters to shorten and the `#` the border draws is not part of it — `--tag "#bug"` matches nothing. The footer says `y copy tag` there for the same reason: naming it an id would send the reader looking for a short id on a border that prints a word
- **The count on a tag frame is every column's, drawn or not**, the rule the standing holds. With the filter on, those columns *are* the tickets carrying the tag, so it counts what is below it without counting it a second way. The noun is spelled out and pluralised, because a bare number on a border says nothing about what was counted, and there is no derived state beside it: a tag is a word and not a piece of work, so there is no `[open]` to be in
@@ -296,7 +296,12 @@ and this file is for what someone changing worklane's own code needs.
- **The picker's rows are `Tab::campaigns`, not a copy taken when it opened**, so a campaign filed elsewhere appears in an open picker on the next tick. It opens on the campaign already selected, so `c` on a filtered board says where you are as well as offering somewhere to go, and a board with no campaigns gets a `Notice` rather than an empty box that has to be dismissed to learn it was empty
- **`t` opens the same picker over the tags instead, and taking a tag filters every column to the cards carrying it.** Every tag the board declares or carries, matched whole and case sensitively the way `ls --tag` matches — the box completes the filter, so offering what the filter would refuse is the one bug it must not have. It opens on the tag already applied, the courtesy `c` pays a campaign-filtered board, and a board carrying no tag gets the same `Notice` a board with no campaigns gets
- **A picker row draws a real codename only.** The row opens with the short id, so the card's `~<id>` fallback would print it twice and say nothing the second time
- **One picker serves both lists, and `PickerRow::key` is what keeps it one.** A second picker would have been a second keyboard, query and highlight to keep in step with the first; instead `PickerKind` decides only which list is built and what the answer filters, and everything between the keypress and the filter runs once against the key — a campaign is keyed by its uuid and a tag by itself, both strings the tab can be filtered by. Picking either clears the other without either setter remembering to, because `select_filter` replaces one `Filter`: one field, which is the same reason the frame slot is shared
- **One picker serves both lists, and `PickerRow::key` is what keeps it one.** A second picker would have been a second keyboard, query and highlight to keep in step with the first; instead `PickerKind` decides only which list is built, and everything between the keypress and the filter runs once against the key — which since the pile arrived is a `PickerKey` enum rather than a bare string, because one of the answers filters on an *absence* and carries no string to hand back. `take_picked` reads the kind off the answer rather than off which list was open. Picking any of them clears the others without either setter remembering to, because `select_filter` replaces one `Filter`: one field, which is the same reason the frame slot is shared
- **The campaign picker opens with a row for the tickets in no campaign**, above both sections and never truncated: the pile is the one question about a board of campaigns that no single campaign answers, and on a board whose completed tail is being kept back it would be pushed off the box if it listed among them. It draws its count where a campaign row draws its standing, so picking an empty pile is seen coming; under a query it answers "no campaign" and "none" and hides like any other row. **It selects `Filter::NoCampaign`, its own variant** — `retain_campaign` compares the field to the uuid it is given, so the absence case is a different predicate beside it (`retain_no_campaign`) and not a different value in it, and a magic uuid meaning none is exactly the thing that later matches a real one. A dangling uuid is *set* wrongly and stays out of the view, as it draws `_missing_` on its card rather than nothing at all
- **The pile crosses boards where a campaign cannot, so it is pickable on the merge tab.** An unset field means the same thing in every `.worklane`, the property that lets a tag filter travel there; the count adds across boards, taken at reload off the unfiltered columns like the standings are (`Tab::no_campaign`), never per draw and never off the filtered columns, which would answer zero about themselves
- **The opening highlight still lands on the first campaign, not on the pile.** Campaigns are what this list opens for; the row sits above the list without claiming it — one step up reaches it, it holds the highlight whenever it was the row selected, and only when every campaign is hidden does it take the opening one
- **The frame speaks for the pile in its own words, because the frame question stays `is_whole()`.** Exempting one variant from either half of that rule would be a state where the selection rests on a frame that is not drawn — the one thing `Focus` exists to make unrepresentable. So the title is grey `no campaign` (no id to shorten and no mark, which keeps `~` meaning a campaign and `#` a tag), the standing corner takes the count, and the prose is one grey sentence the board owns, since no file holds words for an absence
- **`y` has nothing to copy from the pile's frame** — no id to shorten and no word a command line takes, `ls --campaign` being unable to say none — so the footer leaves the key out rather than naming it into a notice, and pressing it anyway still answers "nothing to copy"
- **The picker draws two sections, open campaigns above completed, and truncates the completed tail.** One flat list by title put the finished campaigns among the open ones forever, and the tail only grows, so on a board that has run for a while the campaigns worth picking were pushed towards the bottom of the box and eventually off it. Open keeps the index's order, which is by title; completed is by `Created At` newest first, because what a reader recognises about a finished campaign is that it was finished recently. `COMPLETED_SHOWN` of them survive, behind a grey line naming how many older ones are being kept back — rows that are simply gone read as a board that never held them. An unstamped campaign sinks below every stamped one, the rule `by_status_order` holds for a column
- **The tag sections are declared above undeclared, and truncate neither.** The same two-section shape with the opposite reason for the second: a completed campaign is finished with, so its tail is kept back before it pushes the pickable campaigns off the box, while an undeclared tag — a word somebody typed onto a ticket that the board never agreed on — is the row a reader most wants to see. A declared tag no ticket carries stays a row too: `tags.md` is what the board intends, and the vocabulary the listing reports is the one the picker offers. `campaign` and `campaigns` would have sat one under the other here, in different sections, the day the second was invented
- **`picker_list` is the one place that decides what a picker row is**, and `Picker::row` counts *drawn* rows. The sections reorder the campaigns and add rows of their own, so `Tab::campaigns` and the drawn list agree about no number past the first heading, and a row number that meant one thing to the draw and another to a keypress is how a highlight comes to name a campaign nobody chose. The list is derived on every draw and every keypress and never held, which is what keeps a campaign filed elsewhere reaching an open picker on the next tick
@@ -306,7 +311,8 @@ and this file is for what someone changing worklane's own code needs.
- **`/` in the picker is the key it already is on the board**, and `picker_key` can take it because printable keys used to fall through `_ => {}`. Typing filters case insensitively against the short id, the codename and the title — the three things the row draws and the three a campaign is chosen by. Not the summary: a query that matched prose would answer `disk` with every campaign whose description mentions one. A tag answers by itself or by its annotation, which is a reader who cannot remember the word finding it by what it was for — case insensitive here though `--tag` is not, because matching a tag is the filter and searching for one is a reader typing. **An empty query matches everything**, the opposite of `first_match`'s answer and right for the opposite reason: a jump with nothing typed has nowhere to go, while a filter with nothing typed is not filtering, and pressing `/` must not empty the list
- **A query turns the truncation off**, which is the point of having one: the campaign a reader is searching for is exactly the one the truncation hid
- **The query is a layer, and `esc` takes it off before it takes the picker off**, the order `dismiss` closes the board's own layers in. So the list is whole again after that press, not still filtered with nothing on screen saying why. Movement and `enter` stay live under an open query, because a filtered list nothing can move in is a list nothing can be chosen from; every *printable* key goes into the buffer, so `q` types and so does `j`
- **The highlight follows its row, not its row number.** `place_picker` takes a key — a uuid or a tag, whichever list is open — the same string `Tab::filter` holds for either filter: typing, clearing the query and a tick that finishes a campaign all reshape the list, and a number kept across that names whichever campaign now sits at it. One the list no longer holds drops the highlight to the first row that does, which is where an incremental filter puts it. `reload` reads the highlighted key before the lists are rebuilt and puts it back after
- **The highlight follows its row, not its row number.** `place_picker` takes a key — whichever answer `PickerRow::key` hands back, the same shape `Tab::filter` holds for any of them: typing, clearing the query and a tick that finishes a campaign all reshape the list, and a number kept across that names whichever campaign now sits at it. One the list no longer holds drops the highlight to the first row that does, which is where an incremental filter puts it. `reload` reads the highlighted key before the lists are rebuilt and puts it back after
- **Both ends bring the highlight into the window.** Opening aligns against the screen the dispatch hands `open_picker`, and the draw follows the highlight again through `aligned_offset` on the geometry it is actually drawing — a resize between that keypress and the frame, or a tick that put the highlight back without touching the scroll, cannot leave it below the fold until some later keypress fixes it. The stored offset is left alone, the way a column's is: what is drawn is corrected immediately and the next navigation writes the correction back
- **A miss is a row in the box, `no match` in brightred**, where the search prompt puts its own, and `enter` on it leaves the picker and the query exactly as they are so the query can be corrected in place. An empty box says nothing about why it is empty
- **The picker's footer becomes its query**, the trade `draw_search` makes: with every printable key going into a buffer, a list of keys describes nothing that works. `/ search` is named only on the closed query, and the open one names what `esc` does to *it* rather than what it does to the picker
- **The title says both counts while a query is open**, `campaigns (2 of 6)`. The bare total is what the box is, but over a list a query has cut down it is a lie about what is on screen
@@ -455,11 +461,11 @@ and this file is for what someone changing worklane's own code needs.
- `.opencode/agent/feature-planner-agent.md` is **deliberately not folded into `PLAN.md`**. It decomposes a feature request into new tickets, which is intake; `PLAN.md` orders the tickets that already exist. Merging them would give one document two jobs and a frontmatter description that fits neither, which is the same reason the review skill is its own document
- **`install-tool` is a second command, not a flag on `install-skill`, because the two artifacts are not alike.** A skill is inert markdown that any agent can read and it reaches both from one path; the tool is executable TypeScript that reaches opencode alone. Claude Code has no directory it scans for a tool definition at all: `claude mcp add` with a `stdio`, `sse` or `http` transport is the only way a tool enters its tool list, and its plugin system adopts `agents`, `hooks`, `monitors`, `workflows`, `output-styles` and `themes` and nothing named tools. So an MCP server, a different artifact, would be what reached it. Verified against Claude Code 2.1.238
- **`tools_root()` follows `XDG_CONFIG_HOME`, `skills_root()` does not.** `~/.claude` is not an XDG path and opencode's config root is: `opencode debug paths` reports `$XDG_CONFIG_HOME/opencode` with the variable set and `~/.config/opencode` without. An empty value counts as unset, the convention `colors_wanted` follows for `NO_COLOR`. `opencode_tool_dir` takes both variables as arguments for the reason `colors_wanted` does, since a threaded test binary cannot mutate the process environment to reach one branch at a time
- **Singular `tool`, and it was measured, not guessed.** opencode 1.15.10 loads `~/.config/opencode/tool/` and `~/.config/opencode/tools/` both: each was served in turn from a directory outside any project and `/experimental/tool/ids` registered all eleven worklane tools. The singular is the spelling opencode's own documentation puts first, the way it writes `agent(s)` and `skill(s)`. `opencode serve` plus that endpoint is how to check this again; there is no `opencode debug tool` to ask
- **`worklane.ts` is the file name the tool ids are built from.** opencode names each tool as the file then the export, so the file's eleven `export const` lines become `worklane_add` through `worklane_uncheck`. Renaming the file renames every tool and every permission rule that mentions one, which is why `TOOL.relative` is pinned by a test rather than left as a detail
- **The tool needs nothing installed beside opencode**, which is worth stating because the file is executable and reads as though it wants a toolchain. It is loaded into opencode's own Bun runtime and the `@opencode-ai/plugin` import resolves there: a copy in a project with no `node_modules` anywhere above it registered all eleven tools, on a machine with no `bun` on `PATH`. c092ea7's criterion 6 named those two as runtime requirements and it was wrong about both
- **Singular `tool`, and it was measured, not guessed.** opencode 1.15.10 loads `~/.config/opencode/tool/` and `~/.config/opencode/tools/` both: each was served in turn from a directory outside any project and `/experimental/tool/ids` registered every worklane tool the file carried, eleven at the time and twenty-one at the recheck after the wrapper caught up with the CLI. The singular is the spelling opencode's own documentation puts first, the way it writes `agent(s)` and `skill(s)`. `opencode serve` plus that endpoint is how to check this again; there is no `opencode debug tool` to ask
- **`worklane.ts` is the file name the tool ids are built from.** opencode names each tool as the file then the export, so the file's twenty-one `export const` lines become `worklane_add` through `worklane_tags_set`. Renaming the file renames every tool and every permission rule that mentions one, which is why `TOOL.relative` is pinned by a test rather than left as a detail
- **The tool needs nothing installed beside opencode**, which is worth stating because the file is executable and reads as though it wants a toolchain. It is loaded into opencode's own Bun runtime and the `@opencode-ai/plugin` import resolves there: a copy in a project with no `node_modules` anywhere above it registered all of its tools, on a machine with no `bun` on `PATH`. c092ea7's criterion 6 named those two as runtime requirements and it was wrong about both
- **The closing line differs from the skills', and that is not a wording choice.** opencode reads its config once at startup and never reloads it, so a running one keeps the tools it began with; the skills' "on their next session" would be a claim that is not true here
- **The wrapper is behind the CLI and nothing guards it.** It has no tool for `relate`, `campaign`, `assign` or `tags`, so an agent holding the tools cannot reach campaigns or relations at all. `every_tool_the_wrapper_exports_is_a_real_subcommand` catches the drift in the direction that breaks at call time, a tool for a command that no longer exists, and deliberately not the reverse: the gap is real, nobody has decided to close it, and a test asserting it would fail on that decision rather than on a mistake
- **The wrapper walks clap in both directions now; until this ticket nothing did.** It was behind by four commands — `relate`, `campaign`, `assign` and `tags` had no tool, so an agent holding the tools could not reach campaigns or relations at all — and nothing compared the file to the CLI, which is how the gap opened and stayed open. `every_tool_the_wrapper_exports_is_a_real_subcommand` catches a tool for a command that has been renamed or dropped, which fails only when an agent finally calls it; `every_subcommand_outside_the_exceptions_has_a_tool` catches the other direction, a subcommand with no tool, through the same walk off clap the completion lists take. Its exception list carries a reason per entry rather than being bare, and one of those reasons was learned from the test's first run: a bare `worklane campaign` is refused by the CLI, its subcommand required, so there is no command for a `campaign` tool to wrap and the five `campaign_*` tools are the command
- **Installing it globally reproduces fb3dec6 for the wrapper.** Global tools apply in every project including this one, so once `install-tool` has run, an agent working on worklane uses the installed copy of `assets/TOOL.ts` and not the tree it is editing. Same trap as the `worklane` on `PATH`, second instance
- `every_agent_facing_subcommand_is_documented` stays on `SKILL` alone. It owns the CLI surface; a role document uses the handful of commands its job needs, and requiring the rest would fill a review document with `init` and campaigns to satisfy a test. The two checks that do run over every document are the frontmatter and that no document shows a command that does not exist
- **The README command table has the same guard, `every_subcommand_has_a_row_in_the_readme_command_table` in `command.rs`.** The skill and the table are the two places a command is discovered, one by an agent and one by a person, and the skill was the only one under test: `campaign` and `assign` shipped in 0.12.0 and were still absent from the table at 0.20.0, e6e3a1b, along with the `--campaign` flag on the `ls` row. It walks clap's own subcommands, one level of nesting included, against the `|` lines of `README.md`, so a new command fails the suite until the table lists it. `help` is excluded, being clap's. The tag subcommands are named in a `PENDING` list rather than skipped, since f7dd1a1 rewrites that row and emptying the list is part of closing it
Generated
+1 -1
View File
@@ -1503,7 +1503,7 @@ dependencies = [
[[package]]
name = "worklane"
version = "0.32.8"
version = "0.32.12"
dependencies = [
"anyhow",
"assert_cmd",
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "worklane"
version = "0.32.8"
version = "0.32.12"
edition = "2024"
[dependencies]
+1 -1
View File
@@ -27,7 +27,7 @@ Worklane is a local Kanban flow for agentic software development.
| `worklane tags` | Lists the tags the board carries as the tag, a tab and how many tickets carry it, one per line, unstyled and alphabetical. Case sensitive like `ls --tag`, so `bug` and `Bug` list separately and land next to each other. Every status, done included. The one command that answers what tags exist rather than what carries a tag already known |
| `worklane completions <shell>` | Prints a completion script for `fish`, `bash`, `zsh`, `elvish` or `powershell`. See below |
| `worklane install-skill [skill]` | Writes the embedded agent skills to `~/.claude/skills/<skill>/SKILL.md`, which Claude Code and opencode both read. Four ship: `worklane` teaches the CLI, `worklane-review` reviews a finished ticket against the code that claims to close it, `worklane-plan` grooms the board as a whole, its priorities, due dates, tags and campaigns, and `worklane-admin` sets a board up and repairs one, its tag vocabulary and the faults a board can develop. Every document unless one is named. Leaves a modified copy alone unless `--force`; `--print` writes one to stdout instead and needs the name |
| `worklane install-tool` | Writes the embedded opencode tool definitions to `$XDG_CONFIG_HOME/opencode/tool/worklane.ts`, or `~/.config/opencode/tool/` without it, where opencode loads them for every project. One file and so no name to pass. `--force` and `--print` behave as they do for a skill. opencode only: it registers the eleven `worklane_*` tools from the file name and its exports, and Claude Code has no directory it scans for a tool definition, so reaching it would mean an MCP server rather than this. Restart opencode after installing, since it reads its config at startup and never reloads it. Nothing else to install: the file runs inside opencode's own runtime, so neither Bun nor `@opencode-ai/plugin` has to be on the machine |
| `worklane install-tool` | Writes the embedded opencode tool definitions to `$XDG_CONFIG_HOME/opencode/tool/worklane.ts`, or `~/.config/opencode/tool/` without it, where opencode loads them for every project. One file and so no name to pass. `--force` and `--print` behave as they do for a skill. opencode only: it registers the twenty-one `worklane_*` tools from the file name and its exports, and Claude Code has no directory it scans for a tool definition, so reaching it would mean an MCP server rather than this. Restart opencode after installing, since it reads its config at startup and never reloads it. Nothing else to install: the file runs inside opencode's own runtime, so neither Bun nor `@opencode-ai/plugin` has to be on the machine |
## Environment
+373
View File
@@ -497,3 +497,376 @@ function checkboxTool(verb: "check" | "uncheck") {
export const check = checkboxTool("check");
export const uncheck = checkboxTool("uncheck");
/**
* relate is the only writer of the Relations section, so the tool mirrors it rather
* than folding relations into set.
*
* The clear half is one argument per kind rather than a free-text "kind target" line,
* which is what the CLI's single --clear flag would force here. A kind inside a value
* cannot be typed by the schema, a target is a search that may itself contain spaces,
* and splitting the pair apart by hand re-parses what clap already refuses to guess at.
* Per kind the target stays a plain line, the way every other list argument works.
*/
export const relate = tool({
description:
"Record a relation from one ticket to another, or take one off. Kinds: blocked-by means this one waits on that one and its moves are refused while the target is open; regression-of means this one broke that one's fix; relates-to is a neighbour with no dependency. The edge is stored on the ticket you name alone, and show derives the other end for the target, so never record both directions.",
args: {
ticket: tool.schema
.string()
.describe("Ticket UUID prefix (4+ chars) or title substring (required)"),
blocked_by: tool.schema
.string()
.describe("Target tickets this one waits on, one per line.")
.optional(),
regression_of: tool.schema
.string()
.describe("Target tickets whose fix this one broke, one per line.")
.optional(),
relates_to: tool.schema
.string()
.describe("Target tickets this one merely relates to, one per line.")
.optional(),
clear_blocked_by: tool.schema
.string()
.describe("Targets whose blocked-by edge comes off this ticket, one per line.")
.optional(),
clear_regression_of: tool.schema
.string()
.describe("Targets whose regression-of edge comes off this ticket, one per line.")
.optional(),
clear_relates_to: tool.schema
.string()
.describe("Targets whose relates-to edge comes off this ticket, one per line.")
.optional(),
},
async execute(args: Record<string, any>, context: ToolContext) {
if (!args.ticket) {
return "Error relating tickets: ticket is required";
}
const cmd: string[] = ["relate", args.ticket];
if (args.blocked_by) itemLines(args.blocked_by).forEach((line) => cmd.push("--blocked-by", line));
if (args.regression_of) {
itemLines(args.regression_of).forEach((line) => cmd.push("--regression-of", line));
}
if (args.relates_to) itemLines(args.relates_to).forEach((line) => cmd.push("--relates-to", line));
// The kind is spelled the way the flag records it, not the way show prints it:
// the CLI takes either, and the flag spelling is the one with no space in it.
if (args.clear_blocked_by) {
itemLines(args.clear_blocked_by).forEach((line) => cmd.push("--clear", "blocked-by", line));
}
if (args.clear_regression_of) {
itemLines(args.clear_regression_of).forEach((line) => cmd.push("--clear", "regression-of", line));
}
if (args.clear_relates_to) {
itemLines(args.clear_relates_to).forEach((line) => cmd.push("--clear", "relates-to", line));
}
if (cmd.length === 2) {
return "Error relating tickets: name a relation to record or one to clear";
}
try {
return await run(cmd, context);
} catch (err: any) {
return `Error relating tickets: ${err.message}`;
}
},
});
/**
* Five tools for the five campaign subcommands, one export each.
*
* One tool taking an action argument would mirror the CLI nesting, but the schema
* could then no longer say which arguments belong to which action: campaign_set's
* force only means something beside --codename, and campaign_append's description is
* required where add's is not. Separate exports keep each schema true, and the ids
* read as the CLI path anyway, since opencode builds them from this file name plus
* the export: worklane_campaign_set.
*/
export const campaign_add = tool({
description:
"File a new campaign: several separate tickets that have to be finished together for one goal. Its state is derived from its members, so there is nothing to move or close. Give a codename when you can: one word the board draws on every card in the campaign and the shortest thing that addresses it.",
args: {
title: tool.schema
.string()
.describe("Campaign title (required)"),
description: tool.schema
.string()
.describe("What the campaign is for. Use newlines between paragraphs.")
.optional(),
codename: tool.schema
.string()
.describe("One word to call the campaign by, e.g. 'v1' or 'beaver'.")
.optional(),
owner: tool.schema
.string()
.describe("Campaign owner name. If omitted, defaults to the git user.")
.optional(),
},
async execute(args: Record<string, any>, context: ToolContext) {
if (!args.title) {
return "Error adding campaign: title is required";
}
const cmd: string[] = ["campaign", "add", "--title", args.title];
if (args.description) {
descriptionLines(args.description).forEach((line: string) =>
cmd.push("--description", line),
);
}
if (args.codename) cmd.push("--codename", String(args.codename));
if (args.owner) cmd.push("--owner", args.owner);
try {
return await run(cmd, context);
} catch (err: any) {
return `Error adding campaign: ${err.message}`;
}
},
});
export const campaign_set = tool({
description:
"Replace fields on an existing campaign: its title, its description or its codename. Replacing a codename the campaign already has needs force, since everything refers to the campaign by that word once it exists; setting the codename it already carries is a no-op either way. Membership is not set here, use assign.",
args: {
campaign: tool.schema
.string()
.describe("Campaign UUID prefix, codename or title substring (required)"),
title: tool.schema
.string()
.describe("New title. The file is renamed to match, keeping the UUID.")
.optional(),
description: tool.schema
.string()
.describe("New description, replacing the whole section. Use newlines between paragraphs.")
.optional(),
codename: tool.schema
.string()
.describe("New codename, one word. Replacing an existing one needs force.")
.optional(),
force: tool.schema
.boolean()
.describe("Allow replacing a codename the campaign already has.")
.optional(),
},
async execute(args: Record<string, any>, context: ToolContext) {
if (!args.campaign) {
return "Error setting campaign fields: campaign is required";
}
const cmd: string[] = ["campaign", "set", args.campaign];
if (args.title) cmd.push("--title", args.title);
if (args.description) {
descriptionLines(args.description).forEach((line: string) =>
cmd.push("--description", line),
);
}
if (args.codename) cmd.push("--codename", String(args.codename));
if (args.force) cmd.push("--force");
if (cmd.length === 3) {
return "Error setting campaign fields: give at least one field to change";
}
try {
return await run(cmd, context);
} catch (err: any) {
return `Error setting campaign fields: ${err.message}`;
}
},
});
export const campaign_append = tool({
description:
"Add a paragraph to a campaign's description without replacing what is already written. To replace the whole description, use campaign_set.",
args: {
campaign: tool.schema
.string()
.describe("Campaign UUID prefix, codename or title substring (required)"),
description: tool.schema
.string()
.describe("Text to add as a new paragraph at the end of the description (required)."),
},
async execute(args: Record<string, any>, context: ToolContext) {
if (!args.campaign) {
return "Error appending to campaign: campaign is required";
}
if (!args.description) {
return "Error appending to campaign: description is required";
}
const cmd: string[] = ["campaign", "append", args.campaign];
descriptionLines(args.description).forEach((line: string) =>
cmd.push("--description", line),
);
try {
return await run(cmd, context);
} catch (err: any) {
return `Error appending to campaign: ${err.message}`;
}
},
});
export const campaign_ls = tool({
description:
"List campaigns with how far each has got: id, codename or title, owner, and done members against total. Open until every member is done or discarded.",
args: {
ids: tool.schema
.boolean()
.describe("Print only id and title, tab separated, one per line, for parsing.")
.optional(),
},
async execute(args: Record<string, any>, context: ToolContext) {
const cmd = ["campaign", "ls"];
if (args.ids) cmd.push("--ids");
try {
return await run(cmd, context);
} catch (err: any) {
return `Error listing campaigns: ${err.message}, Dir: ${resolveWorklaneDir(context)}`;
}
},
});
export const campaign_show = tool({
description:
"Show a campaign's body and its members grouped by status, done included, so what is finished against what is left is one answer.",
args: {
campaign: tool.schema
.string()
.describe("Campaign UUID prefix, codename or title substring (required)"),
},
async execute(args: Record<string, any>, context: ToolContext) {
if (!args.campaign) {
return "Error showing campaign: campaign is required";
}
try {
return await run(["campaign", "show", args.campaign], context);
} catch (err: any) {
return `Error showing campaign: ${err.message}`;
}
},
});
export const assign = tool({
description:
"Put a ticket in a campaign, moving it out of whichever campaign it was in: a ticket is in at most one. Note the order, campaign first and ticket second, after chown.",
args: {
campaign: tool.schema
.string()
.describe("Campaign UUID prefix, codename or title substring (required)"),
ticket: tool.schema
.string()
.describe("Ticket UUID prefix (4+ chars) or title substring (required)"),
actor: tool.schema
.string()
.describe("Who the entry is attributed to. If omitted, WORKLANE_ACTOR is used, then the git user, then \"unknown\". Set WORKLANE_ACTOR in the environment opencode is started with rather than passing this on every call.")
.optional(),
},
async execute(args: Record<string, any>, context: ToolContext) {
if (!args.campaign) {
return "Error assigning ticket: campaign is required";
}
if (!args.ticket) {
return "Error assigning ticket: ticket is required";
}
const cmd: string[] = ["assign", args.campaign, args.ticket];
if (args.actor) cmd.push("--actor", args.actor);
try {
return await run(cmd, context);
} catch (err: any) {
return `Error assigning ticket: ${err.message}`;
}
},
});
/**
* Three tools for tags, and none for `tags ls`: it prints exactly what the bare
* `worklane tags` listing prints, which the tags tool runs.
*
* The annotation lines go through descriptionLines, not itemLines: an empty value is
* a paragraph break in an annotation, exactly as it is in a description, because the
* value_parser on the CLI side accepts one and the vocabulary file stores prose under
* the tag heading.
*/
export const tags = tool({
description:
"List the tags the board carries: the tag, how many tickets carry it, and the opening line of its declared meaning. Read this before inventing a tag. Case sensitive, so bug and Bug list separately and land next to each other, which is where a near-duplicate is spotted.",
args: {},
async execute(_args: Record<string, any>, context: ToolContext) {
try {
return await run(["tags"], context);
} catch (err: any) {
return `Error listing tags: ${err.message}, Dir: ${resolveWorklaneDir(context)}`;
}
},
});
export const tags_add = tool({
description:
"Declare a tag and what it means: when the next ticket belongs in it. The tag is spelled exactly the way ls --tag matches it, one word with no comma in it.",
args: {
tag: tool.schema
.string()
.describe("The tag to declare (required), e.g. 'bug' or 'frontend'."),
annotation: tool.schema
.string()
.describe("What the tag means and when it is appropriate. Use newlines between paragraphs.")
.optional(),
},
async execute(args: Record<string, any>, context: ToolContext) {
if (!args.tag) {
return "Error declaring tag: tag is required";
}
const cmd: string[] = ["tags", "add", args.tag];
if (args.annotation) {
descriptionLines(args.annotation).forEach((line: string) =>
cmd.push("--annotation", line),
);
}
try {
return await run(cmd, context);
} catch (err: any) {
return `Error declaring tag: ${err.message}`;
}
},
});
export const tags_set = tool({
description:
"Replace what a declared tag means, keeping the tickets carrying it. There is no rename: changing the word itself means rewriting the Tags field of every ticket that carries it, which is a migration and not this call.",
args: {
tag: tool.schema
.string()
.describe("The tag to change, spelled the way it was declared (required)."),
annotation: tool.schema
.string()
.describe("What the tag means, replacing whatever it said before. Use newlines between paragraphs (required)."),
},
async execute(args: Record<string, any>, context: ToolContext) {
if (!args.tag) {
return "Error setting tag meaning: tag is required";
}
if (!args.annotation) {
return "Error setting tag meaning: annotation is required";
}
const cmd: string[] = ["tags", "set", args.tag];
descriptionLines(args.annotation).forEach((line: string) =>
cmd.push("--annotation", line),
);
try {
return await run(cmd, context);
} catch (err: any) {
return `Error setting tag meaning: ${err.message}`;
}
},
});
+6 -6
View File
@@ -11,10 +11,10 @@
//! costs one `worklane ls --ids` per keypress, which measured at 2.5ms in release on a
//! board of seventy-five tickets, comfortably below anything a person notices.
//!
//! The four statuses are half clap's: `Status` is a `ValueEnum`, so it emits them for
//! `mv --status`, but the fish generator does not emit possible values for a *positional*
//! and `ls <status>` gets nothing. Same for `completions <shell>`. So the block below
//! lists those two, from the enums rather than by hand.
//! Status values are half clap's: `Status` is a `ValueEnum`, so clap emits every one
//! of them for `mv --status`, but the fish generator does not emit possible values for
//! a *positional* and `ls <status>` gets nothing. Same for `completions <shell>`. So
//! the block below lists those two, from the enums rather than by hand.
use std::io;
@@ -231,7 +231,7 @@ complete -c worklane -n '{tag_nested}' -a '(worklane tags | cut -f1,3)'
# has a `--clear` of its own that takes a field name, and clap already offers those.
complete -c worklane -n '__worklane_command_is chown' -l clear -x -a '(worklane ls --ids)'
# clap emits the four for `mv --status`, which is an option, but the fish generator
# clap emits the statuses for `mv --status`, which is an option, but the fish generator
# emits nothing for the possible values of a positional. So the one place a status is
# positional needs them listed, and the same goes for the shell below.
complete -c worklane -n '__worklane_first_arg_of ls' -a '{statuses}' -d status
@@ -616,7 +616,7 @@ mod tests {
}
}
/// The four for `mv --status` are clap's, which is half of why `Status` is a
/// The statuses for `mv --status` are clap's, which is half of why `Status` is a
/// `ValueEnum`. If clap ever stops emitting them, the fish half has to carry them
/// too, and this is what says so.
#[test]
+4 -4
View File
@@ -344,10 +344,10 @@ pub fn cmd_add(args: &AddArgs, start: &Path) -> Result<()> {
// format allows: duplicate titles are supported and `add_allows_duplicate_titles`
// pins it. `cmd_campaign_add` deliberately does not carry it either. What is left is
// the write's own failure, named with the ticket and the path the way the other
// writes in the tree name them.
fs::write(&filepath, body).map_err(|e| {
anyhow!("Could not write ticket '{}' at {}: {}", title, filepath.display(), e)
})?;
// writes in the tree name them. Staged like them too: there is no existing content
// to corrupt, but a partial file in backlog is a ticket the listing would read, so
// the same writer as every edit is the one that makes the new file appear whole.
write_then_replace(&worklane_dir, &filepath, &filename, &body, TICKET, title)?;
println!("Created ticket: {}", filename);
Ok(())
+124 -21
View File
@@ -162,7 +162,8 @@ pub fn skills_root() -> Result<PathBuf> {
/// `NO_COLOR`. Checked against opencode 1.15.10.
///
/// Singular `tool`, though 1.15.10 loads `tools` as well: each was served in turn from a
/// directory outside any project and registered all eleven worklane tools. The singular
/// directory outside any project and registered every worklane tool the file carried,
/// eleven at the time and twenty-one at the recheck. The singular
/// is the spelling opencode's own documentation puts first, the way it writes `agent(s)`
/// and `skill(s)`.
///
@@ -569,7 +570,7 @@ mod tests {
}
/// The file name is the tool id prefix, not decoration: opencode names each tool as
/// the file then the export, so a renamed file renames all eleven tools and every
/// the file then the export, so a renamed file renames all twenty-one tools and every
/// permission rule that mentions one.
#[test]
fn the_tool_lands_flat_in_the_root_under_the_name_that_prefixes_its_ids() {
@@ -579,31 +580,18 @@ mod tests {
assert_eq!(TOOL.relative, "worklane.ts");
}
/// Every tool the file exports names a real subcommand.
/// Every tool the file exports names a real subcommand path.
///
/// The guard the fish completion lists already have, pointed the other way: this
/// catches a tool wrapping a command that has been renamed or dropped, which would
/// fail only when an agent finally called it. It cannot catch the reverse, a
/// subcommand the wrapper never grew a tool for, and the wrapper is behind by
/// several: `relate`, `campaign`, `assign` and `tags` have no tool. That is its own
/// ticket, and asserting it here would fail on a gap nobody has decided to close.
/// fail only when an agent finally called it. The converse, a subcommand the wrapper
/// never grew a tool for, is [`every_subcommand_outside_the_exceptions_has_a_tool`].
#[test]
fn every_tool_the_wrapper_exports_is_a_real_subcommand() {
use clap::CommandFactory;
let commands: Vec<String> = subcommand_paths();
let exported = exported_tools();
let commands: Vec<String> = crate::Cli::command()
.get_subcommands()
.map(|command| command.get_name().to_string())
.collect();
let exported: Vec<&str> = TOOL
.content
.lines()
.filter_map(|line| line.strip_prefix("export const "))
.filter_map(|rest| rest.split_whitespace().next())
.collect();
assert_eq!(exported.len(), 11, "{exported:?}");
assert_eq!(exported.len(), 21, "{exported:?}");
for name in exported {
assert!(
commands.iter().any(|command| command == name),
@@ -611,4 +599,119 @@ mod tests {
);
}
}
/// The export names in the tool file: one per `export const`, which is what makes
/// them tool ids once opencode prefixes its file name.
fn exported_tools() -> Vec<&'static str> {
TOOL.content
.lines()
.filter_map(|line| line.strip_prefix("export const "))
.filter_map(|rest| rest.split_whitespace().next())
.collect()
}
/// Every subcommand as the wrapper spells it: the CLI path joined with `_`, since
/// that is how an export name has to be spelled to be an identifier. So
/// `campaign set` is `campaign_set`, and the hyphen in `install-skill` becomes one.
///
/// Walked off clap rather than written out, the way every other guard here is:
/// a hand-maintained list is the very drift this exists to catch.
fn subcommand_paths() -> Vec<String> {
use clap::CommandFactory;
fn walk(command: &clap::Command, prefix: Option<&str>, paths: &mut Vec<String>) {
for sub in command.get_subcommands() {
let name = sub.get_name();
if name == "help" {
continue;
}
let path = match prefix {
Some(prefix) => format!("{prefix}_{name}"),
None => name.to_string(),
};
let path = path.replace('-', "_");
walk(sub, Some(&path), paths);
paths.push(path);
}
}
let mut paths = Vec::new();
walk(&crate::Cli::command(), None, &mut paths);
paths
}
/// Subcommands the wrapper deliberately does not carry, each with why it is left out.
///
/// Spelled the way [`subcommand_paths`] spells a path, so a renamed command leaves a
/// stale entry behind rather than silently exempting nothing.
const NO_TOOL: [(&str, &str); 6] = [
(
"campaign",
"a bare `worklane campaign` is refused by the CLI, its subcommand is required: the five campaign_* tools are the command",
),
(
"tui",
"the board view is for a person: it takes over the terminal and returns only when quit",
),
(
"completions",
"writes a person's shell configuration, which is not an agent's call to make",
),
(
"install_skill",
"installs the skill documents themselves, so an agent running it would rewrite its own instructions mid-session",
),
(
"install_tool",
"installs this very wrapper, which opencode reads once at startup, so reinstalling from inside changes nothing until restart",
),
(
"tags_ls",
"prints exactly what the bare `worklane tags` listing prints, and the tags tool runs that",
),
];
/// The direction that went unguarded until now: every subcommand outside the
/// exception list has a tool.
///
/// This is the gap e6e3a1b taught the README about and the completion lists have
/// never had: a new subcommand reached clap, the completions and the skill, and
/// stopped there, so an agent holding the tools could not call it at all and its
/// only way to the command was to shell out, which is the thing the wrapper exists
/// to avoid. Nothing else walks the wrapper against clap, so without this test the
/// next command lands in the same silence.
#[test]
fn every_subcommand_outside_the_exceptions_has_a_tool() {
let paths = subcommand_paths();
let exported = exported_tools();
// Guard on the walker itself: if it stopped finding subcommands, both filters
// below would pass on nothing.
assert_eq!(paths.len(), 27, "{paths:?}");
assert_eq!(exported.len(), 21, "{exported:?}");
let missing: Vec<&String> = paths
.iter()
.filter(|path| !NO_TOOL.iter().any(|(name, _)| name == path))
.filter(|path| !exported.iter().any(|tool| tool == path))
.collect();
assert!(
missing.is_empty(),
"no tool for {missing:?}. A new subcommand reaches the CLI, the completions \
and the skill, and stops there: give it a tool in assets/TOOL.ts, or name \
it in NO_TOOL with why it should not have one."
);
// An exception naming a subcommand that has gone, or carrying no reason, is
// drift of exactly the kind this test is for.
for (name, reason) in NO_TOOL {
assert!(
paths.iter().any(|path| path == name),
"the exception {name:?} names no subcommand clap has"
);
assert!(!reason.trim().is_empty(), "the exception for {name} carries no reason");
}
}
}
+675 -87
View File
File diff suppressed because it is too large Load Diff
+14
View File
@@ -574,6 +574,12 @@ fn chmod(path: &Path, mode: u32) {
/// itself, and it is named with the ticket and the path rather than raised as a bare io
/// error. The branch this replaces could not fire at all: the filename carries a fresh
/// uuid, and its message claimed the title was taken.
///
/// The add stages through `write_then_replace` like every other write, so the temp
/// lives under `.worklane/`, outside the directory the chmod keeps closed, and the
/// rename is the step that fails here. Both halves have to be gone afterwards: no half
/// ticket in backlog, and no `.wl-*.tmp` beside it, which is what `stray_files` checks
/// for a move.
#[test]
fn add_names_the_ticket_and_the_path_when_the_write_fails() {
let temp = TempDir::new().unwrap();
@@ -596,6 +602,14 @@ fn add_names_the_ticket_and_the_path_when_the_write_fails() {
chmod(&backlog, 0o755);
assert_eq!(fs::read_dir(&backlog).unwrap().count(), 0);
let strays: Vec<String> = fs::read_dir(&worklane)
.unwrap()
.filter_map(|e| e.ok())
.map(|e| e.file_name().into_string().unwrap())
.filter(|name| name.starts_with(".wl-"))
.collect();
assert_eq!(strays, Vec::<String>::new(), "the staging file was left behind");
}
/// The board above the project is real and empty, and stays empty: a dangling