Walking a wave

A wave names the pulls it carries. You can go from the wave to a pull, to its conversation, and back, on the page and in the terminal.

On the page

  1. Open /<owner>/<repo>/waves and pick a wave, or go to /<owner>/<repo>/waves/<version>.
  2. Tap a pull in its list. The link carries ?from=<owner>/<repo>@<version>, so the pull page knows where you came from.
  3. The pull page opens on its verdict and the conversation. Above the verdict a breadcrumb reads Wave <version> / This pull.
  4. Tap Wave <version> to return to the wave.

The from value is checked against the shape of a wave address before it is used; anything else shows no breadcrumb.

How far the wave got

When a wave's pulls closed issues under a milestone, the wave opens as its headline, then one progress line (<milestone>: 1 of 2 done, the widest milestone it moved), then the highlights. Under Moved each change is a closed fold: tap it to see the pulls of this wave that moved it, and a link to the milestone. Pulls no fold holds (another repository's, or ones that closed no milestone issue) are listed under Pulls; each pull is said once. On the page the line is followed by a bar on its own row, a native <progress> at a fixed width (no script, no inline style, no layout shift at 360px), full when it says 3 of 3 done. A milestone with nothing under it says no issues yet and draws no bar. A wave that moved no milestone has no progress line. The terminal prints the same words but draws no bar. The MCP waves tool says the same line as progress, and the terminal prints it under the date, with each moved milestone's pulls beneath it. Tested in test/wave-folds.test.ts, test/wave-bar.test.ts and test/tui-waves.test.ts.

In the terminal

  1. Open a repository's Waves screen and press Enter on a wave.
  2. n (or Tab) and p move the > mark among the wave's pulls; Enter opens the marked pull.
  3. Esc (or q) on the pull returns to the wave, and again to the list.

Only pulls the viewer may read are listed, and Enter re-checks that before opening one. The walk is tested in test/story-walk.test.ts and test/tui-waves.test.ts.

What a wave changed, in one sentence

Under the headline a wave says in one plain sentence what landed, from the titles of its merged pulls the viewer may read: This wave landed Add search, Fix the nav and 3 more., or No pull in this wave has landed yet. It is built from titles alone (no model), capped at 160 characters, escaped on the page and stripped of control characters in the terminal. The changelog links on to the forge's waves ("Read it by wave"); in the terminal, w on the Changelog screen opens the same waves, then a wave's changes, then a change's pull, and esc returns to the changelog row. Tested in test/wave-sentence.test.ts, test/wave-pulls.test.ts, test/tui-waves.test.ts and test/changelog.test.ts.

A wave's size

Each wave says how big it is in plain numbers, such as 7 changes in 3 apps: on the list row, under the headline on the wave's page, on the terminal's waves list and at the top of a wave there, and as pulls and apps on each item of GET /api/v1/repos/<owner>/<repo>/waves. The numbers count only the pulls you can read, once each, so a guest is not told how many private pulls a wave holds.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs