Go module with the task tree screen; worktrees on and measured; Go installed

2026-11-10 11:20:21 +11:00
parent a60a4a3067
commit 713774485a
10 changed files with 868 additions and 23 deletions
--- a/tui/.gitignore
+++ b/tui/.gitignore
@@ -0,0 +1,3 @@
+# built binaries and local caches
+/harness
+/tui
--- a/tui/go.mod
+++ b/tui/go.mod
@@ -0,0 +1,29 @@
+module paperclip-harness/tui
+
+go 1.26.5
+
+require (
+	github.com/charmbracelet/bubbletea v1.3.10
+	github.com/charmbracelet/lipgloss v1.1.0
+	github.com/lrstanley/bubblezone v1.0.0
+)
+
+require (
+	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
+	github.com/charmbracelet/colorprofile v0.3.1 // indirect
+	github.com/charmbracelet/x/ansi v0.10.1 // indirect
+	github.com/charmbracelet/x/cellbuf v0.0.13 // indirect
+	github.com/charmbracelet/x/term v0.2.1 // indirect
+	github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect
+	github.com/lucasb-eyer/go-colorful v1.2.0 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/mattn/go-localereader v0.0.1 // indirect
+	github.com/mattn/go-runewidth v0.0.16 // indirect
+	github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6 // indirect
+	github.com/muesli/cancelreader v0.2.2 // indirect
+	github.com/muesli/termenv v0.16.0 // indirect
+	github.com/rivo/uniseg v0.4.7 // indirect
+	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
+	golang.org/x/sys v0.36.0 // indirect
+	golang.org/x/text v0.24.0 // indirect
+)
--- a/tui/go.sum
+++ b/tui/go.sum
@@ -0,0 +1,45 @@
+github.com/aymanbagabas/go-osc52/v2 v2.0.1 h1:HwpRHbFMcZLEVr42D4p7XBqjyuxQH5SMiErDT4WkJ2k=
+github.com/aymanbagabas/go-osc52/v2 v2.0.1/go.mod h1:uYgXzlJ7ZpABp8OJ+exZzJJhRNQ2ASbcXHWsFqH8hp8=
+github.com/charmbracelet/bubbletea v1.3.10 h1:otUDHWMMzQSB0Pkc87rm691KZ3SWa4KUlvF9nRvCICw=
+github.com/charmbracelet/bubbletea v1.3.10/go.mod h1:ORQfo0fk8U+po9VaNvnV95UPWA1BitP1E0N6xJPlHr4=
+github.com/charmbracelet/colorprofile v0.3.1 h1:k8dTHMd7fgw4bnFd7jXTLZrSU/CQrKnL3m+AxCzDz40=
+github.com/charmbracelet/colorprofile v0.3.1/go.mod h1:/GkGusxNs8VB/RSOh3fu0TJmQ4ICMMPApIIVn0KszZ0=
+github.com/charmbracelet/lipgloss v1.1.0 h1:vYXsiLHVkK7fp74RkV7b2kq9+zDLoEU4MZoFqR/noCY=
+github.com/charmbracelet/lipgloss v1.1.0/go.mod h1:/6Q8FR2o+kj8rz4Dq0zQc3vYf7X+B0binUUBwA0aL30=
+github.com/charmbracelet/x/ansi v0.10.1 h1:rL3Koar5XvX0pHGfovN03f5cxLbCF2YvLeyz7D2jVDQ=
+github.com/charmbracelet/x/ansi v0.10.1/go.mod h1:3RQDQ6lDnROptfpWuUVIUG64bD2g2BgntdxH0Ya5TeE=
+github.com/charmbracelet/x/cellbuf v0.0.13 h1:/KBBKHuVRbq1lYx5BzEHBAFBP8VcQzJejZ/IA3iR28k=
+github.com/charmbracelet/x/cellbuf v0.0.13/go.mod h1:xe0nKWGd3eJgtqZRaN9RjMtK7xUYchjzPr7q6kcvCCs=
+github.com/charmbracelet/x/term v0.2.1 h1:AQeHeLZ1OqSXhrAWpYUtZyX1T3zVxfpZuEQMIQaGIAQ=
+github.com/charmbracelet/x/term v0.2.1/go.mod h1:oQ4enTYFV7QN4m0i9mzHrViD7TQKvNEEkHUMCmsxdUg=
+github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f h1:Y/CXytFA4m6baUTXGLOoWe4PQhGxaX0KpnayAqC48p4=
+github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f/go.mod h1:vw97MGsxSvLiUE2X8qFplwetxpGLQrlU1Q9AUEIzCaM=
+github.com/lrstanley/bubblezone v1.0.0 h1:bIpUaBilD42rAQwlg/4u5aTqVAt6DSRKYZuSdmkr8UA=
+github.com/lrstanley/bubblezone v1.0.0/go.mod h1:kcTekA8HE/0Ll2bWzqHlhA2c513KDNLW7uDfDP4Mly8=
+github.com/lucasb-eyer/go-colorful v1.2.0 h1:1nnpGOrhyZZuNyfu1QjKiUICQ74+3FNCN69Aj6K7nkY=
+github.com/lucasb-eyer/go-colorful v1.2.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
+github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
+github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/mattn/go-localereader v0.0.1 h1:ygSAOl7ZXTx4RdPYinUpg6W99U8jWvWi9Ye2JC/oIi4=
+github.com/mattn/go-localereader v0.0.1/go.mod h1:8fBrzywKY7BI3czFoHkuzRoWE9C+EiG4R1k4Cjx5p88=
+github.com/mattn/go-runewidth v0.0.16 h1:E5ScNMtiwvlvB5paMFdw9p4kSQzbXFikJ5SQO6TULQc=
+github.com/mattn/go-runewidth v0.0.16/go.mod h1:Jdepj2loyihRzMpdS35Xk/zdY8IAYHsh153qUoGf23w=
+github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6 h1:ZK8zHtRHOkbHy6Mmr5D264iyp3TiX5OmNcI5cIARiQI=
+github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6/go.mod h1:CJlz5H+gyd6CUWT45Oy4q24RdLyn7Md9Vj2/ldJBSIo=
+github.com/muesli/cancelreader v0.2.2 h1:3I4Kt4BQjOR54NavqnDogx/MIoWBFa0StPA8ELUXHmA=
+github.com/muesli/cancelreader v0.2.2/go.mod h1:3XuTXfFS2VjM+HTLZY9Ak0l6eUKfijIfMUZ4EgX0QYo=
+github.com/muesli/termenv v0.16.0 h1:S5AlUN9dENB57rsbnkPyfdGuWIlkmzJjbFf0Tf5FWUc=
+github.com/muesli/termenv v0.16.0/go.mod h1:ZRfOIKPFDYQoDFF4Olj7/QJbW60Ol/kL1pU3VfY/Cnk=
+github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc=
+github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ=
+github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
+github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e h1:JVG44RsyaB9T2KIHavMF/ppJZNG9ZpyihvCd0w101no=
+github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e/go.mod h1:RbqR21r5mrJuqunuUZ/Dhy/avygyECGrLceyNeo4LiM=
+golang.org/x/exp v0.0.0-20220909182711-5c715a9e8561 h1:MDc5xs78ZrZr3HMQugiXOAkSZtfTpbJLDr/lwfgO53E=
+golang.org/x/exp v0.0.0-20220909182711-5c715a9e8561/go.mod h1:cyybsKvd6eL0RnXn6p/Grxp8F5bW7iYuBgsNCOHpMYE=
+golang.org/x/sys v0.0.0-20210809222454-d867a43fc93e/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.36.0 h1:KVRy2GtZBrk1cBYA7MKu5bEZFxQk4NIDV6RLVcC8o0k=
+golang.org/x/sys v0.36.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+golang.org/x/text v0.24.0 h1:dd5Bzh4yt5KYA8f9CJHCP4FB4D51c2c6JvN37xJJkJ0=
+golang.org/x/text v0.24.0/go.mod h1:L8rBsPeo2pSS+xqN0d5u2ikmjtmoJbDBT1b7nHvFCdU=
--- a/tui/main.go
+++ b/tui/main.go
@@ -0,0 +1,86 @@
+// Command harness is the terminal front end for the Paperclip coding factory.
+//
+// This file only wires flags and starts the program. The screens live in
+// model.go. Every fact the program shows comes from the Paperclip API; nothing
+// is stored locally.
+package main
+
+import (
+	"flag"
+	"fmt"
+	"os"
+
+	tea "github.com/charmbracelet/bubbletea"
+
+	"paperclip-harness/tui/paperclip"
+)
+
+func main() {
+	project := flag.String("project", "", "project id or url key (for example spike-2026-11-10)")
+	dump := flag.Bool("dump", false, "print the task tree as plain text and exit (no full-screen interface)")
+	flag.Parse()
+
+	client, err := paperclip.New()
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+	if !client.UsingUserKey() {
+		fmt.Fprintln(os.Stderr, "warning: PAPERCLIP_BOARD_KEY is not set, so replies and status changes will be refused")
+	}
+
+	proj, err := client.ResolveProject(*project)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+
+	if *dump {
+		if err := dumpTree(client, proj); err != nil {
+			fmt.Fprintln(os.Stderr, err)
+			os.Exit(1)
+		}
+		return
+	}
+
+	// Alternate screen: TUIOS keeps its own scrollback, and a full-screen
+	// program that redraws in place must not fight it.
+	p := tea.NewProgram(newModel(client, proj),
+		tea.WithAltScreen(),
+		tea.WithMouseCellMotion(),
+	)
+	if _, err := p.Run(); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
+
+// dumpTree prints the tree without starting the interface. It is how the data
+// path is checked from a script or over ssh.
+func dumpTree(c *paperclip.Client, proj paperclip.Project) error {
+	rows, err := loadRows(c, proj)
+	if err != nil {
+		return err
+	}
+	fmt.Printf("%s (%s)\n\n", proj.Name, proj.Status)
+	for _, g := range groupOrder {
+		any := false
+		for _, r := range rows {
+			if r.Group != g {
+				continue
+			}
+			if !any {
+				fmt.Printf("%s\n", g)
+				any = true
+			}
+			fmt.Printf("  %-8s %-12s %-14s %s\n", r.Issue.Identifier, r.Issue.Status, r.Who, r.Issue.Title)
+			if r.Blocker != nil && r.Blocker.UnresolvedCount > 0 {
+				fmt.Printf("           blocked by %v\n", r.Blocker.BlockingIdentities)
+			}
+		}
+		if any {
+			fmt.Println()
+		}
+	}
+	return nil
+}
--- a/tui/model.go
+++ b/tui/model.go
@@ -0,0 +1,334 @@
+package main
+
+import (
+	"fmt"
+	"strings"
+	"sync"
+
+	tea "github.com/charmbracelet/bubbletea"
+	"github.com/charmbracelet/lipgloss"
+	zone "github.com/lrstanley/bubblezone"
+
+	"paperclip-harness/tui/paperclip"
+)
+
+// groupOrder is the order of the four status groups on screen 1.
+var groupOrder = []string{"Todo", "In progress", "Blocked", "In review", "Done"}
+
+// Row is one task as the screen needs it: the task itself, who has it, and
+// what Paperclip says blocks it.
+type Row struct {
+	Issue   paperclip.Issue
+	Group   string
+	Who     string
+	Blocker *paperclip.BlockerInfo
+}
+
+type rowsMsg []Row
+type errMsg struct{ err error }
+
+func groupOf(status string) string {
+	switch status {
+	case "todo", "backlog":
+		return "Todo"
+	case "in_progress":
+		return "In progress"
+	case "blocked":
+		return "Blocked"
+	case "in_review":
+		return "In review"
+	case "done", "cancelled":
+		return "Done"
+	}
+	return "Todo"
+}
+
+// loadRows reads the project's tasks from Paperclip, then asks about each
+// task's blockers, because the list endpoint never carries them.
+func loadRows(c *paperclip.Client, proj paperclip.Project) ([]Row, error) {
+	issues, err := c.Issues()
+	if err != nil {
+		return nil, err
+	}
+	mine := make([]paperclip.Issue, 0, len(issues))
+	for _, is := range issues {
+		if is.ProjectID == proj.ID {
+			mine = append(mine, is)
+		}
+	}
+
+	names := map[string]string{}
+	if agents, err := c.Agents(); err == nil {
+		for _, a := range agents {
+			names[a.ID] = a.Name
+		}
+	}
+
+	rows := make([]Row, len(mine))
+	for i, is := range mine {
+		who := "—"
+		switch {
+		case names[is.AssigneeAgent] != "":
+			who = names[is.AssigneeAgent]
+		case is.AssigneeAgent != "":
+			who = "agent"
+		case is.AssigneeUser != "":
+			who = "person"
+		}
+		rows[i] = Row{Issue: is, Group: groupOf(is.Status), Who: who}
+	}
+
+	// One request per task. Bounded so a large project does not open a
+	// hundred sockets at once.
+	var wg sync.WaitGroup
+	sem := make(chan struct{}, 6)
+	for i := range rows {
+		wg.Add(1)
+		go func(i int) {
+			defer wg.Done()
+			sem <- struct{}{}
+			defer func() { <-sem }()
+			info, err := c.Blockers(rows[i].Issue.ID)
+			if err == nil {
+				rows[i].Blocker = &info
+			}
+		}(i)
+	}
+	wg.Wait()
+
+	order := map[string]int{}
+	for i, g := range groupOrder {
+		order[g] = i
+	}
+	// Stable sort by group, then by identifier so the tree does not jump
+	// around between refreshes.
+	for i := 1; i < len(rows); i++ {
+		for j := i; j > 0; j-- {
+			a, b := rows[j-1], rows[j]
+			if order[a.Group] > order[b.Group] ||
+				(order[a.Group] == order[b.Group] && a.Issue.Identifier > b.Issue.Identifier) {
+				rows[j-1], rows[j] = rows[j], rows[j-1]
+				continue
+			}
+			break
+		}
+	}
+	return rows, nil
+}
+
+type model struct {
+	client  *paperclip.Client
+	project paperclip.Project
+	zones   *zone.Manager
+
+	rows    []Row
+	cursor  int
+	err     error
+	loading bool
+
+	width  int
+	height int
+}
+
+func newModel(c *paperclip.Client, proj paperclip.Project) model {
+	return model{
+		client:  c,
+		project: proj,
+		// The click-zone manager is created once, here, and the whole view is
+		// wrapped and scanned through it. Wrapping parts separately drifts
+		// when a pane is resized.
+		zones:   zone.New(),
+		loading: true,
+	}
+}
+
+func (m model) Init() tea.Cmd {
+	return m.reload()
+}
+
+func (m model) reload() tea.Cmd {
+	c, proj := m.client, m.project
+	return func() tea.Msg {
+		rows, err := loadRows(c, proj)
+		if err != nil {
+			return errMsg{err}
+		}
+		return rowsMsg(rows)
+	}
+}
+
+func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
+	switch msg := msg.(type) {
+	case tea.WindowSizeMsg:
+		// Sizes are always taken from the message. Nothing is hardcoded.
+		m.width, m.height = msg.Width, msg.Height
+		return m, nil
+
+	case tea.KeyMsg:
+		switch msg.String() {
+		case "q", "ctrl+c":
+			return m, tea.Quit
+		case "r":
+			m.loading = true
+			return m, m.reload()
+		case "up", "shift+tab":
+			if m.cursor > 0 {
+				m.cursor--
+			}
+			return m, nil
+		case "down", "tab":
+			if m.cursor < len(m.rows)-1 {
+				m.cursor++
+			}
+			return m, nil
+		case "home":
+			m.cursor = 0
+			return m, nil
+		case "end":
+			if len(m.rows) > 0 {
+				m.cursor = len(m.rows) - 1
+			}
+			return m, nil
+		case "esc":
+			// A bare Esc stays free for closing a box. Nothing to close yet.
+			return m, nil
+		}
+
+	case rowsMsg:
+		m.rows = msg
+		m.loading = false
+		m.err = nil
+		if m.cursor >= len(m.rows) {
+			m.cursor = max(0, len(m.rows)-1)
+		}
+		return m, nil
+
+	case errMsg:
+		m.err = msg.err
+		m.loading = false
+		return m, nil
+	}
+	return m, nil
+}
+
+var (
+	titleStyle   = lipgloss.NewStyle().Bold(true)
+	groupStyle   = lipgloss.NewStyle().Bold(true).Foreground(lipgloss.Color("12"))
+	selectedStyle = lipgloss.NewStyle().Foreground(lipgloss.Color("0")).Background(lipgloss.Color("12"))
+	mutedStyle   = lipgloss.NewStyle().Foreground(lipgloss.Color("8"))
+	blockedStyle = lipgloss.NewStyle().Foreground(lipgloss.Color("9"))
+)
+
+// minWidth and minHeight are the smallest box that still shows something
+// honest. Below this the program says so instead of drawing a broken tree.
+const (
+	minWidth  = 56
+	minHeight = 12
+)
+
+func (m model) View() string {
+	if m.width == 0 || m.height == 0 {
+		return "loading…"
+	}
+	if m.width < minWidth || m.height < minHeight {
+		return m.zones.Scan(lipgloss.NewStyle().
+			Width(m.width).Height(m.height).
+			Render(fmt.Sprintf("Window is too small.\nNeed %d×%d, have %d×%d.", minWidth, minHeight, m.width, m.height)))
+	}
+
+	var b strings.Builder
+	b.WriteString(titleStyle.Render(truncate(m.project.Name+"  ·  task tree", m.width)))
+	b.WriteString("\n")
+
+	if m.err != nil {
+		b.WriteString(blockedStyle.Render(truncate("error: "+m.err.Error(), m.width)))
+		b.WriteString("\n")
+	}
+
+	if m.loading && len(m.rows) == 0 {
+		b.WriteString(mutedStyle.Render("reading tasks from Paperclip…"))
+		b.WriteString("\n")
+	}
+
+	lines := 0
+	budget := m.height - 3
+	for _, g := range groupOrder {
+		var group []Row
+		for _, r := range m.rows {
+			if r.Group == g {
+				group = append(group, r)
+			}
+		}
+		if len(group) == 0 {
+			continue
+		}
+		if lines >= budget {
+			break
+		}
+		b.WriteString(groupStyle.Render(fmt.Sprintf("%s  (%d)", strings.ToUpper(g), len(group))))
+		b.WriteString("\n")
+		lines++
+		for _, r := range group {
+			if lines >= budget {
+				break
+			}
+			b.WriteString(m.renderRow(r))
+			b.WriteString("\n")
+			lines++
+		}
+	}
+	if len(m.rows) == 0 && !m.loading && m.err == nil {
+		b.WriteString(mutedStyle.Render("no tasks in this project"))
+		b.WriteString("\n")
+	}
+
+	b.WriteString(mutedStyle.Render(truncate(
+		"↑/↓ or Tab/Shift-Tab move · r refresh · q quit", m.width)))
+
+	// One scan for the whole view.
+	return m.zones.Scan(b.String())
+}
+
+func (m model) renderRow(r Row) string {
+	i := m.indexOf(r.Issue.ID)
+	marker := "  "
+	if i == m.cursor {
+		marker = "▸ "
+	}
+	who := r.Who
+	if who == "" {
+		who = "—"
+	}
+	line := fmt.Sprintf("%s%-8s %-11s %-10s %s", marker, r.Issue.Identifier, r.Issue.Status, who, r.Issue.Title)
+	if r.Blocker != nil && r.Blocker.UnresolvedCount > 0 {
+		line += "  [" + strings.Join(r.Blocker.BlockingIdentities, ", ") + "]"
+	}
+	line = truncate(line, m.width)
+	if i == m.cursor {
+		return m.zones.Mark("row-"+r.Issue.ID, selectedStyle.Render(line))
+	}
+	return m.zones.Mark("row-"+r.Issue.ID, line)
+}
+
+func (m model) indexOf(id string) int {
+	for i, r := range m.rows {
+		if r.Issue.ID == id {
+			return i
+		}
+	}
+	return -1
+}
+
+func truncate(s string, w int) string {
+	if w <= 0 {
+		return ""
+	}
+	r := []rune(s)
+	if len(r) <= w {
+		return s
+	}
+	if w == 1 {
+		return "…"
+	}
+	return string(r[:w-1]) + "…"
+}
--- a/tui/paperclip/client.go
+++ b/tui/paperclip/client.go
@@ -0,0 +1,258 @@
+// Package paperclip is a thin read/write client for the Paperclip control plane.
+//
+// It holds no state. Every value it returns came from Paperclip on this call.
+// Nothing here caches, and nothing here writes to disk.
+package paperclip
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"os"
+	"strings"
+	"time"
+)
+
+// Client talks to one Paperclip instance.
+type Client struct {
+	BaseURL string
+	Company string
+	token   string
+	http    *http.Client
+}
+
+// New builds a client from the environment.
+//
+// The token is read from PAPERCLIP_BOARD_KEY (the person's key) and only falls
+// back to PAPERCLIP_API_KEY for read-only use. The token is never logged.
+func New() (*Client, error) {
+	base := os.Getenv("PAPERCLIP_API_URL")
+	if base == "" {
+		base = "http://127.0.0.1:3100"
+	}
+	company := os.Getenv("PAPERCLIP_COMPANY_ID")
+	if company == "" {
+		company = "d4921013-e5da-4d88-8016-57d5746e2d03"
+	}
+	token := os.Getenv("PAPERCLIP_BOARD_KEY")
+	if token == "" {
+		token = os.Getenv("PAPERCLIP_API_KEY")
+	}
+	if token == "" {
+		return nil, errors.New("no key in the environment: set PAPERCLIP_BOARD_KEY")
+	}
+	return &Client{
+		BaseURL: strings.TrimRight(base, "/"),
+		Company: company,
+		token:   token,
+		http:    &http.Client{Timeout: 20 * time.Second},
+	}, nil
+}
+
+// UsingUserKey reports whether the person's key is in use. Writes need it.
+func (c *Client) UsingUserKey() bool { return os.Getenv("PAPERCLIP_BOARD_KEY") != "" }
+
+type Issue struct {
+	ID             string `json:"id"`
+	Identifier     string `json:"identifier"`
+	Title          string `json:"title"`
+	Status         string `json:"status"`
+	Priority       string `json:"priority"`
+	ProjectID      string `json:"projectId"`
+	ParentID       string `json:"parentId"`
+	AssigneeAgent  string `json:"assigneeAgentId"`
+	AssigneeUser   string `json:"assigneeUserId"`
+	ExecutionState string `json:"-"`
+	UpdatedAt      string `json:"updatedAt"`
+}
+
+type Project struct {
+	ID     string `json:"id"`
+	Name   string `json:"name"`
+	URLKey string `json:"urlKey"`
+	Status string `json:"status"`
+}
+
+// Comment is one entry on a task's thread.
+type Comment struct {
+	ID         string `json:"id"`
+	Body       string `json:"body"`
+	AuthorType string `json:"authorType"`
+	AuthorID   string `json:"authorAgentId"`
+	AuthorUser string `json:"authorUserId"`
+	CreatedAt  string `json:"createdAt"`
+}
+
+// BlockerInfo is what Paperclip says about one task's blockers.
+//
+// The list endpoint does not carry blockers, so the tree asks per task.
+type BlockerInfo struct {
+	IssueID            string
+	UnresolvedCount    int
+	AllBlockersDone    bool
+	DependencyReady    bool
+	Diagnosis          string
+	BlockingIdentities []string
+}
+
+type blockerResponse struct {
+	Diagnosis string `json:"diagnosis"`
+	Readiness struct {
+		AllBlockersDone         bool `json:"allBlockersDone"`
+		DependencyReady         bool `json:"isDependencyReady"`
+		UnresolvedBlockerCount  int  `json:"unresolvedBlockerCount"`
+	} `json:"readiness"`
+	Blockers []struct {
+		Identifier string `json:"identifier"`
+		Title      string `json:"title"`
+		Status     string `json:"status"`
+	} `json:"blockers"`
+}
+
+func (c *Client) do(method, path string, body any, out any) error {
+	var rd io.Reader
+	if body != nil {
+		b, err := json.Marshal(body)
+		if err != nil {
+			return err
+		}
+		rd = bytes.NewReader(b)
+	}
+	req, err := http.NewRequest(method, c.BaseURL+path, rd)
+	if err != nil {
+		return err
+	}
+	req.Header.Set("Authorization", "Bearer "+c.token)
+	req.Header.Set("Accept", "application/json")
+	if body != nil {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	resp, err := c.http.Do(req)
+	if err != nil {
+		var ue *url.Error
+		if errors.As(err, &ue) {
+			return fmt.Errorf("cannot reach Paperclip at %s: %w", c.BaseURL, ue.Err)
+		}
+		return err
+	}
+	defer resp.Body.Close()
+	raw, err := io.ReadAll(io.LimitReader(resp.Body, 8<<20))
+	if err != nil {
+		return err
+	}
+	if resp.StatusCode < 200 || resp.StatusCode > 299 {
+		return fmt.Errorf("%s %s returned %d: %s", method, path, resp.StatusCode, snippet(raw))
+	}
+	if out == nil || len(raw) == 0 {
+		return nil
+	}
+	if err := json.Unmarshal(raw, out); err != nil {
+		return fmt.Errorf("%s %s returned unreadable JSON: %w", method, path, err)
+	}
+	return nil
+}
+
+func snippet(b []byte) string {
+	s := strings.TrimSpace(string(b))
+	if len(s) > 300 {
+		s = s[:300] + "…"
+	}
+	return s
+}
+
+// Projects lists the company's projects.
+func (c *Client) Projects() ([]Project, error) {
+	var out []Project
+	err := c.do("GET", "/api/companies/"+c.Company+"/projects", nil, &out)
+	return out, err
+}
+
+// ResolveProject accepts a project id or url key and returns the project.
+func (c *Client) ResolveProject(ref string) (Project, error) {
+	if ref == "" {
+		return Project{}, errors.New("no project given: use -project <id or urlKey>")
+	}
+	ps, err := c.Projects()
+	if err != nil {
+		return Project{}, err
+	}
+	for _, p := range ps {
+		if p.ID == ref || p.URLKey == ref {
+			return p, nil
+		}
+	}
+	return Project{}, fmt.Errorf("no project matches %q", ref)
+}
+
+// Issues returns every task in the company. The caller filters by project,
+// because the list endpoint takes no project filter.
+func (c *Client) Issues() ([]Issue, error) {
+	var out []Issue
+	err := c.do("GET", "/api/companies/"+c.Company+"/issues", nil, &out)
+	return out, err
+}
+
+// Blockers asks Paperclip what blocks one task.
+func (c *Client) Blockers(issueID string) (BlockerInfo, error) {
+	var raw blockerResponse
+	err := c.do("GET", "/api/issues/"+issueID+"/diagnostics/blockers", nil, &raw)
+	info := BlockerInfo{
+		IssueID:         issueID,
+		UnresolvedCount: raw.Readiness.UnresolvedBlockerCount,
+		AllBlockersDone: raw.Readiness.AllBlockersDone,
+		DependencyReady: raw.Readiness.DependencyReady,
+		Diagnosis:       raw.Diagnosis,
+	}
+	for _, b := range raw.Blockers {
+		info.BlockingIdentities = append(info.BlockingIdentities, b.Identifier+" "+b.Status)
+	}
+	return info, err
+}
+
+// Comments returns a task's thread, oldest first.
+func (c *Client) Comments(issueID string) ([]Comment, error) {
+	var out []Comment
+	err := c.do("GET", "/api/issues/"+issueID+"/comments?order=asc", nil, &out)
+	return out, err
+}
+
+// PostComment writes a comment as the person, which requires the user key.
+func (c *Client) PostComment(issueID, body string) (Comment, error) {
+	if !c.UsingUserKey() {
+		return Comment{}, errors.New("refusing to write with the agent key: set PAPERCLIP_BOARD_KEY")
+	}
+	var out Comment
+	err := c.do("POST", "/api/issues/"+issueID+"/comments", map[string]string{"body": body}, &out)
+	return out, err
+}
+
+// SetStatus changes one task's status as the person.
+func (c *Client) SetStatus(issueID, status, comment string) (Issue, error) {
+	if !c.UsingUserKey() {
+		return Issue{}, errors.New("refusing to write with the agent key: set PAPERCLIP_BOARD_KEY")
+	}
+	payload := map[string]any{"status": status}
+	if comment != "" {
+		payload["comment"] = comment
+	}
+	var out Issue
+	err := c.do("PATCH", "/api/issues/"+issueID, payload, &out)
+	return out, err
+}
+
+type Agent struct {
+	ID     string `json:"id"`
+	Name   string `json:"name"`
+	Status string `json:"status"`
+}
+
+// Agents lists the company's agents, used only to put a name on a task.
+func (c *Client) Agents() ([]Agent, error) {
+	var out []Agent
+	err := c.do("GET", "/api/companies/"+c.Company+"/agents", nil, &out)
+	return out, err
+}