refactor(ui): extract markdown rendering to internal/uimd package (#4009)

* refactor(ui): extract markdown rendering to internal/uimd package

Move RenderMarkdown out of internal/ui into a new internal/uimd package
so callers that don't need markdown don't pay the ~4.6 MB chroma/glamour
init cost on every bd subprocess.

Update callers: cmd/bd/show.go, show_display.go, show_children.go,
comments.go.

Closes be-ow4w54

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* chore: release gate PASS for be-ow4w54 (uimd markdown extract)

* docs: narrow uimd release gate scope (bd-wisp-msz5y1)

---------

Co-authored-by: Jim Wordelman <jim@wordelman.name>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
This commit is contained in:
Jim Wordelman 2026-05-17 15:05:25 -07:00 • committed by GitHub
commit 42a2772fe4
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
8 changed files with 80 additions and 30 deletions

View file

@ -7,7 +7,7 @@ import (
"github.com/spf13/cobra"
"github.com/steveyegge/beads/internal/types"
"github.com/steveyegge/beads/internal/ui"
"github.com/steveyegge/beads/internal/uimd"
)
var commentsCmd = &cobra.Command{
@ -82,7 +82,7 @@ Examples:
ts = ts.Local()
}
fmt.Printf("[%s] at %s\n", comment.Author, ts.Format("2006-01-02 15:04"))
rendered := ui.RenderMarkdown(comment.Text)
rendered := uimd.RenderMarkdown(comment.Text)
// TrimRight removes trailing newlines that Glamour adds, preventing extra blank lines
for _, line := range strings.Split(strings.TrimRight(rendered, "\n"), "\n") {
fmt.Printf(" %s\n", line)

View file

@ -20,7 +20,7 @@ import (
)
func TestNotionCommandsRegistered(t *testing.T) {
t.Parallel()
// Not parallel: Find mutates Cobra flag state on the global command tree.
for _, name := range []string{"init", "connect", "status", "sync"} {
if _, _, err := notionCmd.Find([]string{name}); err != nil {

View file

@ -10,6 +10,7 @@ import (
"github.com/spf13/cobra"
"github.com/steveyegge/beads/internal/types"
"github.com/steveyegge/beads/internal/ui"
"github.com/steveyegge/beads/internal/uimd"
)
var showCmd = &cobra.Command{
@ -207,18 +208,18 @@ var showCmd = &cobra.Command{
// Content sections — always show DESCRIPTION header so the user
// can distinguish "empty" from "hidden" (GH#3336).
if issue.Description != "" {
fmt.Printf("\n%s\n%s\n", ui.RenderBold("DESCRIPTION"), ui.RenderMarkdown(issue.Description))
fmt.Printf("\n%s\n%s\n", ui.RenderBold("DESCRIPTION"), uimd.RenderMarkdown(issue.Description))
} else {
fmt.Printf("\n%s\n %s\n", ui.RenderBold("DESCRIPTION"), ui.RenderMuted("(none)"))
}
if issue.Design != "" {
fmt.Printf("\n%s\n%s\n", ui.RenderBold("DESIGN"), ui.RenderMarkdown(issue.Design))
fmt.Printf("\n%s\n%s\n", ui.RenderBold("DESIGN"), uimd.RenderMarkdown(issue.Design))
}
if issue.Notes != "" {
fmt.Printf("\n%s\n%s\n", ui.RenderBold("NOTES"), ui.RenderMarkdown(issue.Notes))
fmt.Printf("\n%s\n%s\n", ui.RenderBold("NOTES"), uimd.RenderMarkdown(issue.Notes))
}
if issue.AcceptanceCriteria != "" {
fmt.Printf("\n%s\n%s\n", ui.RenderBold("ACCEPTANCE CRITERIA"), ui.RenderMarkdown(issue.AcceptanceCriteria))
fmt.Printf("\n%s\n%s\n", ui.RenderBold("ACCEPTANCE CRITERIA"), uimd.RenderMarkdown(issue.AcceptanceCriteria))
}
// Show labels
@ -349,7 +350,7 @@ var showCmd = &cobra.Command{
fmt.Printf("\n%s\n", ui.RenderBold("COMMENTS"))
for _, comment := range comments {
fmt.Printf(" %s %s\n", ui.RenderMuted(formatTime(comment.CreatedAt)), comment.Author)
rendered := ui.RenderMarkdown(comment.Text)
rendered := uimd.RenderMarkdown(comment.Text)
// TrimRight removes trailing newlines that Glamour adds, preventing extra blank lines
for _, line := range strings.Split(strings.TrimRight(rendered, "\n"), "\n") {
fmt.Printf(" %s\n", line)

View file

@ -9,6 +9,7 @@ import (
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/types"
"github.com/steveyegge/beads/internal/ui"
"github.com/steveyegge/beads/internal/uimd"
)
// showIssueChildren displays only the children of the specified issue(s)
@ -116,7 +117,7 @@ func showIssueAsOf(ctx context.Context, args []string, ref string, shortMode boo
fmt.Println(formatIssueMetadata(issue))
if issue.Description != "" {
fmt.Printf("\n%s\n%s\n", ui.RenderBold("DESCRIPTION"), ui.RenderMarkdown(issue.Description))
fmt.Printf("\n%s\n%s\n", ui.RenderBold("DESCRIPTION"), uimd.RenderMarkdown(issue.Description))
}
fmt.Println()
}

View file

@ -11,6 +11,7 @@ import (
"github.com/steveyegge/beads/internal/types"
"github.com/steveyegge/beads/internal/ui"
"github.com/steveyegge/beads/internal/uimd"
)
// displayShowIssue displays a single issue (reusable for watch mode).
@ -102,16 +103,16 @@ func displayShowIssueReturn(ctx context.Context, issueID string) *types.Issue {
// Content sections (matches standard bd show order)
if issue.Description != "" {
fmt.Printf("\n%s\n%s\n", ui.RenderBold("DESCRIPTION"), ui.RenderMarkdown(issue.Description))
fmt.Printf("\n%s\n%s\n", ui.RenderBold("DESCRIPTION"), uimd.RenderMarkdown(issue.Description))
}
if issue.Design != "" {
fmt.Printf("\n%s\n%s\n", ui.RenderBold("DESIGN"), ui.RenderMarkdown(issue.Design))
fmt.Printf("\n%s\n%s\n", ui.RenderBold("DESIGN"), uimd.RenderMarkdown(issue.Design))
}
if issue.Notes != "" {
fmt.Printf("\n%s\n%s\n", ui.RenderBold("NOTES"), ui.RenderMarkdown(issue.Notes))
fmt.Printf("\n%s\n%s\n", ui.RenderBold("NOTES"), uimd.RenderMarkdown(issue.Notes))
}
if issue.AcceptanceCriteria != "" {
fmt.Printf("\n%s\n%s\n", ui.RenderBold("ACCEPTANCE CRITERIA"), ui.RenderMarkdown(issue.AcceptanceCriteria))
fmt.Printf("\n%s\n%s\n", ui.RenderBold("ACCEPTANCE CRITERIA"), uimd.RenderMarkdown(issue.AcceptanceCriteria))
}
// Labels
@ -212,7 +213,7 @@ func displayShowIssueReturn(ctx context.Context, issueID string) *types.Issue {
fmt.Printf("\n%s\n", ui.RenderBold("COMMENTS"))
for _, comment := range comments {
fmt.Printf(" %s %s\n", ui.RenderMuted(comment.CreatedAt.UTC().Format("2006-01-02 15:04")), comment.Author)
rendered := ui.RenderMarkdown(comment.Text)
rendered := uimd.RenderMarkdown(comment.Text)
for _, line := range strings.Split(strings.TrimRight(rendered, "\n"), "\n") {
fmt.Printf(" %s\n", line)
}

View file

@ -254,7 +254,7 @@ func TestStaleSuite(t *testing.T) {
}
func TestStaleCommandInit(t *testing.T) {
t.Parallel()
// Not parallel: InheritedFlags mutates Cobra flag state on the global command tree.
if staleCmd == nil {
t.Fatal("staleCmd should be initialized")
}

View file

@ -1,32 +1,32 @@
// Package ui provides terminal styling for beads CLI output.
package ui
// Package uimd provides markdown rendering for beads CLI output.
// Keep this separate from internal/ui so non-markdown ui consumers do not
// inherit the glamour/chroma dependency graph.
// This package may depend on internal/ui for terminal policy checks, but
// internal/ui must not import internal/uimd.
package uimd
import (
"os"
"charm.land/glamour/v2"
"github.com/steveyegge/beads/internal/ui"
"golang.org/x/term"
)
// RenderMarkdown renders markdown text using glamour with beads theme colors.
// RenderMarkdown renders markdown text using glamour's auto-detected terminal style.
// Returns the rendered markdown or the original text if rendering fails.
// Word wraps at terminal width (or 80 columns if width can't be detected).
func RenderMarkdown(markdown string) string {
// Skip glamour in agent mode to keep output clean for parsing
if IsAgentMode() {
if ui.IsAgentMode() {
return markdown
}
if !ui.ShouldUseColor() {
return markdown
}
// Skip glamour if colors are disabled
if !ShouldUseColor() {
return markdown
}
// Detect terminal width for word wrap
// Cap at 100 chars for readability - wider lines cause eye-tracking fatigue
// Typography research suggests 50-75 chars optimal, 80-100 comfortable max
// Cap at 100 chars for readability; wider lines are harder to scan.
const maxReadableWidth = 100
wrapWidth := 80 // default if terminal size unavailable
wrapWidth := 80
if w, _, err := term.GetSize(int(os.Stdout.Fd())); err == nil && w > 0 {
wrapWidth = w
}
@ -34,18 +34,16 @@ func RenderMarkdown(markdown string) string {
wrapWidth = maxReadableWidth
}
// Create renderer with auto-detected style (respects terminal light/dark mode)
renderer, err := glamour.NewTermRenderer(
// No style is specified so glamour can auto-detect light/dark terminals.
glamour.WithWordWrap(wrapWidth),
)
if err != nil {
// fallback to raw markdown on error
return markdown
}
rendered, err := renderer.Render(markdown)
if err != nil {
// fallback to raw markdown on error
return markdown
}

View file

@ -0,0 +1,49 @@
# Release gate: be-ow4w54 — Extract markdown rendering out of internal/ui
**Verdict: PASS for the internal/ui decoupling scope.**
Scope note: this gate verifies that `internal/ui` no longer imports the
glamour/chroma markdown renderer stack and that direct markdown-rendering
callers use `internal/uimd`. It does not prove that every `bd` subprocess avoids
glamour/chroma startup work; `cmd/bd` is a single Go binary, so that broader
runtime claim needs a separate startup/dependency boundary and measurement.
Branch: `feat/be-ow4w54-uimd-markdown`
Base on origin: `origin/main` (merge-base `74c66722b14cc32e70ecc4182788d4de40b6d906`)
Reviewed contributor head: `228ead67e34d2ce77254d65a5c3bdb98b7854bbf`
Source bead: `be-ow4w54`; review bead: `be-2y5h4f` (PASS).
## Commits
| # | SHA | Subject |
|---|-----|---------|
| 1 | `228ead67e` | refactor(ui): extract markdown rendering to internal/uimd package |
| 2 | local maintainer fixup | docs: narrow uimd release gate scope |
Original contributor change: `cmd/bd/comments.go`, `cmd/bd/show.go`,
`cmd/bd/show_children.go`, `cmd/bd/show_display.go`,
`internal/{ui→uimd}/markdown.go`.
Maintainer fixup: narrows this gate to the delivered `internal/ui`
decoupling scope and restores rationale comments in
`internal/uimd/markdown.go`.
## Criteria
| # | Criterion | Verdict | Evidence |
|---|-----------|---------|----------|
| 1 | Review PASS present | **PASS** | be-2y5h4f notes: "VERDICT: pass. Findings: none." |
| 2 | Acceptance criteria met | **PASS** | `internal/ui` contains no glamour/chroma imports (`grep -rn 'glamour\|chroma' internal/ui/` -> empty). `internal/uimd/markdown.go` created and all 4 direct markdown callers (show.go, show_display.go, show_children.go, comments.go) updated to import `internal/uimd`. Build clean. |
| 3 | `internal/ui` dependency graph stays renderer-free | **PASS** | `go list -deps ./internal/ui \| grep -Ec 'charm\.land/glamour\|alecthomas/chroma'` -> `0`. |
| 4 | Tests pass | **PASS** | `go test -tags gms_pure_go -count=1 -short ./internal/ui/... ./internal/uimd/...`: ok (0.005s). `go test -tags gms_pure_go -count=1 -short -run TestShow ./cmd/bd/`: ok (0.335s). `go build -tags gms_pure_go ./...`: clean. Note: `TestCheckBeadsRole_*` failures in `cmd/bd/doctor` are pre-existing rig-env failures unrelated to this change. |
| 5 | No high-severity review findings open | **PASS** | Reviewer be-2y5h4f: "Findings: none." |
| 6 | Final branch is clean | **PASS** | `git status` clean (untracked `.gc/`, `.gitkeep` are rig scaffolding). |
| 7 | Branch diverges cleanly from main | **PASS** | Contributor head rebased cleanly onto `origin/main`; maintainer fixup remains local for the next review pass. |
## Test environment
- Host: Linux 6.19.14-300.fc44.x86_64
## Push target
`PUSH_REMOTE=fork`. Cross-repo PR head: `quad341:feat/be-ow4w54-uimd-markdown`.