Chapters: a version with an end

A chapter is a named list of a repository's issues that is finished, tagged and closed (#11603). A name (v1.0.0; it becomes the git tag), one sentence of what done means, and the issues in it.

Doors: the page (/chapters, linked from /queue), the terminal (src/tui/screens/chapters.ts, the palette's "Chapters" while an app is open: n drafts, o opens, s ships, c closes (nothing moves; refused with the page's sentence naming what is in the way), u undoes a close within 60 seconds, p patches, enter shows the list where a adds an issue and x takes one out) and the API (GET/POST /api/v1/repos/:owner/:name/chapters, POST …/chapters/:chapter/:verb with open, add, remove, ship, patch). Only a person who administers the repository acts; an agent is refused.

The MCP answers too: the repo tool with view: "chapters" lists a repository's chapters (name, what done means, state); adding chapter: "v1" names that chapter's items (done, building or left), its progress (the same sentence the page and the terminal print, from progressSentence) and finishesOn. chapter without view is invalid; a repository the caller cannot read is refused as the page refuses it.

The same tool acts, for the owner: action is open, add, remove or close, with chapter (and an issue number for add and remove). Without confirm: true it changes nothing and answers { done: false, says }: what it would do (for close, also the tag it would write and the into chapter and moves of what is left), made by the same checks the act makes, so a preview never promises what the act refuses. With confirm: true it does it through the page's own functions (open, fill, close with ship, in src/actions/chapters.ts) and answers { done: true }; each is recorded as the page records it. A refusal is the page's: CHAPTER_WORDS under its code (forbidden for a person who does not administer the repository or an agent, already_open, closed, no_issue, tag_exists, …). A token that may only read gets the previews and is refused the confirmed act. The MCP's close always ships: what is left moves on, so unfinished is the page's refusal only for a close that does not ship.

A closed chapter's list is frozen, so itemsOf keeps it in process memory (at most 200, forgetFrozenItems drops them); an open chapter's list is one pass over the repository's pulls and one grouped read of its runs, however many items it holds, so the anonymous page and API read stay cheap.

The first chapter: v1.0.0

Drafting a chapter named v1.0.0 records the v1 list's issues in it (the issue of every probe in scripts/v1-proven.ts, those that exist in the repository). Closing it (Ship it or Close) runs those read-only probes against the forge's public origin and is refused, naming each probe that does not pass, until every one passes; unproven is not a pass. The close tags the default branch's tip and nothing more: a person cuts the release with scripts/cut-release.ts.

What it has cost (#13261)

An open chapter's page says what it has cost so far and what a chapter of its pace costs, in a line under the progress sentence (costSentence, src/core/chapters.ts). The terminal prints the same sentence after the progress sentence on the chapter's list and on each row of the chapters screen; the MCP repo tool's progress carries it too. A closed chapter keeps its finished page, which already says its cost.

Try it: open /<owner>/<name>/chapters/<open chapter> and read the line under the progress sentence.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs