Commit `2dd892270a`

2dd892270a06712ae7086eebc2450aa92976d7d6

parent: 9a566ebe6f

Verified · cmc

cmc <hello@cleberg.net> · 2026-09-24 00:41 UTC

docs/plans: CLI output refresh

Ref #254

docs/plans/2026-09-23-cli-output-refresh.md added +3371

		@@ -0,0 +1,3371 @@
	1	# CLI output refresh implementation plan
	2
	3	> For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
	4
	5	Goal: Terminal rendering for tables, `show` views and help, selected
	6	by the client, with piped output unchanged in shape, plus the audit
	7	fixes from 2026-09-23.
	8
	9	Architecture: The server renders. The CLI sends
	10	`GITBAY_TERM=<cols>[,color]` on the SSH session; sshd parses it into
	11	`Ctx.Term`; a `table` helper, a `view` helper and an
	12	`internal/termtext` renderer pick terminal or plain output from it.
	13	The CLI adds a pager and a grouped root help. Help text (flag
	14	descriptions, examples) moves into the command registry.
	15
	16	Tech stack: Go, `golang.org/x/crypto/ssh`, goldmark, go-org,
	17	chroma v2, `golang.org/x/text/width`, `golang.org/x/term`, cobra.
	18
	19	Spec: `docs/specs/2026-09-23-cli-output-refresh-design.md`
	20
	21	## Global constraints
	22
	23	- Five MRs, in order, each on its own branch off `main`:
	24	`cli-output-refresh` (Part 1, already holds the spec and this
	25	plan), `cli-output-tables` (Part 2), `cli-output-views` (Part 3),
	26	`cli-output-help` (Part 4), `cli-output-docs` (Part 5).
	27	- Commits are signed (the repository refuses unsigned ones), end with
	28	`Ref #254`; the last commit of Part 5 says `Closes #254`. No
	29	attribution to any assistant or model anywhere.
	30	- MR: `gitbay mr create --source <branch> --target main --title "..."`;
	31	merge with `gitbay mr merge <n> --strategy ff` after CI is green,
	32	then delete the branch locally and on the remote. If the merge says
	33	the branch is behind, rebase onto `main`, force-push, merge again.
	34	- Locally run `go build ./...`, `go vet ./...` (catches test callers
	35	after a signature change), and the unit tests of touched packages.
	36	Run at most the one e2e test being written:
	37	`go test ./e2e -run TestName -count=1`. CI on bay1 runs the rest.
	38	- `--json` output never changes shape except where a task says so
	39	(Part 1 `release list` paging, Part 4 `help --json` gaining two
	40	fields).
	41	- Piped (plain) output keeps its row shape: tab-separated, no header.
	42	Timestamps in plain output become RFC3339 to the second in UTC
	43	(`2026-09-23T23:26:00Z`).
	44	- No ANSI byte (`\x1b`) ever reaches plain output.
	45	- Terminal timestamps: `2006-01-02 15:04 UTC` in views, relative ages
	46	in tables (`just now`, `5m ago`, `2h ago`, `3d ago` under 14 days,
	47	`3w ago` under 8 weeks, then `2006-01-02`).
	48	- Colours are ANSI 16-colour: green (`--ok`), magenta (`--done`), red
	49	(`--bad`), dim (`--neutral`).
	50	- Comments and docs: plain, terse, no before/after commentary.
	51
	52	## File map
	53
	54	\| File \| Part \| Responsibility \|
	55	\|---\|---\|---\|
	56	\| `internal/store/releases.go` \| 1 \| `ListReleasesPage` \|
	57	\| `internal/control/release.go` \| 1 \| `release list` paging, empty title \|
	58	\| `internal/control/notifications.go` \| 1 \| device add message \|
	59	\| `internal/control/dashboard.go` \| 1, 2 \| `none` under empty sections; tables \|
	60	\| `internal/control/term.go` \| 2 \| `Term`, `ParseTerm`, ANSI, cell width, clip, timestamps \|
	61	\| `internal/control/table.go` \| 2 \| `table`, typed cells \|
	62	\| `internal/control/control.go` \| 2, 4 \| `Ctx.Term`, `Ctx.Argv`, `Command.Flags/Examples`, help \|
	63	\| `internal/control/cursor.go` \| 2 \| `more:` hint in terminal mode \|
	64	\| `internal/sshd/sshd.go` \| 2 \| `env` request, `Exec` takes a `Term` \|
	65	\| `cmd/gitbayd/system.go` \| 2 \| forced command reads `GITBAY_TERM` \|
	66	\| `cmd/gitbay/ssh.go` \| 2, 3 \| `SetEnv`, `--no-color`, pager; `alignColumns` removed \|
	67	\| `internal/control/*.go` list sites \| 2 \| every list command on `table` \|
	68	\| `internal/termtext/` \| 3 \| markdown and org to terminal text \|
	69	\| `internal/control/view.go` \| 3 \| layout of every `show` \|
	70	\| `internal/control/help.go` \| 4 \| help rendering, noun summaries \|
	71	\| `cmd/gitbay/main.go` \| 4 \| summaries from the generated table, grouped root help \|
	72	\| `cmd/gitbay/summaries_gen.go` \| 4 \| generated from the registry \|
	73	\| `e2e/readonly_test.go`, `e2e/ssh_test.go`, `e2e/term_test.go` \| 2, 3 \| terminal and plain checks over real ssh \|
	74	\| `.gitbay/wiki/Users.org`, `Admin.org`, `CHANGELOG.org` \| 5 \| rules, operator note, release note \|
	75
	76	---
	77
	78	# Part 1: audit fixes (branch `cli-output-refresh`)
	79
	80	### Task 1.1: `release list` pages and drops a title equal to its tag
	81
	82	Files:
	83	- Modify: `internal/store/releases.go` (`ListReleases`, around line 92)
	84	- Modify: `internal/control/release.go:29-31` (registration), `:199-220` (`runReleaseList`)
	85	- Modify: `cmd/gitbay/main.go` (the `release list` `pass()` short text)
	86	- Test: `internal/control/release_test.go` (create)
	87
	88	Interfaces:
	89	- Produces: `func (s *Store) ListReleasesPage(repoID int64, limit int, afterID int64) ([]Release, error)` — newest first by `(created_at, id)`; `limit` 0 means all; `afterID` 0 means from the start.
	90
	91	- [ ] Step 1: Write the failing test
	92
	93	```go
	94	package control
	95
	96	import (
	97	"bytes"
	98	"strings"
	99	"testing"
	100
	101	"gitbay.org/gitbay/internal/protocol"
	102	"gitbay.org/gitbay/internal/store"
	103	)
	104
	105	func TestReleaseListPagesAndHidesTagTitle(t *testing.T) {
	106	st, repo, uid := newQueueTestRepo(t)
	107	for _, tag := range []string{"v1", "v2", "v3"} {
	108	title := tag
	109	if tag == "v2" {
	110	title = "Second"
	111	}
	112	if _, err := st.CreateRelease(repo.ID, tag, title, "", uid, "md"); err != nil {
	113	t.Fatal(err)
	114	}
	115	}
	116	c, errOut := pruneCtx(st, t.TempDir(), store.User{ID: uid})
	117	if code := Dispatch(c, []string{"release", "list", repo.Path(), "--limit", "2"}); code != protocol.ExitOK {
	118	t.Fatalf("exit %d: %s", code, errOut)
	119	}
	120	lines := strings.Split(strings.TrimSpace(c.Stdout.(*bytes.Buffer).String()), "\n")
	121	if len(lines) != 3 \|\| lines[0] != "v3\t\t0 asset(s)" \|\| lines[1] != "v2\tSecond\t0 asset(s)" \|\| !strings.HasPrefix(lines[2], "next\t") {
	122	t.Fatalf("page 1:\n%s", strings.Join(lines, "\n"))
	123	}
	124	cursor := strings.TrimPrefix(lines[2], "next\t")
	125
	126	c, errOut = pruneCtx(st, t.TempDir(), store.User{ID: uid})
	127	if code := Dispatch(c, []string{"release", "list", repo.Path(), "--cursor", cursor}); code != protocol.ExitOK {
	128	t.Fatalf("exit %d: %s", code, errOut)
	129	}
	130	if got := c.Stdout.(*bytes.Buffer).String(); got != "v1\t\t0 asset(s)\n" {
	131	t.Fatalf("page 2: %q", got)
	132	}
	133	}
	134	```
	135
	136	The three releases can share a `created_at` second; the `(created_at, id)` order is what keeps the pages stable.
	137
	138	- [ ] Step 2: Run it and see it fail
	139
	140	Run: `go test ./internal/control -run TestReleaseListPagesAndHidesTagTitle -count=1`
	141	Expected: FAIL, exit 2 (`--limit` is not accepted).
	142
	143	- [ ] Step 3: Store
	144
	145	Replace `ListReleases` in `internal/store/releases.go` with:
	146
	147	```go
	148	func (s *Store) ListReleases(repoID int64) ([]Release, error) {
	149	return s.ListReleasesPage(repoID, 0, 0)
	150	}
	151
	152	// ListReleasesPage lists newest first. limit 0 is every row; afterID is
	153	// the last release of the previous page, 0 for the first.
	154	func (s *Store) ListReleasesPage(repoID int64, limit int, afterID int64) ([]Release, error) {
	155	q := releaseSelect + " WHERE r.repo_id = ?"
	156	args := []any{repoID}
	157	if afterID > 0 {
	158	q += " AND (r.created_at, r.id) < (SELECT created_at, id FROM releases WHERE id = ?)"
	159	args = append(args, afterID)
	160	}
	161	q += " ORDER BY r.created_at DESC, r.id DESC"
	162	if limit > 0 {
	163	q += " LIMIT ?"
	164	args = append(args, limit)
	165	}
	166	rows, err := s.DB.Query(q, args...)
	167	if err != nil {
	168	return nil, err
	169	}
	170	defer rows.Close()
	171	var out []Release
	172	for rows.Next() {
	173	var r Release
	174	if err := rows.Scan(&r.ID, &r.RepoID, &r.Tag, &r.Title, &r.Notes, &r.NotesFormat, &r.Author, &r.CreatedAt); err != nil {
	175	return nil, err
	176	}
	177	out = append(out, r)
	178	}
	179	if err := rows.Err(); err != nil {
	180	return nil, err
	181	}
	182	for i := range out {
	183	if err := s.releaseAssets(&out[i]); err != nil {
	184	return nil, err
	185	}
	186	}
	187	return out, nil
	188	}
	189	```
	190
	191	- [ ] Step 4: Command
	192
	193	Registration usage becomes `release list <owner/name> [--limit <n>] [--cursor <c>]`. `runReleaseList`:
	194
	195	```go
	196	func runReleaseList(c *Ctx, args []string) int {
	197	rest, p, code := parsePageFlags(c, args, "release", true)
	198	if code >= 0 {
	199	return code
	200	}
	201	if len(rest) != 1 {
	202	return c.usage()
	203	}
	204	repo, code := resolveRepo(c, rest[0], policy.CanRead)
	205	if code >= 0 {
	206	return code
	207	}
	208	rels, err := c.Store.ListReleasesPage(repo.ID, p.queryLimit(), p.keyInt())
	209	if err != nil {
	210	return c.fail(protocol.ExitFailure, "%v", err)
	211	}
	212	rels, next := trimPage(p, rels, "release", func(r store.Release) string { return strconv.FormatInt(r.ID, 10) })
	213	var ds []releaseOut
	214	for _, r := range rels {
	215	ds = append(ds, releaseToOut(r, false))
	216	}
	217	return c.emitPage(p, ds, next, func(w io.Writer) {
	218	for _, d := range ds {
	219	title := d.Title
	220	if title == d.Tag {
	221	title = ""
	222	}
	223	fmt.Fprintf(w, "%s\t%s\t%d asset(s)\n", d.Tag, title, len(d.Assets))
	224	}
	225	})
	226	}
	227	```
	228
	229	Add `strconv` to the imports if missing. In `cmd/gitbay/main.go` the `release list` short text becomes `"releases: <owner/name> [--limit <n>] [--cursor <c>]"` (Part 4 removes these strings).
	230
	231	- [ ] Step 5: Run the test and the package
	232
	233	Run: `go test ./internal/control ./internal/store -count=1`
	234	Expected: PASS.
	235
	236	- [ ] Step 6: Commit
	237
	238	```bash
	239	git add internal/store/releases.go internal/control/release.go internal/control/release_test.go cmd/gitbay/main.go
	240	git commit -m "release list: --limit and --cursor; no title column when it repeats the tag" -m "Ref #254"
	241	```
	242
	243	### Task 1.2: `notifications device add` says `registered device <n>`
	244
	245	Files:
	246	- Modify: `internal/control/notifications.go:282`
	247	- Test: `internal/control/notifications_test.go`
	248
	249	- [ ] Step 1: Find the existing device add test
	250
	251	Run: `grep -n 'registered' internal/control/notifications_test.go e2e/*.go`
	252	Every assertion on `device %d registered` changes with the message. If none asserts on the plain text, add to the existing device add test in `notifications_test.go`, after its successful `Dispatch` (the test runs with `c.JSON` false or add a second plain run):
	253
	254	```go
	255	if got := c.Stdout.(*bytes.Buffer).String(); !strings.HasPrefix(got, "registered device ") {
	256	t.Errorf("device add printed %q", got)
	257	}
	258	```
	259
	260	- [ ] Step 2: Run it and see it fail
	261
	262	Run: `go test ./internal/control -run Device -count=1`
	263	Expected: FAIL on the message.
	264
	265	- [ ] Step 3: Change the message
	266
	267	```go
	268	fmt.Fprintf(w, "registered device %d\n", id)
	269	```
	270
	271	Update any e2e assertion found in Step 1 the same way.
	272
	273	- [ ] Step 4: Run
	274
	275	Run: `go test ./internal/control -count=1`
	276	Expected: PASS.
	277
	278	- [ ] Step 5: Commit
	279
	280	```bash
	281	git add internal/control/notifications.go internal/control/notifications_test.go
	282	git commit -m "notifications device add: verb first" -m "Ref #254"
	283	```
	284
	285	### Task 1.3: `dashboard` prints `none` under an empty section
	286
	287	Files:
	288	- Modify: `internal/control/dashboard.go:165-210` and `printDashboardItems`
	289	- Test: `internal/control/dashboard_test.go`
	290
	291	- [ ] Step 1: Write the failing test
	292
	293	Add to `dashboard_test.go`, using the store/ctx setup the file's existing tests use (read the top of the file for its helper):
	294
	295	```go
	296	func TestDashboardEmptySectionsSayNone(t *testing.T) {
	297	st, _, uid := newQueueTestRepo(t)
	298	c, errOut := pruneCtx(st, t.TempDir(), store.User{ID: uid})
	299	if code := Dispatch(c, []string{"dashboard"}); code != protocol.ExitOK {
	300	t.Fatalf("exit %d: %s", code, errOut)
	301	}
	302	out := c.Stdout.(*bytes.Buffer).String()
	303	for _, h := range []string{"waiting on your review:", "assigned to you:", "open merge requests:", "open issues:"} {
	304	if !strings.Contains(out, h+"\n none\n") {
	305	t.Errorf("%q not followed by none:\n%s", h, out)
	306	}
	307	}
	308	}
	309	```
	310
	311	- [ ] Step 2: Run it and see it fail
	312
	313	Run: `go test ./internal/control -run TestDashboardEmptySectionsSayNone -count=1`
	314	Expected: FAIL.
	315
	316	- [ ] Step 3: Implement
	317
	318	In `printDashboardItems`, before its loop:
	319
	320	```go
	321	if len(items) == 0 {
	322	fmt.Fprintln(w, " none")
	323	return
	324	}
	325	```
	326
	327	(Use the function's own parameter name.) Apply the same guard to the `pinned`, `recent activity` and `builds` loops in the plain formatter:
	328
	329	```go
	330	fmt.Fprintln(w, "pinned:")
	331	if len(d.Pinned) == 0 {
	332	fmt.Fprintln(w, " none")
	333	}
	334	for _, p := range d.Pinned {
	335	```
	336
	337	and likewise for `d.Activity` and `d.Builds`.
	338
	339	- [ ] Step 4: Run
	340
	341	Run: `go test ./internal/control -count=1`
	342	Expected: PASS. Fix any existing dashboard assertion that expected a header followed directly by the next header.
	343
	344	- [ ] Step 5: Commit and open MR 1
	345
	346	```bash
	347	git add internal/control/dashboard.go internal/control/dashboard_test.go
	348	git commit -m "dashboard: none under an empty section" -m "Ref #254"
	349	git push -u origin cli-output-refresh
	350	gitbay mr create --source cli-output-refresh --target main --title "CLI output refresh: spec, plan, audit fixes"
	351	```
	352
	353	Wait for CI, merge (`--strategy ff`), delete the branch both places.
	354
	355	---
	356
	357	# Part 2: transport and tables (branch `cli-output-tables`)
	358
	359	Start: `git switch main && git pull --ff-only && git switch -c cli-output-tables`.
	360
	361	### Task 2.1: `Term`, cell width, clipping, timestamps
	362
	363	Files:
	364	- Create: `internal/control/term.go`
	365	- Test: `internal/control/term_test.go`
	366	- Modify: `go.mod` (`golang.org/x/text` moves from indirect to direct: `go mod tidy`)
	367
	368	Interfaces:
	369	- Produces:
	370	- `type Term struct { Cols int; Color bool }` — zero value is plain.
	371	- `func ParseTerm(v string) Term`
	372	- `func (t Term) paint(sgr, s string) string`
	373	- `func stateColor(s string) string` — an SGR prefix or `""`.
	374	- `func cells(s string) int` — display width, SGR sequences skipped.
	375	- `func runeCells(r rune) int`
	376	- `func clip(s string, w int) string`
	377	- `func pad(s string, w int) string`
	378	- `func parseStamp(s string) (time.Time, bool)`
	379	- `func stamp(s string) string` — plain timestamp.
	380	- `func relAge(s string, now time.Time) string`
	381	- `var termNow = time.Now`
	382	- constants `sgrReset sgrBold sgrDim sgrUnderline sgrRed sgrGreen sgrMagenta`
	383
	384	- [ ] Step 1: Write the failing tests
	385
	386	```go
	387	package control
	388
	389	import (
	390	"testing"
	391	"time"
	392	)
	393
	394	func TestParseTerm(t *testing.T) {
	395	cases := map[string]Term{
	396	"120": {Cols: 120},
	397	"120,color": {Cols: 120, Color: true},
	398	"40": {Cols: 40},
	399	"39": {},
	400	"": {},
	401	"abc": {},
	402	"80,blink": {},
	403	"80,": {},
	404	"5000": {},
	405	}
	406	for in, want := range cases {
	407	if got := ParseTerm(in); got != want {
	408	t.Errorf("ParseTerm(%q) = %+v, want %+v", in, got, want)
	409	}
	410	}
	411	}
	412
	413	func TestCells(t *testing.T) {
	414	cases := map[string]int{
	415	"abc": 3,
	416	"日本": 4,
	417	"é": 1,
	418	"é": 1,
	419	"\x1b[32mopen\x1b[0m": 4,
	420	"": 0,
	421	}
	422	for in, want := range cases {
	423	if got := cells(in); got != want {
	424	t.Errorf("cells(%q) = %d, want %d", in, got, want)
	425	}
	426	}
	427	}
	428
	429	func TestClip(t *testing.T) {
	430	if got := clip("Dependency updates available", 14); got != "Dependency up…" {
	431	t.Errorf("clip = %q", got)
	432	}
	433	if got := clip("short", 14); got != "short" {
	434	t.Errorf("clip = %q", got)
	435	}
	436	if got := clip("日本語のタイトル", 7); got != "日本語…" {
	437	t.Errorf("clip wide = %q", got)
	438	}
	439	}
	440
	441	func TestStampAndRelAge(t *testing.T) {
	442	if got := stamp("2026-09-23T23:26:00.570Z"); got != "2026-09-23T23:26:00Z" {
	443	t.Errorf("stamp = %q", got)
	444	}
	445	if got := stamp("2026-09-23 23:26:00"); got != "2026-09-23T23:26:00Z" {
	446	t.Errorf("stamp sqlite = %q", got)
	447	}
	448	if got := stamp("garbage"); got != "garbage" {
	449	t.Errorf("stamp garbage = %q", got)
	450	}
	451	now := time.Date(2026, 9, 23, 12, 0, 0, 0, time.UTC)
	452	cases := map[string]string{
	453	"2026-09-23T11:59:30Z": "just now",
	454	"2026-09-23T11:55:00Z": "5m ago",
	455	"2026-09-23T10:00:00Z": "2h ago",
	456	"2026-09-20T12:00:00Z": "3d ago",
	457	"2026-09-02T12:00:00Z": "3w ago",
	458	"2026-06-01T12:00:00Z": "2026-06-01",
	459	"2026-09-24T12:00:00Z": "just now",
	460	"not a time": "not a time",
	461	}
	462	for in, want := range cases {
	463	if got := relAge(in, now); got != want {
	464	t.Errorf("relAge(%q) = %q, want %q", in, got, want)
	465	}
	466	}
	467	}
	468	```
	469
	470	- [ ] Step 2: Run and see them fail
	471
	472	Run: `go test ./internal/control -run 'TestParseTerm\|TestCells\|TestClip\|TestStampAndRelAge' -count=1`
	473	Expected: FAIL to compile (`undefined: ParseTerm`).
	474
	475	- [ ] Step 3: Implement `internal/control/term.go`
	476
	477	```go
	478	package control
	479
	480	import (
	481	"fmt"
	482	"strconv"
	483	"strings"
	484	"time"
	485	"unicode"
	486	"unicode/utf8"
	487
	488	"golang.org/x/text/width"
	489	)
	490
	491	// Term is what the client said about its terminal (GITBAY_TERM). The
	492	// zero value is plain output: tab-separated rows, no header, no colour,
	493	// which is what stock ssh, the API and the web get.
	494	type Term struct {
	495	Cols int
	496	Color bool
	497	}
	498
	499	// ParseTerm reads "<cols>[,color]". Anything else, or a width outside
	500	// 40 to 1000, is plain output.
	501	func ParseTerm(v string) Term {
	502	cols, opt, hasOpt := strings.Cut(v, ",")
	503	n, err := strconv.Atoi(cols)
	504	if err != nil \|\| n < 40 \|\| n > 1000 {
	505	return Term{}
	506	}
	507	switch {
	508	case !hasOpt:
	509	return Term{Cols: n}
	510	case opt == "color":
	511	return Term{Cols: n, Color: true}
	512	}
	513	return Term{}
	514	}
	515
	516	const (
	517	sgrReset = "\x1b[0m"
	518	sgrBold = "\x1b[1m"
	519	sgrDim = "\x1b[2m"
	520	sgrUnderline = "\x1b[4m"
	521	sgrRed = "\x1b[31m"
	522	sgrGreen = "\x1b[32m"
	523	sgrMagenta = "\x1b[35m"
	524	)
	525
	526	// paint wraps s in an SGR sequence when colour is on.
	527	func (t Term) paint(sgr, s string) string {
	528	if !t.Color \|\| sgr == "" \|\| s == "" {
	529	return s
	530	}
	531	return sgr + s + sgrReset
	532	}
	533
	534	// stateColor maps a state word to the web's state tokens: --ok green,
	535	// --done magenta, --bad red, --neutral dim.
	536	func stateColor(s string) string {
	537	switch s {
	538	case "open", "success", "approved", "active":
	539	return sgrGreen
	540	case "merged":
	541	return sgrMagenta
	542	case "failed", "failure", "error", "changes requested":
	543	return sgrRed
	544	case "closed", "draft", "pending", "canceled", "cancelled", "archived", "disabled":
	545	return sgrDim
	546	}
	547	return ""
	548	}
	549
	550	// cells is the width of s in terminal cells: SGR sequences and
	551	// combining marks take none, East Asian wide and fullwidth runes two.
	552	func cells(s string) int {
	553	n := 0
	554	for i := 0; i < len(s); {
	555	if s[i] == 0x1b {
	556	j := strings.IndexByte(s[i:], 'm')
	557	if j < 0 {
	558	break
	559	}
	560	i += j + 1
	561	continue
	562	}
	563	r, size := utf8.DecodeRuneInString(s[i:])
	564	i += size
	565	n += runeCells(r)
	566	}
	567	return n
	568	}
	569
	570	func runeCells(r rune) int {
	571	if unicode.In(r, unicode.Mn, unicode.Me) \|\| r == '‍' {
	572	return 0
	573	}
	574	switch width.LookupRune(r).Kind() {
	575	case width.EastAsianWide, width.EastAsianFullwidth:
	576	return 2
	577	}
	578	return 1
	579	}
	580
	581	// clip cuts s to at most w cells, ending in "…" when anything was cut.
	582	// s must carry no SGR sequences: colour goes on after clipping.
	583	func clip(s string, w int) string {
	584	if cells(s) <= w {
	585	return s
	586	}
	587	var b strings.Builder
	588	used := 0
	589	for _, r := range s {
	590	rc := runeCells(r)
	591	if used+rc > w-1 {
	592	break
	593	}
	594	b.WriteRune(r)
	595	used += rc
	596	}
	597	return b.String() + "…"
	598	}
	599
	600	// pad right-pads s with spaces to w cells.
	601	func pad(s string, w int) string {
	602	return s + strings.Repeat(" ", max(0, w-cells(s)))
	603	}
	604
	605	// termNow is the clock ages are measured against; tests pin it.
	606	var termNow = time.Now
	607
	608	// parseStamp reads a stored timestamp: RFC3339 as the store writes it,
	609	// or SQLite's datetime() form.
	610	func parseStamp(s string) (time.Time, bool) {
	611	for _, layout := range []string{time.RFC3339Nano, "2006-01-02 15:04:05"} {
	612	if t, err := time.Parse(layout, s); err == nil {
	613	return t.UTC(), true
	614	}
	615	}
	616	return time.Time{}, false
	617	}
	618
	619	// stamp is a stored timestamp in plain output: RFC3339 to the second.
	620	func stamp(s string) string {
	621	t, ok := parseStamp(s)
	622	if !ok {
	623	return s
	624	}
	625	return t.Format("2006-01-02T15:04:05Z")
	626	}
	627
	628	// relAge is a stored timestamp as a table shows it at a terminal.
	629	func relAge(s string, now time.Time) string {
	630	t, ok := parseStamp(s)
	631	if !ok {
	632	return s
	633	}
	634	d := max(now.Sub(t), 0)
	635	switch {
	636	case d < time.Minute:
	637	return "just now"
	638	case d < time.Hour:
	639	return fmt.Sprintf("%dm ago", int(d/time.Minute))
	640	case d < 24*time.Hour:
	641	return fmt.Sprintf("%dh ago", int(d/time.Hour))
	642	case d < 1424time.Hour:
	643	return fmt.Sprintf("%dd ago", int(d/(24*time.Hour)))
	644	case d < 5624time.Hour:
	645	return fmt.Sprintf("%dw ago", int(d/(724time.Hour)))
	646	}
	647	return t.Format("2006-01-02")
	648	}
	649	```
	650
	651	Then `go mod tidy`.
	652
	653	- [ ] Step 4: Run
	654
	655	Run: `go test ./internal/control -run 'TestParseTerm\|TestCells\|TestClip\|TestStampAndRelAge' -count=1`
	656	Expected: PASS. If `日本語…` fails, check `clip`'s budget: `w-1` cells for runes plus one for `…`.
	657
	658	- [ ] Step 5: Commit
	659
	660	```bash
	661	git add internal/control/term.go internal/control/term_test.go go.mod go.sum
	662	git commit -m "control: Term, cell width, clipping and timestamp formats" -m "Ref #254"
	663	```
	664
	665	### Task 2.2: `table`
	666
	667	Files:
	668	- Create: `internal/control/table.go`
	669	- Modify: `internal/control/control.go` (`Ctx` gains `Term Term`)
	670	- Test: `internal/control/table_test.go`
	671
	672	Interfaces:
	673	- Consumes: everything in Task 2.1.
	674	- Produces:
	675	- `type cell struct { kind cellKind; s string }`
	676	- `func cRef(s string) cell`, `cState(s string) cell`, `cText(s string) cell`, `cFlex(s string) cell`, `cAge(ts string) cell`, `cNum(n int64) cell`
	677	- `func (c Ctx) table(w io.Writer, header ...string) table`
	678	- `func (t *table) row(cells ...cell)`
	679	- `func (t *table) flush()`
	680	- `func stripSGR(s string) string` (test helper exported to the package; used by e2e via its own copy)
	681	- `Ctx.Term Term`
	682
	683	`cFlex` marks the column that shrinks first (a title or description). `cText` columns shrink only after it, rightmost first. `cRef`, `cState`, `cAge`, `cNum` never shrink.
	684
	685	- [ ] Step 1: Write the failing tests
	686
	687	```go
	688	package control
	689
	690	import (
	691	"bytes"
	692	"strings"
	693	"testing"
	694	"time"
	695	)
	696
	697	func fixtureTable(c Ctx, w bytes.Buffer) {
	698	tb := c.table(w, "#", "STATE", "TITLE", "AUTHOR")
	699	tb.row(cRef("#252"), cState("open"), cFlex("Dependency updates available for every module"), cText("gitbay-bot"))
	700	tb.row(cRef("#12"), cState("closed"), cFlex("Android app"), cText("cmc"))
	701	tb.flush()
	702	}
	703
	704	func TestTablePlainIsTabs(t *testing.T) {
	705	var b bytes.Buffer
	706	fixtureTable(&Ctx{}, &b)
	707	want := "#252\topen\tDependency updates available for every module\tgitbay-bot\n" +
	708	"#12\tclosed\tAndroid app\tcmc\n"
	709	if b.String() != want {
	710	t.Errorf("plain:\n%q\nwant\n%q", b.String(), want)
	711	}
	712	}
	713
	714	func TestTableTerminalFits(t *testing.T) {
	715	var b bytes.Buffer
	716	fixtureTable(&Ctx{Term: Term{Cols: 40}}, &b)
	717	want := "# STATE TITLE AUTHOR\n" +
	718	"#252 open Dependency up… gitbay-bot\n" +
	719	"#12 closed Android app cmc\n"
	720	if b.String() != want {
	721	t.Errorf("terminal:\n%s\nwant\n%s", b.String(), want)
	722	}
	723	}
	724
	725	func TestTableColourOnlyAddsSGR(t *testing.T) {
	726	var mono, colour bytes.Buffer
	727	fixtureTable(&Ctx{Term: Term{Cols: 40}}, &mono)
	728	fixtureTable(&Ctx{Term: Term{Cols: 40, Color: true}}, &colour)
	729	if !strings.Contains(colour.String(), sgrGreen+"open"+sgrReset) {
	730	t.Errorf("open not green: %q", colour.String())
	731	}
	732	if !strings.HasPrefix(colour.String(), sgrDim) {
	733	t.Errorf("header not dim: %q", colour.String())
	734	}
	735	if stripSGR(colour.String()) != mono.String() {
	736	t.Errorf("colour changed the layout:\n%s\nvs\n%s", stripSGR(colour.String()), mono.String())
	737	}
	738	}
	739
	740	func TestTableAgesAndPlainStamps(t *testing.T) {
	741	termNow = func() time.Time { return time.Date(2026, 9, 23, 12, 0, 0, 0, time.UTC) }
	742	t.Cleanup(func() { termNow = time.Now })
	743	var plain, term bytes.Buffer
	744	for _, c := range []struct {
	745	ctx *Ctx
	746	w *bytes.Buffer
	747	}{{&Ctx{}, &plain}, {&Ctx{Term: Term{Cols: 80}}, &term}} {
	748	tb := c.ctx.table(c.w, "#", "UPDATED")
	749	tb.row(cRef("#1"), cAge("2026-09-23T10:00:00.123Z"))
	750	tb.flush()
	751	}
	752	if plain.String() != "#1\t2026-09-23T10:00:00Z\n" {
	753	t.Errorf("plain = %q", plain.String())
	754	}
	755	if term.String() != "# UPDATED\n#1 2h ago\n" {
	756	t.Errorf("term = %q", term.String())
	757	}
	758	}
	759
	760	func TestTableEmptyPrintsNothing(t *testing.T) {
	761	var b bytes.Buffer
	762	(&Ctx{Term: Term{Cols: 80}}).table(&b, "#").flush()
	763	if b.Len() != 0 {
	764	t.Errorf("empty table printed %q", b.String())
	765	}
	766	}
	767	```
	768
	769	The empty case prints nothing because `emit` already said `nothing to list`
	770	before the formatter runs.
	771
	772	- [ ] Step 2: Run and see them fail
	773
	774	Run: `go test ./internal/control -run TestTable -count=1`
	775	Expected: FAIL to compile.
	776
	777	- [ ] Step 3: Add `Term` to `Ctx`
	778
	779	In `internal/control/control.go`, inside `type Ctx struct`, after `JSON bool`:
	780
	781	```go
	782	// Term is the client's terminal, from GITBAY_TERM. The zero value
	783	// is plain output.
	784	Term Term
	785	```
	786
	787	- [ ] Step 4: Implement `internal/control/table.go`
	788
	789	```go
	790	package control
	791
	792	import (
	793	"io"
	794	"strconv"
	795	"strings"
	796	)
	797
	798	type cellKind int
	799
	800	const (
	801	kindText cellKind = iota
	802	kindFlex
	803	kindRef
	804	kindState
	805	kindAge
	806	kindNum
	807	)
	808
	809	// cell is one column of a table row. The kind decides colour, time
	810	// format, and whether the column may be clipped to fit the terminal.
	811	type cell struct {
	812	kind cellKind
	813	s string
	814	}
	815
	816	func cRef(s string) cell { return cell{kindRef, s} }
	817	func cState(s string) cell { return cell{kindState, s} }
	818	func cText(s string) cell { return cell{kindText, s} }
	819	func cFlex(s string) cell { return cell{kindFlex, s} }
	820	func cAge(ts string) cell { return cell{kindAge, ts} }
	821	func cNum(n int64) cell { return cell{kindNum, strconv.FormatInt(n, 10)} }
	822
	823	// table is a list command's rows. Plain, each row is written as it
	824	// comes, tab-separated with no header. At a terminal rows are held
	825	// until flush, then written under a header, padded, and fitted to the
	826	// width.
	827	type table struct {
	828	term Term
	829	w io.Writer
	830	header []string
	831	rows [][]cell
	832	}
	833
	834	func (c Ctx) table(w io.Writer, header ...string) table {
	835	return &table{term: c.Term, w: w, header: header}
	836	}
	837
	838	func (t *table) row(cs ...cell) {
	839	if t.term.Cols == 0 {
	840	parts := make([]string, len(cs))
	841	for i, c := range cs {
	842	if c.kind == kindAge {
	843	parts[i] = stamp(c.s)
	844	} else {
	845	parts[i] = c.s
	846	}
	847	}
	848	io.WriteString(t.w, strings.Join(parts, "\t")+"\n")
	849	return
	850	}
	851	now := termNow()
	852	for i := range cs {
	853	if cs[i].kind == kindAge {
	854	cs[i].s = relAge(cs[i].s, now)
	855	}
	856	}
	857	t.rows = append(t.rows, cs)
	858	}
	859
	860	func (t *table) flush() {
	861	if t.term.Cols == 0 \|\| len(t.rows) == 0 {
	862	return
	863	}
	864	n := len(t.header)
	865	widths := make([]int, n)
	866	for i, h := range t.header {
	867	widths[i] = cells(h)
	868	}
	869	for _, r := range t.rows {
	870	for i := 0; i < n && i < len(r); i++ {
	871	widths[i] = max(widths[i], cells(r[i].s))
	872	}
	873	}
	874	t.fit(widths)
	875
	876	var b strings.Builder
	877	line := make([]string, n)
	878	for i, h := range t.header {
	879	line[i] = h
	880	}
	881	b.WriteString(t.term.paint(sgrDim, t.join(line, widths)) + "\n")
	882	for _, r := range t.rows {
	883	for i := 0; i < n; i++ {
	884	s := ""
	885	if i < len(r) {
	886	s = clip(r[i].s, widths[i])
	887	}
	888	line[i] = s
	889	}
	890	b.WriteString(t.joinRow(r, line, widths) + "\n")
	891	}
	892	io.WriteString(t.w, b.String())
	893	}
	894
	895	// fit shrinks columns until a row fits the terminal: the flexible
	896	// column first, down to 8 cells, then the other text columns from the
	897	// right, down to 8 each.
	898	func (t *table) fit(widths []int) {
	899	total := func() int {
	900	s := 2 * (len(widths) - 1)
	901	for _, w := range widths {
	902	s += w
	903	}
	904	return s
	905	}
	906	kinds := make([]cellKind, len(widths))
	907	if len(t.rows) > 0 {
	908	for i := range widths {
	909	if i < len(t.rows[0]) {
	910	kinds[i] = t.rows[0][i].kind
	911	}
	912	}
	913	}
	914	shrink := func(i int) {
	915	if over := total() - t.term.Cols; over > 0 && widths[i] > 8 {
	916	widths[i] = max(8, widths[i]-over)
	917	}
	918	}
	919	for i, k := range kinds {
	920	if k == kindFlex {
	921	shrink(i)
	922	}
	923	}
	924	for i := len(kinds) - 1; i >= 0; i-- {
	925	if kinds[i] == kindText {
	926	shrink(i)
	927	}
	928	}
	929	}
	930
	931	// join pads every column but the last and separates them by two spaces.
	932	func (t *table) join(line []string, widths []int) string {
	933	var b strings.Builder
	934	for i, s := range line {
	935	if i > 0 {
	936	b.WriteString(" ")
	937	}
	938	if i == len(line)-1 {
	939	b.WriteString(s)
	940	} else {
	941	b.WriteString(pad(s, widths[i]))
	942	}
	943	}
	944	return b.String()
	945	}
	946
	947	// joinRow is join with state cells coloured after padding, so the
	948	// SGR bytes never count against the width.
	949	func (t *table) joinRow(r []cell, line []string, widths []int) string {
	950	var b strings.Builder
	951	for i, s := range line {
	952	if i > 0 {
	953	b.WriteString(" ")
	954	}
	955	padding := ""
	956	if i < len(line)-1 {
	957	padding = strings.Repeat(" ", max(0, widths[i]-cells(s)))
	958	}
	959	if i < len(r) && r[i].kind == kindState {
	960	s = t.term.paint(stateColor(s), s)
	961	}
	962	b.WriteString(s + padding)
	963	}
	964	return b.String()
	965	}
	966
	967	// stripSGR removes SGR sequences, for tests and width checks.
	968	func stripSGR(s string) string {
	969	var b strings.Builder
	970	for i := 0; i < len(s); i++ {
	971	if s[i] == 0x1b {
	972	if j := strings.IndexByte(s[i:], 'm'); j >= 0 {
	973	i += j
	974	continue
	975	}
	976	}
	977	b.WriteByte(s[i])
	978	}
	979	return b.String()
	980	}
	981	```
	982
	983	The header line is painted dim as a whole, so `TestTableColourOnlyAddsSGR`'s prefix check holds.
	984
	985	- [ ] Step 5: Run
	986
	987	Run: `go test ./internal/control -run TestTable -count=1`
	988	Expected: PASS. If `TestTableTerminalFits` fails, print widths: `#` 4, `STATE` 6, `TITLE` 45 shrinks by 31 to 14, `AUTHOR` 10; 4+6+14+10+6 = 40.
	989
	990	- [ ] Step 6: Commit
	991
	992	```bash
	993	git add internal/control/table.go internal/control/table_test.go internal/control/control.go
	994	git commit -m "control: table, plain rows or a fitted terminal table" -m "Ref #254"
	995	```
	996
	997	### Task 2.3: `GITBAY_TERM` over SSH, and the multiplexing check
	998
	999	Files:
	1000	- Modify: `internal/sshd/sshd.go` (`handleSession`, `runExec`, `Exec`)
	1001	- Modify: `cmd/gitbayd/system.go:96`
	1002	- Modify: `internal/control/repo.go` (`repo list` plain formatter onto `table`, the first site, so the e2e test has a header to look for)
	1003	- Modify: `e2e/ssh_test.go` (add `sshTerm`)
	1004	- Create: `e2e/term_test.go`
	1005
	1006	Interfaces:
	1007	- Consumes: `control.ParseTerm`, `control.Term`, `Ctx.table`.
	1008	- Produces:
	1009	- `func Exec(cfg config.Config, st *store.Store, user store.User, scope, source string, term control.Term, cmdline string, stdin io.Reader, stdout, stderr io.Writer, done, stopping <-chan struct{}) int`
	1010	- e2e: `func (i instance) sshTerm(t testing.T, key, term string, args ...string) (string, string, int)` — `term` "" sends no `SetEnv`.
	1011
	1012	- [ ] Step 1: Move `repo list` onto `table`
	1013
	1014	Read `runRepoList` in `internal/control/repo.go`. Replace the `fmt.Fprintf` row loop in its plain formatter with a table. Columns: `PATH` (`cRef`), `VISIBILITY` (`cState`), `DESCRIPTION` (`cFlex`), keeping any trailing word column as `cText` in the same position it has today. Example shape (adapt the field names to the struct in the file):
	1015
	1016	```go
	1017	tb := c.table(w, "PATH", "VISIBILITY", "DESCRIPTION")
	1018	for _, r := range rows {
	1019	tb.row(cRef(r.Path), cState(r.Visibility), cFlex(r.Description))
	1020	}
	1021	tb.flush()
	1022	```
	1023
	1024	Run `go test ./internal/control -count=1`: plain bytes are unchanged, so existing tests pass.
	1025
	1026	- [ ] Step 2: Write the failing e2e test
	1027
	1028	`e2e/ssh_test.go`, next to `sshCmd`:
	1029
	1030	```go
	1031	// sshTerm is ssh with GITBAY_TERM set on the session, as the CLI sends
	1032	// it at a terminal. An empty term sends nothing.
	1033	func (i instance) sshTerm(t testing.T, key, term string, args ...string) (string, string, int) {
	1034	t.Helper()
	1035	cmd := i.sshCmd(key, args...)
	1036	if term != "" {
	1037	for j, a := range cmd.Args {
	1038	if a == "git@127.0.0.1" {
	1039	opt := []string{"-o", "SetEnv=GITBAY_TERM=" + term}
	1040	cmd.Args = append(cmd.Args[:j:j], append(opt, cmd.Args[j:]...)...)
	1041	break
	1042	}
	1043	}
	1044	}
	1045	var out, errOut strings.Builder
	1046	cmd.Stdout, cmd.Stderr = &out, &errOut
	1047	err := cmd.Run()
	1048	code := 0
	1049	if ee, ok := err.(*exec.ExitError); ok {
	1050	code = ee.ExitCode()
	1051	} else if err != nil {
	1052	t.Fatalf("ssh: %v", err)
	1053	}
	1054	return out.String(), errOut.String(), code
	1055	}
	1056	```
	1057
	1058	`e2e/term_test.go`:
	1059
	1060	```go
	1061	package e2e
	1062
	1063	import (
	1064	"os"
	1065	"os/exec"
	1066	"path/filepath"
	1067	"strings"
	1068	"testing"
	1069	)
	1070
	1071	// GITBAY_TERM selects terminal output per session. Stock ssh without it
	1072	// gets the plain rows scripts read.
	1073	func TestTermEnvSelectsTerminalOutput(t *testing.T) {
	1074	t.Parallel()
	1075	inst := startInstance(t)
	1076	key := inst.newKey(t, "alice")
	1077	inst.admin(t, "admin", "user", "create", "alice", "--key", key+".pub",
	1078	"--email", "alice@example.test", "--verified")
	1079	if _, errOut, code := inst.ssh(t, key, "", "repo", "create", "alice/app"); code != 0 {
	1080	t.Fatalf("repo create: %d %s", code, errOut)
	1081	}
	1082
	1083	plain, _, _ := inst.sshTerm(t, key, "", "repo", "list")
	1084	if strings.Contains(plain, "PATH") \|\| !strings.Contains(plain, "alice/app\t") {
	1085	t.Errorf("plain repo list: %q", plain)
	1086	}
	1087	term, _, _ := inst.sshTerm(t, key, "80,color", "repo", "list")
	1088	if !strings.HasPrefix(term, "\x1b[2mPATH") {
	1089	t.Errorf("terminal repo list: %q", term)
	1090	}
	1091	}
	1092
	1093	// The CLI shares one connection per instance. Each session's
	1094	// GITBAY_TERM must reach the server, not the one the master was opened
	1095	// with.
	1096	func TestTermEnvOverMultiplexedSession(t *testing.T) {
	1097	t.Parallel()
	1098	inst := startInstance(t)
	1099	key := inst.newKey(t, "alice")
	1100	inst.admin(t, "admin", "user", "create", "alice", "--key", key+".pub",
	1101	"--email", "alice@example.test", "--verified")
	1102	inst.ssh(t, key, "", "repo", "create", "alice/app")
	1103
	1104	dir, err := os.MkdirTemp("", "gbmux")
	1105	if err != nil {
	1106	t.Fatal(err)
	1107	}
	1108	t.Cleanup(func() { os.RemoveAll(dir) })
	1109	sock := filepath.Join(dir, "cm")
	1110	mux := func(term string) string {
	1111	t.Helper()
	1112	cmd := inst.sshCmd(key, "repo", "list")
	1113	opts := []string{"-o", "ControlMaster=auto", "-o", "ControlPath=" + sock, "-o", "ControlPersist=30"}
	1114	if term != "" {
	1115	opts = append(opts, "-o", "SetEnv=GITBAY_TERM="+term)
	1116	}
	1117	for j, a := range cmd.Args {
	1118	if a == "git@127.0.0.1" {
	1119	cmd.Args = append(cmd.Args[:j:j], append(opts, cmd.Args[j:]...)...)
	1120	break
	1121	}
	1122	}
	1123	out, err := cmd.Output()
	1124	if err != nil {
	1125	t.Fatalf("ssh %s: %v", term, err)
	1126	}
	1127	return string(out)
	1128	}
	1129	t.Cleanup(func() {
	1130	exec.Command("ssh", "-o", "ControlPath="+sock, "-O", "exit", "git@127.0.0.1").Run()
	1131	})
	1132
	1133	if out := mux("80"); !strings.HasPrefix(out, "PATH") {
	1134	t.Fatalf("master session: %q", out)
	1135	}
	1136	if out := mux("80,color"); !strings.HasPrefix(out, "\x1b[2mPATH") {
	1137	t.Errorf("second session kept the master's GITBAY_TERM: %q", out)
	1138	}
	1139	if out := mux(""); strings.Contains(out, "PATH") {
	1140	t.Errorf("session without GITBAY_TERM got terminal output: %q", out)
	1141	}
	1142	}
	1143	```
	1144
	1145	- [ ] Step 3: Run and see them fail
	1146
	1147	Run: `go test ./e2e -run 'TestTermEnv' -count=1`
	1148	Expected: FAIL (the server ignores `env`).
	1149
	1150	- [ ] Step 4: sshd
	1151
	1152	In `handleSession`, declare `var term control.Term` before `for req := range reqs`, pass it to `runExec`, and split the `pty-req`/`env` case:
	1153
	1154	```go
	1155	case "env":
	1156	var kv struct{ Name, Value string }
	1157	if ssh.Unmarshal(req.Payload, &kv) == nil && kv.Name == "GITBAY_TERM" {
	1158	term = control.ParseTerm(kv.Value)
	1159	}
	1160	req.Reply(true, nil)
	1161	case "pty-req":
	1162	// Harmless; accept and ignore.
	1163	req.Reply(true, nil)
	1164	```
	1165
	1166	`runExec(sconn, ch, term, payload.Command, done)`; `runExec` passes `term` to `Exec`; `Exec` gains `term control.Term` after `source` and sets `Term: term` in the `control.Ctx` literal (around line 364). In `cmd/gitbayd/system.go:96`:
	1167
	1168	```go
	1169	code := sshd.Exec(cfg, st, user, key.Scope, key.Fingerprint, control.ParseTerm(os.Getenv("GITBAY_TERM")), cmdline, os.Stdin, os.Stdout, os.Stderr, nil, nil)
	1170	```
	1171
	1172	(import `gitbay.org/gitbay/internal/control` there if it is not already.)
	1173
	1174	- [ ] Step 5: Run
	1175
	1176	Run: `go build ./... && go vet ./... && go test ./e2e -run 'TestTermEnv' -count=1`
	1177	Expected: `TestTermEnvSelectsTerminalOutput` PASS.
	1178
	1179	`TestTermEnvOverMultiplexedSession` decides the transport:
	1180	- PASS: keep `SetEnv`. Go to Step 7.
	1181	- FAIL on the second session: OpenSSH's mux client does not forward the new session's `SetEnv`. Do Step 6.
	1182
	1183	- [ ] Step 6 (only if Step 5's mux test failed): `--term` argument
	1184
	1185	In `Dispatch` (`internal/control/control.go`), in the loop that strips `--json`, also strip `--term=<v>`:
	1186
	1187	```go
	1188	for _, a := range rest {
	1189	if a == "--json" {
	1190	c.JSON = true
	1191	continue
	1192	}
	1193	if v, ok := strings.CutPrefix(a, "--term="); ok {
	1194	c.Term = ParseTerm(v)
	1195	continue
	1196	}
	1197	args = append(args, a)
	1198	}
	1199	```
	1200
	1201	(match the loop's real shape). `Lookup` runs before the loop, so a leading `--term=` would break it: strip `--term=` from `argv` before `Lookup` too. Change both e2e tests to pass the term as a leading `--term=<v>` argument instead of `-o SetEnv=…`, keep the `env` handling in sshd (stock ssh users may still use it), and in Task 2.5 the CLI prepends `--term=<v>` to the server argv instead of adding `SetEnv`. Record the outcome in the spec's Transport section.
	1202
	1203	- [ ] Step 7: Commit
	1204
	1205	```bash
	1206	git add internal/sshd/sshd.go cmd/gitbayd/system.go internal/control/repo.go internal/control/control.go e2e/ssh_test.go e2e/term_test.go
	1207	git commit -m "sshd: GITBAY_TERM selects terminal output per session" -m "Ref #254"
	1208	```
	1209
	1210	### Task 2.4: `more:` hint, `Ctx.Argv`
	1211
	1212	Files:
	1213	- Modify: `internal/control/control.go` (`Ctx.Argv`, set in `Dispatch`)
	1214	- Modify: `internal/control/cursor.go` (`emitPage`)
	1215	- Test: `internal/control/cursor_test.go`
	1216
	1217	Interfaces:
	1218	- Produces: `Ctx.Argv []string` — the command's arguments after the path, with `--json` (and `--term=`) removed.
	1219
	1220	- [ ] Step 1: Write the failing test
	1221
	1222	```go
	1223	func TestEmitPageHintsTheNextPageAtATerminal(t *testing.T) {
	1224	st, repo, uid := newQueueTestRepo(t)
	1225	for i := 0; i < 3; i++ {
	1226	if _, err := st.CreateBuild(repo.ID, "unit", "aaa", "main", `["true"]`, "", "", true); err != nil {
	1227	t.Fatal(err)
	1228	}
	1229	}
	1230	c, errOut := pruneCtx(st, t.TempDir(), store.User{ID: uid})
	1231	c.Term = Term{Cols: 100}
	1232	if code := Dispatch(c, []string{"build", "list", repo.Path(), "--limit", "2"}); code != protocol.ExitOK {
	1233	t.Fatalf("exit %d: %s", code, errOut)
	1234	}
	1235	if strings.Contains(c.Stdout.(*bytes.Buffer).String(), "next\t") {
	1236	t.Errorf("cursor row on stdout at a terminal")
	1237	}
	1238	want := "more: gitbay build list " + repo.Path() + " --limit 2 --cursor "
	1239	if !strings.Contains(errOut.String(), want) {
	1240	t.Errorf("stderr = %q, want %q…", errOut.String(), want)
	1241	}
	1242	}
	1243	```
	1244
	1245	Add the imports the file needs (`bytes`, `strings`, `protocol`, `store`).
	1246
	1247	- [ ] Step 2: Run and see it fail
	1248
	1249	Run: `go test ./internal/control -run TestEmitPageHints -count=1`
	1250	Expected: FAIL.
	1251
	1252	- [ ] Step 3: Implement
	1253
	1254	`Ctx` gains, after `Cmd Command`:
	1255
	1256	```go
	1257	// Argv is the command's arguments after its path, global flags
	1258	// removed, so output can print a command to run next.
	1259	Argv []string
	1260	```
	1261
	1262	In `Dispatch`, after the `--json` stripping loop builds `args`: `c.Argv = args`.
	1263
	1264	`emitPage`'s plain closure:
	1265
	1266	```go
	1267	return c.emit(out{items, next}, func(w io.Writer) {
	1268	plain(w)
	1269	if next == "" {
	1270	return
	1271	}
	1272	if c.Term.Cols == 0 {
	1273	fmt.Fprintf(w, "next\t%s\n", next)
	1274	return
	1275	}
	1276	var again []string
	1277	for i := 0; i < len(c.Argv); i++ {
	1278	if c.Argv[i] == "--cursor" {
	1279	i++
	1280	continue
	1281	}
	1282	again = append(again, c.Argv[i])
	1283	}
	1284	fmt.Fprintf(c.Stderr, "more: gitbay %s %s --cursor %s\n", joinPath(c.Cmd.Path), strings.Join(again, " "), next)
	1285	})
	1286	```
	1287
	1288	- [ ] Step 4: Run
	1289
	1290	Run: `go test ./internal/control -count=1`
	1291	Expected: PASS.
	1292
	1293	- [ ] Step 5: Commit
	1294
	1295	```bash
	1296	git add internal/control/control.go internal/control/cursor.go internal/control/cursor_test.go
	1297	git commit -m "control: the next page as a command on stderr at a terminal" -m "Ref #254"
	1298	```
	1299
	1300	### Task 2.5: the CLI sends `GITBAY_TERM`; `--no-color`; tabwriter removed
	1301
	1302	Files:
	1303	- Modify: `cmd/gitbay/ssh.go` (`runSSH`, `sshCapture` unchanged; remove `listVerbs`, `alignColumns`, the `tabwriter`)
	1304	- Modify: `cmd/gitbay/main.go` (`main` strips `--no-color`)
	1305	- Test: `cmd/gitbay/term_test.go` (create)
	1306
	1307	Interfaces:
	1308	- Produces:
	1309	- `var noColor bool` (package `main`)
	1310	- `func termValue(isTerminal bool, cols int, env func(string) string) string`
	1311	- `func stripNoColor(args []string) ([]string, bool)`
	1312
	1313	- [ ] Step 1: Write the failing test
	1314
	1315	```go
	1316	package main
	1317
	1318	import "testing"
	1319
	1320	func TestTermValue(t *testing.T) {
	1321	env := func(m map[string]string) func(string) string {
	1322	return func(k string) string { return m[k] }
	1323	}
	1324	cases := []struct {
	1325	tty bool
	1326	cols int
	1327	env map[string]string
	1328	noColor bool
	1329	want string
	1330	}{
	1331	{true, 120, nil, false, "120,color"},
	1332	{false, 120, nil, false, ""},
	1333	{true, 30, nil, false, ""},
	1334	{true, 120, map[string]string{"NO_COLOR": "1"}, false, "120"},
	1335	{true, 120, map[string]string{"TERM": "dumb"}, false, "120"},
	1336	{true, 120, nil, true, "120"},
	1337	}
	1338	for _, c := range cases {
	1339	noColor = c.noColor
	1340	if got := termValue(c.tty, c.cols, env(c.env)); got != c.want {
	1341	t.Errorf("%+v: got %q", c, got)
	1342	}
	1343	}
	1344	noColor = false
	1345	}
	1346
	1347	func TestStripNoColor(t *testing.T) {
	1348	args, ok := stripNoColor([]string{"gitbay", "issue", "list", "--no-color", "--state", "all"})
	1349	if !ok \|\| len(args) != 5 \|\| args[3] != "--state" {
	1350	t.Errorf("got %v %v", args, ok)
	1351	}
	1352	}
	1353	```
	1354
	1355	- [ ] Step 2: Run and see it fail
	1356
	1357	Run: `go test ./cmd/gitbay -run 'TestTermValue\|TestStripNoColor' -count=1`
	1358	Expected: FAIL to compile.
	1359
	1360	- [ ] Step 3: Implement
	1361
	1362	In `cmd/gitbay/ssh.go`, delete `listVerbs` and `alignColumns`, and add:
	1363
	1364	```go
	1365	// noColor is --no-color, stripped from argv in main.
	1366	var noColor bool
	1367
	1368	// termValue is GITBAY_TERM for this invocation: the terminal's width,
	1369	// and whether colour is wanted. Empty when stdout is not a terminal,
	1370	// so piped output stays the rows stock ssh prints.
	1371	func termValue(isTerminal bool, cols int, env func(string) string) string {
	1372	if !isTerminal \|\| cols < 40 {
	1373	return ""
	1374	}
	1375	v := strconv.Itoa(cols)
	1376	if !noColor && env("NO_COLOR") == "" && env("TERM") != "dumb" {
	1377	v += ",color"
	1378	}
	1379	return v
	1380	}
	1381
	1382	// stripNoColor removes --no-color wherever it appears.
	1383	func stripNoColor(args []string) ([]string, bool) {
	1384	out := args[:0:0]
	1385	found := false
	1386	for _, a := range args {
	1387	if a == "--no-color" {
	1388	found = true
	1389	continue
	1390	}
	1391	out = append(out, a)
	1392	}
	1393	return out, found
	1394	}
	1395	```
	1396
	1397	In `runSSH`, replace the tabwriter block. Before building `args`'s destination:
	1398
	1399	```go
	1400	fd := int(os.Stdout.Fd())
	1401	cols := 0
	1402	isTTY := term.IsTerminal(fd)
	1403	if isTTY {
	1404	cols, _, _ = term.GetSize(fd)
	1405	}
	1406	if v := termValue(isTTY, cols, os.Getenv); v != "" && !slices.Contains(serverArgv, "--json") {
	1407	args = append(args, "-o", "SetEnv=GITBAY_TERM="+v)
	1408	}
	1409	```
	1410
	1411	placed after `args := sshArgs(t.inst)` and before the destination is appended (if Task 2.3 took Step 6, prepend `"--term="+v` to `serverArgv` instead). Remove `cmd.Stdout = tw` handling and the `text/tabwriter` import. In `main()`:
	1412
	1413	```go
	1414	func main() {
	1415	os.Args, noColor = stripNoColor(os.Args)
	1416	if err := newRoot().Execute(); err != nil {
	1417	```
	1418
	1419	- [ ] Step 4: Run
	1420
	1421	Run: `go build ./... && go vet ./cmd/gitbay && go test ./cmd/gitbay -count=1`
	1422	Expected: PASS.
	1423
	1424	- [ ] Step 5: Commit
	1425
	1426	```bash
	1427	git add cmd/gitbay
	1428	git commit -m "gitbay: send GITBAY_TERM at a terminal; --no-color; drop client-side column padding" -m "Ref #254"
	1429	```
	1430
	1431	### Task 2.6: every list command on `table` (issues, MRs, builds, releases, labels, milestones, search, explore)
	1432
	1433	Files:
	1434	- Modify: `internal/control/issue.go`, `mr.go`, `build.go`, `release.go`, `label.go`, `orglabel.go`, `milestone.go`, `search.go`, `explore.go`
	1435	- Test: existing tests in those files' `_test.go`
	1436
	1437	Recipe (applies to Tasks 2.6, 2.7, 2.8):
	1438
	1439	A list site is an `emit`/`emitPage` whose plain formatter prints one row per item. For each:
	1440
	1441	1. Keep the column order exactly as the `fmt.Fprintf` prints it today, so plain bytes are unchanged apart from timestamps.
	1442	2. Choose a cell per column:
	1443	- identifier (`#n`, `!n`, a path, a tag, a sha, a fingerprint, a name that is the row's key) → `cRef`
	1444	- state, status, visibility, role → `cState`
	1445	- stored timestamp → `cAge`
	1446	- count → `cNum` (or `cText` if the value is already a string such as `3 asset(s)`)
	1447	- the title or description → `cFlex` (one per table)
	1448	- anything else → `cText`
	1449	3. Header: one short capitalised word per column (`#`, `STATE`, `TITLE`, `AUTHOR`, `UPDATED`, `TAG`, `JOB`, `STATUS`, `SHA`, `REF`, `NAME`, `DESCRIPTION`, `ASSETS`, `DUE`, `COUNT`, `KIND`, `PATH`, `WHEN`).
	1450	4. Replace the loop:
	1451
	1452	```go
	1453	return c.emit(ds, func(w io.Writer) {
	1454	tb := c.table(w, "#", "STATE", "TITLE", "AUTHOR")
	1455	for _, d := range ds {
	1456	tb.row(cRef(fmt.Sprintf("#%d", d.Number)), cState(d.State), cFlex(d.Title), cText(d.Author))
	1457	}
	1458	tb.flush()
	1459	})
	1460	```
	1461
	1462	5. A column printed with a literal prefix or suffix (`due 2027-01-01`, `via team`) keeps it inside the cell string.
	1463	6. A row printed conditionally (optional trailing column) prints `""` in that cell so every row has the same number of cells.
	1464
	1465	- [ ] Step 1: Convert every list site in the files above, one file at a time. `release list` columns: `TAG` `cRef`, `TITLE` `cFlex`, `ASSETS` `cText`.
	1466
	1467	- [ ] Step 2: Run
	1468
	1469	Run: `go test ./internal/control -count=1`
	1470	Expected: PASS. A failure on a timestamp means the test asserted a stored value; change its expectation to `stamp(value)`'s form (`2026-09-23T23:26:00Z`). A failure anywhere else means a column changed order or content: fix the conversion, not the test.
	1471
	1472	- [ ] Step 3: Commit
	1473
	1474	```bash
	1475	git add internal/control
	1476	git commit -m "control: issue, mr, build, release, label, milestone, search and explore lists as tables" -m "Ref #254"
	1477	```
	1478
	1479	### Task 2.7: list commands in repo, read, sig, status, wiki, mirror, pages, runners, webhooks, diff threads
	1480
	1481	Files:
	1482	- Modify: `internal/control/repo.go` (the six sites left after `repo list`), `read.go`, `sig.go`, `status.go`, `wiki.go`, `mirrorcmd.go`, `pagescmd.go`, `runnerrepo.go`, `webhook.go`, `diffcomment.go`
	1483
	1484	- [ ] Step 1: Convert with the recipe in Task 2.6. `read.go`'s `log`-like listings: `SHA` `cRef`, `DATE` `cAge`, `AUTHOR` `cText`, `SUBJECT` `cFlex`. Sites that print file content (a blob, a diff, a log's body) are not lists; leave them.
	1485
	1486	- [ ] Step 2: Run
	1487
	1488	Run: `go test ./internal/control -count=1`
	1489	Expected: PASS, with the same rule for failures as Task 2.6.
	1490
	1491	- [ ] Step 3: Commit
	1492
	1493	```bash
	1494	git add internal/control
	1495	git commit -m "control: repository, history, status, wiki, mirror, runner and webhook lists as tables" -m "Ref #254"
	1496	```
	1497
	1498	### Task 2.8: list commands in accounts, orgs, admin, notifications, snippets, feed, dashboard
	1499
	1500	Files:
	1501	- Modify: `internal/control/admin.go`, `audit.go`, `identity.go`, `deploykey.go`, `token.go`, `web.go`, `register.go`, `notifications.go`, `org.go`, `teams.go`, `snippet.go`, `dashboard.go`
	1502	- Not `control.go`'s `help` listing: Part 4 rewrites it.
	1503
	1504	- [ ] Step 1: Convert with the recipe in Task 2.6. `admin.go:287` and `token.go:102` format `time.RFC3339` themselves: pass the stored string to `cAge` (or, for a `used`/`expires` word column, keep the word and format the time with `stamp` when plain, `relAge(…, termNow())` at a terminal).
	1505
	1506	`dashboard`: each section keeps its title line; the rows under it become a table per section. Plain output keeps today's two-space indent and tabs, so for the dashboard only, write the plain branch as it is and use `c.table` only when `c.Term.Cols > 0`:
	1507
	1508	```go
	1509	section := func(title string, header []string, rows [][]cell) {
	1510	fmt.Fprintln(w, title)
	1511	if len(rows) == 0 {
	1512	fmt.Fprintln(w, " none")
	1513	return
	1514	}
	1515	if c.Term.Cols == 0 {
	1516	for _, r := range rows {
	1517	parts := make([]string, len(r))
	1518	for i, cl := range r {
	1519	parts[i] = cl.s
	1520	if cl.kind == kindAge {
	1521	parts[i] = stamp(cl.s)
	1522	}
	1523	}
	1524	fmt.Fprintf(w, " %s\n", strings.Join(parts, "\t"))
	1525	}
	1526	return
	1527	}
	1528	tb := c.table(w, header...)
	1529	for _, r := range rows {
	1530	tb.row(r...)
	1531	}
	1532	tb.flush()
	1533	}
	1534	```
	1535
	1536	In terminal mode the section title is bold: `fmt.Fprintln(w, c.Term.paint(sgrBold, title))` in place of the plain `Fprintln` when `c.Term.Cols > 0`.
	1537
	1538	- [ ] Step 2: Run
	1539
	1540	Run: `go test ./internal/control -count=1`
	1541	Expected: PASS.
	1542
	1543	- [ ] Step 3: Commit
	1544
	1545	```bash
	1546	git add internal/control
	1547	git commit -m "control: account, org, admin, notification, snippet, feed and dashboard lists as tables" -m "Ref #254"
	1548	```
	1549
	1550	### Task 2.9: every read command, plain and at 60 columns, over ssh
	1551
	1552	Files:
	1553	- Modify: `e2e/readonly_test.go` (the loop at line ~174)
	1554
	1555	- [ ] Step 1: Extend the loop
	1556
	1557	After the existing `inst.ssh(...)` call and its exit check, add:
	1558
	1559	```go
	1560	argv := append(append([]string{}, cmd.Path...), args...)
	1561	plainOut, _, _ := inst.sshTerm(t, aliceKey, "", argv...)
	1562	if strings.Contains(plainOut, "\x1b") {
	1563	t.Errorf("%s: SGR bytes in plain output", path)
	1564	}
	1565	termOut, _, _ := inst.sshTerm(t, aliceKey, "60,color", argv...)
	1566	if !rawOutput[path] {
	1567	for _, line := range strings.Split(termOut, "\n") {
	1568	if w := displayCells(stripSGRe2e(line)); w > 60 {
	1569	t.Errorf("%s: line of %d cells at 60 columns: %q", path, w, line)
	1570	break
	1571	}
	1572	}
	1573	}
	1574	```
	1575
	1576	and before the loop:
	1577
	1578	```go
	1579	// rawOutput prints content verbatim (a file, a log, a diff) and is
	1580	// not fitted to the terminal.
	1581	rawOutput := map[string]bool{}
	1582	```
	1583
	1584	with helpers at the bottom of the file (e2e does not import unexported control code):
	1585
	1586	```go
	1587	func stripSGRe2e(s string) string {
	1588	return regexp.MustCompile("\x1b\\[[0-9;]*m").ReplaceAllString(s, "")
	1589	}
	1590
	1591	func displayCells(s string) int {
	1592	n := 0
	1593	for _, r := range s {
	1594	switch {
	1595	case unicode.In(r, unicode.Mn, unicode.Me):
	1596	case width.LookupRune(r).Kind() == width.EastAsianWide \|\| width.LookupRune(r).Kind() == width.EastAsianFullwidth:
	1597	n += 2
	1598	default:
	1599	n++
	1600	}
	1601	}
	1602	return n
	1603	}
	1604	```
	1605
	1606	(imports `unicode`, `golang.org/x/text/width`.)
	1607
	1608	- [ ] Step 2: Run
	1609
	1610	Run: `go test ./e2e -run TestReadOnlyCommandsWriteNothing -count=1`
	1611
	1612	For each width failure: if the command's stdout is verbatim content (file, log, diff, raw asset), add its path to `rawOutput` with nothing else; otherwise the list site was missed or a cell kind is wrong, fix it in `internal/control`. Show commands will fail here until Part 3: add every `* show` path that fails to `rawOutput` with the comment `// until the view layout (Part 3)`, and Part 3 removes them.
	1613
	1614	Expected in the end: PASS.
	1615
	1616	- [ ] Step 3: Commit and open MR 2
	1617
	1618	```bash
	1619	git add e2e/readonly_test.go
	1620	git commit -m "e2e: read commands carry no SGR when plain and fit 60 columns at a terminal" -m "Ref #254"
	1621	git push -u origin cli-output-tables
	1622	gitbay mr create --source cli-output-tables --target main --title "CLI output: GITBAY_TERM and terminal tables"
	1623	```
	1624
	1625	Before merging, check at a real terminal against a local instance or after deploy: `gitbay issue list`, `gitbay build list --limit 5`, `gitbay issue list \| cat`.
	1626
	1627	---
	1628
	1629	# Part 3: show views and the pager (branch `cli-output-views`)
	1630
	1631	### Task 3.1: `internal/termtext`, markdown
	1632
	1633	Files:
	1634	- Create: `internal/termtext/termtext.go`, `internal/termtext/markdown.go`
	1635	- Test: `internal/termtext/markdown_test.go`, `internal/termtext/testdata/.md`, `.golden`
	1636
	1637	Interfaces:
	1638	- Produces:
	1639	- `type Options struct { Width int; Color bool; Base string }` — `Width` 0 is plain: no wrapping, no SGR. `Base` is the site URL for relative links.
	1640	- `func Render(src, format string, o Options) string` — `format` `"org"` renders org, anything else markdown.
	1641	- `func Markdown(src string, o Options) string`
	1642	- `func Inline(src, format string) string` — one line, links as their text only, no SGR (for event lines).
	1643
	1644	- [ ] Step 1: Write the golden test
	1645
	1646	`internal/termtext/markdown_test.go`:
	1647
	1648	```go
	1649	package termtext
	1650
	1651	import (
	1652	"flag"
	1653	"os"
	1654	"path/filepath"
	1655	"strings"
	1656	"testing"
	1657	)
	1658
	1659	var update = flag.Bool("update", false, "rewrite golden files")
	1660
	1661	func golden(t *testing.T, name, got string) {
	1662	t.Helper()
	1663	path := filepath.Join("testdata", name)
	1664	if *update {
	1665	os.WriteFile(path, []byte(got), 0o644)
	1666	}
	1667	want, err := os.ReadFile(path)
	1668	if err != nil {
	1669	t.Fatal(err)
	1670	}
	1671	if got != string(want) {
	1672	t.Errorf("%s differs:\n--- got\n%s\n--- want\n%s", name, got, want)
	1673	}
	1674	}
	1675
	1676	func TestMarkdownGolden(t *testing.T) {
	1677	src, err := os.ReadFile("testdata/doc.md")
	1678	if err != nil {
	1679	t.Fatal(err)
	1680	}
	1681	for _, o := range []struct {
	1682	name string
	1683	opt Options
	1684	}{
	1685	{"doc.md.plain.golden", Options{Base: "https://forge.test"}},
	1686	{"doc.md.60.golden", Options{Width: 60, Base: "https://forge.test"}},
	1687	{"doc.md.60color.golden", Options{Width: 60, Color: true, Base: "https://forge.test"}},
	1688	} {
	1689	golden(t, o.name, Markdown(string(src), o.opt))
	1690	}
	1691	}
	1692
	1693	func TestMarkdownWidth(t *testing.T) {
	1694	src, _ := os.ReadFile("testdata/doc.md")
	1695	out := Markdown(string(src), Options{Width: 60, Color: true})
	1696	inCode := false
	1697	for _, line := range strings.Split(out, "\n") {
	1698	plain := stripSGR(line)
	1699	if strings.HasPrefix(plain, " ") {
	1700	inCode = true
	1701	} else if plain != "" {
	1702	inCode = false
	1703	}
	1704	if !inCode && cells(plain) > 60 {
	1705	t.Errorf("line of %d cells: %q", cells(plain), plain)
	1706	}
	1707	}
	1708	}
	1709
	1710	func TestInlineDropsLinkTargets(t *testing.T) {
	1711	got := Inline("referenced in commit [6c4d1e1454](/krz/gitbay/commit/6c4d) by [cmc](/cmc): landing", "md")
	1712	if got != "referenced in commit 6c4d1e1454 by cmc: landing" {
	1713	t.Errorf("Inline = %q", got)
	1714	}
	1715	}
	1716	```
	1717
	1718	`internal/termtext/testdata/doc.md` covers every node the renderer handles:
	1719
	1720	````markdown
	1721	# A heading
	1722
	1723	A paragraph long enough to wrap at sixty columns, with strong and emphasis, `code`, a [link](https://example.com/page), a [forge link](/krz/gitbay/issues/1), an autolink <https://example.com>, and ~~struck~~ text.
	1724
	1725	- one
	1726	- two, which is long enough that its continuation line has to hang under the text rather than the bullet
	1727	- nested
	1728
	1729	1. first
	1730	2. second
	1731
	1732	- [x] done
	1733	- [ ] open
	1734
	1735	> quoted text
	1736
	1737	```go
	1738	func main() { fmt.Println("a line longer than sixty columns stays on one line, unwrapped") }
	1739	```
	1740
	1741	![alt text](/img.png)
	1742
	1743	---
	1744
	1745	\| a \| b \|
	1746	\|---\|---\|
	1747	\| 1 \| 2 \|
	1748	````
	1749
	1750	- [ ] Step 2: Run and see it fail
	1751
	1752	Run: `go test ./internal/termtext -count=1`
	1753	Expected: FAIL to compile.
	1754
	1755	- [ ] Step 3: Implement
	1756
	1757	`internal/termtext/termtext.go`:
	1758
	1759	```go
	1760	// Package termtext renders markdown and org to text for a terminal:
	1761	// wrapped to a width, links reduced to their text, code highlighted
	1762	// with 16 colours. Width 0 is plain: no wrapping and no SGR, for
	1763	// piped output.
	1764	package termtext
	1765
	1766	import (
	1767	"bytes"
	1768	"strings"
	1769	"unicode"
	1770	"unicode/utf8"
	1771
	1772	"github.com/alecthomas/chroma/v2/quick"
	1773	"golang.org/x/text/width"
	1774	)
	1775
	1776	type Options struct {
	1777	Width int
	1778	Color bool
	1779	Base string
	1780	}
	1781
	1782	func Render(src, format string, o Options) string {
	1783	if format == "org" {
	1784	return Org(src, o)
	1785	}
	1786	return Markdown(src, o)
	1787	}
	1788
	1789	const (
	1790	sgrReset = "\x1b[0m"
	1791	sgrBold = "\x1b[1m"
	1792	sgrDim = "\x1b[2m"
	1793	sgrUnderline = "\x1b[4m"
	1794	)
	1795
	1796	// out collects rendered lines. Every block goes through it so the
	1797	// prefixes (indent, list marker, quote bar) and the wrap live in one
	1798	// place.
	1799	type out struct {
	1800	o Options
	1801	b strings.Builder
	1802	noURLs bool // links as their text only (Inline)
	1803	}
	1804
	1805	func (w *out) paint(sgr, s string) string {
	1806	if !w.o.Color \|\| s == "" {
	1807	return s
	1808	}
	1809	return sgr + s + sgrReset
	1810	}
	1811
	1812	// para writes s wrapped to the width, the first line after first and
	1813	// the rest after rest. Hard breaks in s ("\n") start a new line.
	1814	func (w *out) para(s, first, rest string) {
	1815	prefix := first
	1816	for _, hard := range strings.Split(s, "\n") {
	1817	for _, line := range wrap(hard, w.o.Width-cells(rest)) {
	1818	w.b.WriteString(prefix + line + "\n")
	1819	prefix = rest
	1820	}
	1821	}
	1822	}
	1823
	1824	// code writes lines verbatim under prefix plus four spaces,
	1825	// highlighted when colour is on.
	1826	func (w *out) code(src, lang, prefix string) {
	1827	src = strings.TrimRight(src, "\n")
	1828	if w.o.Color && w.o.Width > 0 {
	1829	var hb bytes.Buffer
	1830	if lang == "" {
	1831	lang = "plaintext"
	1832	}
	1833	if quick.Highlight(&hb, src, lang, "terminal16", "monokai") == nil {
	1834	src = strings.TrimRight(hb.String(), "\n")
	1835	}
	1836	}
	1837	for _, line := range strings.Split(src, "\n") {
	1838	w.b.WriteString(prefix + " " + line + "\n")
	1839	}
	1840	}
	1841
	1842	func (w *out) rule(prefix string) {
	1843	w.b.WriteString(prefix + w.paint(sgrDim, "───") + "\n")
	1844	}
	1845
	1846	func (w *out) blank() { w.b.WriteString("\n") }
	1847
	1848	func (w *out) String() string {
	1849	return strings.TrimRight(w.b.String(), "\n") + "\n"
	1850	}
	1851
	1852	// link is a link as terminal text: its text, then the target when the
	1853	// target says something the text does not. Relative targets are made
	1854	// absolute against Base.
	1855	func (w *out) link(text, target string) string {
	1856	if w.noURLs && text != "" {
	1857	return text
	1858	}
	1859	if strings.HasPrefix(target, "/") && w.o.Base != "" {
	1860	target = strings.TrimRight(w.o.Base, "/") + target
	1861	}
	1862	if text == "" {
	1863	return target
	1864	}
	1865	if target == "" \|\| target == text \|\| strings.TrimPrefix(strings.TrimPrefix(target, "https://"), "http://") == text {
	1866	return text
	1867	}
	1868	return text + " (" + target + ")"
	1869	}
	1870
	1871	// wrap breaks s at spaces into lines of at most width cells. A word
	1872	// wider than width is a line of its own. width <= 0 is no wrapping.
	1873	func wrap(s string, width int) []string {
	1874	if width <= 0 {
	1875	return []string{s}
	1876	}
	1877	var lines []string
	1878	var cur string
	1879	for _, word := range strings.Fields(s) {
	1880	switch {
	1881	case cur == "":
	1882	cur = word
	1883	case cells(cur)+1+cells(word) <= width:
	1884	cur += " " + word
	1885	default:
	1886	lines = append(lines, cur)
	1887	cur = word
	1888	}
	1889	}
	1890	if cur != "" \|\| len(lines) == 0 {
	1891	lines = append(lines, cur)
	1892	}
	1893	return lines
	1894	}
	1895
	1896	func cells(s string) int {
	1897	n := 0
	1898	for i := 0; i < len(s); {
	1899	if s[i] == 0x1b {
	1900	j := strings.IndexByte(s[i:], 'm')
	1901	if j < 0 {
	1902	break
	1903	}
	1904	i += j + 1
	1905	continue
	1906	}
	1907	r, size := utf8.DecodeRuneInString(s[i:])
	1908	i += size
	1909	switch {
	1910	case unicode.In(r, unicode.Mn, unicode.Me) \|\| r == '‍':
	1911	case width.LookupRune(r).Kind() == width.EastAsianWide \|\| width.LookupRune(r).Kind() == width.EastAsianFullwidth:
	1912	n += 2
	1913	default:
	1914	n++
	1915	}
	1916	}
	1917	return n
	1918	}
	1919
	1920	func stripSGR(s string) string {
	1921	var b strings.Builder
	1922	for i := 0; i < len(s); i++ {
	1923	if s[i] == 0x1b {
	1924	if j := strings.IndexByte(s[i:], 'm'); j >= 0 {
	1925	i += j
	1926	continue
	1927	}
	1928	}
	1929	b.WriteByte(s[i])
	1930	}
	1931	return b.String()
	1932	}
	1933	```
	1934
	1935	`internal/termtext/markdown.go`:
	1936
	1937	```go
	1938	package termtext
	1939
	1940	import (
	1941	"fmt"
	1942	"strings"
	1943
	1944	"github.com/yuin/goldmark"
	1945	"github.com/yuin/goldmark/ast"
	1946	"github.com/yuin/goldmark/extension"
	1947	east "github.com/yuin/goldmark/extension/ast"
	1948	"github.com/yuin/goldmark/text"
	1949	)
	1950
	1951	// md parses as the web does (CommonMark plus GFM); raw HTML is dropped
	1952	// there and here.
	1953	var md = goldmark.New(goldmark.WithExtensions(extension.GFM))
	1954
	1955	func Markdown(src string, o Options) string {
	1956	return renderMarkdown(src, &out{o: o})
	1957	}
	1958
	1959	func renderMarkdown(src string, w *out) string {
	1960	source := []byte(src)
	1961	doc := md.Parser().Parse(text.NewReader(source))
	1962	r := mdRenderer{w: w, src: source}
	1963	r.blocks(doc, "", "")
	1964	return w.String()
	1965	}
	1966
	1967	// Inline is src as one line of plain text, links reduced to their
	1968	// text, for event lines.
	1969	func Inline(src, format string) string {
	1970	w := &out{noURLs: true}
	1971	var s string
	1972	if format == "org" {
	1973	s = renderOrg(src, w)
	1974	} else {
	1975	s = renderMarkdown(src, w)
	1976	}
	1977	return strings.Join(strings.Fields(s), " ")
	1978	}
	1979
	1980	type mdRenderer struct {
	1981	w *out
	1982	src []byte
	1983	}
	1984
	1985	// blocks renders n's children with a blank line between them. The
	1986	// first child's first line is prefixed by first, every other line by
	1987	// rest.
	1988	func (r mdRenderer) blocks(n ast.Node, first, rest string) {
	1989	p := first
	1990	for c := n.FirstChild(); c != nil; c = c.NextSibling() {
	1991	if c != n.FirstChild() {
	1992	r.w.blank()
	1993	}
	1994	r.block(c, p, rest)
	1995	p = rest
	1996	}
	1997	}
	1998
	1999	func (r mdRenderer) block(n ast.Node, first, rest string) {
	2000	switch n := n.(type) {
	2001	case *ast.Heading:
	2002	r.w.para(r.w.paint(sgrBold, r.inline(n)), first, rest)
	2003	case *ast.Paragraph:
	2004	r.w.para(r.inline(n), first, rest)
	2005	case *ast.TextBlock:
	2006	r.w.para(r.inline(n), first, rest)
	2007	case *ast.List:
	2008	i := n.Start
	2009	p := first
	2010	for item := n.FirstChild(); item != nil; item = item.NextSibling() {
	2011	marker := "• "
	2012	if n.IsOrdered() {
	2013	marker = fmt.Sprintf("%d. ", i)
	2014	i++
	2015	}
	2016	hang := rest + strings.Repeat(" ", cells(marker))
	2017	for c := item.FirstChild(); c != nil; c = c.NextSibling() {
	2018	if c == item.FirstChild() {
	2019	r.block(c, p+marker, hang)
	2020	} else {
	2021	if !n.IsTight {
	2022	r.w.blank()
	2023	}
	2024	r.block(c, hang, hang)
	2025	}
	2026	}
	2027	p = rest
	2028	}
	2029	case *ast.FencedCodeBlock:
	2030	r.w.code(r.lines(n), string(n.Language(r.src)), rest)
	2031	case *ast.CodeBlock:
	2032	r.w.code(r.lines(n), "", rest)
	2033	case *ast.Blockquote:
	2034	bar := r.w.paint(sgrDim, "│ ")
	2035	r.blocks(n, first+bar, rest+bar)
	2036	case *ast.ThematicBreak:
	2037	r.w.rule(first)
	2038	case *ast.HTMLBlock:
	2039	// Dropped, as the web drops it.
	2040	default:
	2041	// GFM tables and anything else: the source, as a code block.
	2042	r.w.code(r.lines(n), "", rest)
	2043	}
	2044	}
	2045
	2046	func (r mdRenderer) lines(n ast.Node) string {
	2047	var b strings.Builder
	2048	ls := n.Lines()
	2049	for i := 0; i < ls.Len(); i++ {
	2050	seg := ls.At(i)
	2051	b.Write(seg.Value(r.src))
	2052	}
	2053	return b.String()
	2054	}
	2055
	2056	func (r mdRenderer) inline(n ast.Node) string {
	2057	var b strings.Builder
	2058	for c := n.FirstChild(); c != nil; c = c.NextSibling() {
	2059	switch c := c.(type) {
	2060	case *ast.Text:
	2061	b.Write(c.Segment.Value(r.src))
	2062	switch {
	2063	case c.HardLineBreak():
	2064	b.WriteString("\n")
	2065	case c.SoftLineBreak():
	2066	b.WriteString(" ")
	2067	}
	2068	case *ast.String:
	2069	b.Write(c.Value)
	2070	case *ast.CodeSpan:
	2071	b.WriteString(r.inline(c))
	2072	case *ast.Emphasis:
	2073	sgr := sgrUnderline
	2074	if c.Level == 2 {
	2075	sgr = sgrBold
	2076	}
	2077	b.WriteString(r.w.paint(sgr, r.inline(c)))
	2078	case *ast.Link:
	2079	b.WriteString(r.w.link(r.inline(c), string(c.Destination)))
	2080	case *ast.AutoLink:
	2081	u := string(c.URL(r.src))
	2082	b.WriteString(r.w.link(u, u))
	2083	case *ast.Image:
	2084	b.WriteString("[image: " + r.inline(c) + "]")
	2085	case *ast.RawHTML:
	2086	case *east.TaskCheckBox:
	2087	if c.IsChecked {
	2088	b.WriteString("[x] ")
	2089	} else {
	2090	b.WriteString("[ ] ")
	2091	}
	2092	default:
	2093	b.WriteString(r.inline(c))
	2094	}
	2095	}
	2096	return b.String()
	2097	}
	2098	```
	2099
	2100	`Inline` calls `renderOrg`, which Task 3.2 adds. Until then, add a stub to `org.go` so the package compiles: `func renderOrg(src string, w *out) string { return src }`.
	2101
	2102	- [ ] Step 4: Generate the golden files and read them
	2103
	2104	Run: `go test ./internal/termtext -run TestMarkdownGolden -update -count=1`, then open each `testdata/doc.md.*.golden` and check by eye:
	2105	- plain: no `\x1b`, paragraphs unwrapped, `link (https://example.com/page)`, `forge link (https://forge.test/krz/gitbay/issues/1)`, the autolink once, `[image: alt text]`, bullets `•`, `[x] done`, the table as its source indented four spaces.
	2106	- 60: no non-code line over 60 cells; the nested item indented under its parent's text.
	2107	- 60color: bold heading, underlined emphasis, dim quote bar, SGR in the code line.
	2108
	2109	Fix the renderer until each reads right, regenerate, then:
	2110
	2111	Run: `go test ./internal/termtext -count=1`
	2112	Expected: PASS.
	2113
	2114	- [ ] Step 5: Commit
	2115
	2116	```bash
	2117	git add internal/termtext
	2118	git commit -m "termtext: markdown for a terminal" -m "Ref #254"
	2119	```
	2120
	2121	### Task 3.2: `internal/termtext`, org
	2122
	2123	Files:
	2124	- Create: `internal/termtext/org.go`
	2125	- Test: `internal/termtext/org_test.go`, `testdata/doc.org`, goldens
	2126
	2127	Interfaces:
	2128	- Produces: `func Org(src string, o Options) string`, `func renderOrg(src string, w *out) string`.
	2129
	2130	- [ ] Step 1: Check go-org's node types
	2131
	2132	Run: `go doc github.com/niklasfasching/go-org/org \| grep -E '^type\|^func String'`
	2133	The code below uses `Headline{Lvl, Title, Children}`, `Paragraph{Children}`, `List{Kind, Items}`, `ListItem{Bullet, Children}`, `DescriptiveListItem{Term, Details}`, `Block{Name, Parameters, Children}`, `Example{Children}`, `HorizontalRule`, `Text{Content}`, `LineBreak`, `ExplicitLineBreak`, `Emphasis{Kind, Content}`, `RegularLink{Protocol, Description, URL}`, `Keyword`, and `org.String(nodes ...Node) string`. Adjust field names to what `go doc` prints.
	2134
	2135	- [ ] Step 2: Write the golden test
	2136
	2137	`internal/termtext/org_test.go`:
	2138
	2139	```go
	2140	package termtext
	2141
	2142	import (
	2143	"os"
	2144	"strings"
	2145	"testing"
	2146	)
	2147
	2148	func TestOrgGolden(t *testing.T) {
	2149	src, err := os.ReadFile("testdata/doc.org")
	2150	if err != nil {
	2151	t.Fatal(err)
	2152	}
	2153	golden(t, "doc.org.plain.golden", Org(string(src), Options{Base: "https://forge.test"}))
	2154	golden(t, "doc.org.60.golden", Org(string(src), Options{Width: 60, Base: "https://forge.test"}))
	2155	golden(t, "doc.org.60color.golden", Org(string(src), Options{Width: 60, Color: true, Base: "https://forge.test"}))
	2156	}
	2157
	2158	// #+INCLUDE reads nothing from the server's disk.
	2159	func TestOrgIncludeIsInert(t *testing.T) {
	2160	got := Org("#+INCLUDE: \"/etc/passwd\"\n\ntext\n", Options{})
	2161	if strings.Contains(got, "root:") {
	2162	t.Fatalf("include read a file: %q", got)
	2163	}
	2164	}
	2165	```
	2166
	2167	`testdata/doc.org`:
	2168
	2169	```org
	2170	#+TITLE: ignored keyword
	2171
	2172	* A heading
	2173	A paragraph long enough to wrap at sixty columns, with bold, /italic/, _underline_, =verbatim=, ~code~, a [[https://example.com/page][link]], and a bare [[https://example.com]].
	2174
	2175	- one
	2176	- two, which is long enough that its continuation line has to hang under the text rather than the bullet
	2177	- nested
	2178
	2179	1. first
	2180	2. second
	2181
	2182	- term :: its description
	2183
	2184	#+BEGIN_SRC go
	2185	func main() { fmt.Println("a line longer than sixty columns stays on one line, unwrapped") }
	2186	#+END_SRC
	2187
	2188	#+BEGIN_QUOTE
	2189	quoted text
	2190	#+END_QUOTE
	2191
	2192	-----
	2193
	2194	\| a \| b \|
	2195	\|---+---\|
	2196	\| 1 \| 2 \|
	2197	```
	2198
	2199	- [ ] Step 3: Run and see it fail
	2200
	2201	Run: `go test ./internal/termtext -run 'TestOrg' -count=1`
	2202	Expected: FAIL to compile.
	2203
	2204	- [ ] Step 4: Implement `internal/termtext/org.go` (replacing the `renderOrg` stub from Task 3.1)
	2205
	2206	```go
	2207	package termtext
	2208
	2209	import (
	2210	"bytes"
	2211	"errors"
	2212	"io"
	2213	"log"
	2214	"strings"
	2215
	2216	"github.com/niklasfasching/go-org/org"
	2217	)
	2218
	2219	func Org(src string, o Options) string {
	2220	return renderOrg(src, &out{o: o})
	2221	}
	2222
	2223	// renderOrg parses with the same restrictions as the web: no file is
	2224	// ever read (#+INCLUDE, #+SETUPFILE), and parse warnings go nowhere.
	2225	func renderOrg(src string, w *out) string {
	2226	c := org.New()
	2227	c.ReadFile = func(string) ([]byte, error) { return nil, errors.New("org: includes are disabled") }
	2228	c.Log = log.New(io.Discard, "", 0)
	2229	doc := c.Parse(bytes.NewReader([]byte(src)), "")
	2230	r := orgRenderer{w: w}
	2231	r.nodes(doc.Nodes, "", "")
	2232	return w.String()
	2233	}
	2234
	2235	type orgRenderer struct{ w *out }
	2236
	2237	func (r orgRenderer) nodes(ns []org.Node, first, rest string) {
	2238	p := first
	2239	wrote := false
	2240	for _, n := range ns {
	2241	if skipOrg(n) {
	2242	continue
	2243	}
	2244	if wrote {
	2245	r.w.blank()
	2246	}
	2247	r.block(n, p, rest)
	2248	p, wrote = rest, true
	2249	}
	2250	}
	2251
	2252	func skipOrg(n org.Node) bool {
	2253	switch n.(type) {
	2254	case org.Keyword, org.PropertyDrawer, org.Comment:
	2255	return true
	2256	}
	2257	return false
	2258	}
	2259
	2260	func (r orgRenderer) block(n org.Node, first, rest string) {
	2261	switch n := n.(type) {
	2262	case org.Headline:
	2263	r.w.para(r.w.paint(sgrBold, r.inline(n.Title)), first, rest)
	2264	if len(n.Children) > 0 {
	2265	r.w.blank()
	2266	r.nodes(n.Children, rest, rest)
	2267	}
	2268	case org.Paragraph:
	2269	r.w.para(r.inline(n.Children), first, rest)
	2270	case org.List:
	2271	p := first
	2272	for i, item := range n.Items {
	2273	if i > 0 && n.Kind == "descriptive" {
	2274	r.w.blank()
	2275	}
	2276	switch item := item.(type) {
	2277	case org.ListItem:
	2278	marker := "• "
	2279	if n.Kind == "ordered" {
	2280	marker = item.Bullet + " "
	2281	}
	2282	hang := rest + strings.Repeat(" ", cells(marker))
	2283	r.nodes(item.Children, p+marker, hang)
	2284	case org.DescriptiveListItem:
	2285	term := r.w.paint(sgrBold, r.inline(item.Term))
	2286	r.w.para(term, p, rest)
	2287	r.nodes(item.Details, rest+" ", rest+" ")
	2288	default:
	2289	r.w.code(org.String(item), "", rest)
	2290	}
	2291	p = rest
	2292	}
	2293	case org.Block:
	2294	switch strings.ToUpper(n.Name) {
	2295	case "SRC":
	2296	lang := ""
	2297	if len(n.Parameters) > 0 {
	2298	lang = n.Parameters[0]
	2299	}
	2300	r.w.code(org.String(n.Children...), lang, rest)
	2301	case "QUOTE":
	2302	bar := r.w.paint(sgrDim, "│ ")
	2303	r.nodes(n.Children, first+bar, rest+bar)
	2304	default:
	2305	r.w.code(org.String(n.Children...), "", rest)
	2306	}
	2307	case org.Example:
	2308	r.w.code(org.String(n.Children...), "", rest)
	2309	case org.HorizontalRule:
	2310	r.w.rule(first)
	2311	default:
	2312	r.w.code(org.String(n), "", rest)
	2313	}
	2314	}
	2315
	2316	func (r orgRenderer) inline(ns []org.Node) string {
	2317	var b strings.Builder
	2318	for _, n := range ns {
	2319	switch n := n.(type) {
	2320	case org.Text:
	2321	b.WriteString(n.Content)
	2322	case org.LineBreak:
	2323	b.WriteString(" ")
	2324	case org.ExplicitLineBreak:
	2325	b.WriteString("\n")
	2326	case org.Emphasis:
	2327	s := r.inline(n.Content)
	2328	switch n.Kind {
	2329	case "*":
	2330	s = r.w.paint(sgrBold, s)
	2331	case "/", "_":
	2332	s = r.w.paint(sgrUnderline, s)
	2333	}
	2334	b.WriteString(s)
	2335	case org.RegularLink:
	2336	b.WriteString(r.w.link(r.inline(n.Description), n.URL))
	2337	default:
	2338	b.WriteString(org.String(n))
	2339	}
	2340	}
	2341	return b.String()
	2342	}
	2343	```
	2344
	2345	Blank lines between list items: go-org separates items with no blank line in a tight list; if the goldens show blank lines between `• one` and `• two`, remove the `blank()` in `nodes` for list children by rendering item children with a local loop that skips it.
	2346
	2347	- [ ] Step 5: Generate the goldens and read them
	2348
	2349	Run: `go test ./internal/termtext -run TestOrgGolden -update -count=1`. Check by eye as in Task 3.1; `#+TITLE` must not appear. Then:
	2350
	2351	Run: `go test ./internal/termtext -count=1`
	2352	Expected: PASS.
	2353
	2354	- [ ] Step 6: Commit
	2355
	2356	```bash
	2357	git add internal/termtext
	2358	git commit -m "termtext: org for a terminal" -m "Ref #254"
	2359	```
	2360
	2361	### Task 3.3: `view`, and `issue show` on it
	2362
	2363	Files:
	2364	- Create: `internal/control/view.go`
	2365	- Modify: `internal/control/issue.go` (`runIssueShow` plain formatter, lines ~231-245)
	2366	- Test: `internal/control/view_test.go`
	2367
	2368	Interfaces:
	2369	- Consumes: `Term`, `stamp`, `parseStamp`, `cells`, `pad`, `termtext.Render`, `termtext.Inline`.
	2370	- Produces:
	2371	- `func (c *Ctx) when(s string) string` — `2006-01-02 15:04 UTC` at a terminal, `stamp(s)` plain.
	2372	- `func (c Ctx) view(w io.Writer) view`
	2373	- `func (v *view) title(ref, title, state string)`
	2374	- `func (v *view) fields(kv ...string)` — alternating key, value; empty values skipped.
	2375	- `func (v *view) body(src, format string)`
	2376	- `func (v *view) event(text, format, ts string)`
	2377	- `func (v *view) comment(author, ts, body, format string)`
	2378	- `func (c *Ctx) siteURL(parts ...string) string` — `server.site_url` joined with `/`.
	2379
	2380	- [ ] Step 1: Write the failing test
	2381
	2382	```go
	2383	package control
	2384
	2385	import (
	2386	"bytes"
	2387	"strings"
	2388	"testing"
	2389
	2390	"gitbay.org/gitbay/internal/protocol"
	2391	"gitbay.org/gitbay/internal/store"
	2392	)
	2393
	2394	func showIssue(t *testing.T, term Term) string {
	2395	t.Helper()
	2396	st, repo, uid := newQueueTestRepo(t)
	2397	n, err := st.CreateIssue(repo.ID, uid, "A title", "Body with a [link](/x/y).", "md")
	2398	if err != nil {
	2399	t.Fatal(err)
	2400	}
	2401	if _, err := st.AddIssueComment(issueIDByNumber(t, st, repo.ID, n), 0, "referenced in commit [abc1234567](/o/r/commit/abc) by [alice](/alice)", "md"); err != nil {
	2402	t.Fatal(err)
	2403	}
	2404	c, errOut := pruneCtx(st, t.TempDir(), store.User{ID: uid})
	2405	c.Cfg.Server.SiteURL = "https://forge.test"
	2406	c.Term = term
	2407	if code := Dispatch(c, []string{"issue", "show", repo.Path(), "1"}); code != protocol.ExitOK {
	2408	t.Fatalf("exit %d: %s", code, errOut)
	2409	}
	2410	return c.Stdout.(*bytes.Buffer).String()
	2411	}
	2412
	2413	func TestIssueShowPlain(t *testing.T) {
	2414	out := showIssue(t, Term{})
	2415	for _, want := range []string{
	2416	"#1 A title open\n",
	2417	" author alice, ",
	2418	" url https://forge.test/",
	2419	"Body with a link (https://forge.test/x/y).",
	2420	" · referenced in commit abc1234567 by alice ",
	2421	} {
	2422	if !strings.Contains(out, want) {
	2423	t.Errorf("missing %q in:\n%s", want, out)
	2424	}
	2425	}
	2426	if strings.Contains(out, "\x1b") \|\| strings.Contains(out, "](") {
	2427	t.Errorf("markup or SGR in plain view:\n%s", out)
	2428	}
	2429	}
	2430
	2431	func TestIssueShowTerminal(t *testing.T) {
	2432	out := showIssue(t, Term{Cols: 60, Color: true})
	2433	if !strings.Contains(out, sgrGreen+"open"+sgrReset) {
	2434	t.Errorf("state not coloured:\n%s", out)
	2435	}
	2436	if !strings.Contains(out, " UTC") {
	2437	t.Errorf("no web-format timestamp:\n%s", out)
	2438	}
	2439	for _, line := range strings.Split(stripSGR(out), "\n") {
	2440	if cells(line) > 60 {
	2441	t.Errorf("line over 60 cells: %q", line)
	2442	}
	2443	}
	2444	}
	2445	```
	2446
	2447	Before writing this, read `internal/store/issues.go` for the real names and signatures of the create-issue and add-comment functions and for how a system comment is stored (author `system`, or an author id of 0, or a kind column), and adjust `showIssue` to match. Write `issueIDByNumber` only if no lookup exists (`st.IssueByNumber(repoID, n)` likely does).
	2448
	2449	- [ ] Step 2: Run and see it fail
	2450
	2451	Run: `go test ./internal/control -run TestIssueShow -count=1`
	2452	Expected: FAIL.
	2453
	2454	- [ ] Step 3: Implement `internal/control/view.go`
	2455
	2456	```go
	2457	package control
	2458
	2459	import (
	2460	"io"
	2461	"strings"
	2462
	2463	"gitbay.org/gitbay/internal/termtext"
	2464	)
	2465
	2466	// when is a stored timestamp in a view: the web's format at a
	2467	// terminal, RFC3339 to the second when plain.
	2468	func (c *Ctx) when(s string) string {
	2469	if c.Term.Cols == 0 {
	2470	return stamp(s)
	2471	}
	2472	t, ok := parseStamp(s)
	2473	if !ok {
	2474	return s
	2475	}
	2476	return t.Format("2006-01-02 15:04 UTC")
	2477	}
	2478
	2479	// siteURL is the instance's address with path segments appended.
	2480	func (c *Ctx) siteURL(parts ...string) string {
	2481	return strings.TrimRight(c.Cfg.Server.SiteURL, "/") + "/" + strings.Join(parts, "/")
	2482	}
	2483
	2484	// view lays out a show: a title line, aligned fields, a body, events,
	2485	// comments. Plain output is the same lines without colour or wrapping.
	2486	type view struct {
	2487	c *Ctx
	2488	w io.Writer
	2489	}
	2490
	2491	func (c Ctx) view(w io.Writer) view { return &view{c: c, w: w} }
	2492
	2493	func (v *view) opts() termtext.Options {
	2494	return termtext.Options{Width: max(0, v.c.Term.Cols-2), Color: v.c.Term.Color, Base: v.c.Cfg.Server.SiteURL}
	2495	}
	2496
	2497	func (v *view) title(ref, title, state string) {
	2498	t := v.c.Term
	2499	io.WriteString(v.w, ref+" "+t.paint(sgrBold, title)+" "+t.paint(stateColor(state), state)+"\n")
	2500	}
	2501
	2502	// fields prints key/value pairs aligned on the widest key, skipping
	2503	// empty values.
	2504	func (v *view) fields(kv ...string) {
	2505	wide := 0
	2506	for i := 0; i+1 < len(kv); i += 2 {
	2507	if kv[i+1] != "" {
	2508	wide = max(wide, cells(kv[i]))
	2509	}
	2510	}
	2511	io.WriteString(v.w, "\n")
	2512	for i := 0; i+1 < len(kv); i += 2 {
	2513	if kv[i+1] == "" {
	2514	continue
	2515	}
	2516	io.WriteString(v.w, " "+v.c.Term.paint(sgrDim, pad(kv[i], wide))+" "+kv[i+1]+"\n")
	2517	}
	2518	}
	2519
	2520	func (v *view) body(src, format string) {
	2521	if strings.TrimSpace(src) == "" {
	2522	return
	2523	}
	2524	io.WriteString(v.w, "\n")
	2525	for _, line := range strings.Split(strings.TrimRight(termtext.Render(src, format, v.opts()), "\n"), "\n") {
	2526	if line == "" {
	2527	io.WriteString(v.w, "\n")
	2528	continue
	2529	}
	2530	io.WriteString(v.w, " "+line+"\n")
	2531	}
	2532	}
	2533
	2534	// event is one line for a system comment: its text without link
	2535	// targets, the time at the right edge at a terminal.
	2536	func (v *view) event(text, format, ts string) {
	2537	line := "· " + termtext.Inline(text, format)
	2538	when := v.c.when(ts)
	2539	if cols := v.c.Term.Cols; cols > 0 {
	2540	room := cols - 2 - 2 - cells(when)
	2541	line = pad(clip(line, room), room)
	2542	}
	2543	io.WriteString(v.w, " "+v.c.Term.paint(sgrDim, line+" "+when)+"\n")
	2544	}
	2545
	2546	func (v *view) comment(author, ts, body, format string) {
	2547	head := "── " + author + ", " + v.c.when(ts) + " "
	2548	if cols := v.c.Term.Cols; cols > 0 {
	2549	head += strings.Repeat("─", max(0, cols-cells(head)))
	2550	}
	2551	io.WriteString(v.w, "\n"+v.c.Term.paint(sgrDim, head)+"\n")
	2552	v.body(body, format)
	2553	}
	2554	```
	2555
	2556	`issue show`'s formatter:
	2557
	2558	```go
	2559	return c.emit(d, func(w io.Writer) {
	2560	v := c.view(w)
	2561	v.title(fmt.Sprintf("#%d", d.Number), d.Title, d.State)
	2562	v.fields(
	2563	"author", d.Author+", "+c.when(d.CreatedAt),
	2564	"assignees", strings.Join(d.Assignees, ", "),
	2565	"labels", strings.Join(d.Labels, ", "),
	2566	"milestone", d.Milestone,
	2567	"url", c.siteURL(repo.Path(), "issues", strconv.FormatInt(d.Number, 10)),
	2568	)
	2569	v.body(d.Body, d.BodyFormat)
	2570	events := false
	2571	for _, cm := range cs {
	2572	if cm.Author != "system" {
	2573	continue
	2574	}
	2575	if !events {
	2576	io.WriteString(w, "\n")
	2577	events = true
	2578	}
	2579	v.event(cm.Body, cm.BodyFormat, cm.CreatedAt)
	2580	}
	2581	for _, cm := range cs {
	2582	if cm.Author == "system" {
	2583	continue
	2584	}
	2585	v.comment(cm.Author, cm.CreatedAt, cm.Body, cm.BodyFormat)
	2586	}
	2587	})
	2588	```
	2589
	2590	Remove the `_ = repo` line. Use the system-comment test that Step 1's store reading found in place of `cm.Author == "system"` if it differs. Check the web issue URL segment (`issues`) against `internal/httpd/routes.go`.
	2591
	2592	In plain mode `event` prints ` · <text> <stamp>` with two spaces between, which the test expects.
	2593
	2594	- [ ] Step 4: Run
	2595
	2596	Run: `go build ./... && go test ./internal/control -count=1`
	2597	Expected: PASS. Existing tests asserting the old `issue show` text (`#1 A title [open] by alice`, `--- alice at`) change to the new layout; e2e tests grepping `issue show` output: `grep -rn '"issue", "show"' e2e/` and update their assertions to substrings the new layout prints.
	2598
	2599	- [ ] Step 5: Commit
	2600
	2601	```bash
	2602	git add internal/control e2e
	2603	git commit -m "control: view layout; issue show on it" -m "Ref #254"
	2604	```
	2605
	2606	### Task 3.4: every other show on `view`
	2607
	2608	Files:
	2609	- Modify: `internal/control/mr.go` (`mr show`), `build.go` (`build show`), `release.go` (`release show`), `snippet.go` (`snippet show`), `repo.go` (`repo show`, `repo settings show`), `org.go` (`org show`), `teams.go` (`org team show`), `profile.go` (`profile show`), `admin.go` (`admin user show`), `wiki.go` (`wiki show`), `notifications.go` (`notifications settings show`), `theme.go` (`web theme show`)
	2610
	2611	- [ ] Step 1: Convert each with this mapping, reading each formatter first:
	2612	- The first line becomes `v.title(<identifier>, <name or title>, <state or visibility>)`. A show with no state passes `""` (the trailing space is harmless; `title` may skip it when empty — make it do so).
	2613	- Every `key: value` line becomes a pair in one `v.fields(...)` call; timestamps through `c.when`; add `"url", c.siteURL(...)` where the web has a page for the object.
	2614	- A body (MR description, release notes, snippet file text is content, not markup: print it verbatim after a blank line; wiki page source → `v.body(src, format)` with format from the file extension, `org` for `.org`).
	2615	- Comments and events on `mr show` exactly as on `issue show`; reviews and checks become `fields` rows (`check ci/build success, 22s`) or a `table` after the fields when there is more than one.
	2616	- Single-value shows (`web theme show`, `notifications settings show`) keep their one-line output if they print one line today.
	2617
	2618	- [ ] Step 2: Remove the Part 2 `rawOutput` entries added "until the view layout" in `e2e/readonly_test.go`.
	2619
	2620	- [ ] Step 3: Run
	2621
	2622	Run: `go test ./internal/control -count=1 && go test ./e2e -run TestReadOnlyCommandsWriteNothing -count=1`
	2623	Expected: PASS. A show that exceeds 60 columns outside a code block is a layout bug; fix it in the formatter.
	2624
	2625	- [ ] Step 4: Commit
	2626
	2627	```bash
	2628	git add internal/control e2e
	2629	git commit -m "control: every show on the view layout" -m "Ref #254"
	2630	```
	2631
	2632	### Task 3.5: the pager
	2633
	2634	Files:
	2635	- Modify: `cmd/gitbay/ssh.go` (`runSSH` → `runSSHPaged`)
	2636	- Modify: `cmd/gitbay/main.go` (`runPass`)
	2637	- Test: `cmd/gitbay/term_test.go`
	2638
	2639	Interfaces:
	2640	- Produces:
	2641	- `func pagerArgv(env func(string) (string, bool)) []string` — nil means no pager.
	2642	- `func pages(server, args []string) bool`
	2643	- `func runSSHPaged(t target, serverArgv []string, stdin io.Reader, page bool) int`; `runSSH(t, argv, stdin)` becomes `runSSHPaged(t, argv, stdin, false)`.
	2644
	2645	- [ ] Step 1: Write the failing test
	2646
	2647	```go
	2648	func TestPagerArgv(t *testing.T) {
	2649	env := func(m map[string]string) func(string) (string, bool) {
	2650	return func(k string) (string, bool) { v, ok := m[k]; return v, ok }
	2651	}
	2652	cases := []struct {
	2653	env map[string]string
	2654	want string
	2655	}{
	2656	{nil, "less"},
	2657	{map[string]string{"PAGER": "more -s"}, "more -s"},
	2658	{map[string]string{"PAGER": "more", "GITBAY_PAGER": "bat -p"}, "bat -p"},
	2659	{map[string]string{"PAGER": "more", "GITBAY_PAGER": ""}, ""},
	2660	}
	2661	for _, c := range cases {
	2662	if got := strings.Join(pagerArgv(env(c.env)), " "); got != c.want {
	2663	t.Errorf("%v: got %q want %q", c.env, got, c.want)
	2664	}
	2665	}
	2666	}
	2667
	2668	func TestPages(t *testing.T) {
	2669	yes := [][]string{{"issue", "show"}, {"mr", "diff"}, {"build", "log"}, {"repo", "log"}}
	2670	for _, s := range yes {
	2671	if !pages(s, nil) {
	2672	t.Errorf("%v should page", s)
	2673	}
	2674	}
	2675	if pages([]string{"build", "log"}, []string{"--follow"}) {
	2676	t.Error("build log --follow must not page")
	2677	}
	2678	if pages([]string{"issue", "show"}, []string{"--json"}) {
	2679	t.Error("--json must not page")
	2680	}
	2681	if pages([]string{"issue", "list"}, nil) {
	2682	t.Error("list must not page")
	2683	}
	2684	}
	2685	```
	2686
	2687	(add `strings` to the test imports.)
	2688
	2689	- [ ] Step 2: Run and see it fail
	2690
	2691	Run: `go test ./cmd/gitbay -run 'TestPagerArgv\|TestPages' -count=1`
	2692	Expected: FAIL to compile.
	2693
	2694	- [ ] Step 3: Implement
	2695
	2696	```go
	2697	// pagerArgv is the pager to run long output through: GITBAY_PAGER,
	2698	// then PAGER, then less. An empty GITBAY_PAGER turns paging off.
	2699	func pagerArgv(env func(string) (string, bool)) []string {
	2700	if v, ok := env("GITBAY_PAGER"); ok {
	2701	return strings.Fields(v)
	2702	}
	2703	if v, ok := env("PAGER"); ok && v != "" {
	2704	return strings.Fields(v)
	2705	}
	2706	return []string{"less"}
	2707	}
	2708
	2709	// pages reports whether a command's output goes through the pager at a
	2710	// terminal: views, diffs and logs, never a follow or JSON.
	2711	func pages(server, args []string) bool {
	2712	if len(server) == 0 \|\| slices.Contains(args, "--json") \|\| slices.Contains(args, "--follow") {
	2713	return false
	2714	}
	2715	switch server[len(server)-1] {
	2716	case "show", "diff", "log":
	2717	return true
	2718	}
	2719	return false
	2720	}
	2721	```
	2722
	2723	In `runSSHPaged`, after `cmd` is built and before `cmd.Run()`:
	2724
	2725	```go
	2726	var pager *exec.Cmd
	2727	var pw io.WriteCloser
	2728	if page && term.IsTerminal(int(os.Stdout.Fd())) {
	2729	if argv := pagerArgv(os.LookupEnv); len(argv) > 0 {
	2730	pager = exec.Command(toolpath.Look(argv[0]), argv[1:]...)
	2731	pager.Stdout, pager.Stderr = os.Stdout, os.Stderr
	2732	if _, ok := os.LookupEnv("LESS"); !ok {
	2733	pager.Env = append(os.Environ(), "LESS=FRX")
	2734	}
	2735	if w, err := pager.StdinPipe(); err == nil && pager.Start() == nil {
	2736	pw = w
	2737	cmd.Stdout = pw
	2738	} else {
	2739	pager = nil
	2740	}
	2741	}
	2742	}
	2743	err := cmd.Run()
	2744	if pager != nil {
	2745	pw.Close()
	2746	pager.Wait()
	2747	}
	2748	```
	2749
	2750	The `GITBAY_TERM` value is computed from `os.Stdout` before this block, so the server still sees the terminal. In `runPass`, the final call becomes `runSSHPaged(t, append(o.server, args...), stdin, pages(o.server, args))`.
	2751
	2752	- [ ] Step 4: Run
	2753
	2754	Run: `go build ./... && go vet ./cmd/gitbay && go test ./cmd/gitbay -count=1`
	2755	Expected: PASS. At a terminal against a local instance: `gitbay issue show <n>` opens `less` only when longer than the screen; `GITBAY_PAGER= gitbay issue show <n>` never does; `gitbay issue show <n> \| cat` never does.
	2756
	2757	- [ ] Step 5: Commit and open MR 3
	2758
	2759	```bash
	2760	git add cmd/gitbay
	2761	git commit -m "gitbay: page views, diffs and logs at a terminal" -m "Ref #254"
	2762	git push -u origin cli-output-views
	2763	gitbay mr create --source cli-output-views --target main --title "CLI output: show views and the pager"
	2764	```
	2765
	2766	---
	2767
	2768	# Part 4: help (branch `cli-output-help`)
	2769
	2770	### Task 4.1: `Flags` and `Examples` on `Command`, and the registry test
	2771
	2772	Files:
	2773	- Modify: `internal/control/control.go` (`Flag`, `Command` fields)
	2774	- Create: `internal/control/help_test.go`
	2775
	2776	Interfaces:
	2777	- Produces:
	2778
	2779	```go
	2780	// Flag is one flag in a command's help.
	2781	type Flag struct {
	2782	Name string // "--state"
	2783	Arg string // "open\|closed\|all"; empty for a switch
	2784	Desc string // what it does, lower case, no full stop
	2785	Default string // empty for none
	2786	}
	2787	```
	2788
	2789	`Command` gains `Flags []Flag` and `Examples []string` (each the full argv after the program, repository named).
	2790
	2791	- [ ] Step 1: Write the test
	2792
	2793	```go
	2794	package control
	2795
	2796	import (
	2797	"regexp"
	2798	"slices"
	2799	"strings"
	2800	"testing"
	2801
	2802	"gitbay.org/gitbay/internal/protocol"
	2803	)
	2804
	2805	var usageFlag = regexp.MustCompile(`--[a-z][a-z0-9-]*`)
	2806
	2807	// Help is written once, in the registry. Every flag in a usage line has
	2808	// a description, every description names a flag in the usage line, and
	2809	// every command has an example that runs it.
	2810	func TestHelpIsComplete(t *testing.T) {
	2811	for _, cmd := range Commands() {
	2812	path := strings.Join(cmd.Path, " ")
	2813	inUsage := map[string]bool{}
	2814	for _, f := range usageFlag.FindAllString(cmd.Usage, -1) {
	2815	if f != "--json" {
	2816	inUsage[f] = true
	2817	}
	2818	}
	2819	described := map[string]bool{}
	2820	for _, f := range cmd.Flags {
	2821	described[f.Name] = true
	2822	if f.Desc == "" {
	2823	t.Errorf("%s: %s has no description", path, f.Name)
	2824	}
	2825	if !inUsage[f.Name] {
	2826	t.Errorf("%s: %s is described but not in the usage", path, f.Name)
	2827	}
	2828	}
	2829	for f := range inUsage {
	2830	if !described[f] {
	2831	t.Errorf("%s: %s is in the usage with no description", path, f)
	2832	}
	2833	}
	2834	if len(cmd.Examples) == 0 {
	2835	t.Errorf("%s: no example", path)
	2836	}
	2837	for _, ex := range cmd.Examples {
	2838	argv, err := protocol.Tokenize(ex)
	2839	if err != nil {
	2840	t.Errorf("%s: example %q: %v", path, ex, err)
	2841	continue
	2842	}
	2843	got, _, ok := Lookup(argv)
	2844	if !ok \|\| !slices.Equal(got.Path, cmd.Path) {
	2845	t.Errorf("%s: example %q runs %v", path, ex, got.Path)
	2846	}
	2847	}
	2848	}
	2849	}
	2850	```
	2851
	2852	- [ ] Step 2: Add the type and fields to `control.go`; run `go test ./internal/control -run TestHelpIsComplete -count=1`. Expected: FAIL listing every command. Keep the list: Tasks 4.2 and 4.3 fill it.
	2853
	2854	- [ ] Step 3: Commit (the test fails; commit it with the next task instead if CI must stay green per commit — it must, since `ff` merges every commit. Do not commit yet; carry it into Task 4.2's commit.)
	2855
	2856	### Task 4.2: flag descriptions and examples, work nouns
	2857
	2858	Files:
	2859	- Modify: registrations in `internal/control/issue.go`, `mr.go`, `build.go`, `release.go`, `milestone.go`, `label.go`, `orglabel.go`, `search.go`, `explore.go`, `dashboard.go`, `thread.go`, `diffcomment.go`, `status.go`, `wiki.go`, `snippet.go`, `read.go`, `repo.go`, `repo*.go`
	2860
	2861	Rules for the text:
	2862	- `Desc`: lower case, no full stop, says what the flag changes, under 50 characters: `which issues`, `only issues carrying this label`, `rows per page`, `continue from the previous page`, `read the body from stdin`.
	2863	- `Arg`: the placeholder exactly as the usage line spells it (`<l>`, `open\|closed\|all`, `-`).
	2864	- `Default`: only when the command applies one (`open`, `30`); read the `Run` function to find it.
	2865	- Examples: the most common real use first, a second only when a flag combination is worth showing. Repository `krz/gitbay`, user `cmc`, numbers that look real. Stdin examples end in `--file - < notes.md`.
	2866
	2867	Example, for `issue list`:
	2868
	2869	```go
	2870	register(Command{Path: []string{"issue", "list"},
	2871	Summary: "list issues",
	2872	Usage: "issue list <owner/name> [--state open\|closed\|all] [--label <l>] [--assignee <user>] [--author <user>] [--milestone <title>\|none] [--search <text>] [--limit <n>] [--cursor <c>]",
	2873	Flags: []Flag{
	2874	{"--state", "open\|closed\|all", "which issues", "open"},
	2875	{"--label", "<l>", "only issues carrying this label", ""},
	2876	{"--assignee", "<user>", "only issues assigned to this user", ""},
	2877	{"--author", "<user>", "only issues opened by this user", ""},
	2878	{"--milestone", "<title>\|none", "only issues in this milestone, or in none", ""},
	2879	{"--search", "<text>", "match title and body", ""},
	2880	{"--limit", "<n>", "rows per page", ""},
	2881	{"--cursor", "<c>", "continue from the previous page", ""},
	2882	},
	2883	Examples: []string{
	2884	"issue list krz/gitbay --label bug --state all",
	2885	"issue list krz/gitbay --assignee cmc",
	2886	},
	2887	ReadOnly: true, Run: runIssueList})
	2888	```
	2889
	2890	(keep the registration's existing field layout and values; only `Flags` and `Examples` are new.) `--limit`/`--cursor` descriptions are the same on every paged command.
	2891
	2892	- [ ] Step 1: Fill every command in the files above.
	2893	- [ ] Step 2: Run `go test ./internal/control -run TestHelpIsComplete -count=1`. Expected: failures only for commands in files Task 4.3 covers.
	2894	- [ ] Step 3: No commit yet (the test still fails).
	2895
	2896	### Task 4.3: flag descriptions and examples, everything else
	2897
	2898	Files:
	2899	- Modify: every remaining registration in `internal/control/*.go` (account, keys, tokens, orgs, teams, admin, runners, webhooks, mirrors, notifications, web, profile, register, import, audit, help).
	2900
	2901	- [ ] Step 1: Fill with the rules in Task 4.2. Admin commands' examples use a made-up user (`alice`). Secrets: examples read them from stdin, never argv (`repo secret set krz/gitbay DEPLOY_KEY --file - < key`).
	2902	- [ ] Step 2: Run `go test ./internal/control -count=1`. Expected: PASS.
	2903	- [ ] Step 3: Commit (Tasks 4.1–4.3 together)
	2904
	2905	```bash
	2906	git add internal/control
	2907	git commit -m "control: every command's flags described, with examples" -m "Ref #254"
	2908	```
	2909
	2910	### Task 4.4: help layouts
	2911
	2912	Files:
	2913	- Create: `internal/control/help.go` (move `runHelp`, `helpEntry` and the `help` registration out of `control.go`)
	2914	- Test: `internal/control/help_test.go`
	2915
	2916	Interfaces:
	2917	- Consumes: `Flag`, `Command.Flags`, `Command.Examples`, `Term`, `hostOf`.
	2918	- Produces:
	2919	- `var nounSummaries = map[string]string{...}` — one line per first path element.
	2920	- `func NounSummaries() map[string]string`
	2921	- `helpEntry` gains `Flags []Flag \`json:"flags,omitempty"\`` and `Examples []string \`json:"examples,omitempty"\``; `Flag` gets JSON tags `name`, `arg`, `desc`, `default` (omitempty on the last three).
	2922
	2923	- [ ] Step 1: Write the failing tests
	2924
	2925	```go
	2926	func helpOut(t *testing.T, term Term, prefix ...string) string {
	2927	t.Helper()
	2928	var out, errOut bytes.Buffer
	2929	c := &Ctx{Stdout: &out, Stderr: &errOut, Term: term}
	2930	c.Cfg.Server.SiteURL = "https://forge.test"
	2931	if code := Dispatch(c, append([]string{"help"}, prefix...)); code != protocol.ExitOK {
	2932	t.Fatalf("help %v: exit %d: %s", prefix, code, errOut.String())
	2933	}
	2934	return out.String()
	2935	}
	2936
	2937	func TestHelpVerb(t *testing.T) {
	2938	out := helpOut(t, Term{Cols: 100}, "issue", "list")
	2939	for _, want := range []string{
	2940	"list issues\n",
	2941	"USAGE\n gitbay issue list [<owner/name>] [flags]\n",
	2942	"FLAGS\n",
	2943	" --state open\|closed\|all",
	2944	"which issues (default open)\n",
	2945	" --json",
	2946	"EXAMPLES\n gitbay issue list krz/gitbay --label bug --state all\n",
	2947	} {
	2948	if !strings.Contains(out, want) {
	2949	t.Errorf("missing %q in:\n%s", want, out)
	2950	}
	2951	}
	2952	plain := helpOut(t, Term{}, "issue", "list")
	2953	if !strings.Contains(plain, " ssh git@forge.test issue list krz/gitbay --label bug --state all\n") {
	2954	t.Errorf("plain examples not ssh:\n%s", plain)
	2955	}
	2956	if !strings.Contains(plain, "USAGE\n ssh git@forge.test issue list <owner/name> [flags]\n") {
	2957	t.Errorf("plain usage:\n%s", plain)
	2958	}
	2959	}
	2960
	2961	func TestHelpNoun(t *testing.T) {
	2962	out := helpOut(t, Term{Cols: 100}, "issue")
	2963	for _, want := range []string{"issues\n", "READ\n", "WRITE\n", " list ", " create ", "gitbay issue <verb> --help for flags.\n"} {
	2964	if !strings.Contains(out, want) {
	2965	t.Errorf("missing %q in:\n%s", want, out)
	2966	}
	2967	}
	2968	if strings.Index(out, " list ") > strings.Index(out, "WRITE") {
	2969	t.Errorf("list is not under READ:\n%s", out)
	2970	}
	2971	}
	2972
	2973	func TestEveryNounHasASummary(t *testing.T) {
	2974	for _, cmd := range Commands() {
	2975	if nounSummaries[cmd.Path[0]] == "" {
	2976	t.Errorf("no noun summary for %q", cmd.Path[0])
	2977	}
	2978	}
	2979	}
	2980	```
	2981
	2982	- [ ] Step 2: Run and see them fail
	2983
	2984	Run: `go test ./internal/control -run 'TestHelpVerb\|TestHelpNoun\|TestEveryNounHasASummary' -count=1`
	2985	Expected: FAIL.
	2986
	2987	- [ ] Step 3: Implement `help.go`
	2988
	2989	`nounSummaries`: one entry per distinct `cmd.Path[0]` in the registry (list them with `go test -run TestEveryNounHasASummary` output). Reuse the CLI's `group(...)` short texts from `cmd/gitbay/main.go` where the noun matches, so the two agree.
	2990
	2991	`runHelp`:
	2992
	2993	```go
	2994	func runHelp(c *Ctx, args []string) int {
	2995	prefix := joinPath(args)
	2996	var matched []Command
	2997	for _, cmd := range registry {
	2998	p := joinPath(cmd.Path)
	2999	if prefix == "" \|\| p == prefix \|\| strings.HasPrefix(p, prefix+" ") {
	3000	matched = append(matched, cmd)
	3001	}
	3002	}
	3003	if len(matched) == 0 {
	3004	return c.fail(protocol.ExitNotFound, "no command matches %q; try: help", prefix)
	3005	}
	3006	slices.SortFunc(matched, func(a, b Command) int { return strings.Compare(joinPath(a.Path), joinPath(b.Path)) })
	3007	entries := make([]helpEntry, len(matched))
	3008	for i, cmd := range matched {
	3009	entries[i] = helpEntry{Path: joinPath(cmd.Path), Summary: cmd.Summary, Usage: cmd.Usage, Flags: cmd.Flags, Examples: cmd.Examples}
	3010	}
	3011	return c.emit(entries, func(w io.Writer) {
	3012	switch {
	3013	case prefix == "":
	3014	for _, e := range entries {
	3015	fmt.Fprintf(w, "%-24s %s\n", e.Path, e.Summary)
	3016	}
	3017	case joinPath(matched[0].Path) == prefix:
	3018	c.helpVerb(w, matched[0], matched[1:])
	3019	default:
	3020	c.helpNoun(w, prefix, matched)
	3021	}
	3022	})
	3023	}
	3024	```
	3025
	3026	(`matched[0]` is the exact match when one exists, because it sorts first.)
	3027
	3028	```go
	3029	// program is how help spells the command it documents: the CLI at a
	3030	// terminal (only the CLI sends GITBAY_TERM), ssh otherwise.
	3031	func (c *Ctx) program() string {
	3032	if c.Term.Cols > 0 {
	3033	return "gitbay"
	3034	}
	3035	return "ssh git@" + hostOf(c.Cfg.Server.SiteURL)
	3036	}
	3037
	3038	func (c *Ctx) heading(w io.Writer, s string) {
	3039	fmt.Fprintln(w, c.Term.paint(sgrBold, s))
	3040	}
	3041
	3042	func (c *Ctx) helpVerb(w io.Writer, cmd Command, below []Command) {
	3043	fmt.Fprintln(w, cmd.Summary)
	3044	fmt.Fprintln(w)
	3045	c.heading(w, "USAGE")
	3046	shape := cmd.Usage
	3047	if i := strings.Index(shape, " [--"); i >= 0 {
	3048	shape = shape[:i]
	3049	} else if i := strings.Index(shape, " --"); i >= 0 {
	3050	shape = shape[:i]
	3051	}
	3052	if c.Term.Cols > 0 {
	3053	shape = strings.Replace(shape, "<owner/name>", "[<owner/name>]", 1)
	3054	}
	3055	if len(cmd.Flags) > 0 {
	3056	shape += " [flags]"
	3057	}
	3058	fmt.Fprintf(w, " %s %s\n", c.program(), shape)
	3059	fmt.Fprintln(w)
	3060	c.heading(w, "FLAGS")
	3061	rows := make([][2]string, 0, len(cmd.Flags)+1)
	3062	for _, f := range cmd.Flags {
	3063	name := f.Name
	3064	if f.Arg != "" {
	3065	name += " " + f.Arg
	3066	}
	3067	desc := f.Desc
	3068	if f.Default != "" {
	3069	desc += " (default " + f.Default + ")"
	3070	}
	3071	rows = append(rows, [2]string{name, desc})
	3072	}
	3073	rows = append(rows, [2]string{"--json", "machine-readable output"})
	3074	wide := 0
	3075	for _, r := range rows {
	3076	wide = max(wide, cells(r[0]))
	3077	}
	3078	for _, r := range rows {
	3079	fmt.Fprintf(w, " %s %s\n", pad(r[0], wide), r[1])
	3080	}
	3081	if len(cmd.Examples) > 0 {
	3082	fmt.Fprintln(w)
	3083	c.heading(w, "EXAMPLES")
	3084	for _, ex := range cmd.Examples {
	3085	fmt.Fprintf(w, " %s %s\n", c.program(), ex)
	3086	}
	3087	}
	3088	if len(below) > 0 {
	3089	fmt.Fprintln(w)
	3090	c.heading(w, "SEE ALSO")
	3091	for _, b := range below {
	3092	fmt.Fprintf(w, " %s %s\n", c.program(), joinPath(b.Path))
	3093	}
	3094	}
	3095	}
	3096
	3097	func (c *Ctx) helpNoun(w io.Writer, prefix string, cmds []Command) {
	3098	head := nounSummaries[strings.Fields(prefix)[0]]
	3099	fmt.Fprintln(w, head)
	3100	fmt.Fprintln(w)
	3101	c.heading(w, "USAGE")
	3102	fmt.Fprintf(w, " %s %s <verb> ...\n", c.program(), prefix)
	3103	wide := 0
	3104	for _, cmd := range cmds {
	3105	wide = max(wide, cells(strings.TrimPrefix(joinPath(cmd.Path), prefix+" ")))
	3106	}
	3107	for _, section := range []struct {
	3108	title string
	3109	read bool
	3110	}{{"READ", true}, {"WRITE", false}} {
	3111	first := true
	3112	for _, cmd := range cmds {
	3113	if cmd.ReadOnly != section.read {
	3114	continue
	3115	}
	3116	if first {
	3117	fmt.Fprintln(w)
	3118	c.heading(w, section.title)
	3119	first = false
	3120	}
	3121	verb := strings.TrimPrefix(joinPath(cmd.Path), prefix+" ")
	3122	fmt.Fprintf(w, " %s %s\n", pad(verb, wide), cmd.Summary)
	3123	}
	3124	}
	3125	fmt.Fprintln(w)
	3126	fmt.Fprintf(w, "%s %s <verb> --help for flags.\n", c.program(), prefix)
	3127	}
	3128	```
	3129
	3130	`TestHelpVerb` expects the plain USAGE with `ssh git@forge.test`; confirm `hostOf("https://forge.test")` returns `forge.test`.
	3131
	3132	- [ ] Step 4: Run
	3133
	3134	Run: `go test ./internal/control -count=1`
	3135	Expected: PASS. Any existing test of `help` plain output (grep `"help"` in `internal/control/*_test.go` and `e2e/`) moves to the new layout; `help --json` consumers are unaffected except for the two added fields.
	3136
	3137	- [ ] Step 5: Commit
	3138
	3139	```bash
	3140	git add internal/control
	3141	git commit -m "help: noun and verb layouts, flags and examples from the registry" -m "Ref #254"
	3142	```
	3143
	3144	### Task 4.5: the CLI's summaries come from the registry; grouped root help
	3145
	3146	Files:
	3147	- Create: `cmd/gitbay/summaries_gen.go` (generated), `cmd/gitbay/summaries_test.go`
	3148	- Modify: `cmd/gitbay/main.go` (`pass` loses its `short` parameter; `group` checked against `NounSummaries`; root help function)
	3149
	3150	Interfaces:
	3151	- Consumes: `control.Commands()`, `control.NounSummaries()`.
	3152	- Produces: `var summaries map[string]string` (package `main`, generated), `var rootSections []rootSection`.
	3153
	3154	- [ ] Step 1: Write the test
	3155
	3156	`cmd/gitbay/summaries_test.go`:
	3157
	3158	```go
	3159	package main
	3160
	3161	import (
	3162	"flag"
	3163	"fmt"
	3164	"os"
	3165	"slices"
	3166	"strings"
	3167	"testing"
	3168
	3169	"gitbay.org/gitbay/internal/control"
	3170	)
	3171
	3172	var updateSummaries = flag.Bool("update", false, "rewrite summaries_gen.go")
	3173
	3174	// summaries_gen.go is the registry's one-line summaries, so the CLI's
	3175	// command list and completions say what help says.
	3176	func TestSummariesAreCurrent(t *testing.T) {
	3177	var b strings.Builder
	3178	b.WriteString("// Code generated by TestSummariesAreCurrent -update; DO NOT EDIT.\n\npackage main\n\nvar summaries = map[string]string{\n")
	3179	var lines []string
	3180	for _, cmd := range control.Commands() {
	3181	lines = append(lines, fmt.Sprintf("\t%q: %q,\n", strings.Join(cmd.Path, " "), cmd.Summary))
	3182	}
	3183	slices.Sort(lines)
	3184	b.WriteString(strings.Join(lines, ""))
	3185	b.WriteString("}\n")
	3186	if *updateSummaries {
	3187	os.WriteFile("summaries_gen.go", []byte(b.String()), 0o644)
	3188	}
	3189	got, _ := os.ReadFile("summaries_gen.go")
	3190	if string(got) != b.String() {
	3191	t.Fatal("summaries_gen.go is stale: go test ./cmd/gitbay -run TestSummariesAreCurrent -update")
	3192	}
	3193	}
	3194
	3195	func TestRootSectionsCoverEveryCommand(t *testing.T) {
	3196	seen := map[string]int{}
	3197	for _, s := range rootSections {
	3198	for _, n := range s.names {
	3199	seen[n]++
	3200	}
	3201	}
	3202	for _, c := range newRoot().Commands() {
	3203	name := c.Name()
	3204	if name == "help" \|\| name == "completion" {
	3205	continue
	3206	}
	3207	if seen[name] != 1 {
	3208	t.Errorf("%s is in %d root sections", name, seen[name])
	3209	}
	3210	}
	3211	}
	3212
	3213	func TestGroupsSayWhatTheServerSays(t *testing.T) {
	3214	nouns := control.NounSummaries()
	3215	for _, c := range newRoot().Commands() {
	3216	if s, ok := nouns[c.Name()]; ok && c.Short != s {
	3217	t.Errorf("%s: CLI says %q, server says %q", c.Name(), c.Short, s)
	3218	}
	3219	}
	3220	}
	3221	```
	3222
	3223	- [ ] Step 2: Generate and wire
	3224
	3225	Run: `go test ./cmd/gitbay -run TestSummariesAreCurrent -update -count=1` (creates the file; the test compiles only after Step 3, so first create an empty `summaries_gen.go` with `package main\n\nvar summaries = map[string]string{}\n`).
	3226
	3227	Change `pass`:
	3228
	3229	```go
	3230	func pass(use string, o passOpts) *cobra.Command {
	3231	return &cobra.Command{
	3232	Use: use,
	3233	Short: summaries[strings.Join(o.server, " ")],
	3234	```
	3235
	3236	and drop the second argument from every `pass(` call in `main.go`:
	3237
	3238	```bash
	3239	sed -i '' -E 's/pass\(("[^"]"), "([^"\\]\|\\.)", /pass(\1, /' cmd/gitbay/main.go
	3240	```
	3241
	3242	then `go build ./cmd/gitbay` and fix any call the pattern missed by hand. Make each `group(...)` short text equal its `nounSummaries` entry where the noun exists on the server.
	3243
	3244	Root help:
	3245
	3246	```go
	3247	type rootSection struct {
	3248	title string
	3249	names []string
	3250	}
	3251
	3252	var rootSections = []rootSection{
	3253	{"WORK", []string{"issue", "mr", "build", "release", "milestone", "label", "search"}},
	3254	{"REPOSITORIES", []string{"repo", "wiki", "status", "webhook", "init"}},
	3255	{"YOU", []string{"dashboard", "feed", "notifications", "auth", "profile", "snippet", "web"}},
	3256	{"INSTANCE", []string{"org", "explore", "register", "migrate", "remote", "admin", "audit"}},
	3257	}
	3258
	3259	// rootHelp is gitbay --help: the nouns grouped by what they are for.
	3260	func rootHelp(root *cobra.Command) {
	3261	byName := map[string]*cobra.Command{}
	3262	wide := 0
	3263	for _, c := range root.Commands() {
	3264	byName[c.Name()] = c
	3265	wide = max(wide, len(c.Name()))
	3266	}
	3267	fmt.Println("gitbay: command-line client for a gitbay forge")
	3268	fmt.Println()
	3269	fmt.Println("USAGE")
	3270	fmt.Println(" gitbay <command> [<owner/name>] [flags]")
	3271	for _, s := range rootSections {
	3272	fmt.Println()
	3273	fmt.Println(s.title)
	3274	for _, n := range s.names {
	3275	if c := byName[n]; c != nil {
	3276	fmt.Printf(" %-*s %s\n", wide, n, c.Short)
	3277	}
	3278	}
	3279	}
	3280	fmt.Println()
	3281	fmt.Println("gitbay <command> --help for its verbs; gitbay help <prefix> for the server reference.")
	3282	}
	3283	```
	3284
	3285	In `newRoot`, after the commands are added: `root.SetHelpFunc(func(cmd *cobra.Command, args []string) { if cmd == root { rootHelp(root); return }; defaultHelp(cmd, args) })` with `defaultHelp := root.HelpFunc()` captured before the call. `helpCmd`'s bare case calls `rootHelp(root)` instead of `root.Help()`. Local commands whose `Short` carries usage (`audit`, `init`, `migrate`, `register`, `search`, `explore`, `feed`, `dashboard`) get summary-only `Short` strings; their usage stays in `Use` and `Long`.
	3286
	3287	- [ ] Step 3: Run
	3288
	3289	Run: `go build ./... && go vet ./... && go test ./cmd/gitbay -count=1`
	3290	Expected: PASS, including `TestEveryCommandIsReachable`.
	3291
	3292	- [ ] Step 4: Commit and open MR 4
	3293
	3294	```bash
	3295	git add cmd/gitbay
	3296	git commit -m "gitbay: summaries generated from the registry; grouped root help" -m "Ref #254"
	3297	git push -u origin cli-output-help
	3298	gitbay mr create --source cli-output-help --target main --title "CLI output: help from the registry"
	3299	```
	3300
	3301	---
	3302
	3303	# Part 5: docs (branch `cli-output-docs`)
	3304
	3305	### Task 5.1: wiki and changelog
	3306
	3307	Files:
	3308	- Modify: `.gitbay/wiki/Users.org` ("Output rules"), `.gitbay/wiki/Admin.org`, `CHANGELOG.org`
	3309
	3310	- [ ] Step 1: Users.org. In "Output rules", change the list rule's timestamp wording to "timestamps are RFC3339 to the second, UTC", replace the sentence about the CLI padding tabs, and add after the list:
	3311
	3312	```org
	3313	** At a terminal
	3314
	3315	The =gitbay= CLI sends =GITBAY_TERM=<cols>[,color]= on the SSH session
	3316	when stdout is a terminal. The server then prints:
	3317
	3318	- lists under a header, padded, fitted to the width (the title or
	3319	description column is cut with =…= first), states in colour, ages as
	3320	=2h ago=, and the next page as a command on stderr;
	3321	- =show= views with a title line, aligned fields, the body rendered
	3322	from markdown or org, one line per event, and comments under a rule;
	3323	timestamps as =2026-09-23 23:26 UTC=;
	3324	- help with flag descriptions and examples.
	3325
	3326	=NO_COLOR=, =TERM=dumb= and =--no-color= drop the colour. Views, diffs
	3327	and logs go through =$GITBAY_PAGER=, else =$PAGER=, else =less=; an
	3328	empty =GITBAY_PAGER= turns it off. Stock ssh gets the plain output
	3329	unless it sets the variable: =ssh -o SetEnv=GITBAY_TERM=120,color
	3330	git@gitbay.org issue list krz/gitbay=.
	3331	```
	3332
	3333	(If Task 2.3 took Step 6, describe the leading =--term=<cols>[,color]= argument instead of =SetEnv=.)
	3334
	3335	- [ ] Step 2: Admin.org. Where the system-sshd forced command (`gitbayd shell`) is documented, add: "Terminal output needs `AcceptEnv GITBAY_TERM` in `sshd_config`; without it every session gets plain output."
	3336
	3337	- [ ] Step 3: CHANGELOG.org. A new top section headed with the next minor version and the release date, in the style of the entries below it:
	3338
	3339	```org
	3340	* v1.36.0 — <date>
	3341
	3342	Terminal output for the CLI (#254).
	3343
	3344	- At a terminal, lists print under a header, fitted to the width, with
	3345	states in colour and relative ages; the next page is a command on
	3346	stderr. Piped output is the same tab-separated rows, with timestamps
	3347	as RFC3339 to the second.
	3348	- =show= commands print a title line, aligned fields, the body rendered
	3349	from markdown or org, events one per line and comments under a rule,
	3350	through a pager when longer than the screen.
	3351	- Help describes every flag, with examples, and =gitbay --help= groups
	3352	the commands. =help --json= adds =flags= and =examples=.
	3353	- =release list= takes =--limit= and =--cursor=, and leaves the title
	3354	empty when it repeats the tag. =notifications device add= prints
	3355	=registered device <n>=. =dashboard= prints =none= under an empty
	3356	section.
	3357
	3358	Operators running the system-sshd forced command add =AcceptEnv
	3359	GITBAY_TERM= to =sshd_config= for terminal output.
	3360	```
	3361
	3362	- [ ] Step 4: Commit and open MR 5
	3363
	3364	```bash
	3365	git add .gitbay/wiki/Users.org .gitbay/wiki/Admin.org CHANGELOG.org
	3366	git commit -m "docs: terminal output rules, sshd AcceptEnv, changelog" -m "Closes #254"
	3367	git push -u origin cli-output-docs
	3368	gitbay mr create --source cli-output-docs --target main --title "CLI output: docs and changelog"
	3369	```
	3370
	3371	Tagging, release and deploy follow the usual release steps once this merges.

docs/specs/2026-09-23-cli-output-refresh-design.md +10 −9

		@@ -84,8 +84,9 @@ for _, is := range issues {
84	84	t.flush()
85	85	```
86	86
87		Cells are typed: `ref`, `state`, `text`, `age`, `num`. The first
88		`text` column is the flexible one.
	87	Cells are typed: `ref`, `state`, `text`, `flex`, `age`, `num`. The
	88	`flex` column (a title or description, one per table) is the one that
	89	shrinks first.
89	90
90	91	Plain (`Term.Cols == 0`): one row per item, cells joined by tabs, no
91	92	header, `age` as RFC3339 to the second in UTC (`2026-09-23T23:26:00Z`).
		@@ -238,12 +239,14 @@ resolves through `Lookup` to its own command.
238	239	- `release list` takes `--limit`/`--cursor`; the title column is
239	240	empty when the title equals the tag.
240	241	- `notifications device add` prints `registered device <n>`.
241		- `build log --follow` giving up on a queued build prints
242		`build <n> still queued after 10m; run build log again to keep
243		watching` and exits 1, unchanged.
244		- Every missing positional goes through `usageWith` (`snippet show`,
245		`org label list`, and any other found by the test below).
246	242	- `dashboard` prints `none` under an empty section.
	243
	244	Two audit findings need no change. `build log --follow` already
	245	says what to do when it gives up on a queued build
	246	(`buildfollow.go`). A missing positional through `c.usage()` already
	247	prints the registered usage and exits 2, which is the rule; converting
	248	198 call sites to `usageWith` for an extra line is not worth the
	249	churn.
247	250	- The stale `build list` help goes with the `pass()` short text.
248	251
249	252	## Rules
		@@ -266,8 +269,6 @@ to the second.
266	269	`\x1b` in stdout; with `GITBAY_TERM=60,color`, asserting no line
267	270	wider than 60 display cells after stripping ANSI, code blocks
268	271	excepted.
269		- e2e: a missing positional on every command exits 2 with the
270		registered usage on stderr.
271	272	- CLI: `SetEnv` sent only when stdout is a terminal; `NO_COLOR`,
272	273	`TERM=dumb` and `--no-color` drop `color`; pager selection order.
273	274

Commit 2dd892270a

Commit `2dd892270a`